fix(infra): pin GlitchTip image to 6.1.6 (v4 tag never existed)

glitchtip/glitchtip:v4 is not a real tag — GlitchTip does not use a
v-prefix in its Docker image versioning. Latest stable release is 6.1.6.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.env.example

@@ -26,6 +26,36 @@ PORT_MAILPIT_SMTP=1025
 # Generate with: python3 -c "import secrets; print(secrets.token_hex(32))"
 OCR_TRAINING_TOKEN=change-me-in-production
 
+# --- Observability ---
+# Optional stack — start with: docker compose -f docker-compose.observability.yml up -d
+# Requires the main stack to already be running (docker compose up -d creates archiv-net).
+
+# Ports for host access
+PORT_GRAFANA=3001
+PORT_GLITCHTIP=3002
+PORT_PROMETHEUS=9090
+
+# Grafana admin password — change this before exposing Grafana beyond localhost
+GRAFANA_ADMIN_PASSWORD=changeme
+
+# GlitchTip domain — production: use https://grafana.raddatz.cloud (must match Caddy vhost)
+GLITCHTIP_DOMAIN=http://localhost:3002
+
+# GlitchTip secret key — Django SECRET_KEY equivalent, used to sign sessions and tokens.
+# REQUIRED in production — must not be empty or 'changeme'. Fail-closed: GlitchTip will
+# refuse to start with an invalid key.
+# Generate with: python3 -c "import secrets; print(secrets.token_hex(50))"
+GLITCHTIP_SECRET_KEY=changeme-generate-a-real-secret
+
+# Error reporting DSNs — leave empty to disable the SDK (safe default).
+# SENTRY_DSN: backend (Spring Boot) — used by the GlitchTip/Sentry Java SDK
+SENTRY_DSN=
+SENTRY_TRACES_SAMPLE_RATE=
+# VITE_SENTRY_DSN: frontend (SvelteKit) — injected at build time via Vite
+VITE_SENTRY_DSN=
+# Sentry/GlitchTip auth token for source map upload at build time (optional)
+SENTRY_AUTH_TOKEN=
+
 # Production SMTP — uncomment and fill in to send real emails instead of catching them
 # APP_BASE_URL=https://your-domain.example.com
 # MAIL_HOST=smtp.example.com

.gitea/workflows/ci.yml

@@ -2,6 +2,7 @@ name: CI
 
 on:
   push:
+    branches: [main]
   pull_request:
 
 jobs:
@@ -32,22 +33,84 @@ jobs:
         run: npx @inlang/paraglide-js compile --project ./project.inlang --outdir ./src/lib/paraglide
         working-directory: frontend
 
+      - name: Sync SvelteKit
+        run: npx svelte-kit sync
+        working-directory: frontend
+
       - name: Lint
         run: npm run lint
         working-directory: frontend
 
+      - name: Assert no banned vi.mock patterns
+        shell: bash
+        run: |
+          # Literal pdfjs-dist (libLoader pattern — ADR 012)
+          if grep -rF "vi.mock('pdfjs-dist'" frontend/src/; then
+            echo "FAIL: banned vi.mock('pdfjs-dist') pattern found — see ADR 012. Use the libLoader prop injection pattern instead."
+            exit 1
+          fi
+          # Async factory with dynamic import in body (named mechanism — ADR 012 / #553).
+          # Multiline PCRE matches `vi.mock(<arg>, async ... { ... await import(...) ... })`
+          # across line breaks. __meta__ is excluded because it contains fixture strings
+          # demonstrating the very pattern this check is meant to forbid.
+          if grep -rPzln 'vi\.mock\([^)]+,\s*async[^{]*\{[\s\S]*?await\s+import\s*\(' \
+              --include='*.spec.ts' --include='*.test.ts' \
+              --exclude-dir='__meta__' \
+              frontend/src/; then
+            echo "FAIL: banned async vi.mock factory with dynamic import in body — see ADR 012 / #553. Use a synchronous factory + vi.hoisted instead."
+            exit 1
+          fi
+
+      - name: Assert no (upload|download)-artifact past v3
+        shell: bash
+        run: |
+          # Self-test: verify the regex catches v4+ and does not catch v3.
+          tmp=$(mktemp)
+          printf '        uses: actions/upload-artifact@v5\n' > "$tmp"
+          grep -qP '^\s+uses:\s+actions/(upload|download)-artifact@v[4-9]' "$tmp" \
+            || { echo "FAIL: guard self-test — regex missed upload-artifact@v5"; rm "$tmp"; exit 1; }
+          printf '        uses: actions/upload-artifact@v3\n' > "$tmp"
+          grep -qvP '^\s+uses:\s+actions/(upload|download)-artifact@v[4-9]' "$tmp" \
+            || { echo "FAIL: guard self-test — regex incorrectly flagged upload-artifact@v3"; rm "$tmp"; exit 1; }
+          rm "$tmp"
+          # Guard: Gitea Actions (act_runner) does not implement the v4 artifact protocol.
+          # Both upload-artifact and download-artifact share the same incompatibility.
+          # Pin to @v3. See ADR-014 / #557.
+          if grep -RPn '^\s+uses:\s+actions/(upload|download)-artifact@v[4-9]' .gitea/workflows/; then
+            echo "::error::actions/(upload|download)-artifact@v4+ is unsupported on Gitea Actions (act_runner). Pin to @v3. See ADR-014 / #557."
+            exit 1
+          fi
+
       - name: Run unit and component tests with coverage
-        run: npm run test:coverage
+        shell: bash
+        run: |
+          set -eo pipefail
+          npm run test:coverage 2>&1 | tee /tmp/coverage-test-${{ github.run_id }}.log
         working-directory: frontend
         env:
           TZ: Europe/Berlin
 
+      # Diagnostic guard: covers the coverage run only. If `npm test` (above)
+      # exits 1 with a birpc error, the named pattern appears here — not there.
+      - name: Assert no birpc teardown race in coverage run
+        shell: bash
+        if: always()
+        run: |
+          if grep -qF "[birpc] rpc is closed" /tmp/coverage-test-${{ github.run_id }}.log 2>/dev/null; then
+            echo "FAIL: [birpc] rpc is closed teardown race detected in coverage run"
+            grep -F "[birpc] rpc is closed" /tmp/coverage-test-${{ github.run_id }}.log
+            exit 1
+          fi
+
+      # Gitea Actions (act_runner) does not implement upload-artifact v4 protocol — pinned per ADR-014. Do NOT upgrade. See #557.
       - name: Upload coverage reports
         if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v3
         with:
           name: coverage-reports
-          path: frontend/coverage/
+          path: |
+            frontend/coverage/
+            /tmp/coverage-test-${{ github.run_id }}.log
 
       - name: Build frontend
         run: npm run build
@@ -76,9 +139,10 @@ jobs:
             || { echo "FAIL: /hilfe/transkription.html missing from prerender output"; exit 1; }
           echo "PASS: only /hilfe/transkription.html prerendered."
 
+      # Gitea Actions (act_runner) does not implement upload-artifact v4 protocol — pinned per ADR-014. Do NOT upgrade. See #557.
       - name: Upload screenshots
         if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v3
         with:
           name: unit-test-screenshots
           path: frontend/test-results/screenshots/
@@ -133,6 +197,14 @@ jobs:
           ./mvnw clean test
         working-directory: backend
 
+      - name: Upload surefire reports
+        if: always()
+        # Gitea Actions (act_runner) does not implement upload-artifact v4 protocol — pinned per ADR-014. Do NOT upgrade. See #557.
+        uses: actions/upload-artifact@v3
+        with:
+          name: surefire-reports
+          path: backend/target/surefire-reports/
+
   # ─── fail2ban Regex Regression ────────────────────────────────────────────────
   # The filter parses Caddy's JSON access log; a Caddy upgrade that reorders
   # the JSON keys would silently break it (fail2ban-regex would return
@@ -232,6 +304,8 @@ jobs:
           MAIL_HOST=mailpit
           MAIL_PORT=1025
           APP_MAIL_FROM=noreply@local
+          IMPORT_HOST_DIR=/tmp/dummy-import
+          COMPOSE_NETWORK_NAME=test-idem-archiv-net
           EOF
 
       - name: Bring up minio

.gitea/workflows/coverage-flake-probe.yml

@@ -0,0 +1,65 @@
+name: Coverage Flake Probe
+
+# Manually-triggered probe for the birpc teardown race documented in ADR 012
+# / #553. Runs the full coverage suite 20× in parallel against a single SHA
+# and asserts zero `[birpc] rpc is closed` lines across every cell. Verifies
+# the acceptance criterion that the race no longer surfaces under coverage.
+
+on:
+  workflow_dispatch:
+
+jobs:
+  coverage-flake-probe:
+    name: Coverage flake probe (run ${{ matrix.run }})
+    runs-on: ubuntu-latest
+    container:
+      image: mcr.microsoft.com/playwright:v1.58.2-noble
+    strategy:
+      fail-fast: false
+      matrix:
+        run: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Cache node_modules
+        id: node-modules-cache
+        uses: actions/cache@v4
+        with:
+          path: frontend/node_modules
+          key: node-modules-${{ hashFiles('frontend/package-lock.json') }}
+
+      - name: Install dependencies
+        if: steps.node-modules-cache.outputs.cache-hit != 'true'
+        run: npm ci
+        working-directory: frontend
+
+      - name: Compile Paraglide i18n
+        run: npx @inlang/paraglide-js compile --project ./project.inlang --outdir ./src/lib/paraglide
+        working-directory: frontend
+
+      - name: Run unit and component tests with coverage
+        shell: bash
+        run: |
+          set -eo pipefail
+          npm run test:coverage 2>&1 | tee /tmp/coverage-test-${{ github.run_id }}-${{ matrix.run }}.log
+        working-directory: frontend
+        env:
+          TZ: Europe/Berlin
+
+      - name: Assert no birpc teardown race
+        shell: bash
+        if: always()
+        run: |
+          if grep -qF "[birpc] rpc is closed" /tmp/coverage-test-${{ github.run_id }}-${{ matrix.run }}.log 2>/dev/null; then
+            echo "FAIL: [birpc] rpc is closed teardown race detected in run ${{ matrix.run }}"
+            grep -F "[birpc] rpc is closed" /tmp/coverage-test-${{ github.run_id }}-${{ matrix.run }}.log
+            exit 1
+          fi
+
+      # Gitea Actions (act_runner) does not implement upload-artifact v4 protocol — pinned per ADR-014. Do NOT upgrade. See #557.
+      - name: Upload coverage log on failure
+        if: failure()
+        uses: actions/upload-artifact@v3
+        with:
+          name: coverage-log-run-${{ matrix.run }}
+          path: /tmp/coverage-test-${{ github.run_id }}-${{ matrix.run }}.log

.gitea/workflows/nightly.yml

@@ -30,6 +30,9 @@ name: nightly
 #   STAGING_OCR_TRAINING_TOKEN
 #   STAGING_APP_ADMIN_USERNAME
 #   STAGING_APP_ADMIN_PASSWORD
+#   GRAFANA_ADMIN_PASSWORD
+#   GLITCHTIP_SECRET_KEY
+#   SENTRY_DSN                  (set after GlitchTip first-run; empty = Sentry disabled)
 
 on:
   schedule:
@@ -74,6 +77,14 @@ jobs:
           MAIL_STARTTLS_ENABLE=false
           APP_MAIL_FROM=noreply@staging.raddatz.cloud
           IMPORT_HOST_DIR=/srv/familienarchiv-staging/import
+          POSTGRES_USER=archiv
+          PORT_GRAFANA=3003
+          PORT_GLITCHTIP=3002
+          PORT_PROMETHEUS=9090
+          GRAFANA_ADMIN_PASSWORD=${{ secrets.GRAFANA_ADMIN_PASSWORD }}
+          GLITCHTIP_SECRET_KEY=${{ secrets.GLITCHTIP_SECRET_KEY }}
+          GLITCHTIP_DOMAIN=https://glitchtip.archiv.raddatz.cloud
+          SENTRY_DSN=${{ secrets.SENTRY_DSN }}
           EOF
 
       - name: Verify backend /import:ro mount is wired
@@ -120,6 +131,13 @@ jobs:
             --profile staging \
             up -d --wait --remove-orphans
 
+      - name: Start observability stack
+        run: |
+          docker compose \
+            -f docker-compose.observability.yml \
+            --env-file .env.staging \
+            up -d --wait --remove-orphans
+
       - name: Reload Caddy
         # Apply any committed Caddyfile changes before smoke-testing the
         # public surface. Without this step, a Caddyfile edit lands in the
@@ -158,28 +176,38 @@ jobs:
         # public surface works. This step catches: Caddy not reloaded, HSTS
         # header dropped, /actuator block bypassed.
         #
-        # --resolve pins staging.raddatz.cloud to the runner's loopback so we
-        # do NOT depend on the host router doing hairpin NAT (many SOHO
-        # routers do not, or do so only after a firmware update). SNI still
-        # uses the public hostname so the cert validates correctly.
+        # --resolve pins staging.raddatz.cloud to the Docker bridge gateway IP
+        # (the host) so we do NOT depend on hairpin NAT on the host router.
+        # 127.0.0.1 cannot be used: job containers run in bridge network mode
+        # (runner-config.yaml), so 127.0.0.1 is the container's loopback, not
+        # the host's. The bridge gateway IS the host; Caddy binds 0.0.0.0:443
+        # and is therefore reachable from the container via that IP.
+        # SNI still uses the public hostname so the TLS cert validates correctly.
+        #
+        # Gateway detection reads /proc/net/route (always present, no package
+        # required) instead of `ip route` to avoid a dependency on iproute2.
+        # Field $2=="00000000" is the default route; field $3 is the gateway as
+        # a little-endian 32-bit hex value which awk decodes to dotted-decimal.
         run: |
           set -e
           HOST="staging.raddatz.cloud"
           URL="https://$HOST"
-          RESOLVE="--resolve $HOST:443:127.0.0.1"
-          echo "Smoke test: $URL (pinned to 127.0.0.1)"
-          curl -fsS $RESOLVE --max-time 10 "$URL/login" -o /dev/null
+          HOST_IP=$(awk 'NR>1 && $2=="00000000"{h=$3;printf "%d.%d.%d.%d\n",strtonum("0x"substr(h,7,2)),strtonum("0x"substr(h,5,2)),strtonum("0x"substr(h,3,2)),strtonum("0x"substr(h,1,2));exit}' /proc/net/route)
+          [ -n "$HOST_IP" ] || { echo "ERROR: could not detect Docker bridge gateway via /proc/net/route"; exit 1; }
+          RESOLVE="--resolve $HOST:443:$HOST_IP"
+          echo "Smoke test: $URL (pinned to $HOST_IP via bridge gateway)"
+          curl -fsS "$RESOLVE" --max-time 10 "$URL/login" -o /dev/null
           # Pin the preload-list-eligible HSTS value, not just header presence:
           # a degraded `max-age=1` or a dropped `includeSubDomains; preload` must
           # fail this check rather than pass it silently.
-          curl -fsS $RESOLVE --max-time 10 -I "$URL/" \
+          curl -fsS "$RESOLVE" --max-time 10 -I "$URL/" \
             | grep -Eqi 'strict-transport-security:[[:space:]]*max-age=31536000.*includeSubDomains.*preload'
           # Permissions-Policy denies APIs the app does not use (camera,
           # microphone, geolocation). A regression that loosens or drops the
           # header now fails the smoke step.
-          curl -fsS $RESOLVE --max-time 10 -I "$URL/" \
+          curl -fsS "$RESOLVE" --max-time 10 -I "$URL/" \
             | grep -Eqi 'permissions-policy:[[:space:]]*camera=\(\),[[:space:]]*microphone=\(\),[[:space:]]*geolocation=\(\)'
-          status=$(curl -s $RESOLVE -o /dev/null -w "%{http_code}" --max-time 10 "$URL/actuator/health")
+          status=$(curl -s "$RESOLVE" -o /dev/null -w "%{http_code}" --max-time 10 "$URL/actuator/health")
           [ "$status" = "404" ] || { echo "expected 404 from /actuator/health, got $status"; exit 1; }
           echo "All smoke checks passed"
 

.gitea/workflows/release.yml

@@ -34,6 +34,9 @@ name: release
 #   MAIL_PORT
 #   MAIL_USERNAME
 #   MAIL_PASSWORD
+#   GRAFANA_ADMIN_PASSWORD
+#   GLITCHTIP_SECRET_KEY
+#   SENTRY_DSN                    (set after GlitchTip first-run; empty = Sentry disabled)
 
 on:
   push:
@@ -72,6 +75,14 @@ jobs:
           MAIL_STARTTLS_ENABLE=true
           APP_MAIL_FROM=noreply@raddatz.cloud
           IMPORT_HOST_DIR=/srv/familienarchiv-production/import
+          POSTGRES_USER=archiv
+          PORT_GRAFANA=3003
+          PORT_GLITCHTIP=3002
+          PORT_PROMETHEUS=9090
+          GRAFANA_ADMIN_PASSWORD=${{ secrets.GRAFANA_ADMIN_PASSWORD }}
+          GLITCHTIP_SECRET_KEY=${{ secrets.GLITCHTIP_SECRET_KEY }}
+          GLITCHTIP_DOMAIN=https://glitchtip.archiv.raddatz.cloud
+          SENTRY_DSN=${{ secrets.SENTRY_DSN }}
           EOF
 
       - name: Build images
@@ -93,6 +104,13 @@ jobs:
             --env-file .env.production \
             up -d --wait --remove-orphans
 
+      - name: Start observability stack
+        run: |
+          docker compose \
+            -f docker-compose.observability.yml \
+            --env-file .env.production \
+            up -d --wait --remove-orphans
+
       - name: Reload Caddy
         # See nightly.yml — same rationale and mechanism: DooD job containers
         # cannot call systemctl directly; nsenter via a privileged sibling
@@ -107,26 +125,28 @@ jobs:
 
       - name: Smoke test deployed environment
         # See nightly.yml — same three checks, against the prod vhost.
-        # --resolve pins archiv.raddatz.cloud to the runner's loopback so
-        # the smoke test does NOT depend on hairpin NAT on the host router.
+        # --resolve pins to the bridge gateway IP (the host), not 127.0.0.1
+        # — see nightly.yml for the full network topology explanation.
         run: |
           set -e
           HOST="archiv.raddatz.cloud"
           URL="https://$HOST"
-          RESOLVE="--resolve $HOST:443:127.0.0.1"
-          echo "Smoke test: $URL (pinned to 127.0.0.1)"
-          curl -fsS $RESOLVE --max-time 10 "$URL/login" -o /dev/null
+          HOST_IP=$(ip route show default | awk '/default/ {print $3}')
+          [ -n "$HOST_IP" ] || { echo "ERROR: could not detect Docker bridge gateway via 'ip route'"; exit 1; }
+          RESOLVE="--resolve $HOST:443:$HOST_IP"
+          echo "Smoke test: $URL (pinned to $HOST_IP via bridge gateway)"
+          curl -fsS "$RESOLVE" --max-time 10 "$URL/login" -o /dev/null
           # Pin the preload-list-eligible HSTS value, not just header presence:
           # a degraded `max-age=1` or a dropped `includeSubDomains; preload` must
           # fail this check rather than pass it silently.
-          curl -fsS $RESOLVE --max-time 10 -I "$URL/" \
+          curl -fsS "$RESOLVE" --max-time 10 -I "$URL/" \
             | grep -Eqi 'strict-transport-security:[[:space:]]*max-age=31536000.*includeSubDomains.*preload'
           # Permissions-Policy denies APIs the app does not use (camera,
           # microphone, geolocation). A regression that loosens or drops the
           # header now fails the smoke step.
-          curl -fsS $RESOLVE --max-time 10 -I "$URL/" \
+          curl -fsS "$RESOLVE" --max-time 10 -I "$URL/" \
             | grep -Eqi 'permissions-policy:[[:space:]]*camera=\(\),[[:space:]]*microphone=\(\),[[:space:]]*geolocation=\(\)'
-          status=$(curl -s $RESOLVE -o /dev/null -w "%{http_code}" --max-time 10 "$URL/actuator/health")
+          status=$(curl -s "$RESOLVE" -o /dev/null -w "%{http_code}" --max-time 10 "$URL/actuator/health")
           [ "$status" = "404" ] || { echo "expected 404 from /actuator/health, got $status"; exit 1; }
           echo "All smoke checks passed"
 

CLAUDE.md

@@ -159,7 +159,7 @@ Input DTOs live flat in the domain package. Response types are the model entitie
 
 → See [CONTRIBUTING.md §Error handling](./CONTRIBUTING.md#error-handling)
 
-**LLM reminder:** use `DomainException.notFound/forbidden/conflict/internal()` from service methods — never throw raw exceptions. When adding a new `ErrorCode`: (1) add to `ErrorCode.java`, (2) mirror in `frontend/src/lib/shared/errors.ts`, (3) add i18n keys in `messages/{de,en,es}.json`.
+**LLM reminder:** use `DomainException.notFound/forbidden/conflict/internal()` from service methods — never throw raw exceptions. When adding a new `ErrorCode`: (1) add to `ErrorCode.java`, (2) add to `ErrorCode` type in `frontend/src/lib/shared/errors.ts`, (3) add a `case` in `getErrorMessage()`, (4) add i18n keys in `messages/{de,en,es}.json`.
 
 ### Security / Permissions
 

backend/pom.xml

@@ -29,6 +29,20 @@
 	<properties>
 		<java.version>21</java.version>
 	</properties>
+	<dependencyManagement>
+		<dependencies>
+			<!-- opentelemetry-spring-boot-starter:2.27.0 was built against opentelemetry-api:1.61.0,
+			     but Spring Boot 4.0.0 BOM only manages 1.55.0 (missing GlobalOpenTelemetry.getOrNoop()).
+			     Import the core OTel BOM here to override it before the Spring Boot BOM applies. -->
+			<dependency>
+				<groupId>io.opentelemetry</groupId>
+				<artifactId>opentelemetry-bom</artifactId>
+				<version>1.61.0</version>
+				<type>pom</type>
+				<scope>import</scope>
+			</dependency>
+		</dependencies>
+	</dependencyManagement>
 	<dependencies>
 		<dependency>
 			<groupId>org.springframework.boot</groupId>
@@ -197,6 +211,42 @@
 			<artifactId>jsoup</artifactId>
 			<version>1.18.1</version>
 		</dependency>
+
+		<!-- Observability: Prometheus metrics scrape endpoint (version managed by Spring Boot BOM) -->
+		<dependency>
+			<groupId>io.micrometer</groupId>
+			<artifactId>micrometer-registry-prometheus</artifactId>
+		</dependency>
+
+		<!-- Observability: Micrometer → OpenTelemetry tracing bridge (version managed by Spring Boot BOM) -->
+		<dependency>
+			<groupId>io.micrometer</groupId>
+			<artifactId>micrometer-tracing-bridge-otel</artifactId>
+		</dependency>
+
+		<!-- Observability: OTel Spring Boot auto-instrumentation — NOT in Spring Boot BOM, pinned explicitly -->
+		<dependency>
+			<groupId>io.opentelemetry.instrumentation</groupId>
+			<artifactId>opentelemetry-spring-boot-starter</artifactId>
+			<version>2.27.0</version>
+			<exclusions>
+				<!-- Excludes AzureAppServiceResourceProvider which references ServiceAttributes.SERVICE_INSTANCE_ID
+				     that does not exist in the semconv version pulled by this project. -->
+				<exclusion>
+					<groupId>io.opentelemetry.contrib</groupId>
+					<artifactId>opentelemetry-azure-resources</artifactId>
+				</exclusion>
+			</exclusions>
+		</dependency>
+
+		<!-- Sentry error reporting (GlitchTip-compatible) — sentry-spring-boot-4 is the
+		     Spring Boot 4 / Spring Framework 7 compatible module (replaces the jakarta starter
+		     which crashes with SF7 due to bean-name generation for triply-nested @Import classes) -->
+		<dependency>
+			<groupId>io.sentry</groupId>
+			<artifactId>sentry-spring-boot-4</artifactId>
+			<version>8.41.0</version>
+		</dependency>
 	</dependencies>
 
 
@@ -273,6 +323,16 @@
 					</profiles>
 				</configuration>
 			</plugin>
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-surefire-plugin</artifactId>
+				<configuration>
+					<forkedProcessTimeoutInSeconds>600</forkedProcessTimeoutInSeconds>
+					<systemPropertyVariables>
+						<junit.jupiter.execution.timeout.default>90 s</junit.jupiter.execution.timeout.default>
+					</systemPropertyVariables>
+				</configuration>
+			</plugin>
 		</plugins>
 	</build>
 

backend/src/main/java/org/raddatz/familienarchiv/exception/ErrorCode.java

@@ -30,6 +30,8 @@ public enum ErrorCode {
     // --- Users ---
     /** A user with the given ID or username does not exist. 404 */
     USER_NOT_FOUND,
+    /** A group with the given ID does not exist. 404 */
+    GROUP_NOT_FOUND,
     /** The supplied email address is already used by another account. 409 */
     EMAIL_ALREADY_IN_USE,
     /** The supplied current password does not match the stored hash. 400 */
@@ -52,6 +54,8 @@ public enum ErrorCode {
     INVITE_REVOKED,
     /** The invite has passed its expiry date. 410 */
     INVITE_EXPIRED,
+    /** A group cannot be deleted because one or more active invites reference it. 409 */
+    GROUP_HAS_ACTIVE_INVITES,
 
     // --- Auth ---
     /** The request is not authenticated. 401 */

backend/src/main/java/org/raddatz/familienarchiv/exception/GlobalExceptionHandler.java

@@ -2,6 +2,7 @@ package org.raddatz.familienarchiv.exception;
 
 import java.util.stream.Collectors;
 
+import io.sentry.Sentry;
 import jakarta.validation.ConstraintViolationException;
 import org.raddatz.familienarchiv.exception.DomainException;
 import org.raddatz.familienarchiv.exception.ErrorCode;
@@ -63,6 +64,7 @@ public class GlobalExceptionHandler {
 
     @ExceptionHandler(Exception.class)
     public ResponseEntity<ErrorResponse> handleGeneric(Exception ex) {
+        Sentry.captureException(ex);
         log.error("Unhandled exception", ex);
         return ResponseEntity.internalServerError()
             .body(new ErrorResponse(ErrorCode.INTERNAL_ERROR, "An unexpected error occurred"));

backend/src/main/java/org/raddatz/familienarchiv/importing/MassImportService.java

@@ -1,5 +1,6 @@
 package org.raddatz.familienarchiv.importing;
 
+import com.fasterxml.jackson.annotation.JsonIgnore;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.apache.poi.ss.usermodel.*;
@@ -52,9 +53,9 @@ public class MassImportService {
 
     public enum State { IDLE, RUNNING, DONE, FAILED }
 
-    public record ImportStatus(State state, String message, int processed, LocalDateTime startedAt) {}
+    public record ImportStatus(State state, String statusCode, @JsonIgnore String message, int processed, LocalDateTime startedAt) {}
 
-    private volatile ImportStatus currentStatus = new ImportStatus(State.IDLE, "Kein Import gestartet.", 0, null);
+    private volatile ImportStatus currentStatus = new ImportStatus(State.IDLE, "IMPORT_IDLE", "Kein Import gestartet.", 0, null);
 
     public ImportStatus getStatus() {
         return currentStatus;
@@ -116,20 +117,29 @@ public class MassImportService {
         if (currentStatus.state() == State.RUNNING) {
             throw DomainException.conflict(ErrorCode.IMPORT_ALREADY_RUNNING, "A mass import is already in progress");
         }
-        currentStatus = new ImportStatus(State.RUNNING, "Import läuft...", 0, LocalDateTime.now());
+        currentStatus = new ImportStatus(State.RUNNING, "IMPORT_RUNNING", "Import läuft...", 0, LocalDateTime.now());
         try {
             File spreadsheet = findSpreadsheetFile();
             log.info("Starte Massenimport aus: {}", spreadsheet.getAbsolutePath());
             int processed = processRows(readSpreadsheet(spreadsheet));
-            currentStatus = new ImportStatus(State.DONE,
+            currentStatus = new ImportStatus(State.DONE, "IMPORT_DONE",
                     "Import abgeschlossen. " + processed + " Dokumente verarbeitet.",
                     processed, currentStatus.startedAt());
+        } catch (NoSpreadsheetException e) {
+            log.error("Massenimport fehlgeschlagen: keine Tabellendatei", e);
+            currentStatus = new ImportStatus(State.FAILED, "IMPORT_FAILED_NO_SPREADSHEET",
+                    "Fehler: " + e.getMessage(), 0, currentStatus.startedAt());
         } catch (Exception e) {
             log.error("Massenimport fehlgeschlagen", e);
-            currentStatus = new ImportStatus(State.FAILED, "Fehler: " + e.getMessage(), 0, currentStatus.startedAt());
+            currentStatus = new ImportStatus(State.FAILED, "IMPORT_FAILED_INTERNAL",
+                    "Fehler: " + e.getMessage(), 0, currentStatus.startedAt());
         }
     }
 
+    private static class NoSpreadsheetException extends RuntimeException {
+        NoSpreadsheetException(String message) { super(message); }
+    }
+
     private File findSpreadsheetFile() throws IOException {
         try (Stream<Path> files = Files.list(Paths.get(importDir))) {
             return files
@@ -138,7 +148,7 @@ public class MassImportService {
                         return name.endsWith(".ods") || name.endsWith(".xlsx") || name.endsWith(".xls");
                     })
                     .findFirst()
-                    .orElseThrow(() -> new RuntimeException(
+                    .orElseThrow(() -> new NoSpreadsheetException(
                             "Keine Tabellendatei (.ods/.xlsx/.xls) in " + importDir + " gefunden!"))
                     .toFile();
         }

backend/src/main/java/org/raddatz/familienarchiv/user/InviteService.java

@@ -52,7 +52,11 @@ public class InviteService {
     public InviteToken createInvite(CreateInviteRequest dto, AppUser creator) {
         Set<UUID> groupIds = new HashSet<>();
         if (dto.getGroupIds() != null && !dto.getGroupIds().isEmpty()) {
-            List<UserGroup> groups = userService.findGroupsByIds(dto.getGroupIds());
+            Set<UUID> uniqueIds = new HashSet<>(dto.getGroupIds());
+            List<UserGroup> groups = userService.findGroupsByIds(new ArrayList<>(uniqueIds));
+            if (groups.size() != uniqueIds.size()) {
+                throw DomainException.notFound(ErrorCode.GROUP_NOT_FOUND, "One or more group IDs do not exist");
+            }
             groups.forEach(g -> groupIds.add(g.getId()));
         }
 

backend/src/main/java/org/raddatz/familienarchiv/user/InviteTokenRepository.java

@@ -24,4 +24,7 @@ public interface InviteTokenRepository extends JpaRepository<InviteToken, UUID>
 
     @Query("SELECT t FROM InviteToken t ORDER BY t.createdAt DESC")
     List<InviteToken> findAllOrderedByCreatedAt();
+
+    @Query("SELECT CASE WHEN COUNT(t) > 0 THEN true ELSE false END FROM InviteToken t JOIN t.groupIds g WHERE g = :groupId AND t.revoked = false AND (t.expiresAt IS NULL OR t.expiresAt > CURRENT_TIMESTAMP) AND (t.maxUses IS NULL OR t.useCount < t.maxUses)")
+    boolean existsActiveWithGroupId(@Param("groupId") UUID groupId);
 }

backend/src/main/java/org/raddatz/familienarchiv/user/UserService.java

@@ -37,6 +37,9 @@ public class UserService {
 
     private final AppUserRepository userRepository;
     private final UserGroupRepository groupRepository;
+    // Injected directly (not via InviteService) to avoid a constructor injection cycle:
+    // InviteService → UserService → InviteService. Spring Framework 7 forbids such cycles.
+    private final InviteTokenRepository inviteTokenRepository;
     private final PasswordEncoder passwordEncoder;
     private final AuditService auditService;
 
@@ -288,6 +291,10 @@ public class UserService {
 
     @Transactional
     public void deleteGroup(UUID id) {
+        if (inviteTokenRepository.existsActiveWithGroupId(id)) {
+            throw DomainException.conflict(ErrorCode.GROUP_HAS_ACTIVE_INVITES,
+                    "Cannot delete group " + id + " — referenced by one or more active invites");
+        }
         groupRepository.deleteById(id);
     }
 }

backend/src/main/resources/application.yaml

@@ -45,9 +45,34 @@ server:
   forward-headers-strategy: native
 
 management:
+  server:
+    # Management port is separate from the app port so that:
+    # (a) Caddy never proxies /actuator/* (it only routes :8080 → the app port)
+    # (b) Prometheus scrapes backend:8081 directly inside archiv-net, not via Caddy
+    # (c) Spring Security's session-authenticated filter chain on :8080 never sees actuator requests
+    port: 8081
+  endpoints:
+    web:
+      exposure:
+        include: health,info,prometheus,metrics
+  endpoint:
+    prometheus:
+      enabled: true
   health:
     mail:
       enabled: false
+  tracing:
+    sampling:
+      probability: 1.0   # 100% in dev; override via MANAGEMENT_TRACING_SAMPLING_PROBABILITY in prod compose
+
+# OpenTelemetry trace export — failures are non-fatal (app starts cleanly without Tempo running)
+# The default http://localhost:4317 ensures CI compatibility when no observability stack is present.
+otel:
+  service:
+    name: familienarchiv-backend
+  exporter:
+    otlp:
+      endpoint: ${OTEL_EXPORTER_OTLP_ENDPOINT:http://localhost:4317}
 
 springdoc:
   api-docs:
@@ -93,3 +118,12 @@ ocr:
   sender-model:
     activation-threshold: 100
     retrain-delta: 50
+
+sentry:
+  dsn: ${SENTRY_DSN:}
+  environment: ${SPRING_PROFILES_ACTIVE:dev}
+  traces-sample-rate: ${SENTRY_TRACES_SAMPLE_RATE:1.0}
+  send-default-pii: false
+  enable-tracing: true
+  ignored-exceptions-for-type:
+    - org.raddatz.familienarchiv.exception.DomainException

backend/src/main/resources/db/migration/V66__add_invite_token_group_id_index.sql

@@ -0,0 +1,3 @@
+-- The composite PK (invite_token_id, group_id) does not support efficient lookups by group_id alone.
+-- Add a dedicated index to support existsActiveWithGroupId queries.
+CREATE INDEX idx_itg_group_id ON invite_token_group_ids (group_id);

backend/src/test/java/org/raddatz/familienarchiv/ApplicationContextTest.java

@@ -1,14 +1,18 @@
 package org.raddatz.familienarchiv;
 
 import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.test.context.SpringBootTest;
 import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
+import org.springframework.context.ApplicationContext;
 import org.springframework.context.annotation.Import;
 import org.springframework.test.context.ActiveProfiles;
 import org.springframework.test.context.bean.override.mockito.MockitoBean;
 import org.testcontainers.containers.PostgreSQLContainer;
 import software.amazon.awssdk.services.s3.S3Client;
 
+import static org.assertj.core.api.Assertions.assertThat;
+
 @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.NONE)
 @ActiveProfiles("test")
 @Import(PostgresContainerConfig.class)
@@ -17,9 +21,18 @@ class ApplicationContextTest {
     @MockitoBean
     S3Client s3Client;
 
+    @Autowired
+    ApplicationContext ctx;
+
     @Test
     void contextLoads() {
         // verifies that the Spring context starts successfully with all beans wired,
         // Flyway migrations applied, and no configuration errors
     }
+
+    @Test
+    void sentry_is_disabled_when_no_dsn_is_configured() {
+        // application-test.yaml has no sentry.dsn — SDK must stay inactive so tests are clean
+        assertThat(io.sentry.Sentry.isEnabled()).isFalse();
+    }
 }

backend/src/test/java/org/raddatz/familienarchiv/audit/AuditServiceIntegrationTest.java

@@ -1,11 +1,11 @@
 package org.raddatz.familienarchiv.audit;
 
+import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.raddatz.familienarchiv.PostgresContainerConfig;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.test.context.SpringBootTest;
 import org.springframework.context.annotation.Import;
-import org.springframework.test.annotation.DirtiesContext;
 import org.springframework.test.context.ActiveProfiles;
 import org.springframework.test.context.bean.override.mockito.MockitoBean;
 import org.springframework.transaction.support.TransactionTemplate;
@@ -18,7 +18,6 @@ import static org.awaitility.Awaitility.await;
 @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.NONE)
 @ActiveProfiles("test")
 @Import(PostgresContainerConfig.class)
-@DirtiesContext(classMode = DirtiesContext.ClassMode.AFTER_EACH_TEST_METHOD)
 class AuditServiceIntegrationTest {
 
     @MockitoBean S3Client s3Client;
@@ -26,6 +25,11 @@ class AuditServiceIntegrationTest {
     @Autowired AuditLogRepository auditLogRepository;
     @Autowired TransactionTemplate transactionTemplate;
 
+    @BeforeEach
+    void resetAuditLog() {
+        auditLogRepository.deleteAll();
+    }
+
     @Test
     void logAfterCommit_writes_ANNOTATION_CREATED_row_after_transaction_commits() {
         transactionTemplate.execute(status -> {

backend/src/test/java/org/raddatz/familienarchiv/document/DocumentSearchPagedIntegrationTest.java

@@ -12,9 +12,9 @@ import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.test.context.SpringBootTest;
 import org.springframework.context.annotation.Import;
 import org.springframework.data.domain.PageRequest;
-import org.springframework.test.annotation.DirtiesContext;
 import org.springframework.test.context.ActiveProfiles;
 import org.springframework.test.context.bean.override.mockito.MockitoBean;
+import org.springframework.transaction.annotation.Transactional;
 import software.amazon.awssdk.services.s3.S3Client;
 
 import java.time.LocalDate;
@@ -33,7 +33,7 @@ import static org.assertj.core.api.Assertions.assertThat;
 @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.NONE)
 @ActiveProfiles("test")
 @Import(PostgresContainerConfig.class)
-@DirtiesContext(classMode = DirtiesContext.ClassMode.AFTER_EACH_TEST_METHOD)
+@Transactional
 class DocumentSearchPagedIntegrationTest {
 
     private static final int FIXTURE_SIZE = 120;

backend/src/test/java/org/raddatz/familienarchiv/exception/GlobalExceptionHandlerTest.java

@@ -0,0 +1,33 @@
+package org.raddatz.familienarchiv.exception;
+
+import io.sentry.Sentry;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.InjectMocks;
+import org.mockito.MockedStatic;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.http.ResponseEntity;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.Mockito.mockStatic;
+
+@ExtendWith(MockitoExtension.class)
+class GlobalExceptionHandlerTest {
+
+    @InjectMocks
+    private GlobalExceptionHandler handler;
+
+    @Test
+    void handleGeneric_captures_exception_in_sentry_and_returns_500() {
+        RuntimeException ex = new RuntimeException("unexpected failure");
+
+        try (MockedStatic<Sentry> sentryMock = mockStatic(Sentry.class)) {
+            ResponseEntity<GlobalExceptionHandler.ErrorResponse> response = handler.handleGeneric(ex);
+
+            sentryMock.verify(() -> Sentry.captureException(ex));
+            assertThat(response.getStatusCode().value()).isEqualTo(500);
+            assertThat(response.getBody()).isNotNull();
+            assertThat(response.getBody().code()).isEqualTo(ErrorCode.INTERNAL_ERROR);
+        }
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/geschichte/GeschichteServiceIntegrationTest.java

@@ -19,9 +19,9 @@ import org.springframework.context.annotation.Import;
 import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
 import org.springframework.security.core.authority.SimpleGrantedAuthority;
 import org.springframework.security.core.context.SecurityContextHolder;
-import org.springframework.test.annotation.DirtiesContext;
 import org.springframework.test.context.ActiveProfiles;
 import org.springframework.test.context.bean.override.mockito.MockitoBean;
+import org.springframework.transaction.annotation.Transactional;
 import software.amazon.awssdk.services.s3.S3Client;
 
 import java.util.List;
@@ -32,7 +32,7 @@ import static org.assertj.core.api.Assertions.assertThat;
 @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.NONE)
 @ActiveProfiles("test")
 @Import(PostgresContainerConfig.class)
-@DirtiesContext(classMode = DirtiesContext.ClassMode.AFTER_EACH_TEST_METHOD)
+@Transactional
 class GeschichteServiceIntegrationTest {
 
     @MockitoBean

backend/src/test/java/org/raddatz/familienarchiv/importing/MassImportServiceTest.java

@@ -20,7 +20,10 @@ import software.amazon.awssdk.core.sync.RequestBody;
 import software.amazon.awssdk.services.s3.S3Client;
 import software.amazon.awssdk.services.s3.model.PutObjectRequest;
 
+import org.apache.poi.xssf.usermodel.XSSFWorkbook;
+
 import java.io.File;
+import java.io.OutputStream;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.time.LocalDate;
@@ -70,14 +73,20 @@ class MassImportServiceTest {
         assertThat(service.getStatus().state()).isEqualTo(MassImportService.State.IDLE);
     }
 
+    @Test
+    void getStatus_hasStatusCode_IMPORT_IDLE_byDefault() {
+        assertThat(service.getStatus().statusCode()).isEqualTo("IMPORT_IDLE");
+    }
+
     // ─── runImportAsync ───────────────────────────────────────────────────────
 
     @Test
     void runImportAsync_setsFailedStatus_whenImportDirectoryDoesNotExist() {
-        // /import directory doesn't exist in test environment → findSpreadsheetFile throws
+        // /import directory doesn't exist in test environment → IOException → IMPORT_FAILED_INTERNAL
         service.runImportAsync();
 
         assertThat(service.getStatus().state()).isEqualTo(MassImportService.State.FAILED);
+        assertThat(service.getStatus().statusCode()).isEqualTo("IMPORT_FAILED_INTERNAL");
     }
 
     @Test
@@ -93,10 +102,35 @@ class MassImportServiceTest {
         assertThat(service.getStatus().message()).contains(tempDir.toString());
     }
 
+    @Test
+    void runImportAsync_setsStatusCode_IMPORT_FAILED_NO_SPREADSHEET_whenDirIsEmpty(@TempDir Path tempDir) {
+        ReflectionTestUtils.setField(service, "importDir", tempDir.toString());
+
+        service.runImportAsync();
+
+        assertThat(service.getStatus().statusCode()).isEqualTo("IMPORT_FAILED_NO_SPREADSHEET");
+    }
+
+    @Test
+    void runImportAsync_setsStatusCode_IMPORT_DONE_whenSpreadsheetHasNoDataRows(@TempDir Path tempDir) throws Exception {
+        Path xlsx = tempDir.resolve("import.xlsx");
+        try (XSSFWorkbook wb = new XSSFWorkbook()) {
+            wb.createSheet("Sheet1");
+            try (OutputStream out = Files.newOutputStream(xlsx)) {
+                wb.write(out);
+            }
+        }
+        ReflectionTestUtils.setField(service, "importDir", tempDir.toString());
+
+        service.runImportAsync();
+
+        assertThat(service.getStatus().statusCode()).isEqualTo("IMPORT_DONE");
+    }
+
     @Test
     void runImportAsync_throwsConflict_whenAlreadyRunning() {
         MassImportService.ImportStatus running = new MassImportService.ImportStatus(
-                MassImportService.State.RUNNING, "Running...", 0, LocalDateTime.now());
+                MassImportService.State.RUNNING, "IMPORT_RUNNING", "Running...", 0, LocalDateTime.now());
         ReflectionTestUtils.setField(service, "currentStatus", running);
 
         assertThatThrownBy(() -> service.runImportAsync())

backend/src/test/java/org/raddatz/familienarchiv/person/PersonServiceIntegrationTest.java

@@ -8,9 +8,9 @@ import org.raddatz.familienarchiv.person.PersonRepository;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.test.context.SpringBootTest;
 import org.springframework.context.annotation.Import;
-import org.springframework.test.annotation.DirtiesContext;
 import org.springframework.test.context.ActiveProfiles;
 import org.springframework.test.context.bean.override.mockito.MockitoBean;
+import org.springframework.transaction.annotation.Transactional;
 import software.amazon.awssdk.services.s3.S3Client;
 
 import static org.assertj.core.api.Assertions.assertThat;
@@ -18,7 +18,7 @@ import static org.assertj.core.api.Assertions.assertThat;
 @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.NONE)
 @ActiveProfiles("test")
 @Import(PostgresContainerConfig.class)
-@DirtiesContext(classMode = DirtiesContext.ClassMode.AFTER_EACH_TEST_METHOD)
+@Transactional
 class PersonServiceIntegrationTest {
 
     @MockitoBean S3Client s3Client;

backend/src/test/java/org/raddatz/familienarchiv/user/AdminControllerTest.java

@@ -40,6 +40,47 @@ class AdminControllerTest {
     @MockitoBean ThumbnailBackfillService thumbnailBackfillService;
     @MockitoBean CustomUserDetailsService customUserDetailsService;
 
+    // ─── GET /api/admin/import-status ─────────────────────────────────────────
+
+    @Test
+    @WithMockUser(authorities = "ADMIN")
+    void importStatus_returns200_withStatusCode_whenAdmin() throws Exception {
+        MassImportService.ImportStatus status = new MassImportService.ImportStatus(
+                MassImportService.State.IDLE, "IMPORT_IDLE", "Kein Import gestartet.", 0, null);
+        when(massImportService.getStatus()).thenReturn(status);
+
+        mockMvc.perform(get("/api/admin/import-status"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.state").value("IDLE"))
+                .andExpect(jsonPath("$.statusCode").value("IMPORT_IDLE"))
+                .andExpect(jsonPath("$.processed").value(0));
+    }
+
+    @Test
+    @WithMockUser(authorities = "ADMIN")
+    void importStatus_messageField_notPresentInApiResponse() throws Exception {
+        MassImportService.ImportStatus status = new MassImportService.ImportStatus(
+                MassImportService.State.IDLE, "IMPORT_IDLE", "Kein Import gestartet.", 0, null);
+        when(massImportService.getStatus()).thenReturn(status);
+
+        mockMvc.perform(get("/api/admin/import-status"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.message").doesNotExist());
+    }
+
+    @Test
+    void importStatus_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/admin/import-status"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser(authorities = "READ_ALL")
+    void importStatus_returns403_whenUserLacksAdminPermission() throws Exception {
+        mockMvc.perform(get("/api/admin/import-status"))
+                .andExpect(status().isForbidden());
+    }
+
     @Test
     void backfillVersions_returns401_whenUnauthenticated() throws Exception {
         mockMvc.perform(post("/api/admin/backfill-versions"))

backend/src/test/java/org/raddatz/familienarchiv/user/InviteControllerTest.java

@@ -20,10 +20,13 @@ import org.springframework.security.test.context.support.WithMockUser;
 import org.springframework.test.context.bean.override.mockito.MockitoBean;
 import org.springframework.test.web.servlet.MockMvc;
 
+import org.mockito.ArgumentCaptor;
+
 import java.time.LocalDateTime;
 import java.util.List;
 import java.util.UUID;
 
+import static org.assertj.core.api.Assertions.assertThat;
 import static org.mockito.ArgumentMatchers.*;
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
@@ -147,6 +150,30 @@ class InviteControllerTest {
                 .andExpect(jsonPath("$.label").value("Für Familie"));
     }
 
+    @Test
+    @WithMockUser(username = "admin@test.com", authorities = {"ADMIN_USER"})
+    void createInvite_forwardsGroupIdsToService() throws Exception {
+        UUID groupId = UUID.randomUUID();
+        AppUser admin = AppUser.builder().id(UUID.randomUUID()).email("admin@test.com").build();
+        when(userService.findByEmail("admin@test.com")).thenReturn(admin);
+
+        InviteToken savedToken = InviteToken.builder()
+                .id(UUID.randomUUID()).code("ABCDE12345").useCount(0).build();
+        when(inviteService.createInvite(any(), eq(admin))).thenReturn(savedToken);
+        when(inviteService.toListItemDTO(any(), anyString()))
+                .thenReturn(makeInviteDTO(savedToken.getId(), "ABCDE12345"));
+
+        String body = "{\"groupIds\":[\"" + groupId + "\"]}";
+        mockMvc.perform(post("/api/invites")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body))
+                .andExpect(status().isCreated());
+
+        ArgumentCaptor<CreateInviteRequest> captor = ArgumentCaptor.forClass(CreateInviteRequest.class);
+        verify(inviteService).createInvite(captor.capture(), eq(admin));
+        assertThat(captor.getValue().getGroupIds()).containsExactly(groupId);
+    }
+
     // ─── DELETE /api/invites/{id} ─────────────────────────────────────────────
 
     @Test

backend/src/test/java/org/raddatz/familienarchiv/user/InviteServiceTest.java

@@ -156,6 +156,35 @@ class InviteServiceTest {
         assertThat(result.getGroupIds()).contains(g.getId());
     }
 
+    @Test
+    void createInvite_throwsGroupNotFound_whenSubmittedGroupIdDoesNotExist() {
+        UUID unknownGroupId = UUID.randomUUID();
+        when(userService.findGroupsByIds(anyList())).thenReturn(List.of());
+
+        CreateInviteRequest req = new CreateInviteRequest();
+        req.setGroupIds(List.of(unknownGroupId));
+
+        assertThatThrownBy(() -> inviteService.createInvite(req, admin))
+                .isInstanceOf(DomainException.class)
+                .extracting(e -> ((DomainException) e).getCode())
+                .isEqualTo(ErrorCode.GROUP_NOT_FOUND);
+    }
+
+    @Test
+    void createInvite_doesNotThrowGroupNotFound_whenDuplicateGroupIdsSubmitted() {
+        UUID groupId = UUID.randomUUID();
+        UserGroup group = UserGroup.builder().id(groupId).name("Familie").build();
+        when(inviteTokenRepository.findByCode(anyString())).thenReturn(Optional.empty());
+        when(userService.findGroupsByIds(anyList())).thenReturn(List.of(group));
+        when(inviteTokenRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        CreateInviteRequest req = new CreateInviteRequest();
+        req.setGroupIds(List.of(groupId, groupId)); // same UUID submitted twice
+
+        // before deduplication: size(groups)==1 != size(submitted)==2 → false GROUP_NOT_FOUND
+        assertThatCode(() -> inviteService.createInvite(req, admin)).doesNotThrowAnyException();
+    }
+
     // ─── redeemInvite ─────────────────────────────────────────────────────────
 
     @Test

backend/src/test/java/org/raddatz/familienarchiv/user/InviteTokenRepositoryIntegrationTest.java

@@ -0,0 +1,78 @@
+package org.raddatz.familienarchiv.user;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.raddatz.familienarchiv.PostgresContainerConfig;
+import org.raddatz.familienarchiv.config.FlywayConfig;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.jdbc.test.autoconfigure.AutoConfigureTestDatabase;
+import org.springframework.boot.data.jpa.test.autoconfigure.DataJpaTest;
+import org.springframework.context.annotation.Import;
+
+import java.time.LocalDateTime;
+import java.util.Set;
+import java.util.UUID;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+@DataJpaTest
+@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
+@Import({PostgresContainerConfig.class, FlywayConfig.class})
+class InviteTokenRepositoryIntegrationTest {
+
+    @Autowired InviteTokenRepository inviteTokenRepository;
+    @Autowired UserGroupRepository userGroupRepository;
+    @Autowired AppUserRepository appUserRepository;
+
+    private UserGroup group;
+    private AppUser admin;
+
+    @BeforeEach
+    void setUp() {
+        inviteTokenRepository.deleteAll();
+        userGroupRepository.deleteAll();
+        appUserRepository.deleteAll();
+        admin = appUserRepository.save(AppUser.builder().email("admin@test.com").password("pw").build());
+        group = userGroupRepository.save(UserGroup.builder().name("Familie").build());
+    }
+
+    // ─── existsActiveWithGroupId ──────────────────────────────────────────────
+
+    @Test
+    void existsActiveWithGroupId_returnsTrueForActiveInviteLinkedToGroup() {
+        inviteTokenRepository.save(token(t -> t));
+
+        assertThat(inviteTokenRepository.existsActiveWithGroupId(group.getId())).isTrue();
+    }
+
+    @Test
+    void existsActiveWithGroupId_returnsFalseWhenInviteIsRevoked() {
+        inviteTokenRepository.save(token(t -> t.revoked(true)));
+
+        assertThat(inviteTokenRepository.existsActiveWithGroupId(group.getId())).isFalse();
+    }
+
+    @Test
+    void existsActiveWithGroupId_returnsFalseWhenInviteIsExpired() {
+        inviteTokenRepository.save(token(t -> t.expiresAt(LocalDateTime.now().minusDays(1))));
+
+        assertThat(inviteTokenRepository.existsActiveWithGroupId(group.getId())).isFalse();
+    }
+
+    @Test
+    void existsActiveWithGroupId_returnsFalseWhenInviteIsExhausted() {
+        inviteTokenRepository.save(token(t -> t.maxUses(1).useCount(1)));
+
+        assertThat(inviteTokenRepository.existsActiveWithGroupId(group.getId())).isFalse();
+    }
+
+    // ─── helpers ─────────────────────────────────────────────────────────────
+
+    private InviteToken token(java.util.function.UnaryOperator<InviteToken.InviteTokenBuilder> customizer) {
+        InviteToken.InviteTokenBuilder builder = InviteToken.builder()
+                .code(UUID.randomUUID().toString().replace("-", "").substring(0, 10))
+                .groupIds(new java.util.HashSet<>(Set.of(group.getId())))
+                .createdBy(admin);
+        return customizer.apply(builder).build();
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/user/UserServiceTest.java

@@ -36,6 +36,7 @@ class UserServiceTest {
 
     @Mock AppUserRepository userRepository;
     @Mock UserGroupRepository groupRepository;
+    @Mock InviteTokenRepository inviteTokenRepository;
     @Mock PasswordEncoder passwordEncoder;
     @Mock AuditService auditService;
     @InjectMocks UserService userService;
@@ -903,6 +904,29 @@ class UserServiceTest {
         assertThat(result.getPermissions()).containsExactlyInAnyOrder("READ_ALL", "WRITE_ALL");
     }
 
+    // ─── deleteGroup ──────────────────────────────────────────────────────────
+
+    @Test
+    void deleteGroup_throwsConflict_whenActiveInviteReferencesGroup() {
+        UUID groupId = UUID.randomUUID();
+        when(inviteTokenRepository.existsActiveWithGroupId(groupId)).thenReturn(true);
+
+        assertThatThrownBy(() -> userService.deleteGroup(groupId))
+                .isInstanceOf(DomainException.class)
+                .extracting(e -> ((DomainException) e).getCode())
+                .isEqualTo(ErrorCode.GROUP_HAS_ACTIVE_INVITES);
+    }
+
+    @Test
+    void deleteGroup_deletesGroup_whenNoActiveInviteReferencesGroup() {
+        UUID groupId = UUID.randomUUID();
+        when(inviteTokenRepository.existsActiveWithGroupId(groupId)).thenReturn(false);
+
+        userService.deleteGroup(groupId);
+
+        verify(groupRepository).deleteById(groupId);
+    }
+
     @Test
     void createGroup_withNullPermissions_savesGroupWithEmptyPermissionSet() {
         org.raddatz.familienarchiv.user.GroupDTO dto = new org.raddatz.familienarchiv.user.GroupDTO();

backend/src/test/resources/application-test.yaml

@@ -13,3 +13,18 @@ spring:
     password: test
   mail:
     host: localhost
+
+# Disable OTel SDK entirely in tests — prevents auto-configuration from loading resource providers
+# (e.g. AzureAppServiceResourceProvider) that fail against the semconv version used here.
+otel:
+  sdk:
+    disabled: true
+
+# Disable trace export in tests — prevents OTLP connection attempts when no Tempo is running.
+# Sampling probability 0.0 means no spans are created, so no export is attempted.
+management:
+  server:
+    port: 0   # random port per context — prevents TIME_WAIT conflicts when @DirtiesContext restarts the context
+  tracing:
+    sampling:
+      probability: 0.0

backend/src/test/resources/application.properties

@@ -0,0 +1,2 @@
+logging.level.root=WARN
+logging.level.org.raddatz=INFO

docker-compose.observability.yml

@@ -0,0 +1,259 @@
+# Observability stack — Grafana LGTM + GlitchTip
+#
+# Requires the main stack to be running first:
+#   docker compose up -d                                    # creates archiv-net
+#   docker compose -f docker-compose.observability.yml up -d
+#
+# To validate without starting:
+#   docker compose -f docker-compose.observability.yml config
+
+services:
+
+  # --- Metrics: Prometheus ---
+
+  prometheus:
+    image: prom/prometheus:v3.4.0
+    container_name: obs-prometheus
+    restart: unless-stopped
+    volumes:
+      - ./infra/observability/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml:ro
+      - prometheus_data:/prometheus
+    command:
+      - '--config.file=/etc/prometheus/prometheus.yml'
+      - '--storage.tsdb.path=/prometheus'
+      - '--storage.tsdb.retention.time=30d'
+      - '--web.enable-lifecycle'
+    ports:
+      - "127.0.0.1:${PORT_PROMETHEUS:-9090}:9090"
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:9090/-/healthy"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+    networks:
+      - archiv-net
+      - obs-net
+
+  node-exporter:
+    image: prom/node-exporter:v1.9.0
+    container_name: obs-node-exporter
+    restart: unless-stopped
+    # pid: host — required for process-level CPU/memory metrics; cgroup isolation applies
+    pid: host
+    volumes:
+      - /proc:/host/proc:ro
+      - /sys:/host/sys:ro
+      - /:/rootfs:ro
+    command:
+      - '--path.procfs=/host/proc'
+      - '--path.sysfs=/host/sys'
+      # $$ is YAML Compose escaping for a literal $ in the regex alternation
+      - '--collector.filesystem.ignored-mount-points=^/(sys|proc|dev|host|etc)($$|/)'
+    expose:
+      - "9100"
+    networks:
+      - obs-net
+
+  cadvisor:
+    image: gcr.io/cadvisor/cadvisor:v0.52.1
+    container_name: obs-cadvisor
+    restart: unless-stopped
+    # privileged: true — required for cgroup and namespace metrics, see cAdvisor docs.
+    # Accepted risk: cAdvisor is pinned, on Renovate, and not exposed outside obs-net.
+    privileged: true
+    volumes:
+      - /:/rootfs:ro
+      # /var/run/docker.sock mounted read-only — sufficient for container metadata discovery
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - /sys:/sys:ro
+      - /var/lib/docker:/var/lib/docker:ro
+    expose:
+      - "8080"
+    networks:
+      - obs-net
+
+  # --- Logs: Loki + Promtail ---
+
+  loki:
+    image: grafana/loki:3.4.2
+    container_name: obs-loki
+    restart: unless-stopped
+    volumes:
+      - ./infra/observability/loki/loki-config.yml:/etc/loki/loki-config.yml:ro
+      - loki_data:/loki
+    command: -config.file=/etc/loki/loki-config.yml
+    expose:
+      - "3100"
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO- http://localhost:3100/ready | grep -q ready || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+    networks:
+      - obs-net
+
+  promtail:
+    image: grafana/promtail:3.4.2
+    container_name: obs-promtail
+    restart: unless-stopped
+    volumes:
+      - ./infra/observability/promtail/promtail-config.yml:/etc/promtail/promtail-config.yml:ro
+      - /var/lib/docker/containers:/var/lib/docker/containers:ro
+      # :ro restricts file-system access but NOT Docker API permissions — a compromised Promtail has full daemon access. Accepted risk on single-operator self-hosted archive.
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - promtail_positions:/tmp  # persists positions.yaml across restarts — avoids duplicate log ingestion
+    command: -config.file=/etc/promtail/promtail-config.yml
+    networks:
+      - archiv-net  # label discovery from application containers via Docker socket
+      - obs-net     # log shipping to Loki
+    depends_on:
+      loki:
+        condition: service_healthy
+
+  # --- Traces: Tempo ---
+
+  tempo:
+    image: grafana/tempo:2.7.2
+    container_name: obs-tempo
+    restart: unless-stopped
+    volumes:
+      - ./infra/observability/tempo/tempo.yml:/etc/tempo.yml:ro
+      - tempo_data:/var/tempo
+    command: -config.file=/etc/tempo.yml
+    expose:
+      - "3200"   # Grafana queries Tempo on this port (obs-net only)
+      - "4317"   # OTLP gRPC — backend sends traces here (archiv-net)
+      - "4318"   # OTLP HTTP — alternative transport (archiv-net)
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO- http://localhost:3200/ready | grep -q ready || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 15s
+    networks:
+      - archiv-net   # backend (archive-backend) reaches tempo:4317 over this network
+      - obs-net      # Grafana reaches tempo:3200 over this network
+
+  # --- Dashboards: Grafana ---
+
+  obs-grafana:
+    image: grafana/grafana-oss:11.6.1
+    container_name: obs-grafana
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:${PORT_GRAFANA:-3001}:3000"
+    environment:
+      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_ADMIN_PASSWORD:-changeme}
+      GF_USERS_ALLOW_SIGN_UP: "false"
+    volumes:
+      - grafana_data:/var/lib/grafana
+      - ./infra/observability/grafana/provisioning:/etc/grafana/provisioning:ro
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO- http://localhost:3000/api/health | grep -q ok || exit 1"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 30s
+    depends_on:
+      prometheus:
+        condition: service_healthy
+      loki:
+        condition: service_healthy
+      tempo:
+        condition: service_healthy
+    networks:
+      - obs-net
+
+  # --- Error Tracking: GlitchTip ---
+
+  obs-redis:
+    image: redis:7-alpine
+    container_name: obs-redis
+    restart: unless-stopped
+    volumes:
+      - glitchtip_data:/data
+    expose:
+      - "6379"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    networks:
+      - obs-net
+
+  obs-glitchtip:
+    image: glitchtip/glitchtip:6.1.6
+    container_name: obs-glitchtip
+    restart: unless-stopped
+    depends_on:
+      obs-redis:
+        condition: service_healthy
+      obs-glitchtip-db-init:
+        condition: service_completed_successfully
+    environment:
+      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@archive-db:5432/glitchtip
+      REDIS_URL: redis://obs-redis:6379/0
+      SECRET_KEY: ${GLITCHTIP_SECRET_KEY}
+      GLITCHTIP_DOMAIN: ${GLITCHTIP_DOMAIN:-http://localhost:3002}
+      DEFAULT_FROM_EMAIL: ${APP_MAIL_FROM:-noreply@familienarchiv.local}
+      EMAIL_URL: smtp://mailpit:1025
+      GLITCHTIP_MAX_EVENT_LIFE_DAYS: 90
+    ports:
+      - "127.0.0.1:${PORT_GLITCHTIP:-3002}:8080"
+    networks:
+      - archiv-net
+      - obs-net
+
+  obs-glitchtip-worker:
+    image: glitchtip/glitchtip:6.1.6
+    container_name: obs-glitchtip-worker
+    restart: unless-stopped
+    command: ./bin/run-celery-with-beat.sh
+    depends_on:
+      obs-redis:
+        condition: service_healthy
+    environment:
+      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@archive-db:5432/glitchtip
+      REDIS_URL: redis://obs-redis:6379/0
+      SECRET_KEY: ${GLITCHTIP_SECRET_KEY}
+    networks:
+      - archiv-net
+      - obs-net
+
+  obs-glitchtip-db-init:
+    image: postgres:16-alpine
+    container_name: obs-glitchtip-db-init
+    restart: "no"
+    environment:
+      PGPASSWORD: ${POSTGRES_PASSWORD}
+    command: >
+      sh -c "psql -h archive-db -U ${POSTGRES_USER} -tc
+      \"SELECT 1 FROM pg_database WHERE datname = 'glitchtip'\" |
+      grep -q 1 ||
+      psql -h archive-db -U ${POSTGRES_USER} -c \"CREATE DATABASE glitchtip;\""
+    networks:
+      - archiv-net
+
+networks:
+  # Shared network created by the main docker-compose.yml.
+  # The observability stack joins as a peer so Prometheus can scrape
+  # archive-backend by container name. The observability stack must NOT
+  # attempt to create this network — it will fail with a clear error if
+  # the main stack is not running yet.
+  archiv-net:
+    external: true
+
+  # Internal network for observability-service-to-service traffic
+  # (e.g. Grafana → Prometheus, Grafana → Loki, Grafana → Tempo).
+  obs-net:
+    driver: bridge
+
+volumes:
+  prometheus_data:
+  loki_data:
+  promtail_positions:
+  tempo_data:
+  grafana_data:
+  glitchtip_data:

docker-compose.prod.yml

@@ -39,6 +39,7 @@
 networks:
   archiv-net:
     driver: bridge
+    name: ${COMPOSE_NETWORK_NAME:-archiv-net}
 
 volumes:
   postgres-data:
@@ -212,10 +213,11 @@ services:
       APP_MAIL_FROM: ${APP_MAIL_FROM:-noreply@raddatz.cloud}
       SPRING_MAIL_PROPERTIES_MAIL_SMTP_AUTH: ${MAIL_SMTP_AUTH:-true}
       SPRING_MAIL_PROPERTIES_MAIL_SMTP_STARTTLS_ENABLE: ${MAIL_STARTTLS_ENABLE:-true}
+      OTEL_EXPORTER_OTLP_ENDPOINT: http://tempo:4317
     networks:
       - archiv-net
     healthcheck:
-      test: ["CMD-SHELL", "wget -qO- http://localhost:8080/actuator/health | grep -q UP || exit 1"]
+      test: ["CMD-SHELL", "wget -qO- http://localhost:8081/actuator/health | grep -q UP || exit 1"]
       interval: 15s
       timeout: 5s
       retries: 10

docker-compose.yml

@@ -147,8 +147,20 @@ services:
       SPRING_MAIL_PROPERTIES_MAIL_SMTP_STARTTLS_ENABLE: ${MAIL_STARTTLS_ENABLE:-false}
       APP_OCR_BASE_URL: http://ocr-service:8000
       APP_OCR_TRAINING_TOKEN: "${OCR_TRAINING_TOKEN:-}"
+      SENTRY_DSN: ${SENTRY_DSN:-}
+      SENTRY_TRACES_SAMPLE_RATE: ${SENTRY_TRACES_SAMPLE_RATE:-1.0}
+      # Observability: send traces to Tempo inside archiv-net (OTLP gRPC port 4317)
+      # Tempo is defined in docker-compose.observability.yml (future issue).
+      # OTLP failures are non-fatal — backend starts cleanly without the observability stack.
+      OTEL_EXPORTER_OTLP_ENDPOINT: http://tempo:4317
+      # 10% sampling in this compose (dev + staging) — override locally to 1.0 if needed
+      MANAGEMENT_TRACING_SAMPLING_PROBABILITY: "0.1"
     ports:
       - "${PORT_BACKEND}:8080"
+      # Management port — Prometheus scrapes /actuator/prometheus from inside archiv-net.
+      # Not exposed to the host; Docker service-name DNS (backend:8081) is sufficient.
+    expose:
+      - "8081"
     networks:
       - archiv-net
     healthcheck:

docs/ARCHITECTURE.md

@@ -63,7 +63,7 @@ Members of the cross-cutting layer have no entity of their own, no user-facing C
 | `audit` | Append-only event store (`audit_log`) for all domain mutations. Feeds the activity feed and Family Pulse dashboard. | Consumed by 5+ domains; no user-facing CRUD of its own |
 | `config` | Infrastructure bean definitions: `MinioConfig`, `AsyncConfig`, `WebConfig` | Framework infra; no business logic |
 | `dashboard` | Stats aggregation for the admin dashboard and Family Pulse widget | Aggregates from 3+ domains; no owned entities |
-| `exception` | `DomainException`, `ErrorCode` enum, `GlobalExceptionHandler` | Framework infra; consumed by every controller and service |
+| `exception` | `DomainException`, `ErrorCode` enum, `GlobalExceptionHandler` | Framework infra; consumed by every controller and service. Adding a new `ErrorCode` requires matching updates in `frontend/src/lib/shared/errors.ts` and all three `messages/*.json` locale files. |
 | `filestorage` | `FileService` — MinIO/S3 upload, download, presigned-URL generation | Generic service; consumed by `document` and `ocr` |
 | `importing` | `MassImportService` — async ODS/Excel batch import | Orchestrates across `person`, `tag`, `document` |
 | `security` | `SecurityConfig`, `Permission` enum, `@RequirePermission` annotation, `PermissionAspect` (AOP) | Framework infra; enforced globally across all controllers |

docs/DEPLOYMENT.md

@@ -43,6 +43,7 @@ graph TD
 - SSE notifications transit Caddy (browser → Caddy → backend); the backend is never reachable directly from the public internet. The SvelteKit SSR layer is bypassed for SSE, but Caddy is not.
 - The Caddyfile responds `404` on `/actuator/*` (defense in depth). Internal monitoring scrapes the backend on the docker network, not through Caddy.
 - Production and staging cohabit on the same host via docker compose project names: `archiv-production` (ports 8080/3000) and `archiv-staging` (ports 8081/3001).
+- An optional observability stack (Prometheus, Node Exporter, cAdvisor) runs as a separate compose file: `docker compose -f docker-compose.observability.yml up -d`. It joins `archiv-net` and scrapes the backend's management port (`:8081`). Configuration lives under `infra/observability/`.
 
 ### OCR memory requirements
 
@@ -106,6 +107,8 @@ All vars are set in `.env` at the repo root (copy from `.env.example`). The back
 | `MAIL_SMTP_AUTH` | SMTP auth enabled | `false` (dev) | YES (prod) | — |
 | `MAIL_STARTTLS_ENABLE` | STARTTLS enabled | `false` (dev) | YES (prod) | — |
 | `SPRING_PROFILES_ACTIVE` | Spring profile | `dev,e2e` (compose) | YES | — |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP gRPC endpoint for distributed traces (Tempo). Set to `http://tempo:4317` via compose. | `http://localhost:4317` | — | — |
+| `MANAGEMENT_TRACING_SAMPLING_PROBABILITY` | Micrometer tracing sample rate; overridden to `0.0` in test profile. | `0.1` (compose) / `1.0` (dev) | — | — |
 
 ### PostgreSQL container
 
@@ -134,6 +137,17 @@ All vars are set in `.env` at the repo root (copy from `.env.example`). The back
 | `BLLA_MODEL_PATH` | Kraken baseline layout analysis model path | `/app/models/blla.mlmodel` | — | — |
 | `OCR_MEM_LIMIT` | Container memory cap for ocr-service in `docker-compose.prod.yml`. Set to `6g` on CX32 hosts; leave unset on CX42+ to use the 12g default | `12g` (prod compose default) | — | — |
 
+### Observability stack (`docker-compose.observability.yml`)
+
+| Variable | Purpose | Default | Required? | Sensitive? |
+|---|---|---|---|---|
+| `PORT_PROMETHEUS` | Host port for the Prometheus UI (bound to `127.0.0.1` only) | `9090` | — | — |
+| `PORT_GRAFANA` | Host port for the Grafana UI (bound to `127.0.0.1` only) | `3001` | — | — |
+| `GRAFANA_ADMIN_PASSWORD` | Grafana `admin` user password | `changeme` | YES (prod) | YES |
+| `PORT_GLITCHTIP` | Host port for the GlitchTip UI (bound to `127.0.0.1` only) | `3002` | — | — |
+| `GLITCHTIP_DOMAIN` | Public-facing base URL for GlitchTip (used in email links and CORS) | `http://localhost:3002` | YES (prod) | — |
+| `GLITCHTIP_SECRET_KEY` | Django secret key for GlitchTip — generate with `python3 -c "import secrets; print(secrets.token_hex(32))"` | — | YES | YES |
+
 ---
 
 ## 3. Bootstrap from scratch
@@ -209,6 +223,9 @@ git.raddatz.cloud      A   <server IP>
 | `MAIL_PORT` | release.yml | typically `587` |
 | `MAIL_USERNAME` | release.yml | SMTP user |
 | `MAIL_PASSWORD` | release.yml | SMTP password |
+| `GRAFANA_ADMIN_PASSWORD` | both | Grafana `admin` login — generate a strong password |
+| `GLITCHTIP_SECRET_KEY` | both | Django secret key — `openssl rand -hex 32` |
+| `SENTRY_DSN` | both | GlitchTip project DSN — set after first-run (§4); leave empty to keep Sentry disabled |
 
 ### 3.4 First deploy
 
@@ -256,9 +273,99 @@ docker compose logs --tail=200 <service>
 - **Spring Actuator health**: `http://localhost:8080/actuator/health` (internal only in prod — port 8081 for Prometheus scraping)
 - **Prometheus scraping**: management port 8081, path `/actuator/prometheus`. Internal only; Caddy blocks `/actuator/*` externally.
 
-### Future observability
+### Observability stack
 
-Phase 7 of the Production v1 milestone adds Prometheus + Loki + Grafana. No monitoring infrastructure is in place yet.
+An observability stack is available via `docker-compose.observability.yml`. Configuration lives under `infra/observability/`. Start it after the main stack is up (which creates `archiv-net`):
+
+```bash
+docker compose up -d                                    # creates archiv-net
+docker compose -f docker-compose.observability.yml up -d
+```
+
+Current services:
+
+| Service | Image | Purpose |
+|---|---|---|
+| `obs-prometheus` | `prom/prometheus:v3.4.0` | Scrapes metrics from backend management port 8081 (`/actuator/prometheus`), node-exporter, and cAdvisor |
+| `obs-node-exporter` | `prom/node-exporter:v1.9.0` | Host-level CPU / memory / disk / network metrics |
+| `obs-cadvisor` | `gcr.io/cadvisor/cadvisor:v0.52.1` | Per-container resource metrics |
+| `obs-loki` | `grafana/loki:3.4.2` | Log aggregation — receives log streams from Promtail. Port 3100 is `expose`-only (not host-bound). |
+| `obs-promtail` | `grafana/promtail:3.4.2` | Log shipping agent — reads all Docker container logs via the Docker socket and forwards them to Loki with `container_name`, `compose_service`, and `compose_project` labels |
+| `obs-tempo` | `grafana/tempo:2.7.2` | Distributed trace storage — OTLP gRPC receiver on port 4317, OTLP HTTP on port 4318 (both `archiv-net`-internal). Grafana queries traces on port 3200 (`obs-net`-internal). All ports are `expose`-only (not host-bound). |
+| `obs-grafana` | `grafana/grafana-oss:11.6.1` | Unified observability UI — metrics dashboards, log exploration, trace viewer. Bound to `127.0.0.1:${PORT_GRAFANA:-3001}` on the host. |
+| `obs-glitchtip` | `glitchtip/glitchtip:v4` | Sentry-compatible error tracker. Receives frontend + backend error events, groups by fingerprint, provides issue UI with stack traces. Bound to `127.0.0.1:${PORT_GLITCHTIP:-3002}`. |
+| `obs-glitchtip-worker` | `glitchtip/glitchtip:v4` | Celery + beat worker — processes async GlitchTip tasks (event ingestion, notifications, cleanup). |
+| `obs-redis` | `redis:7-alpine` | Celery task broker for GlitchTip. Internal to `obs-net`; no host port exposed. |
+| `obs-glitchtip-db-init` | `postgres:16-alpine` | One-shot init container. Creates the `glitchtip` database on the existing `archive-db` PostgreSQL instance if it does not already exist. Runs at stack startup; exits cleanly once done. |
+
+#### Grafana
+
+| Item | Value |
+|---|---|
+| URL | `http://localhost:3001` (or `http://localhost:$PORT_GRAFANA`) |
+| Username | `admin` |
+| Password | `$GRAFANA_ADMIN_PASSWORD` (default: `changeme` — **change before exposing to a network**) |
+
+Datasources are auto-provisioned on first start (Prometheus, Loki, Tempo — no manual setup required). Three dashboards are pre-loaded:
+
+| Dashboard | Grafana ID | Purpose |
+|---|---|---|
+| Node Exporter Full | 1860 | Host CPU, memory, disk, network |
+| Spring Boot Observability | 17175 | JVM metrics, HTTP latency, error rate |
+| Loki Logs | 13639 | Log exploration and filtering |
+
+Tempo traces are accessible via Grafana Explore → Tempo datasource, and linked from Loki logs via the `traceId` derived field.
+
+**Loki quick checks** (after ~60 s, run from inside the `obs-loki` container):
+
+```bash
+# Loki health
+docker exec obs-loki wget -qO- http://localhost:3100/ready
+
+# List labels
+docker exec obs-loki wget -qO- 'http://localhost:3100/loki/api/v1/labels'
+
+# Query logs by service (stable across dev and prod environments)
+docker exec obs-loki wget -qO- \
+  'http://localhost:3100/loki/api/v1/query_range?query=%7Bcompose_service%3D%22backend%22%7D&limit=5'
+```
+
+**Prefer `compose_service` over `container_name` in LogQL queries** — `container_name` differs between dev (`archive-backend`) and prod (`archiv-production-backend-1`), while `compose_service` is stable (`backend`, `db`, `minio`, etc.).
+
+Prometheus port `9090` and Grafana port `3001` are bound to `127.0.0.1` on the host. No other observability ports are host-bound.
+
+#### GlitchTip
+
+| Item | Value |
+|---|---|
+| URL | `http://localhost:3002` (or `http://localhost:$PORT_GLITCHTIP`) |
+
+**Required env vars** — set in `.env` before first start:
+
+```bash
+GLITCHTIP_SECRET_KEY=$(python3 -c "import secrets; print(secrets.token_hex(32))")
+GLITCHTIP_DOMAIN=http://localhost:3002   # change to your public URL in prod
+PORT_GLITCHTIP=3002                      # optional, defaults to 3002
+```
+
+**Database:** GlitchTip shares the existing `archive-db` PostgreSQL instance. The `obs-glitchtip-db-init` one-shot container creates a dedicated `glitchtip` database on first stack start — no manual step required.
+
+**First-run steps** (one-time, after `docker compose -f docker-compose.observability.yml up -d`):
+
+```bash
+# 1. Create the Django superuser (interactive)
+docker exec -it obs-glitchtip ./manage.py createsuperuser
+
+# 2. Open the GlitchTip UI and log in
+open http://localhost:3002
+
+# 3. Create an organisation (e.g. "Familienarchiv")
+# 4. Create two projects:
+#    - "familienarchiv-frontend"  (platform: JavaScript / SvelteKit)
+#    - "familienarchiv-backend"   (platform: Java / Spring Boot)
+# 5. Copy each project's DSN from Settings → Projects → <project> → Client Keys
+# 6. Wire the DSNs into the backend and frontend via env vars (separate issue)
+```
 
 ---
 

docs/adr/012-browser-test-mocking-strategy.md

@@ -0,0 +1,134 @@
+# ADR 012 — Browser-Mode Test Mocking Strategy
+
+**Status:** Accepted  
+**Date:** 2026-05-11 (revised 2026-05-12)  
+**Issues:** [#535 — original incident](https://git.raddatz.cloud/marcel/familienarchiv/issues/535) · [#553 — revision](https://git.raddatz.cloud/marcel/familienarchiv/issues/553)
+
+---
+
+## Context
+
+Vitest browser-mode tests (the `client` project, run with `@vitest/browser-playwright` / Chromium) use a different module resolution path than Node-environment tests. When a spec calls `vi.mock('some-module', factory)`, vitest registers a `ManualMockedModule`. At runtime, every time Chromium requests that module, a playwright route handler intercepts the request and calls the Node worker over **birpc** (`resolveManualMock`) to evaluate the factory and return the module body.
+
+This is safe for modules that are imported **statically** at spec module-eval time (e.g. `$app/navigation`, `$env/static/public`): those requests resolve before the first test runs and well before any teardown occurs.
+
+It is **unsafe** for modules that are imported **dynamically** (e.g. inside an `async onMount`, inside a lazy-loaded chunk): Chromium may fetch the module after the worker's birpc channel has already closed, producing:
+
+```
+Error: [birpc] rpc is closed, cannot call "resolveManualMock"
+  ❯ ManualMockedModule.factory   node_modules/@vitest/browser/dist/index.js:3221:34
+```
+
+This raises an unhandled rejection that exits the vitest process with code 1, even though every test in the run reported green.
+
+`pdfjs-dist` and `pdfjs-dist/build/pdf.worker.min.mjs?url` are loaded via `await Promise.all([import('pdfjs-dist'), import('pdfjs-dist/build/pdf.worker.min.mjs?url')])` inside `usePdfRenderer.svelte.ts::init()`, which is called from `onMount`. These dynamic imports triggered the race.
+
+---
+
+## Decision
+
+**Prefer prop injection over `vi.mock(module, factory)` for any module that is loaded dynamically in browser-mode specs.**
+
+### The libLoader pattern (for external rendering libraries)
+
+When a component depends on a large external library loaded via dynamic import, extract the import into an injectable loader function with a production default:
+
+```typescript
+// usePdfRenderer.svelte.ts
+type LibLoader = () => Promise<readonly [typeof import('pdfjs-dist'), { default: string }]>;
+
+const defaultLibLoader: LibLoader = () =>
+  Promise.all([import('pdfjs-dist'), import('pdfjs-dist/build/pdf.worker.min.mjs?url')]);
+
+export function createPdfRenderer(libLoader: LibLoader = defaultLibLoader) { ... }
+```
+
+The component threads the loader as an optional prop:
+
+```svelte
+<!-- PdfViewer.svelte -->
+let { url, ..., libLoader = undefined } = $props();
+const renderer = untrack(() => createPdfRenderer(libLoader));
+```
+
+Tests supply a synchronous fake — no `vi.mock` needed:
+
+```typescript
+const fakePdfjs = { GlobalWorkerOptions: ..., getDocument: vi.fn(), TextLayer: class {} };
+const fakeLoader = vi.fn().mockResolvedValue([fakePdfjs, { default: '' }] as const);
+render(PdfViewer, { url: '...', libLoader: fakeLoader });
+```
+
+### The test-host pattern (for component behaviour)
+
+For components that fetch data or call services, the `*.test-host.svelte` pattern threads the dependency as a prop rather than mocking the module. See `PersonMentionEditor.test-host.svelte` for the canonical example.
+
+---
+
+## Binding invariant: factory bodies must be synchronous (#553)
+
+The original revision of this ADR allowed `vi.mock(virtualModule, factory)` for SvelteKit/Vite virtual modules on the argument that their consumer imports were resolved at static-import time. **That reasoning is wrong.** What matters is what the **factory body** does, not where the mocked module is consumed.
+
+`EnrichmentBlock.svelte.spec.ts` (issue #553) was statically imported and still produced the race: its `vi.mock('$app/stores', async () => { const mod = await import(...); return mod; })` factory performed a dynamic import in its body, and that body was invoked asynchronously when Chromium fetched the manually-mocked module — sometimes after the worker's birpc channel had already closed.
+
+**Therefore: under `**/*.svelte.{test,spec}.ts`, every `vi.mock` factory body must be synchronous. No `await`, no `import(...)`.**
+
+If a factory needs to share state with the spec (a mutable ref, a `vi.fn`, a writable store), use `vi.hoisted()` to lift the reference above `vi.mock`'s implicit hoist:
+
+```ts
+const { mockNavigating } = vi.hoisted(() => ({
+    mockNavigating: { type: null as string | null }
+}));
+
+vi.mock('$app/state', () => ({
+    get navigating() {
+        return mockNavigating;
+    }
+}));
+```
+
+The getter defers the read until consumption time; `vi.hoisted` guarantees the reference is initialised before the (also hoisted) `vi.mock` factory runs. See `DropZone.svelte.spec.ts:9`, `NotificationBell.svelte.spec.ts:6-10`, and `EnrichmentBlock.svelte.spec.ts` for canonical examples.
+
+### Architectural follow-on: prefer `$app/state` over `$app/stores`
+
+`$app/stores` is the deprecated subscription-based store API; `$app/state` is the modern reactive proxy. New components should import from `$app/state`. As part of #553 we migrated `EnrichmentBlock.svelte` from `$app/stores.navigating` to `$app/state.navigating` with `!!navigating.type` — matching the pattern already established in `routes/aktivitaeten/+page.svelte:117` and `routes/documents/+page.svelte:261`. Migration eliminated the *need* to mock a store at all in that spec.
+
+**Pattern note:** When an overlay or dropdown triggers a navigation action, use `<button type="button">` with an `onclick` handler that calls `goto(path)` — do **not** use `<a href="…">` with `e.preventDefault()`. SvelteKit registers its link interceptor as a capture-phase `document` listener, so it fires before the component's bubble-phase `onclick`. By the time `e.preventDefault()` runs the router has already initiated navigation, which tears down the vitest-browser Playwright orchestrator iframe. A `<button>` carries no `href`, so the capture-phase interceptor never fires. See `NotificationDropdown.svelte` for the canonical example.
+
+**Pattern note (#553):** Browser-mode tests run with `data-sveltekit-preload-data="off"` (set in `src/test-setup.ts` via the client project's `setupFiles`). Hover-prefetch otherwise fires real fetch requests for route loader chunks; those requests go through the same Playwright route handler that serves mocked modules. An in-flight prefetch landing after iframe teardown can hit the handler with a closed birpc channel, raising an unhandled rejection.
+
+---
+
+## Binding invariant: one canonical ID per mocked module (#553 — duplicate-id hazard)
+
+The sync-factory invariant above closes one named trigger of the `[birpc] rpc is closed` race. Investigation of a follow-up flake revealed a second, independent trigger: **the same resolved module URL mocked under two distinct ID strings** across or within spec files.
+
+`@vitest/browser-playwright` registers a Playwright `page.context().route(...)` handler per `vi.mock` call. The predicate matches on the module's resolved URL. When two `vi.mock` calls reference the same module under different IDs — for example `'$lib/foo.svelte'` and `'$lib/foo.svelte.js'` (both resolve to the same Svelte rune-module URL) — the registry stores both predicates but the cleanup map only tracks the latest. The orphan route survives session teardown. When the next session loads the same module, the orphan fires, calls `await module.resolve()` against a closed birpc channel, and crashes the run.
+
+This is fixed upstream in [vitest PR #10267](https://github.com/vitest-dev/vitest/pull/10267) (issue [#9957](https://github.com/vitest-dev/vitest/issues/9957)). Until that fix reaches a published `@vitest/browser-playwright` release, we close the gap from two sides:
+
+**The rule.** Every mocked module must be referenced under exactly one ID string across the entire client test suite. Pick the spelling production code uses. For Svelte 5 rune modules (`*.svelte.ts`), the canonical form is the no-extension import (`'$lib/foo.svelte'`) — matches the source file basename and matches Svelte 5 convention. Never mix `.svelte.js` and `.svelte` for the same module across specs.
+
+**Enforcement layers** (added in #553's second cycle, extending the four-layer chain above):
+
+5. **In-suite meta-test** at `frontend/src/__meta__/no-duplicate-mock-ids.test.ts` globs `src/**/*.svelte.{test,spec}.ts`, extracts every `vi.mock` first-arg string, canonicalises by stripping a trailing `.js`/`.ts` after `.svelte`, and fails if any canonical ID is referenced under two or more distinct spellings. Same shape as `no-async-mock-factories.test.ts`.
+6. **`patch-package` backport** of PR #10267 at `frontend/patches/@vitest+browser-playwright+4.1.0.patch`. Applied automatically by the `postinstall` hook. Closes the race at the route-handler level — even if a contributor reintroduces a duplicate-ID, the patched `register` handler unroutes the existing predicate before installing the new one.
+
+**When to remove the patch.** Once `@vitest/browser-playwright` ships a release containing PR #10267, delete `patches/@vitest+browser-playwright+4.1.0.patch`. Bump the dependency to the version containing the fix. The in-suite meta-test stays — it's a cheap permanent guard against the contributor-facing pattern, independent of upstream library version.
+
+---
+
+## Consequences
+
+- New browser-mode specs that need to stub an external library **must not** use `vi.mock(externalLib, factory)`. Add a loader/factory parameter to the underlying hook or service instead.
+- The CI `unit-tests` job includes a permanent grep guard that fails the build if `rpc is closed` appears in any coverage run log. This catches regressions before they reach the acceptance criterion.
+- Acceptance criterion for #535: 60 consecutive green `workflow_dispatch` CI runs against `main` after the fix is merged, with zero `rpc is closed` lines in any log.
+- **Enforcement (six layers, defence in depth):**
+  1. **ESLint `no-restricted-syntax`** in `eslint.config.js` (scoped to `**/*.{spec,test}.ts`) flags two patterns: (a) the literal `vi.mock('pdfjs-dist', ...)` — enforces the libLoader pattern — and (b) any `vi.mock(..., async () => { ... await import(...) ... })` — enforces the synchronous-factory invariant. Both messages point at this ADR. Failure surfaces at save time.
+  2. **CI grep guard** in `.gitea/workflows/ci.yml` runs before the test suite launches. Mirrors the ESLint patterns with `grep -Pzn`. ~10s round-trip.
+  3. **In-suite meta-test** at `frontend/src/__meta__/no-async-mock-factories.test.ts` globs `src/**/*.svelte.{test,spec}.ts` and asserts none match the banned pattern. Catches at every vitest invocation — the layer hardest to disable.
+  4. **CI birpc assert** runs after the coverage step and fails the build if `[birpc] rpc is closed` appears in any log line. Catches the symptom even if all the upstream layers were bypassed.
+  5. **In-suite duplicate-ID meta-test** at `frontend/src/__meta__/no-duplicate-mock-ids.test.ts` enforces the one-canonical-ID-per-module rule from the duplicate-id-hazard section above.
+  6. **`patch-package` backport** at `frontend/patches/@vitest+browser-playwright+4.1.0.patch` closes the upstream race itself, applied via `postinstall`. To be removed when `@vitest/browser-playwright` releases [vitest PR #10267](https://github.com/vitest-dev/vitest/pull/10267).
+- **Acceptance verification:** `coverage-flake-probe.yml` is a `workflow_dispatch`-triggered matrix workflow that runs the coverage suite 20× in parallel against a single SHA and asserts zero birpc lines. One fire, parallel cost, deterministic signal — replaces accumulating 20 sequential push events.
+- **When to revisit the LibLoader home:** If three or more components adopt this pattern, consider extracting a shared `$lib/types/lib-loader.ts` or a generic `DynamicImportLoader<T>` type to avoid parallel type definitions across modules.

docs/adr/013-client-branches-coverage-threshold.md

@@ -0,0 +1,92 @@
+# ADR 013 — Client-Project Branch Coverage Threshold
+
+**Status:** Accepted  
+**Date:** 2026-05-14  
+**Issues:** [#556 — threshold drop](https://git.raddatz.cloud/marcel/familienarchiv/issues/556) · [#496 — long-tail-grind tracking](https://git.raddatz.cloud/marcel/familienarchiv/issues/496)
+
+---
+
+## Context
+
+The browser-mode component test suite (`vitest.client-coverage.config.ts`) enforces Istanbul coverage thresholds across `lines`, `functions`, `branches`, and `statements`. The `branches` metric was set to 80%, but the codebase sits at **75%** — below the gate — causing every CI run of `unit-tests` and `coverage-flake-probe` to fail on this check alone, even when all tests are green.
+
+**Measured baseline (2026-05-14, branch `feat/issue-553-birpc-async-mock-factory`, head `2e6cc346`):**
+
+```
+branches:   75%  (below the 80% gate — reason for this ADR)
+lines:      ≥ 80%
+functions:  ≥ 80%
+statements: ≥ 80%
+```
+
+Reproducer:
+
+```bash
+cd frontend && npm ci && npx vitest run -c vitest.client-coverage.config.ts --coverage
+```
+
+### The long-tail-grind problem
+
+In Istanbul's branch accounting, when a child component gains test coverage its branches are added to the parent's denominator. A child moving from 40% → 80% coverage can drag a parent from 78% → 72% because more branches in the call graph become reachable and must be covered. This is not a bug — it is how branch accounting works — but it means that on a large SvelteKit application the denominator grows with every coverage improvement, making an arbitrary 80% ceiling a constant grind. Per #496, the expected cost to reach 80% branches from 75% is 30–100+ commits with no guarantee of stability.
+
+### Why this layer is different
+
+The 80% branch floor used for backend unit/integration tests is appropriate for Java service code and permission logic. Browser-mode component coverage measures Svelte template branches: conditional class bindings, `{#if}` blocks, empty/loaded/error state guards. These branches have a fundamentally different accounting model and a higher inherent denominator. This ADR **only** lowers the browser-mode component gate; the backend test coverage gates are unaffected.
+
+### Security-relevant uncovered components
+
+The following auth/permission-boundary components currently have low or zero branch coverage. When ratchet-up work begins (see below), these are the highest-priority targets:
+
+- `src/routes/login/+page.svelte`
+- `src/routes/forgot-password/+page.svelte`
+- `src/routes/reset-password/+page.svelte`
+- `src/routes/register/+page.svelte`
+
+Note: the 75% figure already reflects the absence of coverage on these files. Lowering the gate does not create this gap — it makes the existing state legible.
+
+---
+
+## Decision
+
+Drop the `branches` threshold from `80` → `75` in `frontend/vitest.client-coverage.config.ts`. Leave `lines`, `functions`, and `statements` at `80`.
+
+The 75% figure matches the measured current state, allowing CI to pass while deliberate coverage improvement work (tracked in #496) continues without blocking other PRs. The asymmetry in the thresholds block is intentional and documented with an inline comment pointing here.
+
+---
+
+## Ratchet Rule
+
+The branches threshold ratchets **up by 3 percentage points** when the rolling 3-PR-average client-project branches figure on `main` stays at or above `threshold + 3pp` for ≥ 30 consecutive days. Direction is **up-only** — never lower the floor below 75 without a new ADR superseding this one. Manual today (verify before any `vitest.client-coverage.config.ts` edit); a future automation issue may codify the check.
+
+Concretely:
+- When `main` sustains ≥ 78% branches across 3 consecutive PRs for 30 days → raise gate to 78%
+- When `main` sustains ≥ 81% branches across 3 consecutive PRs for 30 days → raise gate back to 80%
+
+---
+
+## Non-goals
+
+- **Not** raising actual branch coverage — that is #496's job, tracked separately.
+- **Not** touching the server-project coverage configuration (`vitest.config.ts`) — only the client project hits the long-tail-grind pattern.
+- **Not** removing or relaxing any existing test files, `skipIf` guards, or axe-playwright accessibility runs.
+
+---
+
+## Consequences
+
+**Easier:**
+- CI unblocked — `unit-tests` and `coverage-flake-probe` jobs pass when all tests are green
+- The ratchet rule creates a concrete, observable path back to 80%
+
+**Harder:**
+- The gate now has near-zero headroom — any branch regression that drops below 75% will fail CI immediately
+- The 75% floor must not be treated as a permanent ceiling; the ratchet discipline requires active attention
+
+---
+
+## References
+
+- [#496 — Branch coverage long-tail grind](https://git.raddatz.cloud/marcel/familienarchiv/issues/496)
+- [#556 — This threshold drop](https://git.raddatz.cloud/marcel/familienarchiv/issues/556)
+- [ADR 012 — Browser-Mode Test Mocking Strategy](./012-browser-test-mocking-strategy.md)
+- `frontend/vitest.client-coverage.config.ts` — thresholds block (lines 44–51)

docs/adr/014-upload-artifact-v3-pin.md

@@ -0,0 +1,122 @@
+# ADR 014 — Pin actions/upload-artifact to v3 (Gitea act_runner v4 protocol incompatibility)
+
+**Status:** Accepted  
+**Date:** 2026-05-14  
+**Issues:** [#557 — re-regression](https://git.raddatz.cloud/marcel/familienarchiv/issues/557) · [#14 — original incident](https://git.raddatz.cloud/marcel/familienarchiv/issues/14)
+
+---
+
+## Context
+
+`actions/upload-artifact` is available in two incompatible major versions. The v4 client
+uploads via a GitHub-specific artifact API that is **not implemented** in Gitea's
+`act_runner` (the self-hosted CI substrate established by ADR-011). When a workflow step
+uses `actions/upload-artifact@v4` on this runner, `act_runner` returns a non-zero exit
+code from the v4 client even when all tests pass, producing:
+
+> green test suite — red job status — no artifact uploaded
+
+The failure lands in the upload step, _after_ the test output, making it hard to diagnose
+from the build log.
+
+### Incident history
+
+| Date | Commit | Event |
+|---|---|---|
+| 2026-03-19 | `9f3f022e` | Original downgrade: `upload-artifact@v4 → v3` |
+| 2026-03-19 | `4142c7cd` | Rationale committed; closes #14 |
+| 2026-05-05 | `410b91e2` | Re-regression: upgraded back to v4 without referencing #14 |
+| 2026-05-14 | this PR | Second downgrade + ADR + grep guard |
+
+The root cause of the re-regression was institutional-memory failure: the original
+rationale was captured only in a commit body, invisible at the point of change (the
+`uses:` line). This ADR, the inline comments, and the grep guard are the three
+defence layers that replace that missing breadcrumb.
+
+---
+
+## Decision
+
+**Pin all `actions/upload-artifact` and `actions/download-artifact` call sites to `@v3`.**
+
+Both action families share the same v4 protocol incompatibility with `act_runner`.
+Pinning to the major tag (`@v3`) keeps us on the latest v3 patch without Renovate noise.
+
+Three call sites are pinned:
+- `.gitea/workflows/ci.yml` — "Upload coverage reports" step
+- `.gitea/workflows/ci.yml` — "Upload screenshots" step
+- `.gitea/workflows/coverage-flake-probe.yml` — "Upload coverage log on failure" step
+
+Each pinned `uses:` line carries a load-bearing inline comment:
+
+```yaml
+# Gitea Actions (act_runner) does not implement upload-artifact v4 protocol — pinned per ADR-014. Do NOT upgrade. See #557.
+- uses: actions/upload-artifact@v3
+```
+
+A CI grep guard enforces the constraint automatically (see below).
+
+---
+
+## Consequences
+
+### Enforcement layers (defence in depth)
+
+1. **Inline comments** on every `uses:` line — visible at the point of change.
+2. **CI grep guard** in `.gitea/workflows/ci.yml` ("Assert no (upload|download)-artifact
+   past v3") — fails the build if a future commit re-introduces `@v4` or higher on any
+   workflow file. Anchored to YAML `uses:` lines to avoid false positives on embedded
+   shell strings. Includes a self-test that proves the regex catches v4+ before scanning
+   the repo.
+3. **This ADR** — canonical rationale; cross-referenced by comments and guard message.
+
+### How to spot the symptom
+
+- Test suite output shows green (vitest, surefire, pytest all exit 0)
+- CI job status shows red
+- Artifacts section of the run is empty
+- Build log shows a non-zero exit from the `Upload …` step immediately after green tests
+
+### `@v3` maintenance-mode status
+
+GitHub placed `actions/upload-artifact@v3` in maintenance mode (no new features) but it
+has not been removed and carries no known unpatched CVE as of this writing. If GitHub
+publishes a v3-specific security advisory, that is an additional trigger to re-evaluate
+(see upgrade conditions below).
+
+### When to remove this pin
+
+Re-evaluate pinning **when either condition is met:**
+
+1. `gitea/act_runner` ships a release with v4 artifact protocol support. Track upstream:
+   <https://gitea.com/gitea/act_runner>
+2. `actions/upload-artifact@v3` acquires an unpatched CVE that cannot be mitigated
+   at the runner level.
+
+When upgrading: remove the grep guard step, update all three `uses:` lines, remove the
+inline comments, and update this ADR's status to Superseded.
+
+---
+
+## Alternatives
+
+### SHA pinning (`uses: actions/upload-artifact@<sha>`)
+
+More secure against action repository compromise, but adds Renovate update friction
+and is disproportionate for a self-hosted, single-tenant Gitea instance with one
+trusted contributor (ADR-011). Rejected.
+
+### Minor/patch pinning (`@v3.4.0`)
+
+Avoids Renovate PRs but freezes us on a specific patch. The v3 major track is in
+maintenance mode — minor pinning has no benefit and would require manual updates
+for any v3 security patches. Rejected.
+
+### Renovate `packageRules` bypass
+
+Would prevent automated PRs from proposing v4. Not needed while Renovate is not
+configured for this repository. Revisit if Renovate is introduced.
+
+### Migrating the runner to a v4-compatible Gitea release
+
+Out of scope for this issue. A separate decision; tracked in #557's non-goals.

docs/architecture/c4/l2-containers.puml

@@ -17,6 +17,19 @@ System_Boundary(archiv, "Familienarchiv (Docker Compose)") {
     Container(mc, "Bucket / Service-Account Init", "MinIO Client (mc)", "One-shot container on startup. Idempotent: creates the archive bucket, the archiv-app service account, and attaches the readwrite policy.")
 }
 
+System_Boundary(observability, "Observability Stack (docker-compose.observability.yml)") {
+    Container(prometheus, "Prometheus", "prom/prometheus:v3.4.0", "Scrapes metrics from backend management port 8081 (/actuator/prometheus), node-exporter, and cAdvisor. Retention: 30 days.")
+    Container(node_exporter, "Node Exporter", "prom/node-exporter:v1.9.0", "Host-level CPU, memory, disk, and network metrics.")
+    Container(cadvisor, "cAdvisor", "gcr.io/cadvisor/cadvisor:v0.52.1", "Per-container resource metrics.")
+    Container(loki, "Loki", "grafana/loki:3.4.2", "Stores log streams from all containers.")
+    Container(promtail, "Promtail", "grafana/promtail:3.4.2", "Ships Docker container logs to Loki via Docker SD.")
+    Container(tempo, "Tempo", "grafana/tempo:2.7.2", "Distributed trace storage. OTLP gRPC receiver on port 4317 (archiv-net). Grafana queries traces on port 3200 (obs-net). All ports internal only.")
+    Container(grafana, "Grafana", "grafana/grafana-oss:11.6.1", "Unified observability UI — dashboards, logs, traces. Datasources (Prometheus, Loki, Tempo) and three dashboards are auto-provisioned.")
+    Container(glitchtip, "GlitchTip", "glitchtip/glitchtip:v4", "Sentry-compatible error tracker — web process. Receives frontend + backend error events, groups by fingerprint, provides issue UI with stack traces.")
+    Container(obs_glitchtip_worker, "GlitchTip Worker", "glitchtip/glitchtip:v4", "Celery + beat worker — async event ingestion, notifications, cleanup.")
+    Container(obs_redis, "Redis", "redis:7-alpine", "Celery task queue for GlitchTip async workers.")
+}
+
 Rel(user, caddy, "HTTPS", "TLS 1.2/1.3")
 Rel(caddy, frontend, "Reverse proxies non-/api requests", "HTTP / loopback:3000")
 Rel(caddy, backend, "Reverse proxies /api/*", "HTTP / loopback:8080")
@@ -28,5 +41,12 @@ Rel(backend, ocr, "OCR job requests with presigned MinIO URL", "HTTP / REST / JS
 Rel(backend, mail, "Sends notification and password-reset emails (optional)", "SMTP")
 Rel(ocr, storage, "Fetches PDF via presigned URL", "HTTP / S3 presigned")
 Rel(mc, storage, "Bootstraps bucket + service account on startup", "MinIO Client CLI")
+Rel(promtail, loki, "Pushes log streams", "HTTP/Loki push API")
+Rel(backend, tempo, "Sends distributed traces via OTLP", "gRPC / OTLP / port 4317 (archiv-net)")
+Rel(grafana, prometheus, "Queries metrics", "HTTP 9090")
+Rel(grafana, loki, "Queries logs", "HTTP 3100")
+Rel(grafana, tempo, "Queries traces", "HTTP 3200")
+Rel(glitchtip, db, "Stores error events in glitchtip DB", "PostgreSQL / archiv-net")
+Rel(obs_glitchtip_worker, obs_redis, "Processes Celery tasks", "Redis / obs-net")
 
 @enduml

docs/infrastructure/ci-gitea.md

@@ -200,7 +200,7 @@ jobs:
         working-directory: frontend
       - name: Upload screenshots
         if: always()
-        uses: actions/upload-artifact@v4   # ← upgraded from v3
+        uses: actions/upload-artifact@v3  # pinned per ADR-014 — Gitea Actions does not implement v4 protocol. Do NOT upgrade.
         with:
           name: unit-test-screenshots
           path: frontend/test-results/screenshots/
@@ -227,7 +227,7 @@ jobs:
         working-directory: backend
       - name: Upload test results
         if: always()
-        uses: actions/upload-artifact@v4   # ← upgraded from v3
+        uses: actions/upload-artifact@v3  # pinned per ADR-014 — Gitea Actions does not implement v4 protocol. Do NOT upgrade.
         with:
           name: backend-test-results
           path: backend/target/surefire-reports/
@@ -329,7 +329,7 @@ jobs:
           E2E_BACKEND_URL: http://localhost:8080
       - name: Upload E2E results
         if: always()
-        uses: actions/upload-artifact@v4   # ← upgraded from v3
+        uses: actions/upload-artifact@v3  # pinned per ADR-014 — Gitea Actions does not implement v4 protocol. Do NOT upgrade.
         with:
           name: e2e-results
           path: frontend/test-results/e2e/

frontend/CLAUDE.md

@@ -165,7 +165,7 @@ npm run check       # svelte-check (type checking)
 
 ```bash
 npm run test              # Vitest unit + server tests (headless)
-npm run test:coverage     # Coverage report (server project only)
+npm run test:coverage     # Coverage report (server + client)
 npm run test:e2e          # Playwright E2E tests
 npm run test:e2e:headed   # Playwright E2E with visible browser
 npm run test:e2e:ui       # Playwright UI mode

frontend/Dockerfile

@@ -29,6 +29,6 @@ ENV NODE_ENV=production
 COPY --from=build /app/build ./build
 COPY --from=build /app/package.json ./package.json
 COPY --from=build /app/package-lock.json ./package-lock.json
-RUN npm ci --omit=dev
+RUN npm ci --omit=dev --ignore-scripts
 EXPOSE 3000
 CMD ["node", "build"]

frontend/eslint.config.js

@@ -72,6 +72,31 @@ export default defineConfig(
 			]
 		}
 	},
+	{
+		files: ['**/*.spec.ts', '**/*.test.ts'],
+		rules: {
+			'no-restricted-syntax': [
+				'error',
+				{
+					selector:
+						"CallExpression[callee.object.name='vi'][callee.property.name='mock'] > Literal[value=/^pdfjs-dist/]",
+					message:
+						"Banned: vi.mock('pdfjs-dist', factory) causes a birpc teardown race in browser-mode specs — see ADR 012. Use the libLoader prop injection pattern instead."
+				},
+				{
+					// ADR 012 / #553. The named mechanism: an async vi.mock factory whose
+					// body performs `await import(...)` produces a late birpc roundtrip
+					// during worker teardown. The factory body must be synchronous; if
+					// you need to share state between the spec and the mock, use
+					// `vi.hoisted` (see DropZone.svelte.spec.ts).
+					selector:
+						"CallExpression[callee.object.name='vi'][callee.property.name='mock'][arguments.1.type='ArrowFunctionExpression'][arguments.1.async=true]:has(AwaitExpression > ImportExpression)",
+					message:
+						'Banned: vi.mock(..., async () => { await import(...) }) causes a birpc teardown race in browser-mode specs — see ADR 012. Use a synchronous factory + vi.hoisted instead.'
+				}
+			]
+		}
+	},
 	{
 		plugins: { boundaries },
 		settings: {

frontend/messages/de.json

@@ -345,8 +345,11 @@
 	"admin_system_import_btn_retry": "Erneut starten",
 	"admin_system_import_status_idle": "Kein Import gestartet.",
 	"admin_system_import_status_running": "Import läuft…",
-	"admin_system_import_status_done": "Import abgeschlossen – {count} Dokumente verarbeitet.",
-	"admin_system_import_status_failed": "Fehler: {message}",
+	"admin_system_import_status_done": "Import abgeschlossen",
+	"admin_system_import_status_done_label": "Dokumente verarbeitet",
+	"admin_system_import_status_failed": "Import fehlgeschlagen",
+	"admin_system_import_failed_no_spreadsheet": "Keine Tabellendatei gefunden.",
+	"admin_system_import_failed_internal": "Interner Fehler beim Import.",
 	"admin_system_thumbnails_heading": "Thumbnails erzeugen",
 	"admin_system_thumbnails_description": "Erzeugt Vorschaubilder für Dokumente ohne Thumbnail (z. B. nach dem Massenimport).",
 	"admin_system_thumbnails_btn_start": "Thumbnails erzeugen",
@@ -703,6 +706,8 @@
 	"error_invite_exhausted": "Dieser Einladungslink wurde bereits vollständig verwendet.",
 	"error_invite_revoked": "Dieser Einladungslink wurde deaktiviert.",
 	"error_invite_expired": "Dieser Einladungslink ist abgelaufen.",
+	"error_group_has_active_invites": "Diese Gruppe kann nicht gelöscht werden, da sie in einer aktiven Einladung verwendet wird.",
+	"error_group_not_found": "Die angegebene Gruppe existiert nicht.",
 	"register_heading": "Konto erstellen",
 	"register_subtext": "Du wurdest eingeladen, dem Familienarchiv beizutreten.",
 	"register_label_first_name": "Vorname",
@@ -762,6 +767,9 @@
 	"admin_new_invite_prefill_last": "Nachname vorausfüllen (optional)",
 	"admin_new_invite_prefill_email": "E-Mail vorausfüllen (optional)",
 	"admin_new_invite_expires": "Ablaufdatum (optional)",
+	"admin_new_invite_groups": "Gruppen (optional)",
+	"admin_new_invite_no_groups": "Keine Gruppen vorhanden.",
+	"admin_invite_groups_load_error": "Gruppen konnten nicht geladen werden. Die Einladung kann ohne Gruppenauswahl erstellt werden.",
 	"admin_invite_created_title": "Einladung erstellt",
 	"admin_invite_created_desc": "Teile diesen Link mit der einzuladenden Person:",
 	"admin_invite_revoke_confirm": "Einladung wirklich widerrufen?",

frontend/messages/en.json

@@ -345,8 +345,11 @@
 	"admin_system_import_btn_retry": "Start again",
 	"admin_system_import_status_idle": "No import started.",
 	"admin_system_import_status_running": "Import running…",
-	"admin_system_import_status_done": "Import complete – {count} documents processed.",
-	"admin_system_import_status_failed": "Error: {message}",
+	"admin_system_import_status_done": "Import complete",
+	"admin_system_import_status_done_label": "Documents processed",
+	"admin_system_import_status_failed": "Import failed",
+	"admin_system_import_failed_no_spreadsheet": "No spreadsheet file found.",
+	"admin_system_import_failed_internal": "Import failed due to an internal error.",
 	"admin_system_thumbnails_heading": "Generate thumbnails",
 	"admin_system_thumbnails_description": "Generates preview images for documents without a thumbnail (e.g. after the mass import).",
 	"admin_system_thumbnails_btn_start": "Generate thumbnails",
@@ -703,6 +706,8 @@
 	"error_invite_exhausted": "This invite link has already been fully used.",
 	"error_invite_revoked": "This invite link has been deactivated.",
 	"error_invite_expired": "This invite link has expired.",
+	"error_group_has_active_invites": "This group cannot be deleted because it is referenced by one or more active invite links.",
+	"error_group_not_found": "The specified group does not exist.",
 	"register_heading": "Create account",
 	"register_subtext": "You've been invited to join Familienarchiv.",
 	"register_label_first_name": "First name",
@@ -762,6 +767,9 @@
 	"admin_new_invite_prefill_last": "Pre-fill last name (optional)",
 	"admin_new_invite_prefill_email": "Pre-fill email (optional)",
 	"admin_new_invite_expires": "Expiry date (optional)",
+	"admin_new_invite_groups": "Groups (optional)",
+	"admin_new_invite_no_groups": "No groups exist.",
+	"admin_invite_groups_load_error": "Groups could not be loaded. The invite can still be created without group assignment.",
 	"admin_invite_created_title": "Invite created",
 	"admin_invite_created_desc": "Share this link with the person you are inviting:",
 	"admin_invite_revoke_confirm": "Really revoke this invite?",

frontend/messages/es.json

@@ -345,8 +345,11 @@
 	"admin_system_import_btn_retry": "Iniciar de nuevo",
 	"admin_system_import_status_idle": "No hay importación iniciada.",
 	"admin_system_import_status_running": "Importación en curso…",
-	"admin_system_import_status_done": "Importación completada – {count} documentos procesados.",
-	"admin_system_import_status_failed": "Error: {message}",
+	"admin_system_import_status_done": "Importación completada",
+	"admin_system_import_status_done_label": "Documentos procesados",
+	"admin_system_import_status_failed": "Importación fallida",
+	"admin_system_import_failed_no_spreadsheet": "No se encontró ninguna hoja de cálculo.",
+	"admin_system_import_failed_internal": "Error interno durante la importación.",
 	"admin_system_thumbnails_heading": "Generar miniaturas",
 	"admin_system_thumbnails_description": "Genera imágenes de vista previa para documentos sin miniatura (p. ej. tras la importación masiva).",
 	"admin_system_thumbnails_btn_start": "Generar miniaturas",
@@ -703,6 +706,8 @@
 	"error_invite_exhausted": "Este enlace de invitación ya ha sido completamente utilizado.",
 	"error_invite_revoked": "Este enlace de invitación ha sido desactivado.",
 	"error_invite_expired": "Este enlace de invitación ha expirado.",
+	"error_group_has_active_invites": "Este grupo no puede eliminarse porque está referenciado por uno o más enlaces de invitación activos.",
+	"error_group_not_found": "El grupo especificado no existe.",
 	"register_heading": "Crear cuenta",
 	"register_subtext": "Has sido invitado a unirte al Familienarchiv.",
 	"register_label_first_name": "Nombre",
@@ -762,6 +767,9 @@
 	"admin_new_invite_prefill_last": "Prellenar apellido (opcional)",
 	"admin_new_invite_prefill_email": "Prellenar correo (opcional)",
 	"admin_new_invite_expires": "Fecha de vencimiento (opcional)",
+	"admin_new_invite_groups": "Grupos (opcional)",
+	"admin_new_invite_no_groups": "No hay grupos disponibles.",
+	"admin_invite_groups_load_error": "No se pudieron cargar los grupos. La invitación puede crearse sin asignar grupos.",
 	"admin_invite_created_title": "Invitación creada",
 	"admin_invite_created_desc": "Comparte este enlace con la persona invitada:",
 	"admin_invite_revoke_confirm": "¿Realmente revocar esta invitación?",

frontend/package.json

@@ -8,6 +8,7 @@
 		"build": "vite build",
 		"preview": "vite preview",
 		"prepare": "svelte-kit sync || true && git -C .. config core.hooksPath .husky 2>/dev/null || true",
+		"postinstall": "patch-package",
 		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
 		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
 		"format": "prettier --write .",
@@ -15,13 +16,14 @@
 		"lint:boundary-demo": "eslint src/lib/tag/__fixtures__/",
 		"test:unit": "vitest",
 		"test": "npm run test:unit -- --run",
-		"test:coverage": "vitest run --coverage --project=server && vitest run -c vitest.client-coverage.config.ts --coverage",
+		"test:coverage": "vitest run --coverage --project=server; vitest run -c vitest.client-coverage.config.ts --coverage",
 		"test:e2e": "playwright test",
 		"test:e2e:headed": "playwright test --headed",
 		"test:e2e:ui": "playwright test --ui",
 		"generate:api": "openapi-typescript http://localhost:8080/v3/api-docs -o ./src/lib/generated/api.ts"
 	},
 	"dependencies": {
+		"@sentry/sveltekit": "^10.53.1",
 		"@tiptap/core": "3.22.5",
 		"@tiptap/extension-mention": "3.22.5",
 		"@tiptap/starter-kit": "3.22.5",
@@ -54,6 +56,7 @@
 		"eslint-plugin-svelte": "^3.13.0",
 		"globals": "^16.5.0",
 		"openapi-typescript": "^7.8.0",
+		"patch-package": "^8.0.0",
 		"playwright": "^1.56.1",
 		"prettier": "^3.6.2",
 		"prettier-plugin-svelte": "^3.4.0",

frontend/patches/@vitest+browser-playwright+4.1.0.patch

@@ -0,0 +1,62 @@
+diff --git a/node_modules/@vitest/browser-playwright/dist/index.js b/node_modules/@vitest/browser-playwright/dist/index.js
+index 5d0d37b..821d7b4 100644
+--- a/node_modules/@vitest/browser-playwright/dist/index.js
++++ b/node_modules/@vitest/browser-playwright/dist/index.js
+@@ -935,7 +935,7 @@ class PlaywrightBrowserProvider {
+ 	createMocker() {
+ 		const idPreficates = new Map();
+ 		const sessionIds = new Map();
+-		function createPredicate(sessionId, url) {
++		function createPredicate(url) {
+ 			const moduleUrl = new URL(url, "http://localhost");
+ 			const predicate = (url) => {
+ 				if (url.searchParams.has("_vitest_original")) {
+@@ -960,11 +960,7 @@ class PlaywrightBrowserProvider {
+ 				}
+ 				return true;
+ 			};
+-			const ids = sessionIds.get(sessionId) || [];
+-			ids.push(moduleUrl.href);
+-			sessionIds.set(sessionId, ids);
+-			idPreficates.set(predicateKey(sessionId, moduleUrl.href), predicate);
+-			return predicate;
++			return { url: moduleUrl.href, predicate };
+ 		}
+ 		function predicateKey(sessionId, url) {
+ 			return `${sessionId}:${url}`;
+@@ -972,7 +968,23 @@ class PlaywrightBrowserProvider {
+ 		return {
+ 			register: async (sessionId, module) => {
+ 				const page = this.getPage(sessionId);
+-				await page.context().route(createPredicate(sessionId, module.url), async (route) => {
++				const { url: moduleUrl, predicate } = createPredicate(module.url);
++				const key = predicateKey(sessionId, moduleUrl);
++				// Backport of vitest PR #10267: if a route handler is already
++				// registered for this resolved module URL in this session,
++				// unroute it before installing the new one. Without this guard,
++				// duplicate-id mocks (e.g. '$lib/foo.svelte' + '$lib/foo.svelte.js')
++				// leak an orphan route whose handler crashes after the next
++				// session's birpc channel closes.
++				const existingPredicate = idPreficates.get(key);
++				if (existingPredicate) {
++					await page.context().unroute(existingPredicate);
++				}
++				const ids = sessionIds.get(sessionId) ?? new Set();
++				ids.add(moduleUrl);
++				sessionIds.set(sessionId, ids);
++				idPreficates.set(key, predicate);
++				await page.context().route(predicate, async (route) => {
+ 					if (module.type === "manual") {
+ 						const exports$1 = Object.keys(await module.resolve());
+ 						const body = createManualModuleSource(module.url, exports$1);
+@@ -1033,8 +1045,8 @@ class PlaywrightBrowserProvider {
+ 			},
+ 			clear: async (sessionId) => {
+ 				const page = this.getPage(sessionId);
+-				const ids = sessionIds.get(sessionId) || [];
+-				const promises = ids.map((id) => {
++				const ids = sessionIds.get(sessionId) ?? new Set();
++				const promises = [...ids].map((id) => {
+ 					const key = predicateKey(sessionId, id);
+ 					const predicate = idPreficates.get(key);
+ 					if (predicate) {

frontend/src/__meta__/browser-preload-disabled.svelte.test.ts

@@ -0,0 +1,20 @@
+import { describe, it, expect } from 'vitest';
+
+// Browser-mode tests must run with SvelteKit's hover-prefetch disabled.
+// Hover-prefetch fires real `fetch` requests for the target route's loader
+// chunks; those go through the same Playwright route handler that serves
+// mocked modules. Even after `cleanup()` tears down the iframe, an in-flight
+// prefetch can still hit the handler — and if the worker's birpc channel has
+// closed by then, the handler raises an unhandled rejection. ADR-012 / #553.
+//
+// This test enforces that the test-setup file ran and switched preload-data
+// off on `document.body` before any spec started rendering.
+describe('browser test setup', () => {
+	it('disables SvelteKit loader-data prefetch on document.body', () => {
+		expect(document.body.dataset.sveltekitPreloadData).toBe('off');
+	});
+
+	it('disables SvelteKit route-code prefetch on document.body', () => {
+		expect(document.body.dataset.sveltekitPreloadCode).toBe('off');
+	});
+});

frontend/src/__meta__/no-async-mock-factories.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect } from 'vitest';
+import { readdirSync, readFileSync } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+// Belt-and-braces detector for the birpc teardown race named in ADR-012 / #553.
+// ESLint catches the pattern at save time, CI grep catches it before the test
+// suite launches, and this in-suite test catches it at every vitest invocation —
+// the layer hardest to disable or scope around.
+//
+// We scan source text rather than parsing AST: fast, no parser dependency,
+// good enough for the named anti-pattern. The pattern matches
+// `vi.mock(<arg>, async ... { ... await import(...) ... })`.
+
+const ASYNC_MOCK_WITH_DYNAMIC_IMPORT = /vi\.mock\([^)]*,\s*async[^{]*\{[\s\S]*?await\s+import\s*\(/;
+
+export function hasAsyncMockFactoryWithDynamicImport(source: string): boolean {
+	return ASYNC_MOCK_WITH_DYNAMIC_IMPORT.test(source);
+}
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SRC_ROOT = path.resolve(__dirname, '..');
+
+function findBrowserSpecs(): string[] {
+	const entries = readdirSync(SRC_ROOT, { recursive: true, withFileTypes: true });
+	return entries
+		.filter(
+			(e) =>
+				e.isFile() && (e.name.endsWith('.svelte.test.ts') || e.name.endsWith('.svelte.spec.ts'))
+		)
+		.map((e) => path.join(e.parentPath ?? (e as { path: string }).path, e.name));
+}
+
+describe('scan: hasAsyncMockFactoryWithDynamicImport', () => {
+	it('flags async vi.mock factory with await import in body', () => {
+		const fixture = `vi.mock('$app/stores', async () => {
+			const mod = await import('./__mocks__/navigatingStore');
+			return { navigating: mod.navigatingStore };
+		});`;
+		expect(hasAsyncMockFactoryWithDynamicImport(fixture)).toBe(true);
+	});
+
+	it('does not flag sync vi.mock factory', () => {
+		const fixture = `vi.mock('$app/state', () => ({ navigating: { type: null } }));`;
+		expect(hasAsyncMockFactoryWithDynamicImport(fixture)).toBe(false);
+	});
+
+	it('does not flag async vi.mock factory without dynamic import', () => {
+		const fixture = `vi.mock('foo', async () => {
+			const x = await Promise.resolve(42);
+			return { bar: x };
+		});`;
+		expect(hasAsyncMockFactoryWithDynamicImport(fixture)).toBe(false);
+	});
+
+	it('does not flag dynamic import outside any vi.mock', () => {
+		const fixture = `async function load() {
+			const mod = await import('./something');
+			return mod.default;
+		}`;
+		expect(hasAsyncMockFactoryWithDynamicImport(fixture)).toBe(false);
+	});
+
+	it('flags async factory written as async function expression', () => {
+		const fixture = `vi.mock('foo', async function () {
+			const mod = await import('./bar');
+			return mod;
+		});`;
+		expect(hasAsyncMockFactoryWithDynamicImport(fixture)).toBe(true);
+	});
+});
+
+describe('browser specs: no async vi.mock factory contains await import', () => {
+	it('every src/**/*.svelte.{test,spec}.ts file is clean', () => {
+		const specFiles = findBrowserSpecs();
+		expect(specFiles.length).toBeGreaterThan(0);
+		const offenders = specFiles.filter((file) =>
+			hasAsyncMockFactoryWithDynamicImport(readFileSync(file, 'utf-8'))
+		);
+		expect(offenders).toEqual([]);
+	});
+});

frontend/src/__meta__/no-duplicate-mock-ids.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect } from 'vitest';
+import { readdirSync, readFileSync } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+// Belt-and-braces detector for the duplicate-id birpc race named in
+// ADR-012 / #553. When the same resolved module URL is mocked via two
+// distinct vi.mock id strings (e.g. '$lib/foo.svelte' and
+// '$lib/foo.svelte.js'), @vitest/browser-playwright registers two
+// Playwright routes against one cleanup slot — the orphan survives, fires
+// after the next session's birpc closes, and crashes the run with
+// "[birpc] rpc is closed, cannot call resolveManualMock".
+//
+// Fixed upstream in vitest PR #10267; until that fix reaches a published
+// release, normalisation in user-land is the practical guard. This test
+// catches the pattern at every vitest invocation — the layer hardest to
+// disable or scope around.
+
+const VI_MOCK_ID = /vi\.mock\(\s*['"]([^'"]+)['"]/g;
+
+function extractMockIds(source: string): string[] {
+	const ids: string[] = [];
+	for (const match of source.matchAll(VI_MOCK_ID)) {
+		ids.push(match[1]);
+	}
+	return ids;
+}
+
+function canonicalise(id: string): string {
+	if (id.endsWith('.svelte.js')) return id.slice(0, -3);
+	if (id.endsWith('.svelte.ts')) return id.slice(0, -3);
+	return id;
+}
+
+export function findDuplicateMockIds(
+	specSources: Record<string, string>
+): Map<string, Set<string>> {
+	const byCanonical = new Map<string, Set<string>>();
+	for (const source of Object.values(specSources)) {
+		for (const raw of extractMockIds(source)) {
+			const canonical = canonicalise(raw);
+			const existing = byCanonical.get(canonical) ?? new Set<string>();
+			existing.add(raw);
+			byCanonical.set(canonical, existing);
+		}
+	}
+	const duplicates = new Map<string, Set<string>>();
+	for (const [canonical, raws] of byCanonical) {
+		if (raws.size >= 2) duplicates.set(canonical, raws);
+	}
+	return duplicates;
+}
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SRC_ROOT = path.resolve(__dirname, '..');
+
+function findBrowserSpecs(): string[] {
+	const entries = readdirSync(SRC_ROOT, { recursive: true, withFileTypes: true });
+	return entries
+		.filter(
+			(e) =>
+				e.isFile() && (e.name.endsWith('.svelte.test.ts') || e.name.endsWith('.svelte.spec.ts'))
+		)
+		.map((e) => path.join(e.parentPath ?? (e as { path: string }).path, e.name));
+}
+
+describe('scan: findDuplicateMockIds', () => {
+	it('flags two specs mocking the same module under .svelte and .svelte.js', () => {
+		const dup = findDuplicateMockIds({
+			'a.spec.ts': `vi.mock('$lib/foo.svelte', () => ({}));`,
+			'b.spec.ts': `vi.mock('$lib/foo.svelte.js', () => ({}));`
+		});
+		expect(dup.get('$lib/foo.svelte')).toEqual(new Set(['$lib/foo.svelte', '$lib/foo.svelte.js']));
+	});
+
+	it('does not flag two specs both using $lib/foo.svelte', () => {
+		const dup = findDuplicateMockIds({
+			'a.spec.ts': `vi.mock('$lib/foo.svelte', () => ({}));`,
+			'b.spec.ts': `vi.mock('$lib/foo.svelte', () => ({}));`
+		});
+		expect(dup.size).toBe(0);
+	});
+
+	it('does not flag $app/state and $app/stores (different modules)', () => {
+		const dup = findDuplicateMockIds({
+			'a.spec.ts': `vi.mock('$app/state', () => ({}));`,
+			'b.spec.ts': `vi.mock('$app/stores', () => ({}));`
+		});
+		expect(dup.size).toBe(0);
+	});
+
+	it('does not flag $lib/foo and $lib/bar (different canonical paths)', () => {
+		const dup = findDuplicateMockIds({
+			'a.spec.ts': `vi.mock('$lib/foo', () => ({}));`,
+			'b.spec.ts': `vi.mock('$lib/bar', () => ({}));`
+		});
+		expect(dup.size).toBe(0);
+	});
+
+	it('flags both spellings within a single file', () => {
+		const dup = findDuplicateMockIds({
+			'a.spec.ts': `
+				vi.mock('$lib/foo.svelte', () => ({}));
+				vi.mock('$lib/foo.svelte.js', () => ({}));
+			`
+		});
+		expect(dup.get('$lib/foo.svelte')?.size).toBe(2);
+	});
+
+	it('canonicalises .svelte.ts the same way as .svelte.js', () => {
+		const dup = findDuplicateMockIds({
+			'a.spec.ts': `vi.mock('$lib/foo.svelte', () => ({}));`,
+			'b.spec.ts': `vi.mock('$lib/foo.svelte.ts', () => ({}));`
+		});
+		expect(dup.get('$lib/foo.svelte')?.size).toBe(2);
+	});
+});
+
+describe('browser specs: no duplicate-id vi.mock calls across the suite', () => {
+	it('every mocked module is referenced under exactly one id string', () => {
+		const specFiles = findBrowserSpecs();
+		expect(specFiles.length).toBeGreaterThan(0);
+		const sources = Object.fromEntries(
+			specFiles.map((file) => [file, readFileSync(file, 'utf-8')])
+		);
+		const duplicates = findDuplicateMockIds(sources);
+		const report = Object.fromEntries([...duplicates].map(([k, v]) => [k, [...v]]));
+		expect(report).toEqual({});
+	});
+});

frontend/src/hooks.client.ts

@@ -0,0 +1,10 @@
+import * as Sentry from '@sentry/sveltekit';
+
+Sentry.init({
+	dsn: import.meta.env.VITE_SENTRY_DSN,
+	environment: import.meta.env.MODE,
+	tracesSampleRate: 1.0,
+	enabled: !!import.meta.env.VITE_SENTRY_DSN
+});
+
+export const handleError = Sentry.handleErrorWithSentry();

frontend/src/hooks.server.ts

@@ -1,3 +1,4 @@
+import * as Sentry from '@sentry/sveltekit';
 import { redirect, type Handle, type HandleFetch } from '@sveltejs/kit';
 import { paraglideMiddleware } from '$lib/paraglide/server';
 import { sequence } from '@sveltejs/kit/hooks';
@@ -5,6 +6,13 @@ import { env } from 'process';
 import { cookieName, cookieMaxAge } from '$lib/paraglide/runtime';
 import { detectLocale } from '$lib/shared/server/locale';
 
+Sentry.init({
+	dsn: import.meta.env.VITE_SENTRY_DSN,
+	environment: import.meta.env.MODE,
+	tracesSampleRate: 1.0,
+	enabled: !!import.meta.env.VITE_SENTRY_DSN
+});
+
 const PUBLIC_PATHS = [
 	'/login',
 	'/logout',
@@ -113,3 +121,5 @@ export const handleFetch: HandleFetch = async ({ event, request, fetch }) => {
 };
 
 export const handle = sequence(userGroup, handleAuth, handleLocaleDetection, handleParaglide);
+
+export const handleError = Sentry.handleErrorWithSentry();

frontend/src/lib/activity/ChronikFuerDichBox.svelte

@@ -79,7 +79,7 @@ function href(n: NotificationItem): string {
 		<ul role="list" class="flex flex-col gap-2">
 			{#each unread as n (n.id)}
 				<li
-					class="fade-in group flex items-start gap-3 rounded-sm p-2 transition-colors hover:bg-canvas"
+					class="chronik-fade-in group flex items-start gap-3 rounded-sm p-2 transition-colors hover:bg-canvas"
 				>
 					<a
 						href={href(n)}
@@ -124,26 +124,3 @@ function href(n: NotificationItem): string {
 		</ul>
 	{/if}
 </section>
-
-<style>
-.fade-in {
-	animation: chronik-fade-in 160ms ease-out;
-}
-
-@keyframes chronik-fade-in {
-	from {
-		opacity: 0;
-		transform: translateY(-4px);
-	}
-	to {
-		opacity: 1;
-		transform: translateY(0);
-	}
-}
-
-@media (prefers-reduced-motion: reduce) {
-	.fade-in {
-		animation: none;
-	}
-}
-</style>

frontend/src/lib/document/EnrichmentBlock.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-import { navigating } from '$app/stores';
+import { navigating } from '$app/state';
 import DashboardNeedsMetadata from './DashboardNeedsMetadata.svelte';
 import UploadSuccessBanner from './UploadSuccessBanner.svelte';
 
@@ -18,7 +18,7 @@ interface Props {
 
 let { topDocs, totalCount, bannerCount, onBannerClose }: Props = $props();
 
-const showSkeleton = $derived(!!$navigating && topDocs.length === 0);
+const showSkeleton = $derived(!!navigating.type && topDocs.length === 0);
 const showBlock = $derived(topDocs.length > 0 || bannerCount > 0 || showSkeleton);
 </script>
 

frontend/src/lib/document/EnrichmentBlock.svelte.spec.ts

@@ -2,19 +2,23 @@ import { describe, it, expect, afterEach, vi } from 'vitest';
 import { cleanup, render } from 'vitest-browser-svelte';
 import { page } from 'vitest/browser';
 
-// The store must live in a separate module because vi.mock factories are
-// hoisted and cannot reference top-level variables defined in this file.
-import { navigatingStore } from './__mocks__/navigatingStore';
 import EnrichmentBlock from './EnrichmentBlock.svelte';
 
-vi.mock('$app/stores', async () => {
-	const mod = await import('./__mocks__/navigatingStore');
-	return { navigating: mod.navigatingStore };
-});
+// Hoist the mutable navigation reference so vi.mock's factory (also hoisted)
+// can read it via a getter. Sync factory, no dynamic import: ADR-012 invariant.
+const { mockNavigating } = vi.hoisted(() => ({
+	mockNavigating: { type: null as string | null }
+}));
+
+vi.mock('$app/state', () => ({
+	get navigating() {
+		return mockNavigating;
+	}
+}));
 
 afterEach(() => {
 	cleanup();
-	navigatingStore.set(null);
+	mockNavigating.type = null;
 });
 
 type Doc = { id: string; title: string; uploadedAt: string };
@@ -65,8 +69,8 @@ describe('EnrichmentBlock', () => {
 		await expect.element(page.getByTestId('dashboard-needs-metadata')).toBeInTheDocument();
 	});
 
-	it('renders the skeleton when $navigating is active and topDocs is empty', async () => {
-		navigatingStore.set({ type: 'link' });
+	it('renders the skeleton when navigation is active and topDocs is empty', async () => {
+		mockNavigating.type = 'link';
 		render(EnrichmentBlock, {
 			topDocs: [],
 			totalCount: 0,
@@ -76,8 +80,8 @@ describe('EnrichmentBlock', () => {
 		await expect.element(page.getByTestId('enrichment-block-skeleton')).toBeInTheDocument();
 	});
 
-	it('does not render the skeleton when topDocs is non-empty even during $navigating', async () => {
-		navigatingStore.set({ type: 'link' });
+	it('does not render the skeleton when topDocs is non-empty even during navigation', async () => {
+		mockNavigating.type = 'link';
 		render(EnrichmentBlock, {
 			topDocs: [doc('d1')],
 			totalCount: 1,

frontend/src/lib/document/__mocks__/navigatingStore.ts

@@ -1,3 +0,0 @@
-import { writable } from 'svelte/store';
-
-export const navigatingStore = writable<unknown | null>(null);

frontend/src/lib/document/annotation/AnnotationLayer.svelte.spec.ts

@@ -107,7 +107,7 @@ describe('AnnotationLayer', () => {
 		});
 
 		await expect.element(page.getByTestId('annotation-ann-1')).toBeInTheDocument();
-		expect(page.getByTestId('annotation-delete-ann-1').query()).toBeNull();
+		await expect.element(page.getByTestId('annotation-delete-ann-1')).not.toBeInTheDocument();
 	});
 
 	it('does not show delete button when canDraw is false even if annotation is active', async () => {
@@ -120,6 +120,6 @@ describe('AnnotationLayer', () => {
 		});
 
 		await expect.element(page.getByTestId('annotation-ann-1')).toBeInTheDocument();
-		expect(page.getByTestId('annotation-delete-ann-1').query()).toBeNull();
+		await expect.element(page.getByTestId('annotation-delete-ann-1')).not.toBeInTheDocument();
 	});
 });

frontend/src/lib/document/annotation/AnnotationShape.svelte.spec.ts

@@ -45,7 +45,7 @@ describe('AnnotationShape', () => {
 			onpointerleave: () => {}
 		});
 
-		expect(page.getByTestId('annotation-delete-ann-1').query()).toBeNull();
+		await expect.element(page.getByTestId('annotation-delete-ann-1')).not.toBeInTheDocument();
 	});
 
 	it('does not show delete button when showDelete is true but neither hovered nor active', async () => {
@@ -60,7 +60,7 @@ describe('AnnotationShape', () => {
 			onpointerleave: () => {}
 		});
 
-		expect(page.getByTestId('annotation-delete-ann-1').query()).toBeNull();
+		await expect.element(page.getByTestId('annotation-delete-ann-1')).not.toBeInTheDocument();
 	});
 
 	it('shows delete button when showDelete is true and isHovered is true', async () => {

frontend/src/lib/document/transcription/TranscriptionEditView.svelte.test.ts

@@ -5,9 +5,6 @@ import { page } from 'vitest/browser';
 vi.mock('$lib/shared/services/confirm.svelte', () => ({
 	getConfirmService: () => ({ confirm: async () => false })
 }));
-vi.mock('$lib/shared/services/confirm.svelte.js', () => ({
-	getConfirmService: () => ({ confirm: async () => false })
-}));
 
 const { default: TranscriptionEditView } = await import('./TranscriptionEditView.svelte');
 import type { TranscriptionBlockData } from '$lib/shared/types';

frontend/src/lib/document/viewer/PdfViewer.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
-import { onMount, setContext } from 'svelte';
-import { createPdfRenderer } from '$lib/document/viewer/usePdfRenderer.svelte';
+import { onMount, setContext, untrack } from 'svelte';
+import { createPdfRenderer, type LibLoader } from '$lib/document/viewer/usePdfRenderer.svelte';
 import PdfControls from './PdfControls.svelte';
 import AnnotationLayer from '$lib/document/annotation/AnnotationLayer.svelte';
 import type { Annotation } from '$lib/shared/types';
@@ -21,7 +21,8 @@ let {
 	onDeleteAnnotationRequest,
 	documentFileHash,
 	annotationsDimmed = false,
-	flashAnnotationId = null
+	flashAnnotationId = null,
+	libLoader = undefined
 }: {
 	url: string;
 	documentId?: string;
@@ -35,9 +36,11 @@ let {
 	documentFileHash?: string | null;
 	annotationsDimmed?: boolean;
 	flashAnnotationId?: string | null;
+	libLoader?: LibLoader;
 } = $props();
 
-const renderer = createPdfRenderer();
+// untrack: libLoader prop change must not reinitialise the renderer
+const renderer = untrack(() => createPdfRenderer(libLoader));
 
 // Canvas and text layer container refs — bound via bind:this
 let canvasEl = $state<HTMLCanvasElement | null>(null);

frontend/src/lib/document/viewer/PdfViewer.svelte.spec.ts

@@ -1,53 +0,0 @@
-import { vi, describe, it, expect, afterEach } from 'vitest';
-import { cleanup, render } from 'vitest-browser-svelte';
-import { page } from 'vitest/browser';
-
-// pdfjs-dist is a rendering dependency — we mock it so unit tests don't need
-// a real browser PDF engine. The interesting behaviour under test here is the
-// component's own UI logic (controls, page counter), not pdfjs internals.
-vi.mock('pdfjs-dist', () => {
-	function TextLayerMock() {}
-	TextLayerMock.prototype.render = () => Promise.resolve();
-	TextLayerMock.prototype.cancel = () => {};
-
-	return {
-		GlobalWorkerOptions: { workerSrc: '' },
-		getDocument: vi.fn().mockReturnValue({
-			promise: Promise.resolve({
-				numPages: 2,
-				getPage: vi.fn().mockResolvedValue({
-					getViewport: vi.fn().mockReturnValue({ width: 595, height: 842 }),
-					render: vi.fn().mockReturnValue({ promise: Promise.resolve() }),
-					streamTextContent: vi.fn().mockReturnValue(new ReadableStream())
-				})
-			})
-		}),
-		TextLayer: TextLayerMock
-	};
-});
-
-vi.mock('pdfjs-dist/build/pdf.worker.min.mjs?url', () => ({ default: '' }));
-
-import PdfViewer from './PdfViewer.svelte';
-
-afterEach(cleanup);
-
-describe('PdfViewer', () => {
-	it('shows previous and next page navigation buttons', async () => {
-		render(PdfViewer, { url: '/api/documents/test-id/file' });
-		await expect.element(page.getByRole('button', { name: /zurück/i })).toBeInTheDocument();
-		await expect.element(page.getByRole('button', { name: /weiter/i })).toBeInTheDocument();
-	});
-
-	it('shows zoom controls', async () => {
-		render(PdfViewer, { url: '/api/documents/test-id/file' });
-		await expect.element(page.getByRole('button', { name: /vergrößern/i })).toBeInTheDocument();
-		await expect.element(page.getByRole('button', { name: /verkleinern/i })).toBeInTheDocument();
-	});
-
-	it('displays the page counter once the PDF has loaded', async () => {
-		render(PdfViewer, { url: '/api/documents/test-id/file' });
-		// Mock resolves synchronously, so "1 / 2" should appear quickly
-		await expect.element(page.getByText(/1\s*\/\s*2/)).toBeInTheDocument();
-	});
-});

frontend/src/lib/document/viewer/PdfViewer.svelte.test.ts

@@ -1,43 +1,20 @@
 import { describe, it, expect, vi, afterEach } from 'vitest';
 import { cleanup, render } from 'vitest-browser-svelte';
 import { page } from 'vitest/browser';
-
-vi.mock('pdfjs-dist', () => {
-	function TextLayerMock() {}
-	TextLayerMock.prototype.render = () => Promise.resolve();
-	TextLayerMock.prototype.cancel = () => {};
-
-	return {
-		GlobalWorkerOptions: { workerSrc: '' },
-		getDocument: vi.fn().mockReturnValue({
-			promise: Promise.resolve({
-				numPages: 2,
-				getPage: vi.fn().mockResolvedValue({
-					getViewport: vi.fn().mockReturnValue({ width: 595, height: 842 }),
-					render: vi.fn().mockReturnValue({ promise: Promise.resolve() }),
-					streamTextContent: vi.fn().mockReturnValue(new ReadableStream())
-				})
-			})
-		}),
-		TextLayer: TextLayerMock
-	};
-});
-
-vi.mock('pdfjs-dist/build/pdf.worker.min.mjs?url', () => ({ default: '' }));
-
-const { default: PdfViewer } = await import('./PdfViewer.svelte');
+import PdfViewer from './PdfViewer.svelte';
+import { makeFakeLibLoader } from './testHelpers';
 
 afterEach(cleanup);
 
 describe('PdfViewer — empty / error states', () => {
 	it('renders the no-file placeholder when url is empty', async () => {
-		render(PdfViewer, { url: '' });
+		render(PdfViewer, { url: '', libLoader: makeFakeLibLoader() });
 
 		await expect.element(page.getByText('Keine Datei vorhanden')).toBeVisible();
 	});
 
 	it('does not render the controls when url is empty', async () => {
-		render(PdfViewer, { url: '' });
+		render(PdfViewer, { url: '', libLoader: makeFakeLibLoader() });
 
 		const buttons = document.querySelectorAll('button');
 		expect(buttons.length).toBe(0);
@@ -49,10 +26,10 @@ describe('PdfViewer — loaded state', () => {
 		render(PdfViewer, {
 			url: '/api/documents/test/file',
 			documentId: 'test',
-			annotationReloadKey: 0
+			annotationReloadKey: 0,
+			libLoader: makeFakeLibLoader()
 		});
 
-		// PdfControls renders its nav + zoom buttons once the document.promise resolves.
 		await expect.element(page.getByRole('button', { name: 'Zurück' })).toBeVisible();
 		await expect.element(page.getByRole('button', { name: 'Weiter' })).toBeVisible();
 		await expect.element(page.getByRole('button', { name: 'Vergrößern' })).toBeVisible();
@@ -63,7 +40,8 @@ describe('PdfViewer — loaded state', () => {
 		render(PdfViewer, {
 			url: '/api/documents/test/file',
 			documentId: 'test',
-			annotationsDimmed: true
+			annotationsDimmed: true,
+			libLoader: makeFakeLibLoader()
 		});
 
 		await vi.waitFor(() => {
@@ -96,11 +74,10 @@ describe('PdfViewer — loaded state', () => {
 				url: '/api/documents/test/file',
 				documentId: 'test',
 				transcribeMode: true,
-				documentFileHash: 'match'
+				documentFileHash: 'match',
+				libLoader: makeFakeLibLoader()
 			});
 
-			// transcribeMode forces showAnnotations=true; toggle button surfaces with "hide" label
-			// (only when annotationCount > 0).
 			await expect
 				.element(page.getByRole('button', { name: /annotierungen verbergen/i }))
 				.toBeVisible();
@@ -113,7 +90,8 @@ describe('PdfViewer — loaded state', () => {
 		render(PdfViewer, {
 			url: '/api/documents/test/file',
 			documentId: 'test',
-			documentFileHash: 'abc123'
+			documentFileHash: 'abc123',
+			libLoader: makeFakeLibLoader()
 		});
 
 		await vi.waitFor(() => {
@@ -125,7 +103,8 @@ describe('PdfViewer — loaded state', () => {
 		render(PdfViewer, {
 			url: '/api/documents/test/file',
 			documentId: 'test',
-			flashAnnotationId: 'ann-flashing'
+			flashAnnotationId: 'ann-flashing',
+			libLoader: makeFakeLibLoader()
 		});
 
 		await expect.element(page.getByRole('button', { name: 'Zurück' })).toBeVisible();
@@ -135,7 +114,8 @@ describe('PdfViewer — loaded state', () => {
 		render(PdfViewer, {
 			url: '/api/documents/test/file',
 			documentId: 'test',
-			blockNumbers: { 'ann-1': 1, 'ann-2': 2 }
+			blockNumbers: { 'ann-1': 1, 'ann-2': 2 },
+			libLoader: makeFakeLibLoader()
 		});
 
 		await expect.element(page.getByRole('button', { name: 'Zurück' })).toBeVisible();
@@ -145,7 +125,8 @@ describe('PdfViewer — loaded state', () => {
 		render(PdfViewer, {
 			url: '/api/documents/test/file',
 			documentId: 'test',
-			activeAnnotationId: 'ann-1'
+			activeAnnotationId: 'ann-1',
+			libLoader: makeFakeLibLoader()
 		});
 
 		await expect.element(page.getByRole('button', { name: 'Zurück' })).toBeVisible();
@@ -156,10 +137,10 @@ describe('PdfViewer — loaded state', () => {
 			url: '/api/documents/test/file',
 			documentId: 'test',
 			transcribeMode: true,
-			activeAnnotationId: 'ann-1'
+			activeAnnotationId: 'ann-1',
+			libLoader: makeFakeLibLoader()
 		});
 
-		// Without an annotations fetch, the visibility toggle is hidden — just assert the always-on nav.
 		await expect.element(page.getByRole('button', { name: 'Zurück' })).toBeVisible();
 		await expect.element(page.getByRole('button', { name: 'Weiter' })).toBeVisible();
 	});
@@ -169,7 +150,8 @@ describe('PdfViewer — loaded state', () => {
 		render(PdfViewer, {
 			url: '/api/documents/test/file',
 			documentId: 'test',
-			onAnnotationClick
+			onAnnotationClick,
+			libLoader: makeFakeLibLoader()
 		});
 
 		await expect.element(page.getByRole('button', { name: 'Zurück' })).toBeVisible();
@@ -199,7 +181,8 @@ describe('PdfViewer — loaded state', () => {
 			render(PdfViewer, {
 				url: '/api/documents/test/file',
 				documentId: 'test',
-				documentFileHash: 'new-hash'
+				documentFileHash: 'new-hash',
+				libLoader: makeFakeLibLoader()
 			});
 
 			await vi.waitFor(() => {
@@ -234,10 +217,10 @@ describe('PdfViewer — loaded state', () => {
 			render(PdfViewer, {
 				url: '/api/documents/test/file',
 				documentId: 'test',
-				documentFileHash: 'matching-hash'
+				documentFileHash: 'matching-hash',
+				libLoader: makeFakeLibLoader()
 			});
 
-			// Controls finish mounting, and the outdated notice stays absent.
 			await expect.element(page.getByRole('button', { name: 'Zurück' })).toBeVisible();
 			expect(document.querySelector('[data-testid="annotation-outdated-notice"]')).toBeNull();
 		} finally {
@@ -250,10 +233,10 @@ describe('PdfViewer — loaded state', () => {
 		try {
 			render(PdfViewer, {
 				url: '/api/documents/test/file',
-				documentId: 'test'
+				documentId: 'test',
+				libLoader: makeFakeLibLoader()
 			});
 
-			// PDF rendering does not depend on the annotations fetch — controls still appear.
 			await expect.element(page.getByRole('button', { name: 'Zurück' })).toBeVisible();
 			expect(document.querySelector('[data-testid="annotation-outdated-notice"]')).toBeNull();
 		} finally {
@@ -268,7 +251,8 @@ describe('PdfViewer — loaded state', () => {
 		try {
 			render(PdfViewer, {
 				url: '/api/documents/test/file',
-				documentId: 'test'
+				documentId: 'test',
+				libLoader: makeFakeLibLoader()
 			});
 
 			await expect.element(page.getByRole('button', { name: 'Zurück' })).toBeVisible();
@@ -277,4 +261,21 @@ describe('PdfViewer — loaded state', () => {
 			fetchSpy.mockRestore();
 		}
 	});
+
+	it('shows previous and next page navigation buttons', async () => {
+		render(PdfViewer, { url: '/api/documents/test-id/file', libLoader: makeFakeLibLoader() });
+		await expect.element(page.getByRole('button', { name: /zurück/i })).toBeVisible();
+		await expect.element(page.getByRole('button', { name: /weiter/i })).toBeVisible();
+	});
+
+	it('shows zoom controls', async () => {
+		render(PdfViewer, { url: '/api/documents/test-id/file', libLoader: makeFakeLibLoader() });
+		await expect.element(page.getByRole('button', { name: /vergrößern/i })).toBeVisible();
+		await expect.element(page.getByRole('button', { name: /verkleinern/i })).toBeVisible();
+	});
+
+	it('displays the page counter once the PDF has loaded', async () => {
+		render(PdfViewer, { url: '/api/documents/test-id/file', libLoader: makeFakeLibLoader() });
+		await expect.element(page.getByText(/1\s*\/\s*2/)).toBeVisible();
+	});
 });

frontend/src/lib/document/viewer/testHelpers.ts

@@ -0,0 +1,31 @@
+import { vi } from 'vitest';
+import type { LibLoader } from './usePdfRenderer.svelte';
+
+export function makeFakePdfjsLib() {
+	class TextLayerMock {
+		render() {
+			return Promise.resolve();
+		}
+		cancel() {}
+	}
+
+	return {
+		GlobalWorkerOptions: { workerSrc: '' },
+		getDocument: vi.fn().mockReturnValue({
+			promise: Promise.resolve({
+				numPages: 2,
+				getPage: vi.fn().mockResolvedValue({
+					getViewport: vi.fn().mockReturnValue({ width: 595, height: 842 }),
+					render: vi.fn().mockReturnValue({ promise: Promise.resolve() }),
+					streamTextContent: vi.fn().mockReturnValue(new ReadableStream())
+				})
+			})
+		}),
+		TextLayer: TextLayerMock
+	} as unknown as typeof import('pdfjs-dist');
+}
+
+export function makeFakeLibLoader(): LibLoader {
+	const fakePdfjs = makeFakePdfjsLib();
+	return vi.fn().mockResolvedValue([fakePdfjs, { default: '' }] as const);
+}

frontend/src/lib/document/viewer/usePdfRenderer.svelte.test.ts

@@ -1,5 +1,6 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, vi } from 'vitest';
 import { createPdfRenderer } from './usePdfRenderer.svelte';
+import { makeFakeLibLoader } from './testHelpers';
 
 // Note: init() and loadDocument() require pdfjsLib (browser module).
 // These tests cover pure state logic only — bounds clamping and zoom limits.
@@ -122,39 +123,36 @@ describe('createPdfRenderer', () => {
 		expect(r.scale).toBe(before);
 	});
 
-	it('init() is callable and resolves without throwing in browser env', async () => {
-		const r = createPdfRenderer();
+	it('init() sets pdfjsReady to true when loader resolves', async () => {
+		const r = createPdfRenderer(makeFakeLibLoader());
 		await expect(r.init()).resolves.toBeUndefined();
-		// pdfjsReady is now true
 		expect(r.pdfjsReady).toBe(true);
 	});
 
-	it('after init, loadDocument with a bogus URL sets error', async () => {
-		const r = createPdfRenderer();
+	it('after init, loadDocument completes and loading returns to false', async () => {
+		const r = createPdfRenderer(makeFakeLibLoader());
 		await r.init();
 
-		await r.loadDocument('about:invalid-pdf');
-		// Either error is set or loading flips back to false — both are acceptable
+		await r.loadDocument('/some/path');
 		expect(r.loading).toBe(false);
 	});
 
 	it('renderCurrentPage is a no-op when canvasEl is null but pdfjsLib is initialized', async () => {
-		const r = createPdfRenderer();
+		const r = createPdfRenderer(makeFakeLibLoader());
 		await r.init();
 		// Without setElements, canvasEl is null — early return
 		await expect(r.renderCurrentPage()).resolves.toBeUndefined();
 	});
 
 	it('renderCurrentPage is a no-op when textLayerEl is null', async () => {
-		const r = createPdfRenderer();
+		const r = createPdfRenderer(makeFakeLibLoader());
 		await r.init();
-		// Set only canvas, leave textLayer unset is not directly testable;
-		// confirm calling without elements wired returns early.
+		// Without setElements, textLayerEl is null — early return
 		await expect(r.renderCurrentPage()).resolves.toBeUndefined();
 	});
 
 	it('init() can be called multiple times safely', async () => {
-		const r = createPdfRenderer();
+		const r = createPdfRenderer(makeFakeLibLoader());
 		await r.init();
 		await r.init();
 		expect(r.pdfjsReady).toBe(true);
@@ -173,4 +171,57 @@ describe('createPdfRenderer', () => {
 		r.goToPage(1);
 		expect(r.currentPage).toBe(1);
 	});
+
+	it('calls injected libLoader during init and sets pdfjsReady', async () => {
+		const fakePdfjs = {
+			GlobalWorkerOptions: { workerSrc: '' },
+			getDocument: vi.fn(),
+			TextLayer: class {}
+		} as unknown as typeof import('pdfjs-dist');
+		const fakeLoader = vi.fn().mockResolvedValue([fakePdfjs, { default: '' }] as const);
+		const r = createPdfRenderer(fakeLoader);
+		await r.init();
+		expect(fakeLoader).toHaveBeenCalledOnce();
+		expect(r.pdfjsReady).toBe(true);
+	});
+
+	it('leaves pdfjsReady false when libLoader rejects', async () => {
+		const failingLoader = vi.fn().mockRejectedValue(new Error('load failed'));
+		const r = createPdfRenderer(failingLoader);
+		await expect(r.init()).rejects.toThrow('load failed');
+		expect(r.pdfjsReady).toBe(false);
+	});
+
+	it('init() is idempotent — libLoader called only once on repeated calls', async () => {
+		const fakePdfjs = {
+			GlobalWorkerOptions: { workerSrc: '' },
+			getDocument: vi.fn(),
+			TextLayer: class {}
+		} as unknown as typeof import('pdfjs-dist');
+		const fakeLoader = vi.fn().mockResolvedValue([fakePdfjs, { default: '' }] as const);
+		const r = createPdfRenderer(fakeLoader);
+		await r.init();
+		await r.init();
+		expect(fakeLoader).toHaveBeenCalledOnce();
+	});
+
+	it('loadDocument sets error and loading=false when getDocument().promise rejects', async () => {
+		const failingLib = {
+			GlobalWorkerOptions: { workerSrc: '' },
+			getDocument: vi.fn().mockReturnValue({
+				promise: Promise.reject(new Error('PDF not found'))
+			}),
+			TextLayer: class {
+				render() {
+					return Promise.resolve();
+				}
+				cancel() {}
+			}
+		} as unknown as typeof import('pdfjs-dist');
+		const r = createPdfRenderer(vi.fn().mockResolvedValue([failingLib, { default: '' }] as const));
+		await r.init();
+		await r.loadDocument('/bad/path');
+		expect(r.loading).toBe(false);
+		expect(r.error).toBe('PDF not found');
+	});
 });

frontend/src/lib/document/viewer/usePdfRenderer.svelte.ts

@@ -1,6 +1,11 @@
 import type { PDFDocumentProxy, RenderTask } from 'pdfjs-dist';
 
-export function createPdfRenderer() {
+export type LibLoader = () => Promise<readonly [typeof import('pdfjs-dist'), { default: string }]>;
+
+const defaultLibLoader: LibLoader = () =>
+	Promise.all([import('pdfjs-dist'), import('pdfjs-dist/build/pdf.worker.min.mjs?url')]);
+
+export function createPdfRenderer(libLoader: LibLoader = defaultLibLoader) {
 	// Reactive state — exposed via getters
 	let currentPage = $state(1);
 	let totalPages = $state(0);
@@ -18,10 +23,8 @@ export function createPdfRenderer() {
 	let pdfjsLib: typeof import('pdfjs-dist') | null = null;
 
 	async function init(): Promise<void> {
-		const [lib, { default: workerUrl }] = await Promise.all([
-			import('pdfjs-dist'),
-			import('pdfjs-dist/build/pdf.worker.min.mjs?url')
-		]);
+		if (pdfjsReady) return;
+		const [lib, { default: workerUrl }] = await libLoader();
 		lib.GlobalWorkerOptions.workerSrc = workerUrl;
 		pdfjsLib = lib;
 		pdfjsReady = true;

frontend/src/lib/notification/NotificationDropdown.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+import { goto } from '$app/navigation';
 import { m } from '$lib/paraglide/messages.js';
 import { relativeTime } from '$lib/shared/utils/time';
 import type { NotificationItem } from '$lib/notification/notifications.svelte';
@@ -11,6 +12,11 @@ type Props = {
 };
 
 let { notifications, onMarkRead, onMarkAllRead, onClose }: Props = $props();
+
+function handleViewAll() {
+	onClose(); // close first — avoids stale dropdown during navigation transition
+	goto('/aktivitaeten');
+}
 </script>
 
 <div
@@ -127,12 +133,12 @@ let { notifications, onMarkRead, onMarkAllRead, onClose }: Props = $props();
 	{/if}
 
 	<div class="border-t border-line px-4 py-2">
-		<a
-			href="/aktivitaeten"
-			onclick={onClose}
-			class="text-xs font-medium text-ink-2 transition-colors hover:text-ink"
+		<button
+			type="button"
+			onclick={handleViewAll}
+			class="min-h-[44px] px-1 text-xs font-medium text-ink-2 transition-colors hover:text-ink"
 		>
 			{m.chronik_view_all()}
-		</a>
+		</button>
 	</div>
 </div>

frontend/src/lib/notification/NotificationDropdown.svelte.test.ts

@@ -1,9 +1,15 @@
 import { describe, it, expect, vi, afterEach } from 'vitest';
 import { cleanup, render } from 'vitest-browser-svelte';
 import { page } from 'vitest/browser';
+import { goto } from '$app/navigation';
 import NotificationDropdown from './NotificationDropdown.svelte';
 
-afterEach(cleanup);
+vi.mock('$app/navigation', () => ({ goto: vi.fn() }));
+
+afterEach(() => {
+	cleanup();
+	vi.clearAllMocks();
+});
 
 const makeNotification = (overrides: Record<string, unknown> = {}) => ({
 	id: 'n1',
@@ -153,7 +159,7 @@ describe('NotificationDropdown', () => {
 		expect(onMarkAllRead).toHaveBeenCalledOnce();
 	});
 
-	it('calls onClose when the view-all link is clicked', async () => {
+	it('calls onClose when the view-all button is clicked', async () => {
 		const onClose = vi.fn();
 		render(NotificationDropdown, {
 			props: {
@@ -164,11 +170,44 @@ describe('NotificationDropdown', () => {
 			}
 		});
 
-		await page.getByRole('link').click();
+		await page.getByRole('button', { name: /alle aktivitäten|view all/i }).click();
 
 		expect(onClose).toHaveBeenCalledOnce();
 	});
 
+	it('navigates to /aktivitaeten when the view-all button is clicked', async () => {
+		render(NotificationDropdown, {
+			props: {
+				notifications: [],
+				onMarkRead: () => {},
+				onMarkAllRead: () => {},
+				onClose: () => {}
+			}
+		});
+
+		await page.getByRole('button', { name: /alle aktivitäten|view all/i }).click();
+
+		expect(goto).toHaveBeenCalledWith('/aktivitaeten');
+	});
+
+	it('calls onClose before navigating to /aktivitaeten', async () => {
+		const callOrder: string[] = [];
+		const onClose = vi.fn(() => callOrder.push('close'));
+		vi.mocked(goto).mockImplementation(() => callOrder.push('goto'));
+		render(NotificationDropdown, {
+			props: {
+				notifications: [],
+				onMarkRead: () => {},
+				onMarkAllRead: () => {},
+				onClose
+			}
+		});
+
+		await page.getByRole('button', { name: /alle aktivitäten|view all/i }).click();
+
+		expect(callOrder).toEqual(['close', 'goto']);
+	});
+
 	it('renders MENTION items with the mention verb text', async () => {
 		render(NotificationDropdown, {
 			props: {

frontend/src/lib/ocr/OcrTrainingCard.svelte.spec.ts

@@ -1,4 +1,4 @@
-import { afterEach, describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { cleanup, render } from 'vitest-browser-svelte';
 import { page } from 'vitest/browser';
 import OcrTrainingCard from './OcrTrainingCard.svelte';
@@ -74,6 +74,12 @@ describe('OcrTrainingCard — enabled state', () => {
 });
 
 describe('OcrTrainingCard — success dismiss button', () => {
+	beforeEach(() => vi.useFakeTimers());
+	afterEach(() => {
+		vi.runAllTimers();
+		vi.useRealTimers();
+	});
+
 	it('dismiss button has 44×44px touch target (h-11 w-11)', async () => {
 		vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: true }));
 
@@ -108,7 +114,9 @@ describe('OcrTrainingCard — in-flight state', () => {
 		// While fetch is still pending the button label becomes "…"
 		await expect.element(page.getByRole('button', { name: '…' })).toBeInTheDocument();
 
-		// Cleanup: resolve the pending promise
 		resolveFetch({ ok: false });
+		await expect
+			.element(page.getByRole('button', { name: /Training starten/i }))
+			.not.toBeDisabled();
 	});
 });

frontend/src/lib/shared/errors.ts

@@ -22,6 +22,8 @@ export type ErrorCode =
 	| 'INVITE_EXHAUSTED'
 	| 'INVITE_REVOKED'
 	| 'INVITE_EXPIRED'
+	| 'GROUP_HAS_ACTIVE_INVITES'
+	| 'GROUP_NOT_FOUND'
 	| 'ANNOTATION_NOT_FOUND'
 	| 'ANNOTATION_UPDATE_FAILED'
 	| 'TRANSCRIPTION_BLOCK_NOT_FOUND'
@@ -108,6 +110,10 @@ export function getErrorMessage(code: ErrorCode | string | undefined): string {
 			return m.error_invite_revoked();
 		case 'INVITE_EXPIRED':
 			return m.error_invite_expired();
+		case 'GROUP_HAS_ACTIVE_INVITES':
+			return m.error_group_has_active_invites();
+		case 'GROUP_NOT_FOUND':
+			return m.error_group_not_found();
 		case 'ANNOTATION_NOT_FOUND':
 			return m.error_annotation_not_found();
 		case 'ANNOTATION_UPDATE_FAILED':

frontend/src/lib/user/UserGroupsSection.svelte

@@ -1,4 +1,7 @@
 <script lang="ts">
+import { untrack } from 'svelte';
+import { m } from '$lib/paraglide/messages.js';
+
 let {
 	groups,
 	selectedGroupIds = []
@@ -7,12 +10,13 @@ let {
 	selectedGroupIds?: string[];
 } = $props();
 
-let selected = $derived([...selectedGroupIds]);
+let selected = $state<string[]>(untrack(() => [...selectedGroupIds]));
 </script>
 
-<div class="flex flex-wrap gap-3">
+<fieldset class="flex flex-wrap gap-3 border-none p-0">
+	<legend class="sr-only">{m.admin_new_invite_groups()}</legend>
 	{#each groups as group (group.id)}
-		<label class="inline-flex items-center gap-2 text-sm text-ink-2">
+		<label class="inline-flex min-h-[44px] items-center gap-2 text-sm text-ink-2">
 			<input
 				type="checkbox"
 				name="groupIds"
@@ -23,4 +27,4 @@ let selected = $derived([...selectedGroupIds]);
 			{group.name}
 		</label>
 	{/each}
-</div>
+</fieldset>

frontend/src/routes/+layout.svelte

@@ -9,7 +9,7 @@ import NotificationBell from '$lib/notification/NotificationBell.svelte';
 import AppNav from './AppNav.svelte';
 import UserMenu from './UserMenu.svelte';
 import ConfirmDialog from '$lib/shared/primitives/ConfirmDialog.svelte';
-import { provideConfirmService } from '$lib/shared/services/confirm.svelte.js';
+import { provideConfirmService } from '$lib/shared/services/confirm.svelte';
 import { bulkSelectionStore } from '$lib/document/bulkSelection.svelte';
 
 let { children, data } = $props();

frontend/src/routes/admin/groups/[id]/page.svelte.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect, vi, afterEach } from 'vitest';
 import { cleanup, render } from 'vitest-browser-svelte';
 import { page } from 'vitest/browser';
 
-vi.mock('$lib/shared/services/confirm.svelte.js', () => ({
+vi.mock('$lib/shared/services/confirm.svelte', () => ({
 	getConfirmService: () => ({ confirm: async () => false })
 }));
 

frontend/src/routes/admin/groups/new/+page.svelte

@@ -1,7 +1,8 @@
 <script lang="ts">
 import { enhance } from '$app/forms';
-import { beforeNavigate, goto } from '$app/navigation';
 import { m } from '$lib/paraglide/messages.js';
+import { createUnsavedWarning } from '$lib/shared/hooks/useUnsavedWarning.svelte';
+import UnsavedWarningBanner from '$lib/shared/primitives/UnsavedWarningBanner.svelte';
 
 const availableStandard = $derived([
 	{ value: 'READ_ALL', label: m.admin_perm_read_all() },
@@ -18,17 +19,7 @@ const availableAdmin = $derived([
 
 let { form } = $props();
 
-let isDirty = $state(false);
-let showUnsavedWarning = $state(false);
-let discardTarget: string | null = $state(null);
-
-beforeNavigate(({ cancel, to }) => {
-	if (isDirty) {
-		cancel();
-		showUnsavedWarning = true;
-		discardTarget = to?.url.href ?? null;
-	}
-});
+const unsaved = createUnsavedWarning();
 </script>
 
 <div class="flex flex-1 flex-col overflow-hidden">
@@ -58,23 +49,8 @@ beforeNavigate(({ cancel, to }) => {
 
 	<!-- Scrollable body -->
 	<div class="flex-1 overflow-y-auto px-5 py-5">
-		{#if showUnsavedWarning}
-			<div
-				class="mb-5 flex items-center justify-between rounded border border-amber-200 bg-amber-50 p-3 text-sm text-amber-800 dark:border-amber-800 dark:bg-amber-950/40 dark:text-amber-300"
-			>
-				<span>{m.admin_unsaved_warning()}</span>
-				<button
-					type="button"
-					onclick={() => {
-						isDirty = false;
-						showUnsavedWarning = false;
-						if (discardTarget) goto(discardTarget);
-					}}
-					class="ml-4 shrink-0 font-sans text-xs font-bold tracking-widest text-amber-800 uppercase hover:text-amber-900 dark:text-amber-300"
-				>
-					{m.person_discard_changes()}
-				</button>
-			</div>
+		{#if unsaved.showUnsavedWarning}
+			<UnsavedWarningBanner onDiscard={unsaved.discard} />
 		{/if}
 		{#if form?.error}
 			<div class="mb-5 rounded border border-red-200 bg-red-50 p-3 text-sm text-red-700">
@@ -85,11 +61,11 @@ beforeNavigate(({ cancel, to }) => {
 		<form
 			id="new-group-form"
 			method="POST"
-			use:enhance
-			oninput={() => {
-				isDirty = true;
-				showUnsavedWarning = false;
+			use:enhance={() => async ({ result, update }) => {
+				if (result.type === 'redirect') unsaved.clearOnSuccess();
+				await update();
 			}}
+			oninput={unsaved.markDirty}
 			class="space-y-5"
 		>
 			<!-- Name card -->

frontend/src/routes/admin/groups/new/page.svelte.spec.ts

@@ -0,0 +1,125 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render } from 'vitest-browser-svelte';
+import { page } from 'vitest/browser';
+import Page from './+page.svelte';
+
+const enhanceCaptureRef = vi.hoisted(() => ({ submitFn: undefined as unknown }));
+
+vi.mock('$app/forms', () => ({
+	enhance: (_el: HTMLFormElement, fn?: unknown) => {
+		enhanceCaptureRef.submitFn = fn;
+		return { destroy: vi.fn() };
+	}
+}));
+vi.mock('$app/navigation', () => ({ beforeNavigate: vi.fn(), goto: vi.fn() }));
+
+import { beforeNavigate, goto } from '$app/navigation';
+
+afterEach(cleanup);
+
+type SubmitFn = () => Promise<
+	(opts: {
+		result: { type: string; [key: string]: unknown };
+		update: () => Promise<void>;
+	}) => Promise<void>
+>;
+
+// ─── Unsaved-changes guard ────────────────────────────────────────────────────
+
+describe('Admin new group page – unsaved-changes guard', () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+		enhanceCaptureRef.submitFn = undefined;
+	});
+
+	it('does not show unsaved warning initially', async () => {
+		render(Page, { props: { form: null } });
+		await expect.element(page.getByText(/ungespeicherte Änderungen/i)).not.toBeInTheDocument();
+	});
+
+	it('cancels navigation and shows banner when form is dirty', async () => {
+		render(Page, { props: { form: null } });
+		const [callback] = vi.mocked(beforeNavigate).mock.calls[0];
+
+		document
+			.querySelector<HTMLInputElement>('input[name="name"]')!
+			.dispatchEvent(new InputEvent('input', { bubbles: true }));
+
+		const cancel = vi.fn();
+		callback({ cancel, to: { url: new URL('http://localhost/admin/groups') } });
+
+		expect(cancel).toHaveBeenCalled();
+		await expect.element(page.getByText(/ungespeicherte Änderungen/i)).toBeInTheDocument();
+	});
+
+	it('does not cancel navigation when form is clean', async () => {
+		render(Page, { props: { form: null } });
+		const [callback] = vi.mocked(beforeNavigate).mock.calls[0];
+
+		const cancel = vi.fn();
+		callback({ cancel, to: { url: new URL('http://localhost/admin/groups') } });
+
+		expect(cancel).not.toHaveBeenCalled();
+	});
+
+	it('discard button calls goto with the target URL', async () => {
+		render(Page, { props: { form: null } });
+		const [callback] = vi.mocked(beforeNavigate).mock.calls[0];
+
+		document
+			.querySelector<HTMLInputElement>('input[name="name"]')!
+			.dispatchEvent(new InputEvent('input', { bubbles: true }));
+
+		callback({ cancel: vi.fn(), to: { url: new URL('http://localhost/admin/groups') } });
+
+		await page.getByRole('button', { name: /verwerfen/i }).click();
+
+		expect(vi.mocked(goto)).toHaveBeenCalledWith('http://localhost/admin/groups');
+	});
+
+	it('clears banner when enhance callback receives a redirect result', async () => {
+		render(Page, { props: { form: null } });
+		const [navCallback] = vi.mocked(beforeNavigate).mock.calls[0];
+
+		document
+			.querySelector<HTMLInputElement>('input[name="name"]')!
+			.dispatchEvent(new InputEvent('input', { bubbles: true }));
+
+		navCallback({ cancel: vi.fn(), to: { url: new URL('http://localhost/admin/groups') } });
+		await expect.element(page.getByText(/ungespeicherte Änderungen/i)).toBeInTheDocument();
+
+		const innerFn = await (enhanceCaptureRef.submitFn as SubmitFn)();
+		await innerFn({
+			result: { type: 'redirect', location: '/admin/groups', status: 303 },
+			update: vi.fn().mockResolvedValue(undefined)
+		});
+
+		await expect.element(page.getByText(/ungespeicherte Änderungen/i)).not.toBeInTheDocument();
+
+		const cancel = vi.fn();
+		navCallback({ cancel, to: { url: new URL('http://localhost/admin/groups') } });
+		expect(cancel).not.toHaveBeenCalled();
+	});
+
+	it('keeps banner when enhance callback receives a failure result', async () => {
+		render(Page, { props: { form: null } });
+		const [navCallback] = vi.mocked(beforeNavigate).mock.calls[0];
+
+		document
+			.querySelector<HTMLInputElement>('input[name="name"]')!
+			.dispatchEvent(new InputEvent('input', { bubbles: true }));
+
+		navCallback({ cancel: vi.fn(), to: { url: new URL('http://localhost/admin/groups') } });
+		await expect.element(page.getByText(/ungespeicherte Änderungen/i)).toBeInTheDocument();
+
+		const innerFn = await (enhanceCaptureRef.submitFn as SubmitFn)();
+		await innerFn({
+			result: { type: 'failure', status: 400, data: { error: 'Name bereits vergeben' } },
+			update: vi.fn().mockResolvedValue(undefined)
+		});
+
+		const cancel = vi.fn();
+		navCallback({ cancel, to: { url: new URL('http://localhost/admin/groups') } });
+		expect(cancel).toHaveBeenCalled();
+	});
+});

frontend/src/routes/admin/invites/+page.server.ts

@@ -2,6 +2,7 @@ import { fail } from '@sveltejs/kit';
 import { env } from '$env/dynamic/private';
 import { parseBackendError } from '$lib/shared/errors';
 import type { Actions, PageServerLoad } from './$types';
+import type { components } from '$lib/generated/api';
 
 export interface InviteListItem {
 	id: string;
@@ -17,22 +18,37 @@ export interface InviteListItem {
 	shareableUrl: string;
 }
 
+export type UserGroup = components['schemas']['UserGroup'];
+
 export const load: PageServerLoad = async ({ url, fetch }) => {
 	const status = url.searchParams.get('status') ?? 'active';
 	const apiUrl = env.API_INTERNAL_URL || 'http://localhost:8080';
-	const res = await fetch(`${apiUrl}/api/invites?status=${encodeURIComponent(status)}`);
 
-	if (!res.ok) {
-		const backendError = await parseBackendError(res);
-		return {
-			invites: [] as InviteListItem[],
-			status,
-			loadError: backendError?.code ?? 'INTERNAL_ERROR'
-		};
+	const [invitesRes, groupsRes] = await Promise.all([
+		fetch(`${apiUrl}/api/invites?status=${encodeURIComponent(status)}`),
+		fetch(`${apiUrl}/api/groups`)
+	]);
+
+	let invites: InviteListItem[] = [];
+	let loadError: string | null = null;
+	if (!invitesRes.ok) {
+		const backendError = await parseBackendError(invitesRes);
+		loadError = backendError?.code ?? 'INTERNAL_ERROR';
+	} else {
+		invites = await invitesRes.json();
 	}
 
-	const invites: InviteListItem[] = await res.json();
-	return { invites, status, loadError: null };
+	let groups: UserGroup[] = [];
+	let groupsLoadError: string | null = null;
+	if (!groupsRes.ok) {
+		const backendError = await parseBackendError(groupsRes);
+		groupsLoadError = backendError?.code ?? 'INTERNAL_ERROR';
+	} else {
+		const raw: UserGroup[] = await groupsRes.json();
+		groups = [...raw].sort((a, b) => a.name.localeCompare(b.name));
+	}
+
+	return { invites, status, loadError, groups, groupsLoadError };
 };
 
 export const actions = {
@@ -45,6 +61,7 @@ export const actions = {
 		const prefillLastName = (formData.get('prefillLastName') as string) || undefined;
 		const prefillEmail = (formData.get('prefillEmail') as string) || undefined;
 		const expiresAt = (formData.get('expiresAt') as string) || undefined;
+		const groupIds = formData.getAll('groupIds') as string[];
 
 		const apiUrl = env.API_INTERNAL_URL || 'http://localhost:8080';
 		const res = await fetch(`${apiUrl}/api/invites`, {
@@ -56,7 +73,8 @@ export const actions = {
 				prefillFirstName,
 				prefillLastName,
 				prefillEmail,
-				expiresAt
+				expiresAt,
+				groupIds
 			})
 		});
 

frontend/src/routes/admin/invites/+page.svelte

@@ -2,7 +2,8 @@
 import { enhance } from '$app/forms';
 import { m } from '$lib/paraglide/messages.js';
 import { getErrorMessage } from '$lib/shared/errors';
-import type { InviteListItem } from './+page.server.ts';
+import UserGroupsSection from '$lib/user/UserGroupsSection.svelte';
+import type { InviteListItem, UserGroup } from './+page.server.ts';
 
 let {
 	data,
@@ -12,6 +13,8 @@ let {
 		invites: InviteListItem[];
 		status: string;
 		loadError: string | null;
+		groups: UserGroup[];
+		groupsLoadError: string | null;
 	};
 	form?: {
 		createError?: string;
@@ -253,6 +256,23 @@ function statusIcon(status: string) {
 							class="block w-full border border-line px-3 py-2 font-serif text-sm text-ink focus:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring"
 						/>
 					</div>
+					<div class="sm:col-span-2">
+						<p class="mb-2 font-sans text-xs font-bold tracking-widest text-ink-3 uppercase">
+							{m.admin_new_invite_groups()}
+						</p>
+						{#if data.groupsLoadError}
+							<div
+								role="alert"
+								class="rounded-sm border border-amber-200 bg-amber-50 px-3 py-2 font-sans text-xs text-amber-700"
+							>
+								{m.admin_invite_groups_load_error()}
+							</div>
+						{:else if data.groups.length === 0}
+							<p class="font-sans text-xs text-ink-3 italic">{m.admin_new_invite_no_groups()}</p>
+						{:else}
+							<UserGroupsSection groups={data.groups} />
+						{/if}
+					</div>
 					{#if form?.createError}
 						<div class="font-sans text-xs font-medium text-red-600 sm:col-span-2">
 							{getErrorMessage(form.createError)}

frontend/src/routes/admin/invites/page.server.test.ts

@@ -0,0 +1,155 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('$env/dynamic/private', () => ({
+	env: { API_INTERNAL_URL: 'http://localhost:8080' }
+}));
+
+import { load, actions } from './+page.server';
+import type { UserGroup } from './+page.server';
+
+// PageServerLoad annotates the return as `void | (...)`. This explicit shape avoids
+// the void and the Record<string, any> from the generic constraint.
+type LoadData = {
+	invites: unknown[];
+	status: string;
+	loadError: string | null;
+	groups: UserGroup[];
+	groupsLoadError: string | null;
+};
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyFetch = (...args: any[]) => any;
+
+function mockResponse(ok: boolean, body: unknown, status = 200) {
+	return {
+		ok,
+		status,
+		json: async () => body,
+		text: async () => JSON.stringify(body),
+		headers: new Headers({ 'content-type': 'application/json' })
+	} as unknown as Response;
+}
+
+describe('admin/invites load()', () => {
+	const mockFetch = vi.fn<AnyFetch>();
+
+	beforeEach(() => mockFetch.mockReset());
+
+	function event(status = 'active') {
+		return {
+			url: new URL(`http://localhost/admin/invites?status=${status}`),
+			fetch: mockFetch as unknown as typeof fetch
+			// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		} as any;
+	}
+
+	it('returns groups array alongside invites when both succeed', async () => {
+		mockFetch.mockResolvedValueOnce(mockResponse(true, [])).mockResolvedValueOnce(
+			mockResponse(true, [
+				{ id: 'g-1', name: 'Familie', permissions: ['READ_ALL'] },
+				{ id: 'g-2', name: 'Administratoren', permissions: ['ADMIN'] }
+			])
+		);
+
+		const result = (await load(event())) as LoadData;
+
+		expect(result.groups).toHaveLength(2);
+		expect(result.groupsLoadError).toBeNull();
+	});
+
+	it('returns groups sorted alphabetically by name', async () => {
+		mockFetch.mockResolvedValueOnce(mockResponse(true, [])).mockResolvedValueOnce(
+			mockResponse(true, [
+				{ id: 'g-1', name: 'Zebra', permissions: [] },
+				{ id: 'g-2', name: 'Alfa', permissions: [] },
+				{ id: 'g-3', name: 'Mitte', permissions: [] }
+			])
+		);
+
+		const result = (await load(event())) as LoadData;
+
+		expect(result.groups.map((g) => g.name)).toEqual(['Alfa', 'Mitte', 'Zebra']);
+	});
+
+	it('returns groups: [] and non-null groupsLoadError when groups fetch is non-OK', async () => {
+		mockFetch
+			.mockResolvedValueOnce(mockResponse(true, []))
+			.mockResolvedValueOnce(mockResponse(false, { code: 'FORBIDDEN' }, 403));
+
+		const result = (await load(event())) as LoadData;
+
+		expect(result.groups).toEqual([]);
+		expect(result.groupsLoadError).toBe('FORBIDDEN');
+	});
+
+	it('falls back to INTERNAL_ERROR when groups error body has no code', async () => {
+		mockFetch
+			.mockResolvedValueOnce(mockResponse(true, []))
+			.mockResolvedValueOnce(mockResponse(false, null, 500));
+
+		const result = (await load(event())) as LoadData;
+
+		expect(result.groupsLoadError).toBe('INTERNAL_ERROR');
+	});
+
+	it('fetches invites and groups in parallel (both URLs called)', async () => {
+		mockFetch
+			.mockResolvedValueOnce(mockResponse(true, []))
+			.mockResolvedValueOnce(mockResponse(true, []));
+
+		await load(event());
+
+		expect(mockFetch).toHaveBeenCalledTimes(2);
+		expect(mockFetch).toHaveBeenCalledWith(expect.stringContaining('/api/invites'));
+		expect(mockFetch).toHaveBeenCalledWith(expect.stringContaining('/api/groups'));
+	});
+});
+
+describe('admin/invites create action', () => {
+	const mockFetch = vi.fn<AnyFetch>();
+
+	beforeEach(() => mockFetch.mockReset());
+
+	const successBody = {
+		id: 'inv-1',
+		code: 'ABCDE12345',
+		displayCode: 'ABCDE-12345',
+		status: 'active',
+		revoked: false,
+		useCount: 0,
+		createdAt: '2026-01-01T00:00:00Z',
+		shareableUrl: 'http://localhost/register?code=ABCDE12345'
+	};
+
+	it('includes groupIds array in POST body when checkboxes are checked', async () => {
+		const fd = new FormData();
+		fd.append('groupIds', 'g-1');
+		fd.append('groupIds', 'g-2');
+		mockFetch.mockResolvedValueOnce(mockResponse(true, successBody, 201));
+
+		await actions.create({
+			request: new Request('http://localhost', { method: 'POST', body: fd }),
+			fetch: mockFetch as unknown as typeof fetch
+			// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		} as any);
+
+		const [, init] = mockFetch.mock.calls[0] as [string, RequestInit];
+		const sent = JSON.parse(init.body as string);
+		expect(sent.groupIds).toEqual(['g-1', 'g-2']);
+	});
+
+	it('sends groupIds: [] when no checkboxes are checked', async () => {
+		const fd = new FormData();
+		mockFetch.mockResolvedValueOnce(mockResponse(true, successBody, 201));
+
+		await actions.create({
+			request: new Request('http://localhost', { method: 'POST', body: fd }),
+			fetch: mockFetch as unknown as typeof fetch
+			// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		} as any);
+
+		const [, init] = mockFetch.mock.calls[0] as [string, RequestInit];
+		const sent = JSON.parse(init.body as string);
+		expect(sent.groupIds).toEqual([]);
+	});
+});

frontend/src/routes/admin/invites/page.svelte.test.ts

@@ -7,12 +7,15 @@ afterEach(cleanup);
 
 const makeInvite = (overrides: Record<string, unknown> = {}) => ({
 	id: 'i-1',
+	code: 'XYZ1234567',
 	displayCode: 'XYZ-1234',
 	label: 'Familie',
 	useCount: 0,
 	maxUses: 5,
 	expiresAt: '2027-01-01T00:00:00Z',
+	revoked: false,
 	status: 'active' as string,
+	createdAt: '2025-01-01T00:00:00Z',
 	shareableUrl: 'http://example.com/i/i-1',
 	...overrides
 });
@@ -22,11 +25,15 @@ const baseData = (
 		invites: ReturnType<typeof makeInvite>[];
 		status: string;
 		loadError: string | null;
+		groups: { id: string; name: string; permissions: string[] }[];
+		groupsLoadError: string | null;
 	}> = {}
 ) => ({
 	invites: [],
 	status: 'active',
 	loadError: null,
+	groups: [],
+	groupsLoadError: null,
 	...overrides
 });
 
@@ -253,4 +260,115 @@ describe('admin/invites page', () => {
 		const banner = document.querySelector('.bg-red-50');
 		expect(banner).not.toBeNull();
 	});
+
+	// ─── groups section ───────────────────────────────────────────────────────
+
+	it('shows a groups-load warning banner when data.groupsLoadError is set', async () => {
+		render(AdminInvitesPage, {
+			props: { data: { ...baseData(), groups: [], groupsLoadError: 'INTERNAL_ERROR' } }
+		});
+
+		await page
+			.getByRole('button', { name: /neue einladung/i })
+			.first()
+			.click();
+
+		const banner = document.querySelector('.bg-amber-50');
+		expect(banner).not.toBeNull();
+	});
+
+	it('renders group checkboxes inside the new-invite form when groups are provided', async () => {
+		render(AdminInvitesPage, {
+			props: {
+				data: {
+					...baseData(),
+					groups: [
+						{ id: 'g-1', name: 'Administratoren', permissions: ['ADMIN'] },
+						{ id: 'g-2', name: 'Familie', permissions: ['READ_ALL'] }
+					],
+					groupsLoadError: null
+				}
+			}
+		});
+
+		await page
+			.getByRole('button', { name: /neue einladung/i })
+			.first()
+			.click();
+
+		await expect.element(page.getByRole('checkbox', { name: 'Administratoren' })).toBeVisible();
+		await expect.element(page.getByRole('checkbox', { name: 'Familie' })).toBeVisible();
+	});
+
+	it('group checkbox stays checked after being clicked', async () => {
+		render(AdminInvitesPage, {
+			props: {
+				data: {
+					...baseData(),
+					groups: [{ id: 'g-1', name: 'Familie', permissions: ['READ_ALL'] }],
+					groupsLoadError: null
+				}
+			}
+		});
+
+		await page
+			.getByRole('button', { name: /neue einladung/i })
+			.first()
+			.click();
+
+		const checkbox = page.getByRole('checkbox', { name: 'Familie' });
+		await checkbox.click();
+		await expect.element(checkbox).toBeChecked();
+	});
+
+	it('amber warning banner has role="alert"', async () => {
+		render(AdminInvitesPage, {
+			props: { data: { ...baseData(), groups: [], groupsLoadError: 'INTERNAL_ERROR' } }
+		});
+
+		await page
+			.getByRole('button', { name: /neue einladung/i })
+			.first()
+			.click();
+
+		const alert = document.querySelector('[role="alert"]');
+		expect(alert).not.toBeNull();
+	});
+
+	it('checkbox group fieldset has accessible name from i18n key (not hardcoded German)', async () => {
+		render(AdminInvitesPage, {
+			props: {
+				data: {
+					...baseData(),
+					groups: [{ id: 'g-1', name: 'Familie', permissions: ['READ_ALL'] }],
+					groupsLoadError: null
+				}
+			}
+		});
+
+		await page
+			.getByRole('button', { name: /neue einladung/i })
+			.first()
+			.click();
+
+		// m.admin_new_invite_groups() returns "Gruppen (optional)" in de locale
+		// The hardcoded legend "Gruppen" would not match this accessible name
+		await expect.element(page.getByRole('group', { name: 'Gruppen (optional)' })).toBeVisible();
+	});
+
+	it('shows no checkboxes and no warning when groups list is empty and no error', async () => {
+		render(AdminInvitesPage, {
+			props: { data: { ...baseData(), groups: [], groupsLoadError: null } }
+		});
+
+		await page
+			.getByRole('button', { name: /neue einladung/i })
+			.first()
+			.click();
+
+		expect(document.querySelectorAll('input[name="groupIds"]')).toHaveLength(0);
+		expect(document.querySelector('.bg-amber-50')).toBeNull();
+		// empty-state message visible — "Keine Gruppen vorhanden." in de locale
+		await expect.element(page.getByText(/keine gruppen/i)).toBeVisible();
+	});
 });

frontend/src/routes/admin/system/+page.svelte

@@ -1,19 +1,14 @@
 <script lang="ts">
 import { onDestroy } from 'svelte';
 import { m } from '$lib/paraglide/messages.js';
+import ImportStatusCard from './ImportStatusCard.svelte';
+import type { ImportStatus } from './types.js';
 
 let backfillResult: number | null = $state(null);
 let backfillLoading = $state(false);
 let backfillHashesResult: number | null = $state(null);
 let backfillHashesLoading = $state(false);
 
-type ImportStatus = {
-	state: 'IDLE' | 'RUNNING' | 'DONE' | 'FAILED';
-	message: string;
-	processed: number;
-	startedAt: string | null;
-};
-
 type ThumbnailStatus = {
 	state: 'IDLE' | 'RUNNING' | 'DONE' | 'FAILED';
 	message: string;
@@ -177,47 +172,7 @@ async function backfillFileHashes() {
 		</div>
 
 		<!-- Mass import -->
-		<div class="rounded-sm border border-line bg-surface p-6 shadow-sm">
-			<h2 class="mb-1 font-sans text-sm font-bold text-ink">{m.admin_system_import_heading()}</h2>
-			<p class="mb-4 text-sm text-ink-2">{m.admin_system_import_description()}</p>
-
-			{#if importStatus?.state === 'RUNNING'}
-				<p class="text-sm text-ink-2">{m.admin_system_import_status_running()}</p>
-			{:else if importStatus?.state === 'DONE'}
-				<p class="mb-4 rounded-sm border border-green-200 bg-green-50 p-3 text-sm text-green-700">
-					{m.admin_system_import_status_done({ count: importStatus.processed })}
-				</p>
-				<button
-					data-import-trigger
-					onclick={triggerImport}
-					class="rounded-sm bg-primary px-5 py-2 font-sans text-xs font-bold tracking-widest text-primary-fg uppercase transition-opacity hover:opacity-80"
-				>
-					{m.admin_system_import_btn_retry()}
-				</button>
-			{:else if importStatus?.state === 'FAILED'}
-				<p class="mb-4 rounded-sm border border-red-200 bg-red-50 p-3 text-sm text-red-700">
-					{m.admin_system_import_status_failed({ message: importStatus.message })}
-				</p>
-				<button
-					data-import-trigger
-					onclick={triggerImport}
-					class="rounded-sm bg-primary px-5 py-2 font-sans text-xs font-bold tracking-widest text-primary-fg uppercase transition-opacity hover:opacity-80"
-				>
-					{m.admin_system_import_btn_retry()}
-				</button>
-			{:else}
-				{#if importStatus !== null}
-					<p class="mb-4 text-sm text-ink-2">{m.admin_system_import_status_idle()}</p>
-				{/if}
-				<button
-					data-import-trigger
-					onclick={triggerImport}
-					class="rounded-sm bg-primary px-5 py-2 font-sans text-xs font-bold tracking-widest text-primary-fg uppercase transition-opacity hover:opacity-80"
-				>
-					{m.admin_system_import_btn_start()}
-				</button>
-			{/if}
-		</div>
+		<ImportStatusCard importStatus={importStatus} ontrigger={triggerImport} />
 
 		<!-- Thumbnail backfill -->
 		<div class="rounded-sm border border-line bg-surface p-6 shadow-sm">

frontend/src/routes/admin/system/ImportStatusCard.svelte

@@ -0,0 +1,81 @@
+<script lang="ts">
+import { m } from '$lib/paraglide/messages.js';
+import type { ImportStatus } from './types.js';
+
+let {
+	importStatus,
+	ontrigger
+}: {
+	importStatus: ImportStatus | null;
+	ontrigger: () => void;
+} = $props();
+
+const failureMessage = $derived(
+	importStatus?.statusCode === 'IMPORT_FAILED_NO_SPREADSHEET'
+		? m.admin_system_import_failed_no_spreadsheet()
+		: m.admin_system_import_failed_internal()
+);
+</script>
+
+<div class="rounded-sm border border-line bg-surface p-6 shadow-sm">
+	<h2 class="mb-5 font-sans text-xs font-bold tracking-widest text-ink-3 uppercase">
+		{m.admin_system_import_heading()}
+	</h2>
+	<p class="mb-4 text-sm text-ink-2">{m.admin_system_import_description()}</p>
+
+	{#if importStatus?.state === 'RUNNING'}
+		<div class="mb-4 flex items-center gap-3">
+			<span
+				data-testid="spinner"
+				role="status"
+				aria-label={m.admin_system_import_status_running()}
+				class="inline-block h-5 w-5 animate-spin rounded-full border-2 border-ink-3 border-t-brand-mint motion-reduce:animate-none"
+			></span>
+			<div>
+				<p data-testid="processed-count" class="text-base font-bold text-ink">
+					{importStatus.processed}
+				</p>
+				<p class="font-sans text-xs font-bold tracking-widest text-ink-3 uppercase">
+					{m.admin_system_import_status_running()}
+				</p>
+			</div>
+		</div>
+	{:else if importStatus?.state === 'DONE'}
+		<div class="mb-4 rounded-sm border border-green-200 bg-green-50 p-4 text-green-700">
+			<p data-testid="processed-count" class="text-base font-bold">{importStatus.processed}</p>
+			<p class="font-sans text-xs font-bold tracking-widest text-green-800 uppercase">
+				{m.admin_system_import_status_done_label()}
+			</p>
+			<p class="mt-1 text-xs text-green-800">{m.admin_system_import_status_done()}</p>
+		</div>
+		<button
+			data-import-trigger
+			onclick={ontrigger}
+			class="min-h-[44px] rounded-sm bg-primary px-5 py-2 font-sans text-xs font-bold tracking-widest text-primary-fg uppercase transition-opacity hover:opacity-80"
+		>
+			{m.admin_system_import_btn_retry()}
+		</button>
+	{:else if importStatus?.state === 'FAILED'}
+		<p class="mb-4 rounded-sm border border-red-200 bg-red-50 p-3 text-sm text-red-700">
+			{failureMessage}
+		</p>
+		<button
+			data-import-trigger
+			onclick={ontrigger}
+			class="min-h-[44px] rounded-sm bg-primary px-5 py-2 font-sans text-xs font-bold tracking-widest text-primary-fg uppercase transition-opacity hover:opacity-80"
+		>
+			{m.admin_system_import_btn_retry()}
+		</button>
+	{:else}
+		{#if importStatus !== null}
+			<p class="mb-4 text-sm text-ink-2">{m.admin_system_import_status_idle()}</p>
+		{/if}
+		<button
+			data-import-trigger
+			onclick={ontrigger}
+			class="min-h-[44px] rounded-sm bg-primary px-5 py-2 font-sans text-xs font-bold tracking-widest text-primary-fg uppercase transition-opacity hover:opacity-80"
+		>
+			{m.admin_system_import_btn_start()}
+		</button>
+	{/if}
+</div>

frontend/src/routes/admin/system/ImportStatusCard.svelte.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, it, vi } from 'vitest';
+import { render } from 'vitest-browser-svelte';
+import { m } from '$lib/paraglide/messages.js';
+import ImportStatusCard from './ImportStatusCard.svelte';
+import type { ImportStatus } from './types.js';
+
+const makeStatus = (overrides: Partial<ImportStatus> = {}): ImportStatus => ({
+	state: 'IDLE',
+	statusCode: 'IMPORT_IDLE',
+	processed: 0,
+	startedAt: null,
+	...overrides
+});
+
+describe('ImportStatusCard', () => {
+	it('shows spinner while state is RUNNING', async () => {
+		const { getByTestId } = render(ImportStatusCard, {
+			props: {
+				importStatus: makeStatus({ state: 'RUNNING', statusCode: 'IMPORT_RUNNING', processed: 3 }),
+				ontrigger: () => {}
+			}
+		});
+
+		await expect.element(getByTestId('spinner')).toBeInTheDocument();
+	});
+
+	it('shows processed count at text-base while RUNNING', async () => {
+		const { getByTestId } = render(ImportStatusCard, {
+			props: {
+				importStatus: makeStatus({ state: 'RUNNING', statusCode: 'IMPORT_RUNNING', processed: 7 }),
+				ontrigger: () => {}
+			}
+		});
+
+		await expect.element(getByTestId('processed-count')).toHaveTextContent('7');
+	});
+
+	it('shows processed count while DONE', async () => {
+		const { getByText } = render(ImportStatusCard, {
+			props: {
+				importStatus: makeStatus({ state: 'DONE', statusCode: 'IMPORT_DONE', processed: 42 }),
+				ontrigger: () => {}
+			}
+		});
+
+		await expect.element(getByText('42')).toBeVisible();
+	});
+
+	it('shows no-spreadsheet message when statusCode is IMPORT_FAILED_NO_SPREADSHEET', async () => {
+		const { getByText } = render(ImportStatusCard, {
+			props: {
+				importStatus: makeStatus({
+					state: 'FAILED',
+					statusCode: 'IMPORT_FAILED_NO_SPREADSHEET'
+				}),
+				ontrigger: () => {}
+			}
+		});
+
+		await expect.element(getByText(m.admin_system_import_failed_no_spreadsheet())).toBeVisible();
+	});
+
+	it('shows internal error message when statusCode is IMPORT_FAILED_INTERNAL', async () => {
+		const { getByText } = render(ImportStatusCard, {
+			props: {
+				importStatus: makeStatus({ state: 'FAILED', statusCode: 'IMPORT_FAILED_INTERNAL' }),
+				ontrigger: () => {}
+			}
+		});
+
+		await expect.element(getByText(m.admin_system_import_failed_internal())).toBeVisible();
+	});
+
+	it('shows idle text when importStatus is non-null and state is IDLE', async () => {
+		const { getByText } = render(ImportStatusCard, {
+			props: {
+				importStatus: makeStatus({ state: 'IDLE', statusCode: 'IMPORT_IDLE' }),
+				ontrigger: () => {}
+			}
+		});
+
+		await expect.element(getByText(m.admin_system_import_status_idle())).toBeVisible();
+	});
+
+	it('shows no spinner when importStatus is null', async () => {
+		const { getByTestId } = render(ImportStatusCard, {
+			props: { importStatus: null, ontrigger: () => {} }
+		});
+
+		await expect.element(getByTestId('spinner')).not.toBeInTheDocument();
+	});
+
+	it('calls ontrigger when retry button is clicked in DONE state', async () => {
+		const ontrigger = vi.fn();
+		const { getByRole } = render(ImportStatusCard, {
+			props: {
+				importStatus: makeStatus({ state: 'DONE', statusCode: 'IMPORT_DONE', processed: 5 }),
+				ontrigger
+			}
+		});
+
+		await getByRole('button').click();
+		expect(ontrigger).toHaveBeenCalledOnce();
+	});
+
+	it('calls ontrigger when retry button is clicked in FAILED state', async () => {
+		const ontrigger = vi.fn();
+		const { getByRole } = render(ImportStatusCard, {
+			props: {
+				importStatus: makeStatus({ state: 'FAILED', statusCode: 'IMPORT_FAILED_INTERNAL' }),
+				ontrigger
+			}
+		});
+
+		await getByRole('button').click();
+		expect(ontrigger).toHaveBeenCalledOnce();
+	});
+
+	it('calls ontrigger when start button is clicked in IDLE state', async () => {
+		const ontrigger = vi.fn();
+		const { getByRole } = render(ImportStatusCard, {
+			props: {
+				importStatus: makeStatus({ state: 'IDLE', statusCode: 'IMPORT_IDLE' }),
+				ontrigger
+			}
+		});
+
+		await getByRole('button').click();
+		expect(ontrigger).toHaveBeenCalledOnce();
+	});
+});

frontend/src/routes/admin/system/page.svelte.spec.ts

@@ -163,7 +163,7 @@ describe('Admin system page — mass import card', () => {
 					ok: true,
 					json: async () => ({
 						state: 'FAILED',
-						message: 'Datei nicht gefunden.',
+						statusCode: 'IMPORT_FAILED_NO_SPREADSHEET',
 						processed: 0,
 						startedAt: '2026-01-01T10:00:00'
 					})
@@ -182,7 +182,7 @@ describe('Admin system page — mass import card', () => {
 				})
 		);
 		render(Page, {});
-		await expect.element(page.getByText(/Datei nicht gefunden/i)).toBeInTheDocument();
+		await expect.element(page.getByText(/Keine Tabellendatei gefunden/i)).toBeInTheDocument();
 		await expect.element(page.getByRole('button', { name: /Erneut starten/i })).toBeInTheDocument();
 	});
 });

frontend/src/routes/admin/system/page.svelte.test.ts

@@ -246,7 +246,7 @@ describe('admin/system page', () => {
 				return new Response(
 					JSON.stringify({
 						state: 'FAILED',
-						message: 'database error',
+						statusCode: 'IMPORT_FAILED_INTERNAL',
 						processed: 0,
 						startedAt: null
 					}),
@@ -262,7 +262,7 @@ describe('admin/system page', () => {
 		render(AdminSystemPage, { props: {} });
 
 		await vi.waitFor(() => {
-			expect(document.body.textContent).toContain('database error');
+			expect(document.body.textContent).toContain('Interner Fehler beim Import');
 		});
 	});
 

frontend/src/routes/admin/system/types.ts

@@ -0,0 +1,6 @@
+export type ImportStatus = {
+	state: 'IDLE' | 'RUNNING' | 'DONE' | 'FAILED';
+	statusCode: string;
+	processed: number;
+	startedAt: string | null;
+};

frontend/src/routes/admin/tags/[id]/TagDeleteGuard.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
 import { enhance } from '$app/forms';
 import { m } from '$lib/paraglide/messages.js';
-import { getConfirmService } from '$lib/shared/services/confirm.svelte.js';
+import { getConfirmService } from '$lib/shared/services/confirm.svelte';
 
 type FlatTag = {
 	id: string;

frontend/src/routes/admin/tags/[id]/page.svelte.test.ts

@@ -16,9 +16,6 @@ vi.mock('$app/stores', () => ({
 vi.mock('$lib/shared/services/confirm.svelte', () => ({
 	getConfirmService: () => ({ confirm: async () => false })
 }));
-vi.mock('$lib/shared/services/confirm.svelte.js', () => ({
-	getConfirmService: () => ({ confirm: async () => false })
-}));
 
 vi.mock('$app/navigation', () => ({
 	beforeNavigate: () => {},

frontend/src/routes/admin/users/[id]/page.svelte.test.ts

@@ -5,9 +5,6 @@ import { page } from 'vitest/browser';
 vi.mock('$lib/shared/services/confirm.svelte', () => ({
 	getConfirmService: () => ({ confirm: async () => false })
 }));
-vi.mock('$lib/shared/services/confirm.svelte.js', () => ({
-	getConfirmService: () => ({ confirm: async () => false })
-}));
 
 const { default: AdminUserEditPage } = await import('./+page.svelte');
 

frontend/src/routes/admin/users/new/+page.svelte

@@ -1,24 +1,15 @@
 <script lang="ts">
 import { enhance } from '$app/forms';
-import { beforeNavigate, goto } from '$app/navigation';
 import { m } from '$lib/paraglide/messages.js';
 import UserProfileSection from '$lib/user/UserProfileSection.svelte';
 import UserGroupsSection from '$lib/user/UserGroupsSection.svelte';
 import AccountSection from './AccountSection.svelte';
+import { createUnsavedWarning } from '$lib/shared/hooks/useUnsavedWarning.svelte';
+import UnsavedWarningBanner from '$lib/shared/primitives/UnsavedWarningBanner.svelte';
 
 let { data, form } = $props();
 
-let isDirty = $state(false);
-let showUnsavedWarning = $state(false);
-let discardTarget: string | null = $state(null);
-
-beforeNavigate(({ cancel, to }) => {
-	if (isDirty) {
-		cancel();
-		showUnsavedWarning = true;
-		discardTarget = to?.url.href ?? null;
-	}
-});
+const unsaved = createUnsavedWarning();
 </script>
 
 <div class="flex flex-1 flex-col overflow-hidden">
@@ -44,23 +35,8 @@ beforeNavigate(({ cancel, to }) => {
 
 	<!-- Scrollable body -->
 	<div class="flex-1 overflow-y-auto px-5 py-5">
-		{#if showUnsavedWarning}
-			<div
-				class="mb-5 flex items-center justify-between rounded border border-amber-200 bg-amber-50 p-3 text-sm text-amber-800 dark:border-amber-800 dark:bg-amber-950/40 dark:text-amber-300"
-			>
-				<span>{m.admin_unsaved_warning()}</span>
-				<button
-					type="button"
-					onclick={() => {
-						isDirty = false;
-						showUnsavedWarning = false;
-						if (discardTarget) goto(discardTarget);
-					}}
-					class="ml-4 shrink-0 font-sans text-xs font-bold tracking-widest text-amber-800 uppercase hover:text-amber-900 dark:text-amber-300"
-				>
-					{m.person_discard_changes()}
-				</button>
-			</div>
+		{#if unsaved.showUnsavedWarning}
+			<UnsavedWarningBanner onDiscard={unsaved.discard} />
 		{/if}
 		{#if form?.error}
 			<div class="mb-5 rounded border border-red-200 bg-red-50 p-3 text-sm text-red-700">
@@ -71,11 +47,11 @@ beforeNavigate(({ cancel, to }) => {
 		<form
 			id="new-user-form"
 			method="POST"
-			use:enhance
-			oninput={() => {
-				isDirty = true;
-				showUnsavedWarning = false;
+			use:enhance={() => async ({ result, update }) => {
+				if (result.type === 'redirect') unsaved.clearOnSuccess();
+				await update();
 			}}
+			oninput={unsaved.markDirty}
 			class="space-y-5"
 		>
 			<div class="rounded-sm border border-line bg-surface p-5 shadow-sm">

frontend/src/routes/admin/users/new/page.svelte.spec.ts

@@ -1,9 +1,19 @@
-import { afterEach, describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { cleanup, render } from 'vitest-browser-svelte';
 import { page } from 'vitest/browser';
 import Page from './+page.svelte';
 
-vi.mock('$app/forms', () => ({ enhance: () => () => {} }));
+const enhanceCaptureRef = vi.hoisted(() => ({ submitFn: undefined as unknown }));
+
+vi.mock('$app/forms', () => ({
+	enhance: (_el: HTMLFormElement, fn?: unknown) => {
+		enhanceCaptureRef.submitFn = fn;
+		return { destroy: vi.fn() };
+	}
+}));
+vi.mock('$app/navigation', () => ({ beforeNavigate: vi.fn(), goto: vi.fn() }));
+
+import { beforeNavigate, goto } from '$app/navigation';
 
 const groups = [
 	{ id: 'g1', name: 'Editoren', permissions: ['WRITE_ALL'] },
@@ -20,6 +30,13 @@ const baseData = {
 
 afterEach(cleanup);
 
+type SubmitFn = () => Promise<
+	(opts: {
+		result: { type: string; [key: string]: unknown };
+		update: () => Promise<void>;
+	}) => Promise<void>
+>;
+
 // ─── Rendering ────────────────────────────────────────────────────────────────
 
 describe('Admin new user page – rendering', () => {
@@ -66,3 +83,103 @@ describe('Admin new user page – error display', () => {
 		await expect.element(page.getByText('Ein Fehler ist aufgetreten.')).not.toBeInTheDocument();
 	});
 });
+
+// ─── Unsaved-changes guard ────────────────────────────────────────────────────
+
+describe('Admin new user page – unsaved-changes guard', () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+		enhanceCaptureRef.submitFn = undefined;
+	});
+
+	it('does not show unsaved warning initially', async () => {
+		render(Page, { data: baseData, form: null });
+		await expect.element(page.getByText(/ungespeicherte Änderungen/i)).not.toBeInTheDocument();
+	});
+
+	it('cancels navigation and shows banner when form is dirty', async () => {
+		render(Page, { data: baseData, form: null });
+		const [callback] = vi.mocked(beforeNavigate).mock.calls[0];
+
+		document
+			.querySelector<HTMLInputElement>('input[name="email"]')!
+			.dispatchEvent(new InputEvent('input', { bubbles: true }));
+
+		const cancel = vi.fn();
+		callback({ cancel, to: { url: new URL('http://localhost/admin/users') } });
+
+		expect(cancel).toHaveBeenCalled();
+		await expect.element(page.getByText(/ungespeicherte Änderungen/i)).toBeInTheDocument();
+	});
+
+	it('does not cancel navigation when form is clean', async () => {
+		render(Page, { data: baseData, form: null });
+		const [callback] = vi.mocked(beforeNavigate).mock.calls[0];
+
+		const cancel = vi.fn();
+		callback({ cancel, to: { url: new URL('http://localhost/admin/users') } });
+
+		expect(cancel).not.toHaveBeenCalled();
+	});
+
+	it('discard button calls goto with the target URL', async () => {
+		render(Page, { data: baseData, form: null });
+		const [callback] = vi.mocked(beforeNavigate).mock.calls[0];
+
+		document
+			.querySelector<HTMLInputElement>('input[name="email"]')!
+			.dispatchEvent(new InputEvent('input', { bubbles: true }));
+
+		callback({ cancel: vi.fn(), to: { url: new URL('http://localhost/admin/users') } });
+
+		await page.getByRole('button', { name: /verwerfen/i }).click();
+
+		expect(vi.mocked(goto)).toHaveBeenCalledWith('http://localhost/admin/users');
+	});
+
+	it('clears banner when enhance callback receives a redirect result', async () => {
+		render(Page, { data: baseData, form: null });
+		const [navCallback] = vi.mocked(beforeNavigate).mock.calls[0];
+
+		document
+			.querySelector<HTMLInputElement>('input[name="email"]')!
+			.dispatchEvent(new InputEvent('input', { bubbles: true }));
+
+		navCallback({ cancel: vi.fn(), to: { url: new URL('http://localhost/admin/users') } });
+		await expect.element(page.getByText(/ungespeicherte Änderungen/i)).toBeInTheDocument();
+
+		const innerFn = await (enhanceCaptureRef.submitFn as SubmitFn)();
+		await innerFn({
+			result: { type: 'redirect', location: '/admin/users', status: 303 },
+			update: vi.fn().mockResolvedValue(undefined)
+		});
+
+		await expect.element(page.getByText(/ungespeicherte Änderungen/i)).not.toBeInTheDocument();
+
+		const cancel = vi.fn();
+		navCallback({ cancel, to: { url: new URL('http://localhost/admin/users') } });
+		expect(cancel).not.toHaveBeenCalled();
+	});
+
+	it('keeps banner when enhance callback receives a failure result', async () => {
+		render(Page, { data: baseData, form: null });
+		const [navCallback] = vi.mocked(beforeNavigate).mock.calls[0];
+
+		document
+			.querySelector<HTMLInputElement>('input[name="email"]')!
+			.dispatchEvent(new InputEvent('input', { bubbles: true }));
+
+		navCallback({ cancel: vi.fn(), to: { url: new URL('http://localhost/admin/users') } });
+		await expect.element(page.getByText(/ungespeicherte Änderungen/i)).toBeInTheDocument();
+
+		const innerFn = await (enhanceCaptureRef.submitFn as SubmitFn)();
+		await innerFn({
+			result: { type: 'failure', status: 400, data: { error: 'E-Mail bereits vergeben' } },
+			update: vi.fn().mockResolvedValue(undefined)
+		});
+
+		const cancel = vi.fn();
+		navCallback({ cancel, to: { url: new URL('http://localhost/admin/users') } });
+		expect(cancel).toHaveBeenCalled();
+	});
+});

frontend/src/routes/documents/[id]/+page.svelte

@@ -12,7 +12,7 @@ import { createOcrJob } from '$lib/ocr/useOcrJob.svelte';
 import { createTranscriptionBlocks } from '$lib/document/transcription/useTranscriptionBlocks.svelte';
 import { createFileLoader } from '$lib/document/viewer/useFileLoader.svelte';
 import { scrollToCommentFromQuery } from '$lib/shared/utils/deepLinkScroll';
-import { getConfirmService } from '$lib/shared/services/confirm.svelte.js';
+import { getConfirmService } from '$lib/shared/services/confirm.svelte';
 
 let { data } = $props();
 

frontend/src/routes/documents/[id]/edit/page.svelte.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, vi, afterEach } from 'vitest';
 import { cleanup, render } from 'vitest-browser-svelte';
 
-vi.mock('$lib/shared/services/confirm.svelte.js', () => ({
+vi.mock('$lib/shared/services/confirm.svelte', () => ({
 	getConfirmService: () => ({ confirm: async () => false })
 }));
 

frontend/src/routes/documents/[id]/page.svelte.test.ts

@@ -30,9 +30,6 @@ vi.mock('$app/navigation', () => ({
 vi.mock('$lib/shared/services/confirm.svelte', () => ({
 	getConfirmService: () => ({ confirm: async () => false })
 }));
-vi.mock('$lib/shared/services/confirm.svelte.js', () => ({
-	getConfirmService: () => ({ confirm: async () => false })
-}));
 
 const { default: DocumentDetailPage } = await import('./+page.svelte');
 

frontend/src/routes/hilfe/transkription/+page.svelte

@@ -125,15 +125,3 @@ const klaerungChips = [
 		<p class="font-serif text-sm leading-relaxed text-ink-2">{m.richtlinien_closing_body()}</p>
 	</div>
 </main>
-
-<style>
-@media print {
-	:global(.app-nav) {
-		display: none;
-	}
-
-	@page {
-		margin: 1.5cm;
-	}
-}
-</style>

frontend/src/routes/layout.css

@@ -459,3 +459,34 @@
 		transform: translateX(350%);
 	}
 }
+
+@media print {
+	:global(.app-nav) {
+		display: none;
+	}
+
+	@page {
+		margin: 1.5cm;
+	}
+}
+
+.chronik-fade-in {
+	animation: chronik-fade-in 160ms ease-out;
+}
+
+@keyframes chronik-fade-in {
+	from {
+		opacity: 0;
+		transform: translateY(-4px);
+	}
+	to {
+		opacity: 1;
+		transform: translateY(0);
+	}
+}
+
+@media (prefers-reduced-motion: reduce) {
+	.chronik-fade-in {
+		animation: none;
+	}
+}

frontend/src/routes/layout.svelte.spec.ts

@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { cleanup, render } from 'vitest-browser-svelte';
-import { page, userEvent } from 'vitest/browser';
+import { page } from 'vitest/browser';
 import { createRawSnippet } from 'svelte';
 
 vi.mock('$env/static/public', () => ({ PUBLIC_NOTIFICATION_POLL_MS: '60000' }));
@@ -96,13 +96,13 @@ describe('Layout – user dropdown', () => {
 
 	it('opens dropdown on button click', async () => {
 		render(Layout, { data: makeData(), children: emptySnippet });
-		await page.getByRole('button', { name: /MM/ }).click();
+		((await page.getByRole('button', { name: /MM/ }).element()) as HTMLElement).click();
 		await expect.element(page.getByRole('link', { name: /Profil/i })).toBeInTheDocument();
 	});
 
 	it('profile link points to /profile', async () => {
 		render(Layout, { data: makeData(), children: emptySnippet });
-		await page.getByRole('button', { name: /MM/ }).click();
+		((await page.getByRole('button', { name: /MM/ }).element()) as HTMLElement).click();
 		await expect
 			.element(page.getByRole('link', { name: /Profil/i }))
 			.toHaveAttribute('href', '/profile');
@@ -110,16 +110,16 @@ describe('Layout – user dropdown', () => {
 
 	it('logout button is in the dropdown', async () => {
 		render(Layout, { data: makeData(), children: emptySnippet });
-		await page.getByRole('button', { name: /MM/ }).click();
+		((await page.getByRole('button', { name: /MM/ }).element()) as HTMLElement).click();
 		await expect.element(page.getByRole('button', { name: /Abmelden/i })).toBeInTheDocument();
 	});
 
 	it('closes dropdown when Escape is pressed', async () => {
 		render(Layout, { data: makeData(), children: emptySnippet });
-		const btn = page.getByRole('button', { name: /MM/ });
-		await btn.click();
+		const btnEl = (await page.getByRole('button', { name: /MM/ }).element()) as HTMLElement;
+		btnEl.click();
 		await expect.element(page.getByRole('link', { name: /Profil/i })).toBeInTheDocument();
-		await userEvent.keyboard('{Escape}');
+		btnEl.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
 		await tick();
 		await expect.element(page.getByRole('link', { name: /Profil/i })).not.toBeInTheDocument();
 	});

frontend/src/routes/persons/[id]/edit/NameHistoryEditCard.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
 import { enhance } from '$app/forms';
 import { m } from '$lib/paraglide/messages.js';
-import { getConfirmService } from '$lib/shared/services/confirm.svelte.js';
+import { getConfirmService } from '$lib/shared/services/confirm.svelte';
 
 interface Props {
 	aliases: Array<{

frontend/src/routes/persons/[id]/edit/page.svelte.test.ts

@@ -5,9 +5,6 @@ import { page } from 'vitest/browser';
 vi.mock('$lib/shared/services/confirm.svelte', () => ({
 	getConfirmService: () => ({ confirm: async () => false })
 }));
-vi.mock('$lib/shared/services/confirm.svelte.js', () => ({
-	getConfirmService: () => ({ confirm: async () => false })
-}));
 
 const { default: PersonEditPage } = await import('./+page.svelte');
 

frontend/src/test-setup.ts

@@ -0,0 +1,14 @@
+// Disable SvelteKit hover-prefetch (both data + code) in browser-mode tests.
+// ADR-012 / #553.
+//
+// Hover-prefetch fires real fetch requests for route loader chunks; those
+// requests go through the same Playwright route handler that serves mocked
+// modules. An in-flight prefetch landing after iframe teardown can hit the
+// route handler with a closed birpc channel, raising an unhandled rejection
+// that exits the run with code 1 even when every individual test was green.
+//
+// `data-sveltekit-preload-data="off"` disables loader-data prefetch;
+// `data-sveltekit-preload-code="off"` disables route-code chunk prefetch.
+// Both surfaces can produce late module fetches that hit the route handler.
+document.body.dataset.sveltekitPreloadData = 'off';
+document.body.dataset.sveltekitPreloadCode = 'off';

frontend/vite.config.ts

@@ -1,3 +1,4 @@
+import { sentrySvelteKit } from '@sentry/sveltekit';
 import { paraglideVitePlugin } from '@inlang/paraglide-js';
 import devtoolsJson from 'vite-plugin-devtools-json';
 import tailwindcss from '@tailwindcss/vite';
@@ -33,6 +34,21 @@ export default defineConfig({
 		}
 	},
 	plugins: [
+		sentrySvelteKit({
+			org: 'familienarchiv',
+			project: 'frontend',
+			authToken: process.env.SENTRY_AUTH_TOKEN,
+			sentryUrl: (() => {
+				const dsn = process.env.VITE_SENTRY_DSN;
+				if (!dsn) return undefined;
+				try {
+					return new URL(dsn).origin;
+				} catch {
+					return undefined;
+				}
+			})(),
+			autoUploadSourceMaps: !!process.env.SENTRY_AUTH_TOKEN
+		}),
 		tailwindcss(),
 		sveltekit(),
 		devtoolsJson(),
@@ -77,6 +93,7 @@ export default defineConfig({
 						screenshotDirectory: 'test-results/screenshots',
 						screenshotFailures: true
 					},
+					setupFiles: ['./src/test-setup.ts'],
 					include: ['src/**/*.svelte.{test,spec}.{js,ts}'],
 					exclude: ['src/lib/server/**']
 				}