Add renovate.json

backups/catalog-integrity/pre-fix.json is a one-off database snapshot taken
during an incident, not source. Kept on disk for reference, out of git.

.dockerignore

@@ -13,12 +13,34 @@ package-lock.json
 yarn.lock
 bun.lockb
 .npmrc.bak
-# NOTE: .env is intentionally NOT ignored here — the build loads it (only inside
-# a build RUN layer) to produce NEXT_PUBLIC_* + validated build-time values.
-# It is not copied into the runtime image (the runner stage copies only
-# .next/standalone, public/, and .next/static).
-# .env
+# Installation secrets must never enter any image layer (including migrations).
+.env
+.env.*
+**/.env
+**/.env.*
+!.env.example
+*.pem
+*.key
 *.tsbuildinfo
 # Runtime write targets; bound as RW volumes at runtime (see docker-compose.yml)
 public/nitro-assets
 public/swf
+
+.deploy.lock
+logs
+
+# Other installation data and local tool artifacts
+public/cache
+public/tmp
+db_backup_*.sql
+*.log
+.codex
+.agents
+
+.docker-install
+.docker-install.tmp.*
+.env.install.*
+build-reports
+test-results
+playwright-report
+blob-report

.editorconfig

@@ -0,0 +1,14 @@
+# http://editorconfig.org
+root = true
+
+[*]
+indent_style = tab
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{js,ts,tsx,jsx,json,md}]
+indent_style = space
+indent_size = 2

.env.example

@@ -11,6 +11,12 @@ DATABASE_CONNECT_TIMEOUT_MS=5000
 # --- REDIS (Lightning Fast Caching & Sessions) ---
 REDIS_URL=redis://127.0.0.1:6379?connect_timeout=2
 REDIS_CACHE_TTL_DEFAULT=7200
+# In-process cache entries kept per instance, evicted least-recently-used. Raise
+# it if hot keys are evicted while memory headroom remains (default 2000).
+CACHE_MEMORY_MAX_ENTRIES=2000
+# Renders kept per imaging cache directory, counted as .img/.json pairs. A sweep
+# every 5 minutes brings an over-budget directory back to 90% of this (default 20000).
+IMAGING_CACHE_MAX_ENTRIES=20000
 
 # --- CORE RUNTIME & PERFORMANCE FLAGS ---
 NODE_ENV=production
@@ -23,20 +29,122 @@ HOUSEKEEPING_NEXT_PREVIEW_ENABLED=false
 # --- HOTEL & URLS ---
 HOTEL_NAME=EPIC WEB CONTROL
 APP_URL=http://localhost:3002
-NEXT_PUBLIC_APP_URL=http://localhost:3002
 AUTH_URL=http://localhost:3002
 
 # --- IMAGER ---
-IMAGING_UPSTREAM_URL=http://127.0.0.1:3030/imaging
-NEXT_PUBLIC_IMAGER_URL=http://localhost:3002/imaging
+# Avatar imager: Polaris-imager (avatar-imaging-pixinode) serves /avatarimage on 8082.
+IMAGING_UPSTREAM_URL=http://127.0.0.1:8082/avatarimage
+# Runtime values: changing these only requires recreating the container.
+IMAGER_URL=http://127.0.0.1:8082/avatarimage
+BADGE_URL=/swf/c_images/album1584
+# Legacy NEXT_PUBLIC_IMAGER_URL / NEXT_PUBLIC_BADGE_URL are still read at runtime.
 
 # --- SECURITY & HASHING ---
 AUTH_SECRET=your-super-secret-auth-key-change-this-min-32-chars
 APP_KEY=base64:your-app-key-here=
-CONVERT_PASSWORDS=true
-# CONVERT_PASSWORDS: enables legacy md5/argon2id -> bcrypt upgrade on login.
+# Bcrypt cost factor for new password hashes.
 BCRYPT_COST=12
 
+# --- ANTI-DDOS (app-layer gate, production only) ---
+# On by default in production. Set to "false" to disable (not recommended).
+ANTI_DDOS_ENABLED=true
+# Per-category request thresholds over the given window (per client IP).
+ANTI_DDOS_PAGES_LIMIT=300
+ANTI_DDOS_PAGES_WINDOW_SEC=60
+ANTI_DDOS_API_LIMIT=600
+ANTI_DDOS_API_WINDOW_SEC=60
+ANTI_DDOS_AUTH_LIMIT=20
+ANTI_DDOS_AUTH_WINDOW_SEC=60
+# Whole-site safety valve per window (sheds everything for global_halt_ms when hit).
+ANTI_DDOS_GLOBAL_LIMIT=18000
+ANTI_DDOS_GLOBAL_WINDOW_SEC=60
+ANTI_DDOS_GLOBAL_HALT_MS=10000
+# Violations accumulate inside this window before an IP is hard-blocked.
+ANTI_DDOS_VIOLATION_WINDOW_SEC=600
+ANTI_DDOS_MAX_VIOLATIONS=10
+# Escalation tiers "minViolations:ttlSeconds" — how long an offender stays blocked.
+ANTI_DDOS_BLOCK_TIERS=5:600,20:3600,50:86400
+
+# --- CLOUDFLARE API (automatic edge blocks, optional) ---
+# When set, the anti-DDoS gate automatically mirrors hard-blocked IPs to the
+# zone's IP Access Rules so repeat offenders are dropped at the Cloudflare
+# edge (works on every plan, incl. Free). Token permissions required:
+#   Zone > Zone > Read  and  Zone > Firewall > Edit
+CLOUDFLARE_API_TOKEN=
+CLOUDFLARE_ZONE_ID=
+# Runtime toggle; leave true to auto-create Cloudflare blocks at the block
+# threshold. Also overridable live from the admin panel.
+CLOUDFLARE_AUTO_BLOCK_ENABLED=true
+# Override for tests/staging (production uses the public endpoint by default).
+CLOUDFLARE_API_BASE_URL=https://api.cloudflare.com/client/v4
+
+# --- CROWDSEC API (community reputation auto-block, optional) ---
+# Free CTI API key: https://app.crowdsec.net/ → Settings → CTI API Keys.
+# When set, the anti-DDoS gate checks the community reputation of repeat
+# offenders (CTI GET /smoke/{ip}) and immediately hard-blocks known-bad IPs.
+# Lookups only happen for IPs that already tripped a rate bucket and are
+# cached in Redis for 1h, so quota usage stays minimal.
+CROWDSEC_API_KEY=
+# Runtime toggle for reputation-based auto-blocking (also overridable live
+# from the admin panel). Requires CROWDSEC_API_KEY.
+CROWDSEC_AUTO_BLOCK_ENABLED=true
+# Minimum malevolence score 0-5 (CrowdSec scale; 4-5 = "malicious") before an
+# IP is treated as known-bad. IPs with false-positive tags are never blocked.
+CROWDSEC_BLOCK_SCORE=4
+# How long a CrowdSec-confirmed bad IP stays blocked (seconds).
+CROWDSEC_BLOCK_TTL_SECONDS=86400
+# Endpoint — override only for tests/staging.
+CROWDSEC_CTI_BASE_URL=https://cti.api.crowdsec.net/v2
+# Daily enrichment-call ceiling (freemium plan ≈ 10k/day). Once today's
+# counter reaches it, reputation lookups pause until tomorrow so a spread
+# DDoS cannot silently burn the whole quota. 0 = unlimited.
+CROWDSEC_CTI_DAILY_QUOTA=10000
+# How many new community-reputation blocks within a 5-minute window justify an
+# ops alert (quota/backoff/report alerts all use HEALTH_ALERT_COOLDOWN_MIN).
+CROWDSEC_ALERT_BLOCK_BURST=10
+
+# --- CROWDSEC SIGNAL PUSH (share our blocks back, optional) ---
+# Opt-in: pushes blocked IPs + behaviors to the CrowdSec Central API (CAPI) so
+# the community blocklist protects other members too. Set to "true" to enable.
+# Requires watcher credentials — either set both CROWDSEC_REPORT_MACHINE_ID
+# (48 chars, [A-Za-z0-9]) and CROWDSEC_REPORT_PASSWORD now, or leave them
+# unset and let the app generate a stable pair persisted in Redis automatically.
+CROWDSEC_REPORT_ENABLED=false
+CROWDSEC_REPORT_MACHINE_ID=
+CROWDSEC_REPORT_PASSWORD=
+# Optional: attachment key from https://app.crowdsec.net → Console settings —
+# links our watcher to your account so pushed signals show up there.
+CROWDSEC_REPORT_ENROLL_KEY=
+# Central API base — override only for tests/staging.
+CROWDSEC_CAPI_BASE_URL=https://api.crowdsec.net/v3
+
+# --- CROWDSEC LOCAL (opt-in engine on this Docker host, no proxy changes) ---
+# App-layer LAPI bouncer: the anti-DDoS gate asks the local engine per client
+# IP (short-cached) and blocks ban/captcha decisions before its own buckets.
+# Start everything with `bash cms security`; it writes the key below into .env
+# and starts the CrowdSec engine bound to 127.0.0.1. Set to "true" to load the
+# bouncer without the local engine (not recommended).
+CROWDSEC_LOCAL_ENABLED=false
+# Host access-log directory mounted into the engine for detection (Nginx only).
+CROWDSEC_NGINX_LOG_DIR=/var/log/nginx
+# Change LAPI port AND LAPI URL together when 18080 is already taken.
+CROWDSEC_LAPI_PORT=18080
+CROWDSEC_LAPI_URL=http://127.0.0.1:18080
+# Generated by `bash cms security`; keep in .env, never commit a value.
+CROWDSEC_LAPI_API_KEY=
+# IP blocklist sync (`bash cms security blocklists`): space-separated URLs, by
+# default Spamhaus DROP/EDROP, DShield, CINS, Greensnow, StopForumSpam,
+# blocklist.de, Emerging Threats, abuse.ch Feodo/SSLBL/URLhaus, IPsum,
+# Firehol ipsets and Tor exit nodes. Requires internet to fetch; detection and
+# blocking stay local.
+#CROWDSEC_BLOCKLIST_SOURCES=https://www.spamhaus.org/drop/drop.txt https://example.org/list.txt
+# Expiration for each blocklist decision (re-synced keeps them fresh).
+#CROWDSEC_BLOCKLIST_DURATION=24h
+# Combined cap per sync (safety valve against excessive decisions).
+#CROWDSEC_BLOCKLIST_MAX_DECISIONS=1000000
+# Comma-separated IPs/CIDRs that a sync must always skip (allowlist).
+#CROWDSEC_BLOCKLIST_ALLOW=1.2.3.4,10.0.0.0/8
+
 # --- PATHS ---
 BADGE_UPLOAD_DIR=./public/assets/images/badges
 EMULATOR_JAR_PATH=./emulator/Arcturus.jar
@@ -74,8 +182,8 @@ PAYPAL_API=https://api-m.sandbox.paypal.com
 # --- LOGGING ---
 LOG_LEVEL=error
 
-# --- FLARESOLVERR (Cloudflare bypass for clone sources) ---
-FLARESOLVERR_URL=http://localhost:8191
+# --- BYPARR (Cloudflare bypass for clone sources) ---
+BYPARR_URL=http://localhost:8191
 
 # Catalog Studio export: dedicated clean clone on Beta-3 with Git push credentials.
 CATALOG_GIT_CHECKOUT=

.gitea/workflows/ci.yaml

@@ -2,19 +2,24 @@ name: CI
 
 on:
   push:
-    branches: [main, master]
+    branches: [main, master, "codex/**"]
     tags: ["v*"]
   pull_request:
     branches: [main, master]
   workflow_dispatch:
 
+# Reuse the Playwright browsers that ship with the host runner (snapped to
+# the root HOME cache instead of a fresh per-job HOME) so `playwright install`
+# is a near-instant no-op instead of a ~100s CDN download on every run.
+env:
+  PLAYWRIGHT_BROWSERS_PATH: /opt/ms-playwright
+
 jobs:
   # ─────────────────────────────────────────────
-  # Lint, typecheck & unit tests
-  # Draait op de host (self-hosted) waar Node 26 +
-  # pnpm 11 geïnstalleerd zijn en internet beschikbaar is.
-  # De job-container (docker mode) heeft GEEN outbound
-  # internet, dus we draaien alles direct op de host.
+  # Fast quality gate: toolchain, install, dependabot audit,
+  # lint, i18n contracts & typecheck. No heavy test suites here.
+  # Draait op de host (self-hosted) waar Node 26 + pnpm 11
+  # geïnstalleerd zijn en internet beschikbaar is.
   # ─────────────────────────────────────────────
   check:
     runs-on: self-hosted
@@ -43,7 +48,25 @@ jobs:
       - name: Typecheck
         run: pnpm typecheck
 
-      - name: Test
+  # ─────────────────────────────────────────────
+  # Test suites. Parallel jobs (host runner capacity >= 3) so unit,
+  # integration and UI tests each get a worker instead of running
+  # back-to-back inside the check job (~2min wall-time saving).
+  # ─────────────────────────────────────────────
+  tests-unit:
+    needs: check
+    runs-on: self-hosted
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ gitea.repository }}
+          token: ${{ gitea.token }}
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Unit & coverage tests
         env:
           SKIP_ENV_VALIDATION: 1
           NODE_ENV: test
@@ -53,13 +76,87 @@ jobs:
           BCRYPT_ROUNDS: 4
         run: |
           if [ -x /usr/bin/time ]; then
-            /usr/bin/time -f 'Tests: %e seconds; peak process RSS: %M KiB' pnpm test --maxWorkers=2
+            /usr/bin/time -f 'Tests: %e seconds; peak process RSS: %M KiB' pnpm test:coverage --maxWorkers=4
           else
-            time pnpm test --maxWorkers=2
+            time pnpm test:coverage --maxWorkers=4
           fi
 
-      - name: Knip (unused files/exports)
-        run: pnpm knip
+  tests-integration:
+    needs: check
+    runs-on: self-hosted
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ gitea.repository }}
+          token: ${{ gitea.token }}
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: MariaDB and Redis integration tests
+        run: pnpm test:integration
+
+  tests-ui:
+    needs: check
+    runs-on: self-hosted
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ gitea.repository }}
+          token: ${{ gitea.token }}
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      # Compare against reviewed Linux references; updates are explicit.
+      - name: Install UI test browser
+        run: pnpm exec playwright install chromium
+
+      - name: Accessibility and UI regression checks
+        run: pnpm test:ui
+
+      - name: Upload UI results
+        if: always()
+        uses: https://gitea.com/actions/gitea-upload-artifact@62ac910c5d3dfa85c7cb2df15afe2e342b2407c2
+        with:
+          name: ui-results
+          path: |
+            e2e/ui/__screenshots__/linux/
+            playwright-report/ui/
+            test-results/ui/
+          retention-days: 14
+
+  # Validate branch/PR Docker images before integration into a deployment branch.
+  preflight:
+    needs: [tests-unit, tests-integration, tests-ui]
+    if: gitea.event_name == 'pull_request' || (gitea.event_name == 'push' && startsWith(gitea.ref, 'refs/heads/codex/'))
+    runs-on: self-hosted
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ gitea.repository }}
+          token: ${{ gitea.token }}
+
+      - name: Toolchain check
+        run: node scripts/check-node-toolchain.mjs
+
+      - name: Build and verify isolated candidate
+        shell: bash
+        run: bash scripts/ci-preflight.sh
+
+      - name: Upload preflight news browser results
+        if: always()
+        uses: https://gitea.com/actions/gitea-upload-artifact@62ac910c5d3dfa85c7cb2df15afe2e342b2407c2
+        with:
+          name: preflight-news-browser-results
+          path: |
+            test-results/news-real/
+            playwright-report/news-real/
+          if-no-files-found: warn
+          retention-days: 14
 
   # ─────────────────────────────────────────────
   # Docker build & deploy
@@ -67,7 +164,7 @@ jobs:
   # toegang heeft tot de daemon en volumes.
   # ─────────────────────────────────────────────
   deploy:
-    needs: check
+    needs: [tests-unit, tests-integration, tests-ui]
     if: gitea.event_name == 'push' && (gitea.ref_name == 'main' || gitea.ref_name == 'master')
     runs-on: self-hosted
     steps:
@@ -82,3 +179,23 @@ jobs:
         env:
           DEPLOY_BRANCH: ${{ gitea.ref_name }}
         run: bash scripts/ci-deploy.sh
+
+      - name: Upload isolated news browser results
+        if: always()
+        uses: https://gitea.com/actions/gitea-upload-artifact@62ac910c5d3dfa85c7cb2df15afe2e342b2407c2
+        with:
+          name: news-browser-results
+          path: |
+            test-results/news-real/
+            playwright-report/news-real/
+          if-no-files-found: warn
+          retention-days: 14
+
+      - name: Upload JavaScript size report
+        if: always()
+        uses: https://gitea.com/actions/gitea-upload-artifact@62ac910c5d3dfa85c7cb2df15afe2e342b2407c2
+        with:
+          name: javascript-size-report
+          path: build-reports/
+          if-no-files-found: warn
+          retention-days: 14

.gitea/workflows/renovate.yaml

@@ -1,30 +0,0 @@
-name: Renovate
-on:
-  schedule:
-    - cron: "0 5 * * *" # Every day at 05:00 UTC
-  workflow_dispatch: # Manual trigger
-
-jobs:
-  renovate:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Fix Git safe directory
-        run: "git config --global --add safe.directory '*' && git remote set-url origin https://epicnabbo.nl || true"
-      - name: Install Bash in Alpine
-        run: "if [ -f /etc/alpine-release ]; then apk add --no-cache bash; fi"
-      - name: Self-hosted Renovate
-        run: |
-          set -e
-
-          # Ensure cache dir exists before Docker starts
-          mkdir -p /var/tmp/renovate-cache
-
-          docker run --rm \
-            --user "$(id -u):$(id -g)" \
-            -e RENOVATE_TOKEN="${{ secrets.RENOVATE_TOKEN }}" \
-            -e RENOVATE_AUTODISCOVER=false \
-            -e RENOVATE_REPOSITORIES="${{ gitea.repository }}" \
-            -e RENOVATE_ONBOARDING=false \
-            -e LOG_LEVEL=info \
-            -v /var/tmp/renovate-cache:/tmp/renovate-cache \
-            ghcr.io/renovatebot/renovate:latest

.gitea/workflows/test-runner.yaml

@@ -0,0 +1,17 @@
+name: Gitea Actions Runner Test
+on: [push]
+
+jobs:
+  test-job:
+    runs-on: self-hosted
+    steps:
+      - name: Check Host Environment
+        run: |
+          echo "The v3.5.0 runner works!"
+          echo "Current date/time on VPS:"
+          date
+          echo "Running kernel version:"
+          uname -a
+
+      - name: Test Bash Command
+        run: echo "Greetings from the host runner!"

.gitignore

@@ -6,6 +6,8 @@ node_modules.prev/
 .next-staging/
 next-env.d.ts
 .env
+.env.local
+.env.*.local
 *.tsbuildinfo
 src/generated/
 # Runtime avatar/badge imaging disk cache
@@ -18,7 +20,8 @@ prod.log
 db_backup_*.sql
 
 # Local project documentation
-/docs/
+/docs/*
+!/docs/cms-upgrade-2026-09.md
 
 # Local gitea binary symlink
 gitea
@@ -33,11 +36,25 @@ public/tmp/
 
 # Test coverage reports
 coverage/
-
-# Playwright test artifacts
-test-results/
-playwright-report/
-blob-report/
 .aider*
 
 /public/vendor/tinymce/
+
+# Shared deployment lock (never application source)
+.deploy.lock
+
+# Browser verification artifacts
+test-results/
+playwright-report/
+blob-report/
+
+# Local Docker installation metadata
+.docker-install
+.docker-install.tmp.*
+.env.install.*
+build-reports/
+!/docs/performance-budgets.md
+
+# One-off local snapshots (o.a. catalog-integrity/pre-fix.json): runtime-werk,
+# geen bron. Per map opgeslagen om een incident terug te kunnen lezen.
+backups/

.gitlab-ci.yml

@@ -0,0 +1,33 @@
+image: node:26
+
+stages:
+  - test
+  - build
+
+cache:
+  paths:
+    - node_modules/
+
+before_script:
+  - corepack enable
+  - pnpm install --frozen-lockfile
+
+lint:
+  stage: test
+  script:
+    - pnpm run lint
+
+typecheck:
+  stage: test
+  script:
+    - pnpm run typecheck
+
+test:
+  stage: test
+  script:
+    - pnpm run test
+
+build:
+  stage: build
+  script:
+    - pnpm run build

.husky/pre-commit

@@ -1 +0,0 @@
-pnpm exec lint-staged

.husky/pre-push

@@ -1,2 +0,0 @@
-pnpm typecheck
-pnpm test

.nvmrc

@@ -1 +1 @@
-26.8.1
+26.10.0

Dockerfile

@@ -1,43 +1,65 @@
 # syntax=docker/dockerfile:1
-# node:alpine = latest Node within the supported LTS major (tracks the newest
-# patch automatically; currently v26.x, which satisfies package.json's
-# engines ">=26.8.1 <27").
-FROM node:alpine AS builder
+# Pin the runtime to the supported engine; update both stages deliberately.
+FROM node:26.10.0-alpine AS migrations
 WORKDIR /app
 ENV NEXT_TELEMETRY_DISABLED=1
-# Real release id supplied by CI (ci-deploy.sh) so next.config.ts skips git
-# entirely (there is no .git in the build context). Defaults to "unknown".
-ARG NEXT_DEPLOYMENT_ID="unknown"
-ENV NEXT_DEPLOYMENT_ID="$NEXT_DEPLOYMENT_ID"
-# pnpm install is always pinned to the version in package.json's
-# `packageManager` field (pnpm auto-selects it on install), so this global
-# install only needs to exist as a bootstrap and follows the active major.
-RUN apk add --no-cache git \
-    && npm install -g pnpm@latest
+# Keep the bootstrap aligned with package.json packageManager.
+# The apk cache is persisted in a BuildKit cache mount so git is not
+# re-downloaded on every build.
+RUN --mount=type=cache,target=/var/cache/apk \
+    apk add --no-cache git \
+    && npm install -g [email protected]
+# The pnpm store is kept in a BuildKit cache mount that persists across builds
+# on the builder. This is what stops disk usage from growing unbounded: the
+# downloaded dependency store is shared and reused instead of being copied into
+# a fresh image layer on every build. Unlike an image layer it is also prunable
+# independently, so a hard cap (see ci-deploy.sh) keeps it bounded.
+ENV PNPM_HOME=/pnpm PNPM_STORE=/pnpm/store
 # pnpm-workspace.yaml + .npmrc must be present too: the lockfile records the
 # overrides from pnpm-workspace.yaml, and --frozen-lockfile rejects a build
 # where the workspace config is absent (ERR_PNPM_LOCKFILE_CONFIG_MISMATCH).
 COPY package.json pnpm-lock.yaml* pnpm-workspace.yaml* .npmrc* ./
-# pnpm fetch: download all deps into $PNPM_STORE first, so only the lockfile
-# change (not source changes) invalidates the network-heavy download layer.
-RUN pnpm fetch --ignore-scripts
-RUN pnpm install --frozen-lockfile --ignore-scripts --offline
+# pnpm fetch: download all deps into the shared cache-mounted store.
+RUN --mount=type=cache,target=/pnpm \
+    pnpm fetch --ignore-scripts
+# Install offline from the cache-mounted store; the store itself stays in the
+# build cache between builds.
+RUN --mount=type=cache,target=/pnpm \
+    pnpm install --frozen-lockfile --ignore-scripts --offline
 COPY . .
-RUN pnpm run build
+ARG NEXT_DEPLOYMENT_ID="unknown"
+LABEL org.opencontainers.image.revision="$NEXT_DEPLOYMENT_ID"
+FROM migrations AS builder
+ARG NEXT_DEPLOYMENT_ID="unknown"
+ENV NEXT_DEPLOYMENT_ID="$NEXT_DEPLOYMENT_ID"
+# Fixture values exist only for this build command; production secrets are runtime-only.
+# Cache Next.js build output and webpack caches so rebuilds only redo the
+# changed parts.
+RUN --mount=type=cache,target=/app/.next/cache \
+    DATABASE_URL="mysql://build:[email protected]:9/build" \
+    HOTEL_NAME="Build fixture" APP_URL="http://localhost:3002" \
+    AUTH_SECRET="build-fixture-not-for-runtime-use-000000000000" \
+    pnpm run build \
+    && PERFORMANCE_COMMIT_SHA="$NEXT_DEPLOYMENT_ID" node scripts/performance-report.mjs --output-dir build-reports
 
-FROM node:alpine AS runner
+FROM node:26.10.0-alpine AS runner
+ARG NEXT_DEPLOYMENT_ID="unknown"
+LABEL org.opencontainers.image.revision="$NEXT_DEPLOYMENT_ID"
 WORKDIR /app
 ENV NODE_ENV=production \
     NEXT_TELEMETRY_DISABLED=1 \
     PORT=3002 \
     HOSTNAME=0.0.0.0
-RUN apk add --no-cache tini \
+RUN apk add --no-cache tini curl \
     && addgroup -g 33 -S nextjs && adduser -u 33 -S -G nextjs nextjs \
     && mkdir -p /app/storage /app/public/nitro-assets /app/public/swf /var/www/Gamedata \
     && chown -R 33:33 /app/storage /app/public /var/www/Gamedata
 COPY --from=builder --chown=nextjs:nextjs /app/public ./public
 COPY --from=builder --chown=nextjs:nextjs /app/.next/standalone ./
 COPY --from=builder --chown=nextjs:nextjs /app/.next/static ./.next/static
+COPY --from=builder --chown=nextjs:nextjs /app/build-reports ./build-reports
+COPY --from=builder --chown=nextjs:nextjs /app/drizzle/migrations ./drizzle/migrations
+COPY --chown=nextjs:nextjs scripts/docker-start.mjs ./docker-start.mjs
 USER nextjs
 EXPOSE 3002
 # Self-contained healthcheck so `docker run` (ci-deploy) also gets Docker-level
@@ -45,4 +67,4 @@ EXPOSE 3002
 HEALTHCHECK --interval=30s --timeout=5s --start-period=30s --retries=3 \
     CMD ["node", "-e", "fetch('http://127.0.0.1:'+(process.env.PORT||'3002')+'/api/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
 ENTRYPOINT ["/sbin/tini", "--"]
-CMD ["node", "server.js"]
+CMD ["node", "docker-start.mjs"]

README.md

@@ -10,13 +10,13 @@ Features a premium animated homepage (typewriter hero, floating orbs, scroll cou
 
 | Component       | Version        | Notes                                    |
 | --------------- | -------------- | ---------------------------------------- |
-| Node.js         | 26.8.1         | Current release pinned in `.nvmrc`       |
+| Node.js         | 26.9.0         | Current release pinned in `.nvmrc`       |
 | pnpm            | >= 11.25.0     | Recommended package manager              |
 | npm             | >= 11.x        | Supported alternative                    |
 | yarn            | >= 4.x         | Supported alternative                    |
 | MySQL / MariaDB | 8.0+ / 10.6+   | Shared with the emulator                 |
 | Docker          | 24+            | Optional — for containerized deployment  |
-| DragonflyDB     | 1.x+           | Optional — caching, rate limiting, SSE   |
+| Valkey          | 8.x+           | Optional — caching, rate limiting, SSE   |
 
 ---
 
@@ -73,7 +73,7 @@ HOTEL_NAME=YourHotel
 APP_URL=http://localhost:3002
 ```
 
-See `.env.example` for all optional variables (RCON, email, DragonflyDB, OAuth, PayPal, etc.).
+See `.env.example` for all optional variables (RCON, email, Valkey, OAuth, PayPal, etc.).
 
 ### 4. Run CMS Migrations
 
@@ -137,79 +137,162 @@ pm2 stop next 2>/dev/null || true
 
 # 3. Ensure the write directories are owned by www-data (UID/GID 33) so the
 #    container user can write imports/uploads to them.
-sudo chown -R 33:33 ./public/nitro-assets ./public/swf ./storage
+sudo mkdir -p ./public/nitro-assets ./public/swf ./storage /var/www/Gamedata
+sudo chown -R 33:33 ./public/nitro-assets ./public/swf ./storage /var/www/Gamedata
 
-# 4. Build and start
-docker compose up -d --build
+# 4. Build, migrate and start a release tied to the Git commit.
+# Requires Linux, Bash, Git, flock and Docker Compose v2; no host Node/pnpm.
+bash scripts/docker-update.sh
 
-# 5. Run migrations. The slim runtime image has no source/tsx, so run migrations
-#    on the HOST (against the same database) before/after starting the container.
-pnpm db:migrate          # or: npm run db:migrate / yarn db:migrate
-
-# 6. Check logs
+# 5. Follow logs
 docker compose logs -f cms
 ```
 
-The CMS will be available at `http://localhost:3002`.
+The CMS listens on port 3002 using Linux host networking. Existing database,
+Redis, emulator and shared gamedata services must already be configured.
+Create the mounted directories before installation; do not mount the checkout,
+`.next` or `node_modules` over `/app` inside the production container.
 
-> **Reverse proxy:** This setup is designed to run behind the existing nginx on the host. nginx serves the Nitro/Octane client (`/client/`, `/nitro-client/`) and `/gamedata/` directly from `/var/www/Octane/dist` and `/var/www/Gamedata`, and proxies `/` to the CMS on `127.0.0.1:3002`. Point `APP_URL`/`NEXT_PUBLIC_APP_URL` at the public site URL.
+### Updating a Docker clone
 
-### Automatic Updates
-
-Updating is fully scripted — no need to touch Docker or nginx by hand. The
-script `scripts/docker-update.sh` pulls the latest `main`, runs CMS migrations
-on the host, rebuilds the image, recreates the container and waits for a healthy
-status. It also makes sure a stale host-side PM2 CMS (`pm2 stop next`) stays
-stopped so it can't clash on port 3002.
-
-**Automatically (recommended):** a nightly cron job is already configured on a
-production server that installed this setup. It runs the script every night at
-03:30 and appends to `logs/docker-update.cron.log`:
+From your clone, run:
 
 ```bash
-crontab -e
-# 30 3 * * * /var/www/atom-nexst/scripts/docker-update.sh >> /var/www/atom-nexst/logs/docker-update.cron.log 2>&1
+# Also verifies that your public domain serves the expected commit:
+CMS_PUBLIC_URL=https://your-hotel.example bash scripts/docker-update.sh
 ```
 
-**Manually** — to update right now (same steps as the cron runs):
+The script follows the **current branch's configured Git upstream**. It refuses
+local uncommitted/untracked work, pulls fast-forward only and restarts itself if
+the updater changed. It does not reset or delete local work. Configure the
+upstream to your fork/branch if that is where you receive updates.
+
+It builds a commit-tagged image and runs migrations in the matching builder
+container, using the clone's `.env`; no host dependency installation is needed.
+Only after build and migrations succeed does it recreate the CMS service. It
+compares the running image ID, image revision and `/api/health` release with the
+expected Git commit. With `CMS_PUBLIC_URL`, it also checks the domain through
+your proxy/CDN. A healthy response from another release is an error.
+
+`git pull` alone updates source files, not an existing container. `docker compose
+restart` restarts the same image. `docker compose pull` downloads registry images;
+it does not fetch changes to this Git-built CMS. Use the updater for releases.
+A clone does **not** install an automatic scheduler. If desired, explicitly add a
+cron entry with the absolute path of **your** checkout; keep logs in its `logs`
+directory. Do not configure both CI and Compose updates for the same instance.
+The updater refuses an active `epicnext-cms-app` CI-managed container.
+
+Logs: `logs/docker-update.log`. After cutover, a startup, image or HTTP check
+failure automatically recreates the CMS with its previous image and verifies its
+local HTTP release and database health. The command still returns nonzero: a
+rollback is not a successful update. Recovery uses the current Compose configuration
+and `.env`; it restores application code, not configuration edits or database migrations.
+The previous image must carry a valid release label. First installations have no
+previous release: a failed candidate remains available for diagnosis. A failed
+rollback is explicitly logged with a retained `epicnext-cms:rollback-...` recovery tag.
+Public routing must be checked separately after rollback. SIGKILL or host power loss
+cannot run the rollback handler.
+
+After success, the updater keeps the two most recent distinct releases tracked in
+`logs/docker-release-history.log`. Cleanup only removes older recorded CMS image
+tags, without force; images referenced by other containers (including stopped ones)
+are preserved and retried on later updates. Untracked historical images, build cache,
+other services and persistent volumes are not pruned. Retain the history file between
+updates. Before production migrations, retain your normal database backup.
+
+### Portable images on the Gitea registry
+
+Docker builds no longer load your installation's `.env`. The builder uses disposable
+fixture values; the runtime reads `HOTEL_NAME`, `APP_URL`, `AUTH_SECRET`, database and
+asset settings when the container starts. Missing/invalid required runtime values
+stop startup with the setting names, without printing credentials.
+
+Configure `IMAGER_URL` with the actual avatar renderer endpoint and `BADGE_URL` with
+the badge directory URL (or a local path). The legacy `NEXT_PUBLIC_IMAGER_URL` and
+`NEXT_PUBLIC_BADGE_URL` names remain supported at runtime. If the imager points back
+to the CMS `/imaging` proxy, set `IMAGING_UPSTREAM_URL` to the actual renderer to avoid
+a loop. With no imager configured, the CMS uses Habbo's public renderer. Client
+requests use the existing `/api/imaging/avatar` proxy. Admin badges preserve their
+local `/swf/c_images/album1584` fallback. Public URL resolution uses runtime `APP_URL`.
+After changing `.env`, recreate the container; an image rebuild is not required.
+`NEXT_PUBLIC_CMS_RELEASE` deliberately remains compiled into the image.
+
+### Guided installation from this repository
+
+On a Linux host with Docker Engine, the Compose plugin, Git and `flock` available:
 
 ```bash
-cd /var/www/atom-nexst
-./scripts/docker-update.sh
-# log: logs/docker-update.log
+git clone https://gitlab.epicnabbo.nl/remco/EpicNext-Cms.git
+cd EpicNext-Cms
+bash cms install
 ```
 
-The script aborts safely (exit 1) if the working tree has uncommitted changes so
-a `git pull` can never clobber local edits, and leaves the container running if
-health fails so you can debug it (exit 3). Failed runs are reported in the log;
-an exit of 0 means the CMS is healthy on the new commit.
+The wizard asks for your public URL, delivery method, hotel name, existing database
+connection, Redis and avatar imager. It generates an authentication secret and
+creates `.env` with private permissions. An existing `.env` is preserved; review
+its `APP_URL`, `AUTH_URL`, RCON and optional original Laravel `APP_KEY` when moving
+an existing hotel. This installs the CMS, not the Habbo database, emulator, Redis
+or reverse proxy. Point HTTPS at port 3002 before running the final public check.
+The wizard may request sudo to prepare persistent directories for UID/GID 33;
+it does not recursively change ownership of existing assets.
 
-### Docker Commands
+Choose **prebuilt** to download the images specified by this repository in
+`docker-image.txt`, without entering a registry namespace or commit tag. Choose
+**source** when building your own fork on the installation host. Private packages
+still require `docker login` on that host. Maintainers must update `docker-image.txt`
+if the publication registry or namespace changes.
 
-| Command                                    | Description                          |
-| ------------------------------------------ | ------------------------------------ |
-| `docker compose up -d --build`             | Build and start in background        |
-| `docker compose down`                      | Stop and remove containers           |
-| `docker compose logs -f cms`               | Follow CMS logs                      |
-| `docker compose exec cms sh`               | Open a shell in the CMS container    |
-| `docker compose restart cms`               | Restart the CMS container            |
-| `docker compose pull && docker compose up -d --build` | Update and redeploy     |
-| `pnpm db:migrate` (on the **host**)        | Run database migrations (slim image has no source) |
-| `./scripts/docker-update.sh`               | Full automated update (manual or cron) |
-| `pnpm db:up` / `pnpm db:down`              | Start / stop the `mariadb-turbo` bulk-load container |
+After installation, update with:
 
-### How Package Manager Detection Works
+```bash
+bash cms update
+```
 
-The Dockerfile checks for lockfiles in this order:
+The updater pulls the configured Git upstream, loads `.docker-install`, uses the
+matching application/migration images and verifies the running release locally
+and at the saved public URL. Existing application rollback remains available on a failed cutover;
+database migrations are not reversed.
 
-1. **`pnpm-lock.yaml`** → uses pnpm (fastest, recommended)
-2. **`yarn.lock`** → uses yarn
-3. **`package-lock.json`** → uses npm
-4. **No lockfile** → falls back to `npm install`
+`bash cms install --configure-only` saves configuration without preparing runtime
+directories or starting containers. Neither `.env` nor `.docker-install` is
+committed or sent in Docker build contexts. Existing users of
+`bash scripts/docker-update.sh` retain the previous behavior when no wizard
+profile exists; explicit `CMS_IMAGE_REPOSITORY`/`CMS_PUBLIC_URL` overrides still work.
 
-This means you can use any package manager on your host machine — the Docker build will automatically match.
+Container publication is disabled. CI builds, checks and deploys the CMS, but it does not log in to a registry or upload container images.
 
-> Override the detection explicitly with `docker compose build --build-arg PACKAGE_MANAGER=pnpm` (or `npm` / `yarn`).
+### Diagnose an update that is not visible
+
+```bash
+git rev-parse HEAD
+docker inspect --format '{{.Image}}' epicnext-cms
+docker inspect --format '{{index .Config.Labels "org.opencontainers.image.revision"}}' epicnext-cms
+curl -fsS http://127.0.0.1:3002/api/health
+curl -fsS https://your-hotel.example/api/health
+```
+
+Both HTTP responses must report the expected `release`. `unknown` means the image
+was built without a commit ID. If the local endpoint is current but the public
+one is old, check nginx's upstream, other CMS processes and proxy/CDN caching.
+Health responses must not be cached. The release is compiled into Next.js and
+cannot be changed simply by injecting a new variable into an old container.
+
+### Docker commands
+
+| Command | Purpose |
+| --- | --- |
+| `bash scripts/docker-update.sh` | Pull, build, migrate, recreate and verify |
+| `docker compose logs -f cms` | View CMS logs |
+| `docker compose exec cms sh` | Open a shell in the running CMS |
+| `docker compose restart cms` | Restart the existing release |
+| `docker compose down` | Stop services; does not update code |
+| `pnpm db:up` / `pnpm db:down` | Manage the optional MariaDB service |
+
+For a manual build, export `CMS_RELEASE=$(git rev-parse HEAD)` before
+`docker compose build cms`; deployment and migration verification remain your
+responsibility. Docker uses the committed pnpm lockfile and pinned Node version.
+The build cache can stay enabled: copying changed source invalidates the
+application build layer. Deleting all Docker cache is not an update mechanism.
 
 ### Volumes
 
@@ -235,7 +318,8 @@ Only the CMS (and the optional avatar imager container, see [Avatar Imaging](#av
 **Container user & write permissions:** the CMS container runs as `www-data` (UID/GID 33) by default to match the host owner of `/var/www/Gamedata`. Ensure the other write volumes (`./public/nitro-assets`, `./public/swf`, `./storage`) are also owned by `www-data` on the host:
 
 ```bash
-sudo chown -R 33:33 ./public/nitro-assets ./public/swf ./storage
+sudo mkdir -p ./public/nitro-assets ./public/swf ./storage /var/www/Gamedata
+sudo chown -R 33:33 ./public/nitro-assets ./public/swf ./storage /var/www/Gamedata
 sudo chmod -R o+rX ./public/nitro-assets ./public/swf ./storage
 ```
 
@@ -247,7 +331,7 @@ docker compose build --build-arg RUN_USER=1000
 
 ### Networking
 
-The CMS container runs with `network_mode: host`. This lets the existing `127.0.0.1` references in `.env` keep working against host services — MariaDB (`3306`), DragonflyDB/Redis (`6379`), the emulator RCON/API (`3003`/`3001`) and the avatar imager — without re-writing any environment variables. The container consequently listens **directly on the host's port 3002**, so stop any previous host-side CMS (e.g. `pm2 stop next`) that occupies that port before starting it.
+The CMS container runs with `network_mode: host`. This lets the existing `127.0.0.1` references in `.env` keep working against host services — MariaDB (`3306`), Valkey/Redis (`6379`), the emulator RCON/API (`3003`/`3001`) and the avatar imager — without re-writing any environment variables. The container consequently listens **directly on the host's port 3002**, so stop any previous host-side CMS (e.g. `pm2 stop next`) that occupies that port before starting it.
 
 The **build** also runs on the host network (`build.network: host`) because this host disables Docker iptables (`/etc/docker/daemon.json`: `"iptables": false`), which would otherwise leave build containers without outbound NAT/DNS when fetching packages.
 
@@ -361,28 +445,35 @@ The script sets `FOREIGN_KEY_CHECKS=0` for the session and is safe to interrupt:
 
 ---
 
-## DragonflyDB (Caching, Rate Limiting, SSE)
+## Valkey (Caching, Rate Limiting, SSE)
 
-DragonflyDB is a drop-in, Redis-compatible in-memory datastore. The CMS connects to it via `REDIS_URL` using the `ioredis` client. It is optional: without it the CMS falls back to in-process memory.
+Valkey is a drop-in, Redis-compatible open-source in-memory datastore (successor to Redis OSS). The CMS connects to it via `REDIS_URL` using the `ioredis` client. It is optional: without it the CMS falls back to in-memory memory.
 
 ### Install (Ubuntu/Debian)
 
 ```bash
-curl -fsSL -o /tmp/dragonfly_amd64.deb \
-  https://github.com/dragonflydb/dragonfly/releases/download/v1.40.1/dragonfly_amd64.deb
-apt-get install -y /tmp/dragonfly_amd64.deb
-systemctl enable --now dragonfly
+# Option 1: Package repository (recommended)
+curl -fsSL https://packages.valkey.io/valkey-pgp-key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/valkey-archive-keyring.gpg
+echo "deb [signed-by=/usr/share/keyrings/valkey-archive-keyring.gpg] https://packages.valkey.io/apt $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/valkey.list
+apt-get update && apt-get install -y valkey
+
+# Option 2: Direct .deb download
+curl -fsSL -o /tmp/valkey_amd64.deb \
+  https://github.com/valkey-io/valkey/releases/download/8.1.1/valkey_8.1.1-1_amd64.deb
+apt-get install -y /tmp/valkey_amd64.deb
+
+systemctl enable --now valkey
 ```
 
 ### Configure
 
-Edit `/etc/dragonfly/dragonfly.conf`:
+Edit `/etc/valkey/valkey.conf`:
 
 ```ini
---bind=127.0.0.1
---port=6379
---maxmemory=2gb
---version_check=false
+bind 127.0.0.1
+port 6379
+maxmemory 2gb
+maxmemory-policy allkeys-lru
 ```
 
 ### Point the CMS at it
@@ -529,7 +620,11 @@ The container runs `restart: unless-stopped` and ships a healthcheck that probes
 curl -o avatar.png 'http://127.0.0.1:8082/avatarimage?figure=hr-893-45.hd-600-1.ch-255-66.lg-280-110.sh-295-62&img_format=png&size=l'
 ```
 
-A production issue that this section documents: **the `avatar-imaging-pixinode` image can be removed by a `docker image prune`**, which takes the whole site's avatars offline (502 on `/imaging/*`). Keep the image tagged and re-build it via the commands above if it ever disappears (`docker compose build && docker compose up -d`).
+A production issue that this section documents: **the `avatar-imaging-pixinode` image can be removed by a `docker image prune`**, which used to take the whole site's avatars offline (502 on `/imaging/*`). Keep the image tagged and re-build it via the commands above if it ever disappears (`docker compose build && docker compose up -d`).
+
+### Automatic upstream fallback
+
+Since then the CMS-side avatar proxies (`/api/imaging/avatar` and `/imaging`) are resilient: when the configured upstream (the Polaris container on `8082`) fails or times out, the request is retried against Habbo's public renderer (`https://www.habbo.com/habbo-imaging/avatarimage`), with the `effect` parameter stripped and `img_format` forced to `png`, since the public renderer supports neither. The response is then marked with `X-Imager-Source: primary|fallback` and a shorter `Cache-Control` TTL when served from fallback, so the configured imager is retried soon instead of being masked for hours. No fallback is attempted when the configured upstream already is the Habbo public renderer. As a last line of defence every avatar `<img>` on the site falls back to a grayscale silhouette placeholder instead of a broken-image glyph.
 
 ### Figure string validation (`src/app/api/imaging/avatar/route.ts`)
 
@@ -588,27 +683,380 @@ For bulk-written tables (game-data JSON, imports) a containerized **`mariadb-tur
 
 ### 4. Cache layers (Redis + CDN)
 
-The CMS caches through `cached()` / `cachedQuery()` (`src/lib/cache.ts`): an in-memory fast path with a Redis (DragonflyDB-compatible) fallback and single-flight protection against cache stampedes. Public API routes (home, leaderboard, online count, radio, photos, …) fill Redis keys per route; verify with `redis-cli DBSIZE`. With Cloudflare in front, static and `/imaging/*` responses are additionally cached edge-side (`cf-cache-status`), cutting origin load further.
+The CMS caches through `cached()` / `cachedQuery()` (`src/lib/cache.ts`): an in-memory fast path with a Redis (Valkey-compatible) fallback and single-flight protection against cache stampedes. Public API routes (home, leaderboard, online count, radio, photos, …) fill Redis keys per route; verify with `redis-cli DBSIZE`. With Cloudflare in front, static and `/imaging/*` responses are additionally cached edge-side (`cf-cache-status`), cutting origin load further.
+
+#### nginx micro-cache (edge of the origin)
+
+A short-lived nginx cache sits in front of the origin for an explicit whitelist of
+public API reads. It is configured in `/etc/nginx/sites-enabled/cms.conf` and its
+backends come from `/etc/nginx/snippets/cms_upstream_servers.conf`.
+
+Why nginx and not the app: Next.js emits
+`private, no-cache, no-store, max-age=0, must-revalidate` for dynamic route
+handlers, and its response helper then drops the `Cache-Control` set by
+`publicCacheControl()`. Every one of the whitelisted routes was verified to be
+free of `auth()`, `cookies()`, `headers()` and request data, so the edge may
+cache them on their behalf.
+
+| Class | Endpoints | TTL |
+| --- | --- | --- |
+| 1 | `/api/online`, `/api/online/count` | 10s |
+| 2 | `/api/photos`, `/api/leaderboard`, `/api/radio/current-dj`, `/api/radio/points/leaderboard` | 60s |
+| 3 | `/api/staff`, `/api/teams`, `/api/guilds`, `/api/shop`, `/api/shop/categories`, `/api/values`, `/api/values/categories`, `/api/values/[0-9]+` | 300s |
+
+`/api/radio/shouts` is intentionally excluded: it is live chat.
+
+Three details are easy to get wrong and are worth keeping intact:
+
+- **`proxy_ignore_headers "Cache-Control" "Vary";` is what makes the cache work.**
+  `proxy_hide_header` only strips the header from the response to the client; the
+  cache module has already read the upstream's `no-store` by then and stores
+  nothing. Ignore the upstream directive and let nginx emit a single
+  `Cache-Control` of its own.
+- **`$upstream_status` is empty on a cache HIT** — it is only populated on a MISS.
+  The header map therefore matches both `|2` and the empty-status form, so HITs
+  get the same class as the MISS that stored them. A status-gated map alone sends
+  every HIT down the `default` branch and quietly returns `private`.
+- **A session must never be advertised as `public`.** With a session cookie nginx
+  already refuses to store the response (`proxy_no_cache`), but without the skip
+  flag in the header map the response would still claim `public, s-maxage=...` and
+  Cloudflare could share it. The map keys on
+  `"$cms_cc_class|$cms_skip_cache|$upstream_status"`.
+
+HTML is deliberately **not** cached: `src/app/(site)/page.tsx` performs `auth()`
+with a redirect to `/me` and reads `headers()` for a per-request CSP nonce.
+
+### Files changed for stability and caching
+
+| File | Change |
+| --- | --- |
+| `/etc/nginx/nginx.conf` | `worker_connections 4096`, `multi_accept on`, TLS 1.2/1.3 only, `proxy_cache_path` for the micro-cache |
+| `/etc/nginx/sites-enabled/cms.conf` | single correct `Cache-Control` per path, micro-cache on the whitelist, session/Authorization bypass, SSE block with buffering off, `upstream cms_app` + `proxy_next_upstream` |
+| `/etc/nginx/snippets/cms_upstream_servers.conf` | backend list, rewritten by `ci-deploy.sh` during a cutover |
+| `src/app/api/online/count/stream/route.ts` | `X-Accel-Buffering: no` |
+| `src/app/api/radio/stream/route.ts` | `X-Accel-Buffering: no` |
+| `src/app/api/admin/import/{audit,furni/route,furni/batch,furni/batch-regen,furni/repair-icons}/route.ts` | `X-Accel-Buffering: no` |
+| `src/app/api/admin/studio/nitro-cleanup{,/rebuild}/route.ts` | `X-Accel-Buffering: no` |
+| `scripts/ci-deploy.sh` | resource limits, blue/green cutover, `switch_upstream`, rollback split by cutover state |
+| `deploy.sh` | reduced to a wrapper around `ci-deploy.sh` |
+| `docker-compose.yml` | two replica services from a shared anchor, resource limits, port-aware healthcheck, dead `mariadb-turbo` removed |
+| `src/lib/services/cache-warmup.ts` | corrected a comment that described delays the code never had |
+| `src/lib/ci-deploy.test.ts`, `src/test/ci-deploy-harness.sh` | blue/green coverage; nginx paths are injectable so the in-place path stays tested |
+| `ecosystem.config.cjs` | removed (PM2 supervised no process, and nothing referenced it) |
+
+> The nginx files live on the host only, not in this repository. Rebuilding the
+> host loses the cache configuration — keep a copy under version control if that
+> becomes a real risk.
 
 ---
 
-## Production Deployment (PM2)
+## Cloudflare & Anti-DDoS Protection
 
-```bash
-pnpm build
-pm2 start pnpm --name "next" -- start
-pm2 save
+Two layers work together to keep the origin alive during misuse, floods, and
+repeat-offender attacks:
+
+1. **App-layer gate** (production only) — per-IP request buckets per category
+   (pages / API / auth), a whole-site safety valve, and escalation tiers that
+   temporarily hard-block offending IPs (`src/lib/ddos-guard.ts`).
+   `/api/health` is always exempt so the Docker liveness probe never trips it.
+2. **Automatic Cloudflare edge blocks** (optional, works on every Cloudflare
+   plan including Free) — when the gate hard-blocks an IP, the CMS mirrors the
+   block to the zone's **IP Access Rules** (`src/lib/cloudflare-api.ts`), so a
+   repeat offender is dropped at the Cloudflare edge before it reaches your
+   server. Blocks expire together with the gate's tiered block (a 30s sweep
+   removes them; see `src/instrumentation.ts`).
+
+### Prerequisites
+
+- The domain must actually be **proxied through Cloudflare** (orange cloud) —
+  automatic edge rules can only stop traffic that transits the edge. Restrict
+  direct access to the origin ports (e.g. only allow your server IP(s),
+  Cloudflare IPs, or swap the firewall to 443/80 only) so attackers cannot
+  bypass Cloudflare.
+- A Cloudflare API token with the following zone permissions:
+  - `Zone > Zone > Read`
+  - `Zone > Firewall > Edit`
+  Create one at **My Profile → API Tokens → Create Token** (custom token).
+
+### 1. Environment variables
+
+`.env.example` documents every anti-DDoS / Cloudflare variable. In your real
+`.env`:
+
+```dotenv
+# --- App-layer gate (production only) ---
+ANTI_DDOS_ENABLED=true
+ANTI_DDOS_PAGES_LIMIT=300
+ANTI_DDOS_PAGES_WINDOW_SEC=60
+ANTI_DDOS_API_LIMIT=600
+ANTI_DDOS_API_WINDOW_SEC=60
+ANTI_DDOS_AUTH_LIMIT=20
+ANTI_DDOS_AUTH_WINDOW_SEC=60
+ANTI_DDOS_GLOBAL_LIMIT=18000
+ANTI_DDOS_GLOBAL_WINDOW_SEC=60
+ANTI_DDOS_GLOBAL_HALT_MS=10000
+ANTI_DDOS_VIOLATION_WINDOW_SEC=600
+ANTI_DDOS_MAX_VIOLATIONS=10
+ANTI_DDOS_BLOCK_TIERS=5:600,20:3600,50:86400
+
+# --- Cloudflare API (automatic edge blocks) ---
+CLOUDFLARE_API_TOKEN=<your API token>
+CLOUDFLARE_ZONE_ID=<your zone id — Dashboard → your domain → Overview>
+CLOUDFLARE_AUTO_BLOCK_ENABLED=true
 ```
 
-Restart after updates:
+Credentials live in env only and are never stored in Redis-visible config.
+Restart the container after changing them.
+
+### 2. Verify in the admin panel
+
+Open **DevOps → Anti-DDoS protection**
+(`/admin/devops/antiddos`, requires `settings.view`) and:
+
+- Check the **Cloudflare** card shows the request arrived proxied, and the
+  green **API configured** badge.
+- Click **Verify connection** — it confirms the token can read the zone and
+  shows the zone name.
+- Keep the **Automatically create Cloudflare edge blocks** toggle on.
+- The **Cloudflare edge blocks** card lists every auto-created rule with its
+  remaining TTL; **Remove rule** deletes it — and **Unban** lifts both the
+  host-block and the edge rule in one action.
+
+### 3. Notes
+
+- **Only proxied traffic** is edge-blocked. The gate verifies a request
+  actually transited Cloudflare (`CF-Ray` / `CDN-Loop`); a spoofable
+  `CF-Connecting-IP` alone is never trusted.
+- **Free plan**: IP Access Rules support is plan-independent; the limit is
+  ~300 rules per zone and the 30s sweep keeps expired rules cleaned up.
+- **Distributed botnets**: many unique IPs each under the threshold are shed
+  by the whole-site valve (short global halt) rather than banned one-by-one,
+  which avoids collateral damage to shared IPs.
+- **Volumetric L3/L4 floods** cannot be stopped by application code — for
+  those, keep the domain on Cloudflare's orange cloud so Cloudflare's own
+  always-on DDoS protection absorbs them.
+
+---
+
+## Local CrowdSec Engine (opt-in)
+
+The repository ships a self-contained CrowdSec engine that runs on the same
+Docker host. It runs `crowdsecurity/crowdsec:v1.8.1` in its own Compose project
+and exposes **LAPI only** on `127.0.0.1:18080`. When enabled, the app-layer
+anti-DDoS gate (`src/lib/crowdsec-local.ts`) asks the local LAPI per client IP
+(short-cached) and blocks `ban` / `captcha` decisions before its own rate
+buckets run. No reverse-proxy, Traefik, Cloudflare or firewall configuration is
+changed.
+
+The engine boots in **LAPI-only mode** (`DISABLE_AGENT=true`): it does not
+consume the host Nginx access log and needs no outbound access to
+`crowdsec.net`, which is often blocked on hardened hosts. Combined with
+`DISABLE_ONLINE_API=true` (no CrowdSec Central API) the engine needs no account
+and no inbound internet — blocking comes from the imported blocklists
+(Step 4) and the app's own rate buckets. Re-enable the agent only on a host
+with outbound internet by removing `DISABLE_AGENT: "true"` from
+`deployment/crowdsec/compose.crowdsec.yml`.
+
+### Step 1 — Enable the engine and register the bouncer
 
 ```bash
-git pull
-pnpm install
-pnpm build
-pm2 restart next
+bash cms security
 ```
 
+This generates `CROWDSEC_LAPI_API_KEY` (random 64 hex chars), writes the
+CrowdSec flags into `.env`, starts the engine and registers the `cms` bouncer
+against the local LAPI. The engine does **not** enroll into the CrowdSec
+Central API (`DISABLE_ONLINE_API=true`) and runs without the agent
+(`DISABLE_AGENT=true`), so it never phones home.
+
+### Step 2 — Restart the CMS so it loads the bouncer credentials
+
+A CI-managed `epicnext-cms-app` picks the new `.env` values up on its next
+deployment. For a clone running via the updater:
+
+```bash
+bash cms update --skip-pull
+```
+
+or restart the container directly (`docker compose restart cms`). Without the
+restart the gate has not loaded the LAPI URL/key yet.
+
+### Step 3 — Verify
+
+```bash
+bash cms security status
+```
+
+Expect `CROWDSEC_LOCAL_ENABLED=yes` and `LAPI health: OK (127.0.0.1:18080)`.
+In the admin panel, **DevOps → Anti-DDoS protection** shows live block
+statistics split per origin (`community` vs `local`).
+
+### Step 4 — Stop the engine again (optional)
+
+```bash
+bash cms security disable
+```
+
+Stops the container and sets `CROWDSEC_LOCAL_ENABLED=false`. Volumes and the
+`.env` key are kept.
+
+### Step 5 — Load external IP blocklists (optional)
+
+The engine has no built-in lists, so provide your own via a one-shot sync
+(fetches the sources, replaces every previous `cscli-import` decision):
+
+```bash
+bash cms security blocklists
+```
+
+Defaults: Spamhaus DROP/EDROP, DShield, CINS, Greensnow, StopForumSpam,
+Binary Defense, blocklist.de, Emerging Threats, BruteForceBlocker, abuse.ch
+Feodo/SSLBL, Darklist, Botvrij, IPsum, Firehol ipsets and Tor exit nodes
+(26 sources). URLhaus was removed because its `text_online` feed lists URLs,
+not IPs; a malformed token in it could otherwise expand into a bogus
+huge CIDR. The validator only accepts whole-line bare IPs or proper CIDRs,
+enforces sane prefix bounds and drops reserved/private/loopback space, so a
+bad source entry can never block the origin or internal traffic. The largest
+commercial/crowdsourced lists (AbuseIPDB, MaxMind, Cisco Talos, AlienVault
+OTX) are not included because they require an account or API key; IPsum
+already aggregates ~30 additional feeds. No account is needed, but internet
+access is — only for fetching; detection and blocking remain local. Sync
+hourly as a cron job:
+
+```bash
+bash cms security blocklists-install-cron
+```
+
+Removal: `bash cms security blocklists-uninstall-cron`. Dry-run without
+touching LAPI: `bash cms security blocklists --dry-run`. Override the sources,
+duration, a combined cap or an allowlist in `.env`
+(`CROWDSEC_BLOCKLIST_SOURCES`, `CROWDSEC_BLOCKLIST_DURATION`,
+`CROWDSEC_BLOCKLIST_MAX_DECISIONS`, `CROWDSEC_BLOCKLIST_ALLOW`). Existing
+`cscli-import` decisions are replaced on every sync, so removed entries
+expire.
+
+### Environment variables
+
+| Variable                     | Default                       | Purpose                              |
+| ---------------------------- | ----------------------------- | ------------------------------------ |
+| `CROWDSEC_LOCAL_ENABLED`     | `false`                       | Master switch for the local stack    |
+| `CROWDSEC_LAPI_URL`          | `http://127.0.0.1:18080`      | LAPI endpoint (loopback only)        |
+| `CROWDSEC_LAPI_PORT`         | `18080`                       | Host port the engine maps to LAPI    |
+| `CROWDSEC_LAPI_API_KEY`      | —                             | Bouncer key; required when enabled   |
+| `CROWDSEC_LAPI_TIMEOUT_MS`   | `500`                         | Per-decision request timeout         |
+| `CROWDSEC_LAPI_RETRY_MS`     | `500`                         | Backoff before retrying LAPI         |
+| `CROWDSEC_NGINX_LOG_DIR`     | `/var/log/nginx`              | Access-log directory for the engine  |
+
+### Notes and limitations
+
+- Changing the port means updating `CROWDSEC_LAPI_PORT` **and**
+  `CROWDSEC_LAPI_URL` together, then re-running `bash cms security`.
+- Rotate the key by editing `CROWDSEC_LAPI_API_KEY` in `.env`, running
+  `bash cms security` again (re-registers the bouncer) and restarting the CMS.
+- The gate is **fail-closed at startup** when the feature is enabled without a
+  key (startup aborts with a clear message). At runtime a LAPI network error
+  **fails open** (traffic is allowed, decisions paused); a 403 from LAPI
+  pauses local decisions for 5 minutes.
+- This bouncer is **application-layer**: it sheds known-bad IPs at the CMS
+  process only. It does not drop traffic before the origin, does not protect
+  other host ports/services, and depends on the client IP being trustworthy at
+  the ingress. Keep the upstream protections (Cloudflare IP rules, proxy rate
+  limits) for defense before the origin.
+
+---
+
+## Production Deployment (blue/green)
+
+PM2 is **not** used in production. It is neither started nor supervised here; the
+CMS runs as a single Docker container per replica, started by
+`scripts/ci-deploy.sh`.
+
+```
+git push main
+  └─ Gitea Actions "deploy" job
+       └─ bash scripts/ci-deploy.sh
+            ├─ build image epicnext-cms:<sha>
+            ├─ pnpm db:migrate
+            ├─ start candidate on the idle port   (live replica keeps serving)
+            ├─ health gate + release-hash check + Playwright e2e
+            ├─ switch the nginx upstream, reload  (cutover)
+            └─ stop and retire the previous replica
+```
+
+### Why host ports instead of `--scale`
+
+The containers run with `network_mode: host`, so every replica binds a **host**
+port rather than sharing a published docker port. `docker compose up --scale
+cms=2` therefore cannot work here: the replicas would collide on 3002. Instead
+there are two fixed slots, and each release lands in the idle one:
+
+| Slot | Host port | Container name |
+| --- | --- | --- |
+| A | 3002 | `epicnext-cms-app` |
+| B | 3003 | `epicnext-cms-green` |
+
+`docker-compose.yml` defines both services (`cms`, and `cms-green` behind the
+`green` profile) from one shared YAML anchor so they cannot drift apart. Note
+that the CI deploy path deliberately uses `docker run` rather than compose, so
+the resource limits are declared in **both** places — limits that only existed
+in compose would never apply to a real release.
+
+### The nginx upstream is the switch
+
+nginx does not know about container names; it reads a plain list of backends from
+`/etc/nginx/snippets/cms_upstream_servers.conf`, which `ci-deploy.sh` rewrites
+during the cutover:
+
+```nginx
+upstream cms_app {
+    least_conn;
+    keepalive 32;
+    include /etc/nginx/snippets/cms_upstream_servers.conf;
+}
+```
+
+```
+server 127.0.0.1:3002 max_fails=2 fail_timeout=10s;
+```
+
+`switch_upstream()` writes the new backend, runs `nginx -t`, and only then
+reloads. If the test fails the previous file is restored untouched, so a typo can
+never take the site down.
+
+### Failover between replicas
+
+`max_fails`/`fail_timeout` mark a dead replica as unavailable, but only
+`proxy_next_upstream` actually retries the other one:
+
+```nginx
+proxy_next_upstream error timeout invalid_header http_502 http_503 http_504;
+proxy_next_upstream_tries 2;
+proxy_next_upstream_timeout 10s;
+```
+
+`non_idempotent` is deliberately **absent**, so `POST` is never replayed against
+the second replica — a retried import or write would otherwise apply twice. A
+stream that already emitted events is likewise not resumed elsewhere.
+
+### Resource limits
+
+`--memory=4g --memory-swap=5g --cpus=2 --pids-limit=512` per replica. The limits
+were previously removed ("Next may run unrestricted"); on a shared host that
+means a single leak can starve MariaDB, nginx and Traefik.
+
+> **Watch this on the first heavy import.** The 4 GiB ceiling is not yet
+> exercised by a real bulk import. If the container is OOM-killed during a large
+> furniture import, raise `mem_limit` in `docker-compose.yml` *and* `mem_limit` /
+> `mem_swap_limit` in `scripts/ci-deploy.sh` together.
+
+### Manual deploys
+
+`./deploy.sh` is a thin wrapper around `scripts/ci-deploy.sh`, so a manual
+release and a CI release follow exactly the same path. The previous version
+killed whatever held port 3002 with `fuser -k` and ran `docker compose down`
+before anything new existed — guaranteed downtime on every failed build. The
+branch guard inside `ci-deploy.sh` only accepts `main`/`master`.
+
 ---
 
 ## Scripts
@@ -645,7 +1093,7 @@ pm2 restart next
 | **View Transitions API**       | Native browser transitions between page navigations            |
 | **Lenis Smooth Scroll**        | Fluid, customizable scrolling                                  |
 | **Server-Sent Events**         | Real-time radio now-playing & listeners via SSE                |
-| **DragonflyDB Caching**        | Caches API responses up to 30s in DragonflyDB                  |
+| **Valkey Caching**             | Caches API responses up to 30s in Valkey                     |
 | **RCON (TCP Socket)**          | Live commands to the emulator (credits, badges, kick, ban)     |
 | **Streaming & Suspense**       | Next.js App Router streaming for fast page loads               |
 | **Automatic Image Optimization** | `next/image` with Sharp for resizing and WebP/AVIF          |
@@ -680,7 +1128,7 @@ pm2 restart next
 │   │   ├── auth/              # NextAuth, password hashing, 2FA, SSO tickets
 │   │   ├── services/          # RCON, email, currency, PayPal, alerts
 │   │   ├── db.ts              # Drizzle connection singleton (runtime)
-│   │   ├── redis.ts           # Cache client (ioredis → DragonflyDB)
+│   │   ├── redis.ts           # Cache client (ioredis → Valkey)
 │   │   └── motion.ts          # Framer Motion animation variants
 │   ├── messages/              # i18n translations (en, nl, de, fr, es, it, pt, da, no, sv)
 │   └── env.ts                 # Zod-validated environment schema
@@ -727,16 +1175,16 @@ pnpm jobs:worker    # or: npm run jobs:worker / yarn jobs:worker
 
 Optional OpenAI-powered moderation for comments and guestbook posts. Set `OPENAI_API_KEY`.
 
-### FlareSolverr (Cloudflare Bypass)
+### Byparr (Cloudflare Bypass)
 
-Some clone sources are protected by Cloudflare. FlareSolverr solves these challenges automatically.
+Some clone sources are protected by Cloudflare. Byparr (a FlareSolverr successor) solves these challenges automatically.
 
 ```bash
-docker compose up -d flaresolverr
+docker compose up -d byparr
 ```
 
 ```dotenv
-FLARESOLVERR_URL=http://localhost:8191
+BYPARR_URL=http://localhost:8191
 ```
 
 ### Furniture Import with Auto-Translation

biome.json

@@ -7,7 +7,7 @@
 	},
 	"files": {
 		"ignoreUnknown": false,
-		"includes": ["**", "!setup", "!*.cjs", "!coverage"]
+		"includes": ["**", "!setup", "!*.cjs", "!coverage", "!drizzle/drafts/meta"]
 	},
 	"formatter": {
 		"enabled": true,
@@ -28,6 +28,18 @@
 			}
 		}
 	},
+	"overrides": [
+		{
+			"includes": ["**/*.test.ts", "**/*.test.tsx"],
+			"linter": {
+				"rules": {
+					"suspicious": {
+						"noExplicitAny": "off"
+					}
+				}
+			}
+		}
+	],
 	"css": {
 		"parser": {
 			"tailwindDirectives": true

cms

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+case "${1:-help}" in
+  install) shift; exec bash "$DIR/scripts/docker-install.sh" "$@" ;;
+  update) shift; exec bash "$DIR/scripts/docker-update.sh" "$@" ;;
+  security) shift; exec bash "$DIR/scripts/crowdsec-setup.sh" "$@" ;;
+  help|--help|-h) printf '%s\n' 'bash cms install   Configure and install on a Linux Docker host' 'bash cms update    Update using saved settings; --skip-pull uses checked-out release' 'bash cms security  Configure the opt-in local CrowdSec stack (enable|status|disable|blocklists)' ;;
+  *) echo "Unknown command. Use: bash cms install | update | security" >&2; exit 1 ;;
+esac

deploy.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Handmatige release uitvoeren.
+#
+# Dit script is bewust een dunne wrapper. Het echte werk zit in
+# `scripts/ci-deploy.sh`, want dat is wat Gitea Actions ook draait. Eén deploypad
+# betekent dat een handmatige release niet anders kan werken dan een release uit
+# CI, dus er is geen tweede, slechter onderhouden pad meer.
+#
+# Waarom dit niet meer zelf doet wat het deed:
+#   - `fuser -k 3002/tcp` sloopte de live release bij elke mislukte build;
+#   - `docker compose down` haalde de site omlaag vóórdat er iets nieuws stond;
+#   - de container draait via `docker run` uit ci-deploy.sh, niet via compose, dus
+#     compose beheerde hier nooit de release die er echt draaide.
+#
+# `scripts/ci-deploy.sh` start nu blue/green: de nieuwe release komt op de vrije
+# poort terwijl de live release door blijft draaien, en nginx gaat pas om nadat
+# de kandidaat gezond is en de e2e-test heeft gewonnen.
+set -Eeuo pipefail
+
+deploy_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$deploy_dir"
+
+if [ "${1:-}" = "--help" ] || [ "${1:-}" = "-h" ]; then
+	sed -n '2,20p' "$deploy_dir/deploy.sh" | sed 's/^# \{0,1\}//'
+	exit 0
+fi
+
+# De branch-guard in ci-deploy.sh accepteert alleen main/master, en controleert
+# daarna of de HEAD-commit nog de nieuwste op de remote is. Deployen vanuit een
+# feature-branch kan dus niet per ongeluk; dat was eerder wél mogelijk.
+exec bash "$deploy_dir/scripts/ci-deploy.sh" "$@"

deployment/crowdsec/acquis.d/nginx.yaml

@@ -0,0 +1,4 @@
+filenames:
+  - /var/log/nginx/access.log
+labels:
+  type: nginx

deployment/crowdsec/compose.crowdsec.yml

@@ -0,0 +1,41 @@
+services:
+  crowdsec:
+    image: crowdsecurity/crowdsec:${CROWDSEC_VERSION:-v1.8.1}
+    container_name: epicnext-crowdsec
+    restart: unless-stopped
+    profiles: ["security"]
+    environment:
+      DISABLE_AGENT: "true"
+      BOUNCER_KEY_cms: ${CROWDSEC_LAPI_API_KEY:?CROWDSEC_LAPI_API_KEY must be set}
+      DISABLE_ONLINE_API: "true"
+      GID: "${CROWDSEC_GID:-0}"
+      TZ: "${TZ:-UTC}"
+    ports:
+      - "${CROWDSEC_LAPI_BIND_HOST:-127.0.0.1}:${CROWDSEC_LAPI_PORT:-18080}:8080"
+    volumes:
+      - ./acquis.d:/etc/crowdsec/acquis.d:ro
+      - ${CROWDSEC_NGINX_LOG_DIR:-/var/log/nginx}:/var/log/nginx:ro
+      - crowdsec-config:/etc/crowdsec
+      - crowdsec-data:/var/lib/crowdsec/data
+    security_opt:
+      - no-new-privileges:true
+    pids_limit: 256
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
+    healthcheck:
+      test:
+        [
+          "CMD-SHELL",
+          "wget -q -O - http://127.0.0.1:8080/health >/dev/null 2>&1",
+        ]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 30s
+
+volumes:
+  crowdsec-config:
+  crowdsec-data:

deployment/proxy/cloudflare-ips.conf

@@ -0,0 +1,81 @@
+# Trusted edge networks + live Cloudflare CDN ranges.
+# Managed/regenerated by scripts/cf-ips-sync.sh - do not hand-edit the ranges.
+
+# Topology: Cloudflare -> Traefik (:443, docker bridge proxy_traefik-proxy) ->
+# nginx (:9443) -> CMS. nginx ALSO receives direct connections on :9443 from
+# Cloudflare edges and from the game client (ws.epicnabbo.nl is not proxied).
+
+# nginx only trusts the peers listed here as a source of $remote_addr
+# (via CF-Connecting-IP). Anyone else presenting a CF-Connecting-IP or
+# CF-ray header is spoofing and is rejected in nginx-cms.conf.
+
+# 1 = peer is a trusted edge or internal network (keyed on the raw peer,
+#     unaffected by real_ip rewrites).
+geo $realip_remote_addr $cms_trusted_edge {
+    default 0;
+    127.0.0.0/8 1;                    # localhost (health checks, admin)
+    ::1 1;                            # localhost v6
+    172.22.0.0/16 1;                # Traefik (proxyserver_traefik-proxy)
+    # --- Cloudflare IPv4 ranges (live from cloudflare.com/ips-v4) ---
+    173.245.48.0/20 1;
+    103.21.244.0/22 1;
+    103.22.200.0/22 1;
+    103.31.4.0/22 1;
+    141.101.64.0/18 1;
+    108.162.192.0/18 1;
+    190.93.240.0/20 1;
+    188.114.96.0/20 1;
+    197.234.240.0/22 1;
+    198.41.128.0/17 1;
+    162.158.0.0/15 1;
+    104.16.0.0/13 1;
+    104.24.0.0/14 1;
+    172.64.0.0/13 1;
+    131.0.72.0/22 1;
+    # --- Cloudflare IPv6 ranges (live from cloudflare.com/ips-v6) ---
+    2400:cb00::/32 1;
+    2606:4700::/32 1;
+    2803:f800::/32 1;
+    2405:b500::/32 1;
+    2405:8100::/32 1;
+    2a06:98c0::/29 1;
+    2c0f:f248::/32 1;
+}
+
+# 1 when an UNTRUSTED peer still presents a CF-Connecting-IP header: that is a
+# spoof attempt (only real Cloudflare edges or Traefik may do that lawfully).
+map "$cms_trusted_edge:$http_cf_connecting_ip" $cms_disallow_forwarding {
+    default 0;
+    "~^0:.+" 1;
+}
+
+# Rewrite $remote_addr from CF-Connecting-IP but ONLY for the trusted peers
+# above. Direct game clients (untrusted) keep their real peer address.
+set_real_ip_from 127.0.0.0/8;
+set_real_ip_from ::1;
+set_real_ip_from 172.22.0.0/16;
+set_real_ip_from 173.245.48.0/20;
+set_real_ip_from 103.21.244.0/22;
+set_real_ip_from 103.22.200.0/22;
+set_real_ip_from 103.31.4.0/22;
+set_real_ip_from 141.101.64.0/18;
+set_real_ip_from 108.162.192.0/18;
+set_real_ip_from 190.93.240.0/20;
+set_real_ip_from 188.114.96.0/20;
+set_real_ip_from 197.234.240.0/22;
+set_real_ip_from 198.41.128.0/17;
+set_real_ip_from 162.158.0.0/15;
+set_real_ip_from 104.16.0.0/13;
+set_real_ip_from 104.24.0.0/14;
+set_real_ip_from 172.64.0.0/13;
+set_real_ip_from 131.0.72.0/22;
+set_real_ip_from 2400:cb00::/32;
+set_real_ip_from 2606:4700::/32;
+set_real_ip_from 2803:f800::/32;
+set_real_ip_from 2405:b500::/32;
+set_real_ip_from 2405:8100::/32;
+set_real_ip_from 2a06:98c0::/29;
+set_real_ip_from 2c0f:f248::/32;
+
+real_ip_header CF-Connecting-IP;
+real_ip_recursive off;

deployment/proxy/cms_upstream_servers.conf

@@ -0,0 +1,2 @@
+# Default; ci-deploy.sh (blue/green) herschrijft dit bestand bij elke switch.
+server 127.0.0.1:3002;

deployment/proxy/compose.loopback.yml

@@ -0,0 +1,9 @@
+# Opt in through COMPOSE_FILE in the clone's .env; see docs/operations/docker-installation.md.
+# The base service uses Linux host networking: bind the process, do not add ports.
+services:
+  cms:
+    environment:
+      HOSTNAME: 127.0.0.1
+      PORT: "3002"
+    healthcheck:
+      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3002/api/health').then(r=>{if(!r.ok)process.exit(1)}).catch(()=>process.exit(1))"]

deployment/proxy/nginx-cms.conf

@@ -0,0 +1,528 @@
+# ─── EpicNabbo CMS — nginx site config ───
+# Source of truth: deployment/proxy/nginx-cms.conf in the EpicNext-Cms repo.
+# Installed at /etc/nginx/sites-available/cms.conf by scripts/nginx-sync.sh.
+#
+# Ingeladen binnen http{} uit /etc/nginx/sites-enabled/*.conf.
+#
+# PRINCIPE — één eigenaar per URL-klasse:
+#   * Alleen nginx (dit bestand) mag Cache-Control toevoegen voor routes die
+#     een publieke, gedeelde cache toestaan.
+#   * Alles wat de app zelf (src/proxy.ts) als no-store stuurt, blijft no-store.
+#   * Er is GEEN byte-cache meer (geen proxy_cache_*): de app deed ooit zelf
+#     al single-flight/stale-while-revalidate in src/lib/cache.ts. Daarmee is
+#     "dubbele cache" (nginx HIT naast de app) structureel onmogelijk.
+#   * De headers die hieronder staan zijn de enige Cache-Control die een
+#     client/CDN te zien krijgt; er wordt nooit een tweede toegevoegd.
+
+# ─── Maps (moeten op http level staan) ───
+
+map $request_method $cors_headers {
+    OPTIONS 1;
+    default 0;
+}
+
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    '' close;
+}
+
+# ─── Cachebeleid: één plek die beslist of een antwoord gedeeld mag worden ───
+#
+# Waarom op nginx: Next.js overschrijft `Cache-Control` op dynamische route
+# handlers (next/dist/server/send-response.js weigert een al aanwezige header
+# te overschrijven) en src/proxy.ts zet die paden bovendien op no-store. Deze
+# maps nemen de publieke beslissing daarom expliciet over van de app, zodat
+# browser + CDN daadwerkelijk cachen — met één enkele header.
+
+# Nooit als "publiek" aankondigen als er een sessie aan hangt. NextAuth v5
+# zet `__Secure-authjs.session-token` (en `authjs.*` zonder prefix); de
+# Nitro-client gebruikt een eigen cookie. Elke cookie waarvan de naam op
+# session-token eindigt of met authjs. begint telt als "ingelogd", plus elk
+# Authorization-header. Zo kan een persoonlijke variant nooit publiek worden.
+map $http_cookie $cms_sess_cookie {
+    default            0;
+    "~*session-token=" 1;
+    "~*authjs\."       1;
+}
+
+map $http_authorization $cms_authz_header {
+    default 1;
+    ""      0;
+}
+
+# "1" zodra er ook maar één auth-signaal aanwezig is.
+map "$cms_sess_cookie$cms_authz_header" $cms_skip_cache {
+    default 1;
+    "~^00$" 0;
+}
+
+# Cacheklasse per endpoint. De TTL's komen overeen met wat de app zelf al
+# aangeeft (publicCacheControl in src/lib/api.ts) zodat de edge niets
+# verscherper maakt dan de applicatie toestaat. Klasse 0 = no-store.
+map $uri $cms_cc_class {
+    default 0;
+    # online count wordt door elke pagina en de SSE-stream gepolld
+    ~^/api/online(/count)?$                                                              1;
+    # snel verouderende, maar publieke lijsten
+    ~^/api/(photos|leaderboard|radio/current-dj|radio/points/leaderboard)$                2;
+    # stabiele catalogus- en rosterdata
+    ~^/api/(staff|teams|guilds|shop|values)(/categories|/[0-9]+)?$                        3;
+}
+
+# Eén bron van waarheid: klasse + al dan niet ingelogd. De `|`-scheiding is
+# nginx' string-samenvoeging; `~^1\|0` leest "klasse 1 en niet ingelogd".
+map "$cms_cc_class|$cms_skip_cache" $cms_public_cc {
+    default     "private, no-cache, no-store, max-age=0, must-revalidate";
+    "~^1\|0"    "public, max-age=10, s-maxage=10, stale-while-revalidate=30";
+    "~^2\|0"    "public, max-age=60, s-maxage=60, stale-while-revalidate=180";
+    "~^3\|0"    "public, max-age=300, s-maxage=300, stale-while-revalidate=600";
+}
+
+# ─── Mime fix ───
+types {
+    application/json jsonc;
+}
+
+# ==========================================
+# REDIRECT HTTP -> HTTPS (Poort 9444)
+# ==========================================
+server {
+    listen 9444 default_server;
+    listen [::]:9444 default_server;
+    server_name _;
+
+    location / {
+        return 301 https://$host$request_uri;
+    }
+}
+
+# ==========================================
+# WEBSOCKET GAME SERVER (ws.epicnabbo.nl)
+# ==========================================
+server {
+    listen 9443 ssl;
+    listen [::]:9443 ssl;
+    server_name ws.epicnabbo.nl;
+
+    ssl_certificate /etc/ssl/epicnabbo-backend.pem;
+    ssl_certificate_key /etc/ssl/epicnabbo-backend.key;
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_prefer_server_ciphers off;
+
+    # ─── Trusted Edge Gate ───
+    # Real Cloudflare edges and Traefik are the only peers trusted to supply a
+    # CF-Connecting-IP (see cloudflare-ips.conf). Any other peer that does is
+    # spoofing and is rejected before it reaches the CMS. Legitimate direct
+    # visitors (game client, :9443) never carry that header and pass through
+    # with their real peer address.
+    if ($cms_disallow_forwarding) {
+        return 403;
+    }
+
+    location /health {
+        access_log off;
+        return 200 "OK";
+        add_header Content-Type text/plain;
+    }
+
+    location / {
+        proxy_pass http://127.0.0.1:2096;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+
+# Echt client IP (trusted peers via real_ip, directe clients = eigen peer)
+        proxy_set_header CF-Connecting-IP "";
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $remote_addr;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        proxy_read_timeout 86400s;
+        proxy_send_timeout 86400s;
+    }
+}
+
+# ==========================================
+# MAIN HTTPS SERVER (Poort 9443)
+# ==========================================
+server {
+    listen 9443 ssl reuseport default_server;
+    listen [::]:9443 ssl reuseport default_server;
+    listen 9443 quic reuseport;
+    listen [::]:9443 quic reuseport;
+    http2 on;
+
+    server_name epicnabbo.nl www.epicnabbo.nl;
+
+    ssl_certificate /etc/ssl/epicnabbo-backend.pem;
+    ssl_certificate_key /etc/ssl/epicnabbo-backend.key;
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_prefer_server_ciphers off;
+    ssl_early_data on;
+    add_header Alt-Svc 'h3=":9443"; ma=86400' always;
+
+    index index.html;
+
+    # ─── Security Headers ───
+    add_header X-Frame-Options "SAMEORIGIN" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header X-XSS-Protection "1; mode=block" always;
+    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+    add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
+    add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;
+
+    # ─── Trusted Edge Gate ───
+    # Real Cloudflare edges / Traefik are the only peers allowed to supply a
+    # CF-Connecting-IP (see cloudflare-ips.conf). Any other peer presenting one
+    # is spoofing (direct :9443 traffic), and is rejected before it reaches the
+    # CMS. Legitimate direct visitors never carry that header and pass through
+    # with their real peer address.
+    if ($cms_disallow_forwarding) {
+        return 403;
+    }
+
+    # ─── Client Limits & Timeouts ───
+    client_max_body_size 20m;
+    client_body_buffer_size 16k;
+    client_header_buffer_size 1k;
+    large_client_header_buffers 4 8k;
+    client_body_timeout 12s;
+    client_header_timeout 12s;
+    keepalive_timeout 30s;
+    send_timeout 10s;
+
+# Abuse limits. Deliberately NOT set at server scope: a room load and a page
+    # load are not the same request profile, so each location picks its own zone.
+    # /gamedata/* has no request limit at all — it is a disk cache, so limiting
+    # it only cost players their icons. The page routes carry the budget.
+    limit_conn cms_conn_per_ip 30;
+
+    # Traefik health-check route herstellen
+    location = /health {
+        access_log off;
+        return 200 "OK";
+        add_header Content-Type text/plain;
+    }
+
+    # ─── Statische Bestanden & Assets ───
+    location ^~ /client/ {
+        alias /var/www/Octane/dist/;
+        try_files $uri $uri/ =404;
+        limit_req zone=cms_static_per_ip burst=1000 nodelay;
+
+        location ~* \.(js|json|css|html|wasm|ttf|woff|woff2|gif|webp|png|jpg|jpeg|svg|dat)$ {
+            add_header Cache-Control "public, max-age=2592000";
+            access_log off;
+            add_header Cache-Tag "cms-client";
+            add_header Access-Control-Allow-Origin $http_origin always;
+            add_header Access-Control-Allow-Methods "GET, OPTIONS" always;
+        }
+    }
+
+    location ^~ /nitro-client/ {
+        alias /var/www/Octane/dist/;
+        try_files $uri $uri/ =404;
+        limit_req zone=cms_static_per_ip burst=1000 nodelay;
+
+        location ~* \.(js|json|css|html|wasm|ttf|woff|woff2|gif|webp|png|jpg|jpeg|svg|dat)$ {
+            add_header Cache-Control "public, max-age=2592000";
+            access_log off;
+            add_header Cache-Tag "cms-client";
+            add_header Access-Control-Allow-Origin $http_origin always;
+            add_header Access-Control-Allow-Methods "GET, OPTIONS" always;
+            if ($cors_headers) {
+                add_header Access-Control-Max-Age 1728000;
+                add_header Content-Type "text/plain; charset=utf-8";
+                return 204;
+            }
+        }
+    }
+
+    location = /gamedata { return 301 /gamedata/config/; }
+    location = /gamedata/ { return 301 /gamedata/config/; }
+
+    # ─── Gamedata: vier cache-klassen, want niet alles onder /gamedata/ is
+    # even veranderlijk.
+    #
+    # Dit pad had één regel voor de hele boom: `max-age=604800` (7 dagen). De
+    # Habbo-client haalt FurnitureData.json hier op, dus na een import bleef het
+    # client-side dagenlang de oude versie tonen — een nieuw geïmporteerd
+    # meubel was gewoon onzichtbaar. De purge van de `cms-gamedata`-tag
+    # (edge-cache.ts) raakt alleen de Cloudflare-kopie, niet de browser.
+    #
+    # 1. config/     — FurnitureData.json + de vertaalde bestanden. Verandert
+    #                  bij elke import. Kort, en `must-revalidate` sluit de
+    #                  "stuur uit de cache"-route uit zodat de client na de
+    #                  TTL een 304 vraagt in plaats van de oude body te hergebruiken.
+    # 2. bundled/    — nitro-bundles per sprite. De inhoud kan veranderen zonder
+    #                  dat de bestandsnaam verandert (schalen, repareren), dus
+    #                  ook revalideren, maar minder vaak: ze worden veel vaker
+    #                  opgehaald dan ze worden geschreven.
+    # 3. icons/      — `{classname}_icon.png`. Wordt wél herschreven onder
+    #                  dezelfde naam (repair-icons.ts, herimport), dus ook
+    #                  klasse 4's "nooit herschreven" geldt hier niet. Wel
+    #                  minder vaak dan 2: per uur een must-revalidate is één
+    #                  304 per icon per uur, en een gerepareerd icon is zo
+    #                  binnen een uur zichtbaar in plaats van dagenlang oud.
+    # 4. alles wat overblijft (c_images, album*, clothes, …) — content-addressed
+    #      of per item uniek, nooit herschreven onder dezelfde naam. Blijft lang.
+    location ^~ /gamedata/config/ {
+        alias /var/www/Gamedata/config/;
+        add_header Cache-Control "public, max-age=300, must-revalidate";
+        access_log off;
+        add_header Cache-Tag "cms-gamedata";
+
+        add_header Access-Control-Allow-Origin $http_origin always;
+        add_header Access-Control-Allow-Methods "GET, OPTIONS" always;
+        if ($cors_headers) {
+            add_header Access-Control-Max-Age 1728000;
+            add_header Content-Type "text/plain; charset=utf-8";
+            return 204;
+        }
+        error_page 404 = @gamedata_missing;
+    }
+
+    location ^~ /gamedata/bundled/ {
+        alias /var/www/Gamedata/bundled/;
+        add_header Cache-Control "public, max-age=3600, must-revalidate";
+        access_log off;
+        add_header Cache-Tag "cms-gamedata";
+
+        add_header Access-Control-Allow-Origin $http_origin always;
+        add_header Access-Control-Allow-Methods "GET, OPTIONS" always;
+        if ($cors_headers) {
+            add_header Access-Control-Max-Age 1728000;
+            add_header Content-Type "text/plain; charset=utf-8";
+            return 204;
+        }
+        error_page 404 = @gamedata_missing;
+    }
+
+    location ^~ /gamedata/icons/ {
+        alias /var/www/Gamedata/icons/;
+        add_header Cache-Control "public, max-age=3600, must-revalidate";
+        access_log off;
+        add_header Cache-Tag "cms-gamedata";
+
+        # Geen limit_req: gamedata is schijf-cache, geen CMS-backend. Een
+        # kamerladen vuurt honderden bestanden in één burst af en elke limiet
+        # hier leidde alleen tot zichtbaar gemiste icons.
+
+        add_header Access-Control-Allow-Origin $http_origin always;
+        add_header Access-Control-Allow-Methods "GET, OPTIONS" always;
+        if ($cors_headers) {
+            add_header Access-Control-Max-Age 1728000;
+            add_header Content-Type "text/plain; charset=utf-8";
+            return 204;
+        }
+        error_page 404 = @gamedata_missing;
+    }
+
+    location /gamedata/ {
+        alias /var/www/Gamedata/;
+        add_header Cache-Control "public, max-age=604800";
+        access_log off;
+        add_header Cache-Tag "cms-gamedata";
+
+        add_header Access-Control-Allow-Origin $http_origin always;
+        add_header Access-Control-Allow-Methods "GET, OPTIONS" always;
+        if ($cors_headers) {
+            add_header Access-Control-Max-Age 1728000;
+            add_header Content-Type "text/plain; charset=utf-8";
+            return 204;
+        }
+        error_page 404 = @gamedata_missing;
+    }
+
+    # Een ONTBREKEND gamedata-bestand mag nooit gecacht worden, en daarom
+    # krijgt elke 404 hier een eigen handler.
+    #
+    # Zonder deze handler stuurde nginx op een 404 helemaal geen Cache-Control:
+    # `add_header` geldt zonder `always` alleen voor 2xx/3xx. Cloudflare vond
+    # dan geen expliciete cache-instructie en nam de zone-instelling over:
+    # "Browser Cache TTL = 1 jaar". Gevolg: de 404 kwam terug als
+    # `cache-control: max-age=31536000` met `cf-cache-status: HIT` — dus
+    # vastgezet in de browser van de bezoeker én op de edge. Een icon dat één
+    # keer te vroeg werd opgevraagd (import nog bezig) bleef daarom het hele
+    # jaar een 404, ook nadat het bestand er wél stond. Dat was de "sommige
+    # icons laden wel, sommige niet"-klacht.
+    #
+    # `no-store` (niet een korte TTL): het bestand kan elk moment verschijnen,
+    # dus er is geen enkel venster waarin we een 404 willen vasthouden. De
+    # Cache-Tag blijft meegegeven zodat een al gecachte 404 alsnog te purgen is
+    # via `scripts/cf-purge.sh cms-gamedata`.
+    location @gamedata_missing {
+        add_header Cache-Control "no-store" always;
+        add_header Cache-Tag "cms-gamedata" always;
+        add_header Access-Control-Allow-Origin $http_origin always;
+        add_header Access-Control-Allow-Methods "GET, OPTIONS" always;
+        return 404;
+    }
+
+    location /camera/ {
+        alias /var/www/Camera/;
+        add_header Cache-Control "public, max-age=31536000, immutable";
+        add_header Cache-Tag "cms-camera";
+    }
+
+    location = /favicon.ico { expires 1y; access_log off; log_not_found off; try_files $uri =404; }
+    location = /robots.txt { expires 1d; access_log off; log_not_found off; try_files $uri =404; }
+
+    # ─── Static Next.js Assets ───
+    location /_next/static/ {
+        proxy_pass http://cms_app;
+        proxy_set_header Connection "";
+        proxy_http_version 1.1;
+        # Enige eigenaar: een enkele immutable header; de app-header wordt
+        # altijd verwisseld zodat er nooit twee tegensprekende ontstaan
+        # (ook op 404's).
+        proxy_hide_header Cache-Control;
+        add_header Cache-Control "public, max-age=31536000, immutable";
+    }
+
+    location /_next/data/ {
+        proxy_pass http://cms_app;
+        proxy_set_header Connection "";
+        proxy_http_version 1.1;
+        proxy_hide_header Cache-Control;
+        add_header Cache-Control "public, max-age=0, must-revalidate";
+    }
+
+    # ─── API Proxy's ───
+    location /api/auth/ {
+        proxy_pass http://cms_app;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $remote_addr;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header CF-Connecting-IP "";
+        proxy_set_header Connection "";
+        # Auth is per sessie: nooit cachen, en de app-header onderdrukken zodat
+        # er precies één Cache-Control overblijft.
+        proxy_hide_header Cache-Control;
+        add_header Cache-Control "private, no-cache, no-store, max-age=0, must-revalidate" always;
+    }
+
+    # ─── Publieke API: één gedeelde Cache-Control, geen byte-cache ───
+    #
+    # nginx is de enige plek die hier cacheverantwoordelijkheid heeft: de app
+    # zet dit op no-store (Next-force) en Traefik + Cloudflare voegen niets
+    # toe, dus er is geen tweede laag die met deze header concurreert. De
+    # body zelf wordt NIET tussen-gecachet (geen proxy_cache_*): stampede-
+    # bescherming doet src/lib/cache.ts (in-process single-flight + Redis).
+    # De header zet de TTL voor browser + CDN (10/60/300s + SWR).
+    location ~ ^/api/(?:staff|teams|guilds|photos|leaderboard|online|online/count|shop|shop/categories|values|values/categories|values/[0-9]+|radio/current-dj|radio/points/leaderboard)$ {
+        proxy_pass http://cms_app;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $remote_addr;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header CF-Connecting-IP "";
+        proxy_set_header Connection "";
+
+        proxy_hide_header Cache-Control;
+        add_header Cache-Control $cms_public_cc;
+        # Cloudflare cache-tag: laat de edge precies deze publieke API's cachen
+        # (via een cache-rule) en purge alleen deze tag na een CMS-wijziging.
+        add_header Cache-Tag "cms-public";
+    }
+
+    # ─── SSE / lange streams ───
+    #
+    # Drie dingen moeten kloppen of een EventSource-stroom knapt af:
+    #  1. proxy_buffering off — anders houdt nginx het antwoord vast tot de
+    #     verbinding sluit, dus de browser ziet de stream pas als een blok.
+    #  2. proxy_read_timeout — de default van 60s beëindigt een stroom die
+    #     tijdens een batch-job even stilvalt, waarna de client reconnectt en
+    #     opnieuw 504 krijgt: een reconnect-loop die de app juist belast.
+    #  3. send_timeout — de server-level 10s meet de pauze tussen twee writes.
+    #     Een stream die 25s pingt, of een batch die minuten niets doet, wordt
+    #     daar dus losgekapt. Daarom hier een eigen, ruime waarde.
+    location ~ ^/api/(?:online/count/stream|radio/stream|admin/import/.*|admin/studio/nitro-cleanup.*)$ {
+        proxy_pass http://cms_app;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $remote_addr;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header CF-Connecting-IP "";
+        proxy_set_header Connection "";
+
+        proxy_buffering off;
+        gzip off;
+        chunked_transfer_encoding on;
+        proxy_read_timeout 3600s;
+        proxy_send_timeout 3600s;
+        send_timeout 3600s;
+
+        proxy_hide_header Cache-Control;
+        add_header Cache-Control "private, no-cache, no-store, max-age=0, must-revalidate" always;
+        # Vrijwel elke SSE-route miste dit; zonder de header blijft nginx
+        # alsnog bufferen, ook met proxy_buffering off.
+        add_header X-Accel-Buffering "no" always;
+    }
+
+    location /api/badges/custom {
+        proxy_pass http://127.0.0.1:2096;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $remote_addr;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header CF-Connecting-IP "";
+        proxy_set_header Connection "";
+        # De emulator levert zelf geen Cache-Control; zonder proxy_hide_header
+        # zou de app-header hier een tweede keer worden toegevoegd.
+        proxy_hide_header Cache-Control;
+        add_header Cache-Control "private, no-cache, no-store, max-age=0, must-revalidate" always;
+    }
+
+    # ─── Imaging & media: de app levert de eigen Cache-Control ───
+    # De catch-all hieronder forceert no-store; avatars en uploads zijn
+    # onveranderlijk per sleutel en moeten door de browser gecachet worden.
+    location /api/imaging/ {
+        proxy_pass http://cms_app;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $remote_addr;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header CF-Connecting-IP "";
+        proxy_set_header Connection "";
+        proxy_read_timeout 30s;
+    }
+
+    location /api/media/ {
+        proxy_pass http://cms_app;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $remote_addr;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header CF-Connecting-IP "";
+        proxy_set_header Connection "";
+    }
+
+    # ─── Hoofd-routering ───
+    location / {
+        proxy_pass http://cms_app;
+        limit_req zone=cms_req_per_ip burst=60 nodelay;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $remote_addr;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header CF-Connecting-IP "";
+        proxy_set_header Connection "";
+        # De HTML is per sessie: `auth()` in de homepage-layout stuurt
+        # ingelogde bezoekers door naar /me, en de CSP-nonce is per request.
+        # Dus nooit cachen — maar wel als één enkele, expliciete header.
+        # Zonder proxy_hide_header voeg je hier een tweede, tegensprekende
+        # Cache-Control toe aan degene die Next al meestuurt.
+        proxy_hide_header Cache-Control;
+        add_header Cache-Control "private, no-cache, no-store, max-age=0, must-revalidate" always;
+    }
+}

deployment/proxy/nginx-direct.example.conf

@@ -0,0 +1,43 @@
+# Include at nginx http scope (for example /etc/nginx/conf.d/cms.conf).
+# Mode: browsers connect directly to this nginx, on the CMS Docker host.
+# Replace EVERY hotel.example and both certificate paths before nginx -t.
+# Requires ngx_http_realip_module: $realip_remote_addr keeps the socket peer
+# even when an unrelated global real_ip configuration rewrites $remote_addr.
+server {
+    listen 80;
+    listen [::]:80;
+    server_name hotel.example;
+    if ($host != hotel.example) { return 444; }
+    return 308 https://hotel.example$request_uri;
+}
+
+server {
+    listen 443 ssl;
+    listen [::]:443 ssl;
+    server_name hotel.example;
+    if ($host != hotel.example) { return 444; }
+    ssl_certificate /etc/letsencrypt/live/hotel.example/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/hotel.example/privkey.pem;
+    ssl_protocols TLSv1.2 TLSv1.3;
+    # Studio's authenticated attachment endpoints accept at most 52 MiB.
+    # This ingress allowance includes multipart overhead; application caps remain.
+    client_max_body_size 64m;
+
+    location / {
+        proxy_pass http://127.0.0.1:3002;
+        proxy_http_version 1.1;
+        proxy_set_header Host hotel.example;
+        proxy_set_header X-Forwarded-Host hotel.example;
+        proxy_set_header X-Forwarded-Proto https;
+        proxy_set_header X-Forwarded-Port 443;
+        proxy_set_header X-Forwarded-For $realip_remote_addr;
+        proxy_set_header X-Real-IP $realip_remote_addr;
+        proxy_set_header CF-Connecting-IP "";
+        proxy_set_header X-Real-Client-IP "";
+        proxy_set_header Forwarded "";
+        proxy_set_header Connection "";
+        proxy_buffering off;
+        proxy_read_timeout 300s;
+        proxy_cache off;
+    }
+}

deployment/proxy/nginx-mime.types

@@ -0,0 +1,34 @@
+types {
+    text/html html htm shtml;
+    text/css css;
+    text/xml xml;
+    text/plain txt;
+    application/javascript js mjs;
+    application/json json map;
+    application/ld+json jsonld;
+    application/rss+xml rss;
+    application/wasm wasm;
+    application/xml xsd xsl;
+    font/ttf ttf;
+    font/otf otf;
+    font/woff woff;
+    font/woff2 woff2;
+    image/svg+xml svg svgz;
+    image/bmp bmp;
+    image/gif gif;
+    image/jpeg jpeg jpg;
+    image/png png;
+    image/webp webp;
+    image/avif avif;
+    image/x-icon ico cur;
+    video/mp4 mp4 m4v;
+    video/webm webm;
+    audio/mpeg mp3;
+    audio/ogg ogg;
+    audio/wav wav;
+    application/octet-stream dat bin swf;
+    application/zip zip;
+    application/gzip gz;
+    application/pdf pdf;
+    application/vnd.apple.mpegurl m3u8;
+}

deployment/proxy/nginx-trusted-proxy.example.conf

@@ -0,0 +1,51 @@
+# ALTERNATIVE to nginx-direct.example.conf; never enable both for the same host.
+# Remote edge -> TLS -> this nginx on the CMS host -> loopback CMS.
+# Replace hotel.example/certificate paths and BOTH occurrences of 203.0.113.10/32.
+# The example peer is reserved documentation space, so it permits no real edge.
+# Requires ngx_http_realip_module. The remote edge MUST overwrite X-Forwarded-For
+# with one verified client IP and enforce the public HTTPS/Host configuration.
+geo $realip_remote_addr $cms_trusted_edge {
+    default 0;
+    203.0.113.10/32 1;
+}
+
+server {
+    listen 443 ssl;
+    listen [::]:443 ssl;
+    server_name hotel.example;
+    if ($host != hotel.example) { return 444; }
+    if ($cms_trusted_edge = 0) { return 403; }
+    ssl_certificate /etc/letsencrypt/live/hotel.example/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/hotel.example/privkey.pem;
+    ssl_protocols TLSv1.2 TLSv1.3;
+    client_max_body_size 64m;
+
+    set_real_ip_from 203.0.113.10/32;
+    real_ip_header X-Forwarded-For;
+    real_ip_recursive off;
+
+    location / {
+        proxy_pass http://127.0.0.1:3002;
+        proxy_http_version 1.1;
+        proxy_set_header Host hotel.example;
+        proxy_set_header X-Forwarded-Host hotel.example;
+        proxy_set_header X-Forwarded-Proto https;
+        proxy_set_header X-Forwarded-Port 443;
+        proxy_set_header X-Forwarded-For $remote_addr;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header CF-Connecting-IP "";
+        proxy_set_header X-Real-Client-IP "";
+        proxy_set_header Forwarded "";
+        proxy_set_header Connection "";
+        proxy_buffering off;
+        proxy_read_timeout 300s;
+        proxy_cache off;
+    }
+}
+
+# Cloudflare variant: use this same restricted-edge mode, NOT the direct mode.
+# Replace the documentation peer in BOTH geo/set_real_ip_from lists with the
+# current verified Cloudflare IPv4 AND IPv6 CIDRs, then change real_ip_header to
+# CF-Connecting-IP. Use Full (strict) TLS and review authenticated origin pulls.
+# CF-Connecting-IP is still removed before forwarding to the CMS: nginx sends
+# only its normalized, trusted result in X-Forwarded-For and X-Real-IP.

deployment/proxy/nginx.conf

@@ -0,0 +1,73 @@
+# Canonical nginx config for the EpicNabbo CMS edge.
+# Source of truth: repository deployment/proxy/nginx-cms.conf (the site block)
+# and this file. Installed/synced by scripts/nginx-sync.sh so it cannot be
+# lost again while nginx keeps running on an in-memory copy.
+#
+# Traffic path: Cloudflare -> Traefik (:443) -> nginx (:9443) -> CMS (:3002),
+# with direct Cloudflare-origin and game-client (ws.epicnabbo.nl) connections
+# also terminating on :9443.
+# nginx is the last layer that can still rewrite Cache-Control, so it owns the
+# headers it adds explicitly; everything proxied to the CMS is passed through
+# untouched unless this file says otherwise.
+
+user www-data;
+worker_processes auto;
+# Raise the file-descriptor rlimit for the workers. Must stay <= the master's
+# RLIMIT_NOFILE *hard* limit, otherwise nginx refuses to start with
+# "setrlimit(RLIMIT_NOFILE) failed". Bounded from above by the systemd drop-in
+# /etc/systemd/system/nginx.service.d/override.conf (LimitNOFILE=65536).
+worker_rlimit_nofile 65536;
+pid /run/nginx.pid;
+
+error_log /var/log/nginx/error.log warn;
+
+events {
+    worker_connections 2048;
+    use epoll;
+}
+
+http {
+    include /etc/nginx/mime.types;
+    default_type application/octet-stream;
+
+    # Compression is done once, at the edge (Traefik / Cloudflare). Enabling
+    # gzip here too would double-compress proxied responses and fight Vary.
+    gzip off;
+
+    sendfile on;
+    tcp_nopush on;
+    server_tokens off;
+    keepalive_timeout 30s;
+
+    client_max_body_size 64m;
+    client_body_buffer_size 16k;
+    client_header_buffer_size 1k;
+    large_client_header_buffers 4 8k;
+
+    # Rate limiting per client IP.
+    #
+    # Two zones, because a room load and a page load are not the same thing.
+    # Loading a Nitro room fires several hundred gamedata icons in one burst;
+    # at the page rate that produced 503s on real players. Static assets
+    # therefore get their own, much higher allowance. These are small immutable
+    # files, so a request rate is not what protects them anyway — nginx already
+    # serves them with must-revalidate, and the CMS upstream stays behind
+    # cms_req_per_ip for the expensive routes.
+    limit_req_zone $binary_remote_addr zone=cms_req_per_ip:10m rate=30r/s;
+    limit_req_zone $binary_remote_addr zone=cms_static_per_ip:10m rate=1000r/s;
+    limit_conn_zone $binary_remote_addr zone=cms_conn_per_ip:10m;
+
+    # Blue/green cutover: ci-deploy.sh writes the active upstream here, and
+    # `proxy_pass http://cms_app` below follows it via graceful nginx -s reload.
+    upstream cms_app {
+        include /etc/nginx/snippets/cms_upstream_servers.conf;
+    }
+
+    # Cache policy maps and server blocks live in the site file so they are
+    # synced together and can never drift apart.
+    include /etc/nginx/sites-enabled/*.conf;
+
+    # Trusted edge / real-IP handling (regenerated by scripts/cf-ips-sync.sh
+    # from the live Cloudflare ranges; installed via scripts/nginx-sync.sh).
+    include /etc/nginx/conf.d/cloudflare-ips.conf;
+}

docker-compose.yml

@@ -1,177 +1,102 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# Next.js CMS — blue/green
+#
+# De app draait met `network_mode: host`, dus een replica neemt een host-poort in
+# plaats van een gedeelde docker-poort. Daarom twee expliciete services in plaats
+# van `docker compose up --scale cms=2`: die zou op poort 3002 botsen.
+#
+# `deploy.sh` start een release op de vrije poort, wacht op /api/health, schrijft
+# daarna /etc/nginx/snippets/cms_upstream_servers.conf en herlaadt nginx. Pas dan
+# wordt de oude replica gestopt. De hele release is dus zero-downtime: faalt de
+# nieuwe replica, dan blijft de oude gewoon draaien.
+#
+# De YAML-anchor houdt beide replicas identiek. Wil je ze bewust uit elkaar
+# halen (bv. één release canary-en), verwijder dan `<<: *cms` en vul de
+# afwijkende velden opnieuw in.
+# ─────────────────────────────────────────────────────────────────────────────
+x-cms: &cms
+  image: epicnext-cms:${CMS_RELEASE:-local}
+  build:
+    context: .
+    dockerfile: Dockerfile
+    args:
+      NEXT_DEPLOYMENT_ID: ${CMS_RELEASE:-unknown}
+    network: host
+  network_mode: host
+  # 15s: Next moet een lopend request nog netjes kunnen afronden voordat SIGKILL
+  # volgt. Met 10s werden streams en imports afgekapt.
+  stop_grace_period: 15s
+  restart: unless-stopped
+  env_file:
+    - .env
+  volumes:
+    - ./public/nitro-assets:/app/public/nitro-assets
+    - ./public/swf:/app/public/swf
+    - ./storage:/app/storage
+    - /var/www/Gamedata:/var/www/Gamedata
+
+  # ── Resource limits ──
+  # De limieten waren eerder weggehaald ("Next mag onbeperkt presteren"). Op een
+  # gedeelde host is juist dat gevaarlijk: één geheugenlek vult dan de hele
+  # machine en MariaDB + nginx + Traefik gaan er allemaal onderuit. 4 GiB met
+  # 1 GiB swap geeft de V8-heap ruimte om zich te organiseren voor hij hard wordt
+  # afgesneden, maar houdt de schade begrensd. 2 CPU laat drie keer zoveel
+  # achtergrondwerk toe als de cores, zodat de 6 cores van deze host niet
+  # volledig door twee replicas worden opgeëist.
+  mem_limit: 4g
+  memswap_limit: 5g
+  cpus: 2.0
+  pids_limit: 512
+
+  # Leest de poort uit de eigen omgeving, dus dezelfde healthcheck werkt voor
+  # 3002 én 3003 zonder dat deze tweemaal in de compose hoeft te staan.
+  healthcheck:
+    test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:'+(process.env.PORT||'3002')+'/api/health').then(r=>{process.exit(r.ok?0:1)}).catch(()=>process.exit(1))"]
+    interval: 15s
+    timeout: 5s
+    retries: 3
+    start_period: 40s
+
 services:
+  # Blauwe replica: host-poort 3002.
   cms:
-    build:
-      context: .
-      dockerfile: Dockerfile
-      # The host disables Docker iptables (daemon.json: "iptables": false), so
-      # build containers on the bridge network have no outbound NAT/DNS. Build on
-      # the host network instead so pnpm/npm/yarn can reach the registry.
-      network: host
+    <<: *cms
     container_name: epicnext-cms
-    # Runs on the host network so existing 127.0.0.1 refs in .env keep working:
-    # MariaDB (3306), DragonflyDB/Redis (6379), emulator RCON (3003) + API (3001),
-    # and the imaging renderer (8082). The container then listens directly on the
-    # host's 3002 (the same port the current host-side CMS uses).
-    # NOTE: stop the host CMS (next-server on 3002) first, otherwise the port is taken.
-    network_mode: host
-    restart: unless-stopped
-    env_file:
-      - .env
     environment:
       - HOSTNAME=0.0.0.0
-    volumes:
-      # ── Write targets (runtime imports/uploads, persistent on the host) ──
-      # The CMS writes imported furni/figures/pets/effects here (see
-      # src/lib/services/furni-asset-dirs.ts). These must be RW, and owned by
-      # UID/GID 33 (www-data) on the host so the container user can write to them:
-      #   sudo chown -R 33:33 ./public/nitro-assets ./public/swf ./storage
-      - ./public/nitro-assets:/app/public/nitro-assets
-      - ./public/swf:/app/public/swf
-      # Runtime uploaded media (persistent on the host).
-      - ./storage:/app/storage
+      - PORT=3002
 
-      # ── Shared gamedata (absolute path the CMS hardcodes & writes to) ──
-      # src/lib/services/furni-asset-dirs.ts: `DEFAULT_GAMEDATA_ROOT =
-      # /var/www/Gamedata`. nginx on the host also serves /gamedata/ from this
-      # same directory, so mount it into the container at the same absolute path.
-      # Must be RW so furniture/badge imports can write mirrors to it.
-      - /var/www/Gamedata:/var/www/Gamedata
-      #
-      # ── node_modules corruption (§ host-sync) ──
-      # pnpm node_modules must NEVER be a host bind-mount: shared-filesystem
-      # sync (Docker Desktop gRPC-FUSE/VirtioFS, Unison, Syncthing) corrupts
-      # pnpm's hardlinked store and .bin shims. The production image already
-      # bakes node_modules in at build time and is NOT bind-mounted here.
-      # For local dev use a *named volume* instead of a host bind:
-      #   - node_modules:/app/node_modules
-      # and never share `node_modules` / `pnpm store` via the Docker bind.
-      # On macOS add `:cached`/`:delegated` consistency labels per mount.
+  # Groene replica: host-poort 3003. Meestal uitgeschakeld; alleen tijdens een
+  # release gestart, totdat nginx hem in de upstream-lijst heeft overgenomen.
+  cms-green:
+    <<: *cms
+    container_name: epicnext-cms-green
+    profiles: ["green"]
+    environment:
+      - HOSTNAME=0.0.0.0
+      - PORT=3003
 
-    healthcheck:
-      test: ["CMD", "node", "-e", "fetch('http://localhost:3002/api/health').then(r=>{if(!r.ok)process.exit(1)}).catch(()=>process.exit(1))"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 40s
-    mem_limit: 2g
-
-  # ── FlareSolverr (Cloudflare bypass for clone sources) ──
-  # Solves Cloudflare/TLS-fingerprint blocks via a headless Chrome browser.
-  # The CMS calls this on http://localhost:8191 for sources that block Node's
-  # TLS fingerprint (e.g. Leet.city). Used by src/lib/services/flare-solver.ts.
-  flaresolverr:
-    image: ghcr.io/flaresolverr/flaresolverr:latest
-    container_name: flaresolverr
+  # ── Byparr (Cloudflare bypass for clone sources) ──
+  byparr:
+    image: ghcr.io/thephaseless/byparr:latest
+    container_name: byparr
     network_mode: host
     restart: unless-stopped
     environment:
-      - LOG_LEVEL=info
-      - BROWSER_TIMEOUT=60000
-      - BROWSER_WORKERS=1
-    mem_limit: 2g
+      - LOG_LEVEL=INFO
+    
+    # Resource limits verwijderd: Headless Chrome heeft bij zware pagina-scrapes 
+    # soms tijdelijk meer dan 1 GB RAM nodig. Nu krijgt hij alle ruimte.
+    pids_limit: 256
+
     healthcheck:
-      test: ["CMD", "curl", "-sf", "http://localhost:8191/health"]
+      test: ["CMD", "curl", "http://localhost:8191/health"]
       interval: 30s
       timeout: 10s
       retries: 3
       start_period: 30s
 
-  # ── Opt-in: Octane-Renderer (Habbo avatar imager) ──
-  # Serves /imaging on port 3030 (the CMS proxies /imaging to it). Renders
-  # avatars into /var/www/Gamedata/habbo-imaging, so it needs RW access.
-  # Disabled by default — uncomment to run the renderer as a container.
-  # imager:
-  #   build:
-  #     context: /var/www/Octane-Renderer
-  #   container_name: epicnext-octane-renderer
-  #   ports:
-  #     - "3030:3030"
-  #   restart: unless-stopped
-  #   volumes:
-  #     - /var/www/Gamedata:/var/www/Gamedata
-
-  # ── MariaDB "Turbo" (heavy JSON / bulk-loads) ──
-  # Dedicated MariaDB tuned for >50 MB JSON imports. All tuning lives inline
-  # in the service `command:` (bulk_insert_buffer_size,
-  # innodb_flush_log_at_trx_commit=2, max_allowed_packet=512M, ...) so the
-  # container configures itself — no external .cnf to mount or keep in sync.
-  # Opt-in via profile so `docker compose up` keeps running the standalone
-  # stack as today.
-  #
-  # Start:  docker compose --profile db up -d   (= pnpm db:up)
-  # Note:   host networking binds 127.0.0.1:3306 → STOP the host MariaDB
-  #         first (the app's .env DATABASE_URL points at localhost:3306).
-  #         Fixes the "Pulling schema from database..." hang: raise
-  #         net_read/net_write_timeout (done above) + stop imports while
-  #         running `pnpm db:generate` / drizzle-kit introspection.
-  mariadb-turbo:
-    image: mariadb:11
-    container_name: mariadb-turbo
-    profiles: ["db"]
-    network_mode: host
-    restart: unless-stopped
-    environment:
-      # mariadb:11 uses MARIADB_*; MYSQL_* also works but is deprecated there.
-      - MARIADB_ROOT_PASSWORD=${MARIADB_ROOT_PASSWORD:-root}
-      - MARIADB_DATABASE=${MARIADB_DATABASE:-habbo}
-      - MARIADB_USER=${MARIADB_USER:-cms}
-      - MARIADB_PASSWORD=${MARIADB_PASSWORD:-cms}
-      - MARIADB_AUTO_UPGRADE=1
-    # MariaDB tunes itself — the Official image appends these flags to mysqld,
-    # no external .cnf file needed.
-    command: [
-        # Charset
-        "--character-set-server=utf8mb4",
-        "--collation-server=utf8mb4_unicode_ci",
-        # 50 MB JSON batches: raise the 16 MB default packet ceiling.
-        "--max-allowed-packet=512M",
-        "--net-buffer-length=1M",
-        # Timeouts — fixes the "Pulling schema from database..." hang
-        # (drizzle-kit introspection no longer starves behind big imports).
-        "--connect-timeout=30",
-        "--wait-timeout=3600",
-        "--interactive-timeout=3600",
-        "--net-read-timeout=600",
-        "--net-write-timeout=600",
-        # InnoDB: durability/performance trade-off for bulk writes.
-        "--innodb-flush-log-at-trx-commit=2",
-        "--innodb-buffer-pool-size=2G",
-        "--innodb-buffer-pool-instances=4",
-        "--innodb-log-file-size=1G",
-        "--innodb-log-buffer-size=64M",
-        "--innodb-flush-method=O_DIRECT",
-        "--innodb-autoextend-increment=512",
-        "--innodb-max-dirty-pages-pct=90",
-        "--bulk-insert-buffer-size=512M",
-        # Raise so the engine nearly never double-writes during a 50 MB load.
-        "--innodb-doublewrite=0",
-        # libaio/native_aio misbehaves in some containers; io_uring path is fine.
-        "--innodb-use-native-aio=0",
-        # Temp tables used when MariaDB scans JSON blobs cannot be indexed.
-        "--tmp-table-size=256M",
-        "--max-heap-table-size=256M",
-        "--read-buffer-size=4M",
-        "--read-rnd-buffer-size=16M",
-        # Save ~1-2 GB RAM; bulk loads don't need the instrumentation.
-        "--performance-schema=OFF",
-        "--skip-name-resolve",
-      ]
-    volumes:
-      # Named volume, NOT a host bind — shared-filesystem sync trashes InnoDB
-      # files the same way it trashes pnpm's node_modules. Named volumes live
-      # inside the container filesystem, so 50 MB of JSON writes never cross a
-      # host-sync boundary.
-      - mariadb-turbo-data:/var/lib/mysql
-    healthcheck:
-      # healthcheck.sh ships in the official mariadb image.
-      test: ["CMD-SHELL", "healthcheck.sh --connect --innodb_initialized || mariadb-admin ping --silent"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-      start_period: 30s
-    mem_limit: 4g
-
-# Named volumes declared once; used by the MariaDB service above.
-volumes:
-  mariadb-turbo-data:
-    driver: local
+# De database draait niet meer in Docker. `mariadb-turbo` is verwijderd: de
+# service is nooit gestart, de volume bestond niet, en de echte MariaDB draait
+# al als host-proces op 127.0.0.1:3306. De optimalisatie-vlaggen daar stonden
+# dus al langer niets meer in beheer.

docker-image.txt

@@ -0,0 +1 @@
+gitlab.epicnabbo.nl/simo/epicnext-cms

docs/cms-upgrade-2026-09.md

@@ -0,0 +1,156 @@
+# CMS upgrade — September 2026
+
+## Operator changes
+
+| Area | Behavior and location |
+| --- | --- |
+| Release | Deployment checks HTTP health, release identity and Chromium pages before marking the running image verified. Registry publication reuses that verified digest on the shared runner; independent hosts build and verify their own image. |
+| Shared HK | Dialogs scroll within the available viewport. Table column preferences persist per page in the current browser session; filters already remain in the URL. No favorites added. |
+| Catalog Studio | Dedicated detail drawer and five separate completeness states: SQL, offers, furnidata, icon and Nitro. Sprite/type conflicts are consistently excluded from import and linked to audit. Missing source files are never represented as available. |
+| Operations | Command center includes permission-filtered error groups, personal import failures, open support tickets and news drafts. A failed source is shown separately from an empty source. |
+| Error center | Retained occurrence counts, first/last times, identified users, release counts, self-assignment and recognized local links. Assignment requires edit permission and is audited. |
+| News | Private server-backed autosave, recover/discard/retry, prior saved revisions restored as a draft, and concurrent-edit detection. New status/search filters and pagination make older drafts reachable. |
+| Jobs | Cancellation finishes the current item and stops pending items. Completed work stays completed. Uncertain interrupted mutations are excluded from retry. Live lease checks stop known stale worker writes. |
+| Installation | `/admin/devops/installation` shows release, DB latency, Redis, emulator, storage permissions, migration history and worker heartbeat. Renderer defaults are recognized. Registry access is explicitly unverified from the web process. |
+| Public dashboard | Current/next published event, clearer unread-message action, useful empty/error states and mobile layout refinements. |
+| Audit | Exact actor/action and UTC date filters, readable recorded before/after values and permission-protected CSV of the filtered page, capped at 100 rows. |
+| Performance | Active import polling remains 5 seconds; idle polling is 30 seconds and pauses in hidden tabs. History returns at most 30 owned jobs and initially renders 50 items per job. Health probes are deduplicated within a render; diagnostics report observed probe duration. |
+| Text | New messages are translated in English, Italian and Dutch. Other locales have explicit English fallback strings. Existing translation debt is not reported as resolved. |
+
+## Deployment requirements
+
+- Apply migration `0026_article_editor_recovery.sql` through `pnpm db:migrate` before enabling the new news editor. It adds private drafts and revision tables without modifying existing articles.
+- Keep `storage` persistent and writable. Error assignments and import cancellation markers use the existing shared storage.
+- Run the existing `pnpm jobs:worker` process with the installation configuration. It now publishes a heartbeat to Redis every minute. A web process alone does not establish that scheduled-news jobs are running.
+- The deploy runner installs Chromium before cutover. Browser checks visit only public login/news/staff pages; they do not create production content or authenticate staff. The host must satisfy Chromium system-library requirements.
+- Use the existing Gitea registry secrets. The CMS does not read or display those credentials.
+
+## Boundaries
+
+- Operations is a bounded operational summary: errors use at most 1,000 retained events and imports use the latest 30 owned jobs. Empty checked records do not prove that all historical work is resolved.
+- Import history bounds payloads and concurrent file reads. Directory metadata scanning and worker enumeration still scale with stored history.
+- Redis lease checks and file saves are separate operations. They reduce stale writes but do not provide atomic fencing across Redis, SQL and filesystem operations. An import interrupted after SQL may require local-data inspection.
+- Revision history displays the latest 20 saved versions; revisions are retained in the database. New-article recovery has one private slot per staff account.
+- The database connection probe is a measurement, not a performance benchmark. No throughput or latency improvement is claimed without production measurements.
+- A rollback restores an application image; it does not reverse database migrations. The new tables are additive.
+
+## Verification
+
+Local verification on 2026-09-09:
+
+- Production build succeeded with fixture configuration and an intentionally unavailable database. Build-time fallback logs are expected in this check.
+- Full Vitest run: 254 files passed, 4 skipped; 1,466 tests passed, 6 skipped. Coverage thresholds passed (19.89% lines); this does not imply exhaustive coverage.
+- Global Biome rules/import checks passed across 1,328 files; modified source/locales were formatted separately to avoid unrelated Windows line-ending changes.
+- Translation audit: no invalid ICU messages, variable mismatches or missing static references. Existing locale gaps and 1,560 hardcoded-text candidates still need editorial work; they are not silently marked translated.
+- Headless Edge verification of actual shared components with compiled CSS and the CMS theme at widths 1,280 and 390 pixels: the switch changes state and thumb position, the dialog stays within the 720px viewport, the final button is reachable, and the background page does not scroll. This isolated fixture does not establish full authenticated-page parity.
+- Deployment rollback, verified-digest publication, ownership/cancellation and concurrent news edit behavior have focused regression tests.
+
+Docker runtime, database migration execution and authenticated browser flows still require an integration environment. Check the Gitea pipeline and live release identifier after publication. A successful local build is not production verification.
+
+
+## Catalog packages
+
+The normal catalog toolbar now opens a dedicated Catalog packages dialog.
+Create a named draft from selected categories and their descendants, either to
+update those categories or copy them under a chosen parent. Drafts are shared
+with authorized staff; saving a draft does not modify the live catalog.
+
+Edit category metadata and offer prices, or review bulk price changes before
+applying them to the draft. The catalog preview supports category navigation,
+search, real local furniture icons and rank/Club/VIP access simulation. It does
+not render the game client or evaluate ancestors outside the selected package;
+special layouts and that access limitation are disclosed in the preview.
+
+Publication requires a saved draft and a fresh review. Concurrent source changes
+block publication; version checks prevent one editor overwriting another.
+Copying preserves the underlying category and offer fields and remaps internal
+references while retaining furniture IDs and assets. The catalog writes and
+published result are committed together; retrying the same published package
+does not copy it again. Failures in hotel notifications, audit or Git export
+scheduling after commit are reported as warnings rather than failed publication.
+
+Apply additive migration `0027_catalog_packages.sql` before opening this tool.
+Existing migration automation discovers the file. Limits are 200 categories,
+500 offers and 8 MB of package data. Package source checks inspect at most 20,000
+catalog categories. Publication briefly locks category rows while validating and
+writing changes, so large live catalogs should be checked under realistic load.
+English, Italian and Dutch copy is provided; other locales use the new English
+strings pending translation. No new dependency is required.
+
+Validation: 1,506 tests passed (six skipped), type checking, lint, translation
+contracts and a production build with fixture configuration. A browser fixture
+verified the real dialog at 1280 and 390 pixels; server actions were simulated.
+The new database migration and package publication have not run in production.
+
+## Housekeeping search and user overview
+
+The existing global search now includes furniture, normal/Club catalog categories
+and both ticket sources. Results respect module permissions, accept single-digit
+IDs, and remain usable when one source fails. Keyboard navigation and cancellation
+prevent stale search responses from replacing newer results.
+
+User details open on an operational overview with up to five records from each
+authorized source: bans, active mute, support tickets, help tickets, reports,
+payments, catalog purchases and audit activity. Failed sources are distinguished
+from empty results. User detail and edit pages also apply log permissions before
+loading activity and exposing counters.
+
+Italian and Dutch navigation, user management, news and support labels were
+reviewed. The new search and overview copy has English, Italian and Dutch text;
+other locales receive English fallback strings. This is a focused editorial pass,
+not a full translation of every CMS page. No database migration or dependency
+change is required. Browser checks use real components with simulated data at
+1280 and 390 pixels; production database behavior still needs deployment validation.
+
+## Operational reliability and recovery
+
+- Audit history now records category settings (normal/Club), individual/bulk offer prices, update-mode package publication and news edits inside the write transaction. The audit screen previews and restores individual changes after locking and comparing the current recorded fields. Deleted records, hierarchy changes, LTD counters, imports and historical entries without complete snapshots cannot be restored. Restores create their own history entry. Apply migration `0028_history_snapshots.sql` before running this version: it widens audit snapshots to MEDIUMTEXT without deleting existing data.
+- `/admin/operations` reuses durable import jobs, stable history pagination and owner-scoped failed-item retries. A deterministic child ID prevents duplicate retries. The shared Git export queue displays actual pending/running state and latest result; synchronous/SSE synchronization remains linked rather than represented as a durable job history.
+- Catalog maintenance includes a read-only integrity report for normal/Club categories, offers, furniture references and local icons. Known sentinel IDs are preserved. Only categories pointing to a missing positive parent have an automated repair: preview lists every affected category and apply compares the locked graph before reattaching those categories at the root. No records are deleted. Other issues require an explicit manual edit. Reports display up to 200 issues with complete counts; unavailable icon storage is distinguished from missing assets.
+- CMS errors support exact release and time filters plus frequency sorting. Counts refer to retained matching events, while group resolution remains current across releases.
+- User/settings forms now protect unsaved edits and preserve failed submissions. User/news validation errors appear at the affected fields; settings show returned validation errors inline. Existing submission locking is retained and tested in a browser.
+- `/admin/permissions/preview` shows one role's section access and known CMS grants using live ACL and the existing highest-rank policy. It never changes sessions. Additional user roles, navigation customization and record-specific authorization remain explicit limits of the preview.
+
+New UI copy is supplied in English, Italian and Dutch; other locales receive English fallback strings. No new runtime dependencies. Browser fixtures use real UI components with simulated server responses; the database migration and production behavior have not been exercised on the live hotel.
+
+Validation for this increment: 1,589 tests passed, six skipped; TypeScript, Biome, translation contracts and fixture production build passed. Browser checks covered user/settings/news forms, permission preview, CMS errors, integrity preview and history restore at 1280 and 390 pixels. Double submission, stale preview, blocked navigation, field focus and horizontal overflow were checked with simulated server actions. No live database writes or deployment were performed.
+
+
+## September 11: public pages and staff workflows
+
+- Docker stages now follow the exact `.nvmrc` release, enforced by the toolchain check.
+- `/news` supports search, ordering by effective publication date and real pagination.
+- `/events` supports upcoming/ongoing/completed filters, explicit UTC week windows, local displayed times and personal registrations.
+- `/search` searches users, open rooms, published news and events with independent pagination and partial failure states.
+- `/me` shows support replies, incoming friend requests, the next registered event and available referral rewards. Reply availability does not claim unread status.
+- Profile privacy is managed in `/settings`. Wallet values are private by default; visitors do not receive hidden sections in HTML. Photo galleries initially show six photos and can expand to the loaded limit of 24.
+- Ticket desks support waiting-for-staff and assignment filters, with elapsed time since the latest reply.
+- HK table views save filters, order and visible columns per account and table (maximum 20). Existing session column preferences remain available until a named view is applied.
+- Official and clone synchronization run through the existing durable import queue. Reloading restores history; interrupted uncertain writes still require inspection before repair. Successful items are not repeated.
+- Publication preflight validates URL syntax/protocols and schedules, shows affected page links and keeps existing article previews. It does not claim remote URLs are reachable. Drafts remain savable. Partial event updates preserve omitted fields.
+- Admin APIs return `x-operation-id`; server errors, staff audit records and import jobs share correlation context. Error and audit screens link to each other. Older records without this context remain readable.
+- Public reads distinguish unavailability from empty results and real 404s, preserving independently available sections on home, dashboard, staff, photos, rankings and groups/forums.
+
+### Data and verification
+
+Additive migrations `0029_admin_table_views.sql` and `0030_profile_privacy.sql` run through the existing deployment migration runner. They create CMS-owned tables and do not change emulator user settings. Keep the existing shared storage volume and background jobs worker for durable imports.
+
+Browser verification used real components with controlled data fixtures at 1280 and 390 pixels, including failure and partial-result cases. Production compilation and full lint were checked locally. No production content was created during those checks; real authenticated content and external source availability remain environment-dependent.
+
+## Original furniture bundle recovery and progress
+
+Catalog Studio queued imports and repairs now search other enabled Nitro sources when their initial downloads/conversion produce no local bundle. Recovery checks an exact classname, floor/wall type and positive revision against the source furnidata, then validates the bundle filename, internal name and PNG texture before writing it. It does not copy the alternative source's prices, IDs or descriptive metadata.
+
+The recovery pass checks at most eight eligible sources, excludes the selected source, and has a 20-second network budget with four-second request limits. Catalog downloads are capped at 20 MiB; bundle downloads and attachment decompression are capped at 50 MiB. A bounded catalog cache avoids downloading full furnidata for every item. Blocked or incompatible sources can still require the original bundle to be attached manually.
+
+Import history displays the current phase and elapsed time, the last phase on failure/interruption, and the source/revision of a recovered bundle. Phases are persisted under the existing worker lease; a retry clears old phase/provenance fields. Synchronization jobs also report their existing importer phases, but their clone-specific asset strategy is unchanged.
+
+No additional secrets or environment variables are needed. Source definitions remain managed through the existing source configuration.
+
+## Catalog workflow and public diagnostics
+
+- Bulk offer edits retain the existing preview and now record complete price/category snapshots. The success notification offers an atomic batch Undo for 15 seconds; individual changes remain restorable from audit history afterward. Undo rejects changed records or missing categories rather than overwriting newer edits. No additional migration is needed beyond the existing history snapshot migration.
+- Catalog Studio preserves the existing in-place search/filter/selection flow and now restores list scroll and focus after closing furniture details. Escape closes details before clearing selection. Obsolete list responses cannot replace a newer search; switching source invalidates pending review preparation.
+- Import review groups furniture needing completion, conflicting records and unverified components. Each row lists missing or unknown components and suggests the next action. These are inspection recommendations; final import validation remains authoritative.
+- DevOps performance has separate HK API and public-page groups, each limited to 200 recent samples for one hour. Public instrumentation measures root server page invocations on /me, news, profiles, events and search, including measured database/external work. It excludes metadata, separately rendered children, cached responses that do not invoke the page, network transfer and browser rendering. Static build invocations are excluded. Routes use fixed labels without usernames or search terms; component outcomes are distinct from HTTP status codes.
+- Shared unsaved-change protection now coordinates dirty forms and protects global-search navigation. Prefix, badge and room-furniture editors protect explicit dismissal and remain open after failed saves. Browser Back is intercepted when the cancellable Navigation API is available; reload/close and links retain their existing protection. Prefix saving now waits for the real server action result before closing.

docs/operations/backup-and-restore-drill.md

@@ -0,0 +1,93 @@
+# Backup and isolated restore drill
+
+This opt-in operator tool creates one MariaDB logical dump and copies explicitly selected persistent files. It never runs during install, update or CI deployment. The only restore operation is a **disposable drill**: there is no production restore command, database target, destination directory or overwrite option.
+
+## Scope and prerequisites
+
+Use the existing project Node toolchain and Docker CLI/Engine on a Linux host. Creation uses a short-lived `mariadb:11.4.5` client on the Docker host network, so `127.0.0.1` means that host. Use a local Docker Engine/context with the same filesystem; remote Docker daemons and Docker Desktop are not supported for creation. The image must already be available or downloadable through the operator's normal image policy. No packages are installed by this tool.
+
+Choose the single application database explicitly. Its tables must use InnoDB; empty databases, system schemas and unsupported engines are rejected. The backup account needs access to every application table, view, trigger, routine and event being exported. Account/grant provisioning belongs to the operator; the tool does not change privileges. Restore compatibility is checked with the pinned MariaDB image, not guaranteed across arbitrary server versions, plugins, collations or external schema dependencies.
+
+Before starting, pause **every database/file writer** and schema changer for the whole creation command: CMS requests that write, workers, schedulers, emulator processes, MariaDB events, import jobs and other tools using these resources. Keep them paused until the command exits. `--writers-quiesced` records your acknowledgement; it does not stop services or prove that they are stopped. No DDL may run while dumping. InnoDB's transaction snapshot alone cannot make independently copied files consistent with rows or coordinate other services. The before/after table inventory and second source-file hash pass detect many concurrent changes, but cannot replace quiescing.
+
+The dump explicitly uses `--single-transaction --quick --skip-lock-tables --routines --events --triggers --hex-blob --tz-utc`. It retains schema/data and named SQL objects while streaming rows. See [MariaDB dump snapshot and object options](https://mariadb.com/docs/server/clients-and-utilities/backup-restore-and-import-clients/mariadb-dump). This is a logical application backup, not point-in-time recovery: binlogs, server accounts/grants, server configuration, Redis state and unrelated databases are outside its scope.
+
+## Private configuration
+
+Create a private JSON file **outside the clone and every selected source directory**, for example `/etc/epicnext/backup.json`. Use a directory accessible only to the operator and file mode `0600`. Edit it with the host's normal private configuration workflow; do not put a password in a shell command or commit the file.
+
+```json
+{
+  "database": {
+    "host": "127.0.0.1",
+    "port": 3306,
+    "user": "REPLACE_WITH_BACKUP_ACCOUNT",
+    "password": "REPLACE_PRIVATELY",
+    "database": "REPLACE_WITH_APPLICATION_DATABASE"
+  },
+  "roots": {
+    "storage": "/srv/epicnext/storage",
+    "nitro": "/srv/epicnext/public/nitro-assets",
+    "swf": "/srv/epicnext/public/swf",
+    "gamedata": "/var/www/Gamedata"
+  }
+}
+```
+
+Replace the example clone path and database settings. `storage`, `nitro` and `swf` are required existing directories, including when empty. `gamedata` is optional; omit its key only when those files are independently backed up or not used. All paths must be absolute, distinct, non-overlapping and free of `..` and symlink/junction components. Links, hardlinked files, special files and secret configuration filenames such as `.env`, `.docker-install` and `persistent.path` inside a selected root cause rejection. The configuration itself may not be inside any source root. Keep writers and directory ownership controlled for the duration; this is not a filesystem snapshot resistant to hostile concurrent renames.
+
+The tool reads only this explicit JSON. It does not source `.env`, inspect a running application's environment or inherit its secrets into Docker. The MariaDB password is written to a random private temporary directory/file (`0700`/`0600`) and read through a read-only container mount with `--defaults-file` as the first client option. It is absent from process arguments and tool logs; source configuration and absolute source paths are absent from the manifest. Temporary credentials are removed on ordinary success/failure. See [MariaDB option-file handling](https://mariadb.com/docs/server/clients-and-utilities/backup-restore-and-import-clients/mariadb-dump#defaults-file-name).
+
+Only Docker connection/runtime environment variables are passed to child processes. Do not point `DOCKER_HOST`/`DOCKER_CONTEXT` at another host or enable shell tracing around private configuration work.
+
+## Create and verify
+
+Provision a private backup parent directory, with adequate free space, outside all source roots. Choose a **new** absolute artifact directory for each run. After pausing the writers described above, run from the clone root:
+
+```sh
+node scripts/backup/cli.mjs create \
+  --config /etc/epicnext/backup.json \
+  --output /srv/epicnext-backups/2026-09-13T200000Z \
+  --writers-quiesced
+```
+
+The date is an example; use a new name for the actual run. Existing directories are refused, including earlier incomplete attempts. A successful artifact contains:
+
+```text
+manifest.json
+ database.sql
+ files/storage/...
+ files/nitro/...
+ files/swf/...
+ files/gamedata/...   (only when selected)
+```
+
+`manifest.json` is written last and marks the format complete. It records each relative file path, byte count and SHA-256, empty directories, selected logical roots, creation time and database inventory. The inventory includes table row counts and MariaDB extended table checksums plus names/types of views, triggers, routines and events. These checksums validate restored table contents; they are not cryptographic signatures or a substitute for application-level checks. See [MariaDB CHECKSUM TABLE semantics and version limits](https://mariadb.com/docs/server/reference/sql-statements/table-statements/checksum-table).
+
+On a caught failure the newly created artifact is removed; an interrupted process can leave an incomplete directory, which verification refuses. Source roots and existing backup directories are never overwritten. Files are copied and hashed as streams, then source hashes are checked again across the dump interval. This performs multiple full reads of the assets and table data; allow sufficient time and disk capacity during the maintenance window.
+
+After creation you may resume writers. Copy the completed artifact to the designated protected backup location according to the operator's retention/encryption policy. SQL and uploaded files contain application data and may themselves contain sensitive values. Hashes detect corruption against the manifest, not an attacker who can replace both. Keep the manifest and artifact under trusted access control. Secrets, TLS material and deployment configuration excluded from this artifact need their separate recovery procedure.
+
+## Isolated restore drill
+
+Run the drill against a trusted completed artifact:
+
+```sh
+node scripts/backup/cli.mjs drill \
+  --artifact /srv/epicnext-backups/2026-09-13T200000Z
+```
+
+The drill first rejects missing, extra, changed or unsafe paths/files. It copies the persistent files into a new private temporary directory and verifies their contents. It creates a randomly named MariaDB container with **no network and no published ports**, a fresh password supplied by file, and a disposable database volume. SQL is imported through the container's standard input; there is no connection to the source database. The event scheduler stays off. The resulting table counts/checksums and object inventory must match the manifest. This proves dump importability and the recorded contents, not a full CMS/emulator startup or external-service recovery.
+
+On ordinary completion/failure it removes the container, its anonymous volume and temporary files. Cleanup failure makes the drill fail. A host crash or forced process termination can interrupt cleanup; inspect only resources labeled `cms.backup-drill=true` and private `cms-backup-private-*` temporary directories from that run, and review their ownership before manual removal. Never substitute an existing database/container into this procedure.
+
+A real production recovery remains a separate, reviewed procedure with its own deployment configuration, credentials, downtime and application checks. This tool deliberately cannot perform it.
+
+## Repository verification
+
+```sh
+pnpm exec vitest run --coverage.enabled=false scripts/backup
+pnpm exec vitest run --config vitest.integration.config.ts integration/backup.test.ts
+```
+
+The local suite exercises real file copies, empty directories, SQL/file tampering, manifest traversal, links, secret-file rejection, overwrites, cleanup and changes during backup. The integration suite requires Docker: failure to start MariaDB fails the suite. It uses a real database with Unicode text, large unsigned identifiers, a foreign key, view, trigger, procedure and event; it creates an artifact, restores it to a second disposable server and checks both byte corruption and a SQL content change with a recomputed file hash. A passing local file suite alone is not evidence that the MariaDB drill ran.

docs/operations/ci-preflight.md

@@ -0,0 +1,17 @@
+# Docker and news checks before merging
+
+Push work to a `codex/**` branch and open a pull request targeting `main` or `master`. CI runs the existing `check` job first. After it passes, the new `preflight` job builds the production Dockerfile and runs the isolated news browser suite against that exact image. Review both results before merging; repository branch protection can require `check` and `preflight` for pull requests.
+
+Each execution uses `epicnext-cms:preflight-<commit>-<random suffix>`, including retries and separate push/PR runs of the same commit. The full checked-out commit is passed as `NEXT_DEPLOYMENT_ID` and `NEWS_E2E_RELEASE`; `NEWS_E2E_IMAGE` identifies that execution's image. Failures in dependency/browser setup, Docker build, news tests or cleanup fail the job. News browser artifacts are uploaded even when the gate fails.
+
+The script installs dependencies with the frozen lockfile and installs Chromium on the CI runner. The real Docker build uses the existing Dockerfile's fixture build settings. It never copies or sources a deployment `.env`, connects to a VPS, runs live migrations, updates live containers, publishes a registry image or changes release tags. The existing isolated news runner owns its disposable MariaDB, Redis and application containers. Cleanup removes only the preflight tag and its empty private temporary directory; it does not prune Docker resources.
+
+The `deploy` and `publish-container` conditions remain restricted to pushes on `main`/`master`. Deployment still runs its own news gate before live migrations/cutover. A successful branch preflight supplies earlier evidence; the deployed commit is independently checked again.
+
+On a Linux development or CI host with the project toolchain, Docker Engine and normal browser prerequisites, the same gate can be run from a clean checkout:
+
+```sh
+bash scripts/ci-preflight.sh
+```
+
+Shell orchestration is covered by `pnpm exec vitest run --coverage.enabled=false src/lib/ci-preflight.test.ts`. Those tests execute the real shell script with external command boundaries simulated; they prove ordering, failure propagation, unique tags and cleanup scope. They do not build an image or run the news browser suite. The branch/PR CI job provides that Docker/browser evidence.

docs/operations/cms-error-center.md

@@ -44,7 +44,7 @@ stack is diagnostic evidence, not an automatic root-cause determination.
 ## Dependencies
 
 `pnpm install --frozen-lockfile`, `pnpm deps:audit`, `pnpm typecheck`, `pnpm test`,
-`pnpm knip`, `pnpm biome:lint`, and `pnpm build` are the verification sequence.
+`pnpm biome:lint`, and `pnpm build` are the verification sequence.
 `pnpm analyze --output` writes a Next.js bundle analysis (not an application build).
 
 TinyMCE 8.9 is pinned in pnpm. `pnpm assets:editor` copies its runtime files and
@@ -56,10 +56,30 @@ Lenis has been removed; the public site now uses native scrolling. Other used
 runtime libraries remain. Vitest and its coverage provider are upgraded together;
 `clearMocks: false` preserves initialization-time permission contract assertions.
 
-Renovate uses separate development/UI/Vitest groups with manual merge and a
-three-day release age. The existing external Gitea bot configuration is retained.
-Node/pnpm upgrades remain coordinated with Docker and the runner toolchain.
+Dependency updates are manual: Renovate has been removed, so there is no bot
+opening upgrade pull requests. Node/pnpm upgrades remain coordinated with
+Docker and the runner toolchain.
 Obsolete global overrides were removed; a scoped esbuild override remains because
 Drizzle Kit's loader still resolves a vulnerable legacy development-server build.
 The two deprecated esbuild-kit packages remain upstream dependencies of Drizzle
 Kit; replacing the ORM is not warranted for this tooling issue.
+
+## HK request performance
+
+Open **DevOps → Request performance** (`/admin/devops/performance`). Access requires `DEVOPS_VIEW`; collection only retains requests that passed authentication and permission checks through `withAdmin`.
+
+The view shows recent requests, their server duration, completed database query count/time/errors, monitored curl download count/time/errors, HTTP status and the existing operation ID. Search by route or operation ID, sort by duration or recency, and filter requests taking at least one second.
+
+### Measurement boundaries
+
+- Duration ends when the handler returns its response. Streaming completion, background jobs, browser rendering and public pages are not measured.
+- Database spans wrap the shared mysql2 promise pool and transaction connection query/execute calls. Query parameters and SQL are never collected. Explicit transaction connection acquisition and transaction control methods are not separate spans.
+- External spans currently cover `curlFetchText` and `curlDownload`; ordinary fetch calls and other integrations are not covered.
+- Concurrent dependency durations can exceed wall-clock request duration. Do not subtract the sums to infer application CPU time.
+- Dynamic route values and query strings are removed. No request bodies, headers, usernames, download URLs or SQL text are stored.
+
+### Storage and operation
+
+No new environment variables or packages are required. Redis stores at most 200 recent samples under `cms:performance:v1`, with one-hour retention. Writes are best effort, restricted to an already-ready connection and at most four pending batches; the request never waits for persistence. The view reads at most 200 entries and falls back after one second if shared storage is unavailable.
+
+An in-process buffer preserves up to 200 samples during outages. The page explicitly labels this local mode; it is per instance and disappears on restart. Filtering applies to the retained samples, not complete traffic history. Under load or during storage outages, some shared samples may be omitted.

docs/operations/docker-installation.md

@@ -0,0 +1,138 @@
+# Install a clone and choose an update
+
+## Requirements and first installation
+
+Use a Linux host with Docker Engine, the Compose plugin, Git and `flock`. This Compose file uses host networking and port 3002. Provide an existing compatible Habbo MariaDB database, reachable Redis, persistent storage and an HTTP(S) reverse proxy. The installer does not provision the emulator, a database, TLS, or a registry account.
+
+Clone this repository from the Gitea URL supplied by your administrator, enter the clone, then run:
+
+```sh
+bash cms install
+```
+
+The wizard asks for the public URL and delivery mode. **Source** (the default for a new installation) builds the locked source locally and only needs repository access plus access to public build dependencies. **Prebuilt** downloads the application and migrations from the repository's `docker-image.txt`; a private package needs a separate registry login with package-read permission. Git access alone may not grant package access. Existing saved mode and `.env` are preserved. `bash cms install --configure-only` saves configuration without starting containers.
+
+Credentials are entered on the host, never in the dashboard. Do not paste `.env` into support tickets. Installation prepares `public/nitro-assets`, `public/swf`, `storage`, and `/var/www/Gamedata` for UID/GID 33 without recursively taking ownership of existing files. Existing nested assets may still need operator permission repair. The updater tests access to those mounts as the candidate container user before migrations; this checks directory access, not every nested file or filesystem capacity.
+
+After startup, visit `/admin/devops/installation` with the appropriate permission. Verify database, Redis, storage and migration status. Worker heartbeat is a separate runtime signal: a healthy HTTP endpoint does not prove an import worker is processing jobs. Check the worker status and investigate a missing/stale heartbeat before scheduling imports. The dashboard is read-only and cannot start Docker, upgrade the host or grant registry access.
+
+## Client IP trust at the reverse proxy
+
+The application validates and normalizes client addresses from `cf-connecting-ip`, the first `x-forwarded-for` entry, then `x-real-ip`. It never accepts `x-real-client-ip`; that legacy derived header is also stripped by the Next.js proxy. Missing or invalid addresses resolve to `0.0.0.0` for rate limits and audit records. API routes use the same resolver even though they do not run through the Next.js proxy.
+
+These headers are trustworthy only when the ingress sanitizes them. Configure the reverse proxy to discard client-supplied forwarding/derived headers and replace the accepted address from a verified connection or a specifically trusted upstream proxy. Do not append an untrusted incoming `x-forwarded-for` chain and then treat its first entry as authoritative. Forward `cf-connecting-ip` only after verifying that it came through your trusted CDN path; otherwise remove it.
+
+Restrict direct access to the application port so requests must pass through that ingress. The provided Compose file uses host networking with `HOSTNAME=0.0.0.0`; it does not enforce this restriction or provision nginx/Traefik trust rules. Verify the host firewall and actual reverse-proxy configuration before relying on client IPs for blocking, auditing or abuse limits. Repository tests prove rejection of the derived-header bypass and malformed addresses; they do not certify the deployed forwarding trust chain.
+
+## Opt-in profile: Nginx on the same host
+
+Use this profile for a new Linux Compose clone whose public HTTPS endpoint is Nginx on that same host. It leaves `docker-compose.yml` and CI-managed production deployments unchanged. Nginx must include `ngx_http_realip_module`; check `nginx -V` before using the templates. The CMS remains on the existing host network for database/Redis connectivity, but its HTTP process listens on `127.0.0.1:3002`. Host networking shares the host network namespace; a `ports:` mapping would not provide the restriction. See [Docker host networking](https://docs.docker.com/engine/network/drivers/host/).
+
+1. Run `bash cms install --configure-only` and choose the intended public HTTPS URL. Obtain a valid certificate for that hostname using the host's existing certificate-management process. The templates do not issue certificates or configure renewal.
+2. In the clone's existing `.env`, add or replace this single setting, preserving all other values:
+
+   ```dotenv
+   COMPOSE_FILE=docker-compose.yml:deployment/proxy/compose.loopback.yml
+   ```
+
+   Keep `APP_URL`, `AUTH_URL` and the saved installer public URL on the same canonical `https://` hostname. The profile pins the existing port 3002 as well as the loopback address. Do not place `COMPOSE_FILE` in `.docker-install`; that file accepts only `MODE` and `PUBLIC_URL`.
+3. Copy [nginx-direct.example.conf](../../deployment/proxy/nginx-direct.example.conf) into the host's Nginx configuration directory, outside this Git clone. Replace **every** `hotel.example` and both certificate paths. Load it at `http` scope, for example through `/etc/nginx/conf.d/cms.conf`. Review any existing virtual host for that hostname to avoid two competing configurations. The example handles only CMS HTTP traffic; emulator WebSocket and other hotel services need their own reviewed ingress.
+4. Validate the effective Nginx configuration with `nginx -t`, then enable/reload it through the host's normal service-management procedure. Prepare this endpoint before starting the installer, because installation verifies the saved public URL. It can return an upstream-unavailable response until the CMS starts.
+5. From the clone root, remove conflicting Compose overrides from the deployment shell and validate the model:
+
+   ```sh
+   unset COMPOSE_FILE COMPOSE_PATH_SEPARATOR COMPOSE_ENV_FILES COMPOSE_DISABLE_ENV_FILE
+   docker compose config --quiet
+   bash cms install
+   ```
+
+   These `unset` commands remove shell overrides; they do not remove the `COMPOSE_FILE` line in `.env`. Do not set `COMPOSE_DISABLE_ENV_FILE=1`, use an alternate `--env-file`, or supply a competing shell `COMPOSE_FILE` for this workflow. Environment values can override `.env` selection. Do not print or paste the full rendered Compose configuration, because it contains runtime credentials. See [Compose predefined variables and precedence](https://docs.docker.com/compose/how-tos/environment-variables/envvars/).
+6. Confirm the running configuration without dumping the environment:
+
+   ```sh
+   docker compose exec -T cms node -e 'if(process.env.HOSTNAME!=="127.0.0.1"||process.env.PORT!=="3002")process.exit(1);console.log("CMS configured for 127.0.0.1:3002")'
+   ss -lnt '( sport = :3002 )'
+   curl --fail --silent --show-error https://hotel.example/api/health
+   ```
+
+   The listener must be `127.0.0.1:3002`, not `0.0.0.0:3002` or `[::]:3002`. From another machine, the host's public IP on port 3002 must be unreachable. Check both address families when the host has IPv6. Loopback isolation covers the CMS process only: other containers and host services, including Byparr, retain their existing bindings.
+
+The direct template uses the original socket peer (`$realip_remote_addr`), overwrites the two accepted forwarding headers, and removes incoming `CF-Connecting-IP`, `X-Real-Client-IP` and `Forwarded`. It fixes forwarded host/protocol to the configured HTTPS origin. An unrelated inherited real-IP rule cannot turn a caller-supplied header into the forwarded client address in this mode. See [Nginx original-peer variables](https://nginx.org/en/docs/http/ngx_http_realip_module.html) and [header replacement/removal](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_set_header).
+
+Response buffering is disabled for progress streams, and this example adds no proxy response cache or CORS policy. Its 64 MiB ingress body cap accommodates the existing 52 MiB Studio attachment limit; route and Server Action limits remain authoritative and may be lower. TLS 1.2/1.3 are configured explicitly. See [Nginx buffering](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering) and [TLS protocols](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_protocols).
+
+### Why the profile survives an update
+
+The installer preserves an existing `.env`. The installer invokes `docker-update.sh`, and the updater's config, build, candidate run, cutover and rollback paths all call **bare `docker compose` from the clone root**, without `-f`. Compose therefore reads the saved file list on each invocation. The base file appears first so its relative mount/build paths remain rooted in the clone; the later profile overrides only the CMS environment and healthcheck. No installer/updater patch is required for this selection. See [Compose merge order and relative paths](https://docs.docker.com/compose/how-tos/multiple-compose-files/merge/).
+
+Keep the profile selected for every routine `bash cms update` and selected-release update. A one-off `docker compose -f ... up` does not persist selection for later installer/updater commands. Do not add an untracked `docker-compose.override.yml`: it makes the clone dirty unless separately excluded and is bypassed when `COMPOSE_FILE` selects an explicit list. Before selecting an older release, verify that `deployment/proxy/compose.loopback.yml` exists in that release; a missing selected file fails configuration rather than silently using the public bind.
+
+This profile does not change `scripts/ci-deploy.sh`, which owns a separate `docker run` deployment and currently sets its own public binding. Do not use the clone installer to take over a host managed by CI. Restricting that deployment's listener requires a separate compatibility review and rollout.
+
+### Separate mode: verified remote edge or Cloudflare
+
+A remote proxy cannot connect to the CMS loopback listener directly. The supported topology here is **remote edge → TLS → Nginx on the CMS host → loopback CMS**, retaining the same Compose profile. Use [nginx-trusted-proxy.example.conf](../../deployment/proxy/nginx-trusted-proxy.example.conf) instead of the direct template. Do not enable both templates for one hostname.
+
+For your own remote edge, replace `203.0.113.10/32` in both the `geo` peer allowlist and `set_real_ip_from` with the exact approved connection source addresses. The reserved example address deliberately permits no real edge. Require the edge to overwrite `X-Forwarded-For` with one verified client IP, use the configured hostname, enforce public HTTPS, and validate this origin's TLS certificate. The origin checks the original socket peer before accepting the rewritten address. Never use `0.0.0.0/0`, `::/0` or arbitrary client networks as trusted proxies. See [Nginx real-IP trust configuration](https://nginx.org/en/docs/http/ngx_http_realip_module.html).
+
+For Cloudflare, use that same restricted-edge mode and replace both peer lists with the **current verified IPv4 and IPv6 Cloudflare ranges**, maintained by the operator; use `real_ip_header CF-Connecting-IP` instead of `X-Forwarded-For`. Configure Full (strict) TLS and review authenticated origin pulls. Obtain ranges from [Cloudflare's official IP list](https://www.cloudflare.com/ips/) and follow its [visitor-IP restoration guidance](https://developers.cloudflare.com/support/troubleshooting/restoring-visitor-ips/restoring-original-visitor-ips/). Do not copy a historical range list from a support ticket or trust `CF-Connecting-IP` merely because it is present. This setup still removes the CF header before the CMS and forwards only Nginx's normalized result in XFF/X-Real-IP.
+
+The direct template intentionally records the CDN/edge socket address when placed behind an unconfigured CDN; it does not silently trust an upstream header. After configuring the restricted-edge mode, verify with requests from an allowed edge and a disallowed direct client, including forged CF/XFF headers, and check the recorded client address. Neither the repository nor the installer changes the host firewall or certifies another proxy's header behavior.
+
+### Local verification and deployment boundary
+
+`pnpm exec vitest run --coverage.enabled=false scripts/proxy-config.test.mjs` runs the installed Docker Compose CLI against a disposable clone configuration, without contacting Docker Engine, building images or reading the real `.env`. It verifies selection through `.env`, loopback/port override precedence, the IPv4 healthcheck and preservation of mounts, release selection and host networking. It explicitly skips when Compose is unavailable. This is not a container-start or network-isolation test.
+
+`pnpm test:integration` additionally starts disposable Nginx containers from the actual templates, supplies a temporary test certificate, and sends real HTTPS requests with forged identity headers. It checks direct-mode replacement even with an inherited real-IP rule, rejection of untrusted peers, and acceptance through an explicitly trusted peer. This requires Docker Engine and the OpenSSL CLI and does not read deployment credentials. The templates must still pass `nginx -t` on the intended host after its hostname/certificate substitution, then the listener and trusted-header checks above; the disposable fixture cannot certify that host or its firewall.
+
+## Opt-in: CrowdSec on the same Docker host
+
+A self-contained CrowdSec engine ships in `deployment/crowdsec`. It runs `crowdsecurity/crowdsec:v1.8.1` in its own Compose project in **LAPI-only mode** (`DISABLE_AGENT=true`) and exposes LAPI only on `127.0.0.1:18080`. No reverse-proxy, Traefik, Cloudflare or firewall configuration is changed.
+
+```sh
+bash cms security
+```
+
+The command generates `CROWDSEC_LAPI_API_KEY`, writes the CrowdSec flags into `.env`, starts the engine and registers the `cms` bouncer. The anti-DDoS gate then consults the local LAPI per client IP (short-cached) and blocks `ban`/`captcha` decisions before its own rate buckets. `bash cms security status` reports engine state and `bash cms security disable` stops the engine and flips the toggle off.
+
+The engine does not enroll into the CrowdSec Central API (`DISABLE_ONLINE_API=true`) and runs without the agent (`DISABLE_AGENT=true`), so it needs no account and no outbound access to `crowdsec.net` (often blocked on hardened hosts). Blocking comes from the imported blocklists plus the app's own rate buckets; it does not parse the host Nginx log. The app still has its separate opt-in traffic-sharing channel via `CROWDSEC_REPORT_ENABLED`. Change `CROWDSEC_LAPI_PORT` and `CROWDSEC_LAPI_URL` together when `18080` is already in use. `CROWDSEC_NGINX_LOG_DIR` is honored for when the agent is re-enabled.
+
+This bouncer is application-layer: it sheds known-bad IPs at the CMS process and only for traffic that reaches the Next.js proxy. It does not drop traffic before the origin, does not protect other host ports/services, and depends on the client IP being trustworthy at the ingress. Keep the upstream protections (Cloudflare IP rules, proxy rate limits) for defense before the origin.
+
+The running CMS loads the new env values on its next restart or deployment. For a CI-managed `epicnext-cms-app`, the next deploy (which sources `.env`) applies them; for a clone, `bash cms update --skip-pull` restarts it. `.env` now holds the LAPI key — keep its permissions restrictive.
+
+External IP blocklists (Spamhaus, DShield, CINS, blocklist.de, abuse.ch, IPsum, Firehol, Tor exit nodes, …) can be synced into the local LAPI with `bash cms security blocklists`, and hourly with `bash cms security blocklists-install-cron` (no account, but internet to fetch). Configure via `CROWDSEC_BLOCKLIST_*`.
+
+## Routine and selected-release updates
+
+```sh
+bash cms update
+```
+
+This requires a clean clone and fast-forwards its configured Git upstream, then builds/pulls artifacts for that exact commit. It validates the application and migration revision labels, validates runtime configuration and storage, runs migrations and verifies the recreated CMS locally and through the saved public URL.
+
+To install a specific published version, fetch it and select its commit on the host first:
+
+```sh
+git fetch origin
+git switch --detach <reviewed-commit-or-tag>
+bash cms update --skip-pull
+```
+
+`--skip-pull` deliberately uses the checked-out commit, including detached HEAD. For routine updates again, switch back to your tracked deployment branch. The script does not invent version-to-schema compatibility or automatically change branches.
+
+In prebuilt mode you can additionally require immutable artifacts from the configured repository:
+
+```sh
+bash cms update --skip-pull --app-digest sha256:<64-lowercase-hex> --migrations-digest sha256:<64-lowercase-hex>
+```
+
+Replace both placeholders with publisher-provided digests. Both are mandatory together. Revision labels must match the checked-out commit; a digest alone does not establish schema compatibility. Older migration images without a revision label must be republished from matching source, or the same checkout can be installed in source mode. No migration runs when the artifact or candidate validation fails.
+
+## Compatibility and recovery
+
+Before upgrading, read the selected release's migration changes and take a database backup with a tested restore procedure. Preserve `.env`, persistent assets and the previous release identifier. The current tooling does not provide a validated matrix of supported source/target database versions. Pinning an old commit is therefore not a supported database downgrade procedure.
+
+On a failure after container replacement, the updater attempts to restore the previous image and checks it locally. **Image rollback does not reverse database migrations.** A migration may partially apply or make the old application incompatible, including when migration fails before container replacement. Recover the database only through the reviewed backup/restore procedure and coordinate downtime; do not assume restarting the old image recovers it. First installation has no prior image to restore. Host logs remain in `logs/docker-update.log` and may contain application/database diagnostics; restrict access.
+
+Local Git Bash tests cover selection validation and mocked failure paths. They do not establish Linux container startup, runtime filesystem permissions, registry availability or real MariaDB upgrade compatibility.

docs/operations/personal-tokens/README.md

@@ -0,0 +1,26 @@
+# Personal API token scopes
+
+Public API bearer authentication accepts only tokens owned by the exact `App\Models\User` model. The owner ID must be a positive, safely representable user ID, and the token must satisfy its existing expiration check. Both plaintext tokens and the existing `{id}|{plaintext}` request format remain supported; only the SHA-256 hash is looked up in the database.
+
+The `abilities` column must contain a non-empty JSON array of non-empty strings. Null, malformed JSON, non-array JSON, empty arrays, non-string entries, and entries with surrounding whitespace are rejected. A valid `"*"` entry grants access to all existing bearer-protected endpoints. Other permissions match exactly: there is no `tickets:*` expansion, implicit read/write inheritance, or fallback to unrestricted access.
+
+| Ability | Endpoint access |
+| --- | --- |
+| `tickets:read` | `GET /api/tickets`, `GET /api/tickets/{id}` |
+| `tickets:write` | `POST /api/tickets`, `POST /api/tickets/{id}/reply` |
+| `articles:write` | `POST /api/articles/{slug}/comment` |
+| `radio:read` | `GET /api/radio/points` |
+| `radio:write` | `POST /api/radio/shouts` |
+| `badges:read` | Personal viewer data in `GET /api/badges/leaderboard` |
+
+For example, `["tickets:read","radio:read"]` allows reading the owner's tickets and radio points. It cannot create tickets, send replies, post article comments, or send radio shouts. Endpoint ownership checks and rate limits still apply after scope authorization.
+
+Required-token endpoints return the existing generic `401 Unauthorized` response when authorization fails. The badge leaderboard remains public: a denied bearer token receives the anonymous view, without personal viewer data. When an Authorization header is present, this endpoint does not use a session cookie to bypass a denied token. Session-only requests continue to personalize the leaderboard normally.
+
+## Compatibility and maintenance
+
+Existing valid wildcard tokens remain compatible. The existing session-authenticated `POST /api/tokens` endpoint continues issuing `["*"]`; this change does not add token-creation options or alter stored tokens. Legacy null, malformed, empty, differently cased model names, and unrelated model tokens are intentionally denied. Review and replace affected tokens with explicit intended scopes, or reissue through the existing token endpoint when full access is appropriate.
+
+Every new bearer-authenticated endpoint must pass its required abilities to `bearerUserId`. Multiple required abilities use AND semantics. Omitting the requirements, or passing an empty list, requires a wildcard token rather than granting arbitrary scoped tokens access.
+
+No plaintext token or stored hash is added to error responses or logs by these checks. The existing issuance endpoint returns plaintext once by design.

docs/operations/security-review-2026-09-13.md

@@ -0,0 +1,31 @@
+# Security report verification — 2026-09-13
+
+The supplied review describes commit `baeb54ae` plus a separate port for another hotel. Its “Fixed” labels were not evidence that the changes existed in EpicNext-Cms. This verification inspected canonical `main` at `52f6d149` and the corrective changes prepared here. No exploit or authenticated mutation was performed against production.
+
+| Supplied finding | Verified state in baseline | Correction / remaining boundary |
+| --- | --- | --- |
+| 1. Logo authorization/upload | Confirmed missing action permission and per-file validation | Require settings edit before input or storage access; bounded decoded raster uploads |
+| 2. Favicon authorization/delete | Confirmed missing action permission; SVG accepted | Same permission boundary for create/delete, bounded raster/ICO validation |
+| 3. Active uploaded SVG | Confirmed SVG served inline without route CSP | Route CSP sandbox and nosniff on success/errors; existing SVG served as attachment |
+| 4. Client IP spoofing | Confirmed direct trust in caller-controlled `x-real-client-ip` | Shared validated resolver ignores that header. Forwarded headers still require trusted ingress that overwrites them and prevents direct public origin access |
+| 5. Email token action exports | Confirmed token helpers in a `use server` module | Move token creation/validation and delivery to a server-only module. Registration and verification call it internally |
+| 6. Locale cookie | Confirmed missing allowlist | Supported locales only, validate before reading/writing cookies |
+| 7. Email header injection | Confirmed unsanitized values in sendmail headers | Reject control characters before any mail transport or file fallback; includes configured sender |
+| 8. Gateway CORS | Supplied gateway path is outside this repository | Read-only GET to our `/api/health` with an unrelated Origin returned a fixed `https://epicnabbo.nl` allow-origin and no allow-credentials. This does not reproduce the report on that route, nor certify every host/route |
+| 9. Token abilities | Confirmed abilities and owner type not checked by bearer authentication | Enforce User owner type and explicit endpoint abilities; existing wildcard user tokens remain supported |
+| 10. Broad script CDN | Confirmed unrestricted jsDelivr script source, without a source-code consumer | Remove the broad script source; retain required captcha/analytics sources and nonce |
+
+The additional `withNitroStaff` code and its tests mentioned in the supplied port do not exist in this checkout; they were not assumed to have been reviewed or imported.
+
+## Evidence and limits
+
+- Regression tests exercise authorization before I/O, actual file decoding, SVG/error response headers, token-boundary exports, token abilities, forged derived-IP headers across consumers, locale values, and mail header control characters.
+- An updated `pnpm audit --json` reported zero known advisories. This is a dependency database result, not proof that application code has no vulnerabilities.
+- Next.js treats exported Server Actions as public endpoints; unused actions can also be removed by the compiler. The email refactor removes the action boundary entirely instead of relying on whether a specific build exports an unused helper. See [Next.js data security](https://nextjs.org/docs/app/guides/data-security).
+- The framework also has its own Server Action body limit. The logo defect was absence of application-level file validation, not evidence of literally unlimited bytes through every deployment layer.
+- No live database, user accounts, uploaded files, or gateway configuration were modified during verification. These changes do not constitute a penetration test or an audit of the emulator, host, or all CMS endpoints.
+- No nginx/Traefik ingress configuration is versioned here. The deployment guide records the forwarding-header trust requirement. That external boundary remains unverified.
+
+## Follow-up identified during verification
+
+The separate comment review is now implemented: both the website form and REST API use one submission service, require a published article whose publication time is due, apply the same moderation, and share a five-attempt/30-second per-user quota. The publication check locks the current article in the insertion transaction. Regression tests cover both entrypoints; real MariaDB/Redis coverage includes publication eligibility, word filtering and alternating submissions. Moderation retains its existing fail-open behavior on service outages. Form input beyond 255 characters is now rejected instead of truncated, and temporary API storage failures return 503. Real integration execution remains a required CI check.

docs/performance-budgets.md

@@ -0,0 +1,39 @@
+# Informational route JavaScript budgets
+
+Run after the existing production build; no second build or server is needed:
+
+```sh
+node scripts/performance-report.mjs --next-dir .next --config scripts/performance-budgets.json --output-dir build-reports
+```
+
+The command writes `report.json` and `report.md` and prints the Markdown report. An optional `PERFORMANCE_COMMIT_SHA` environment variable records the commit declared by the build caller; the script does not infer that an existing build matches the current checkout. JSON also records `BUILD_ID`, Node/zlib versions, manifest provenance, exact file paths, sizes and source entries.
+
+## What is measured
+
+For each configured App Router route, resolve its exact app path using `app-path-routes-manifest.json` and `server/app-paths-manifest.json`. Read its generated `page_client-reference-manifest.js` as a JSON assignment **without executing JavaScript**. Use its sibling `page/build-manifest.json`, falling back to the root build manifest only if that sibling is absent.
+
+The **initial entry envelope** is the union of route bootstrap `rootMainFilesTree[appPath]` (or `rootMainFiles`) and every `entryJSFiles` list in that route's client-reference manifest. This includes layout, page and boundary/loading entries. The definition follows the data exposed by the installed Next 16.3.4 Turbopack build and the `getLinkAndScriptTags` / `getRequiredScripts` renderer helpers; it is deliberately a build-artifact envelope, not a browser network trace. Conditional rendering, redirects, streaming and browser caches can change actual requests.
+
+- Raw bytes are filesystem byte lengths of unique JavaScript assets in that envelope.
+- Gzip bytes are the **sum of independent gzip level 9 compressions** of those files using the recorded Node/zlib runtime. They are not gzip of concatenated source, nor observed CDN transfer sizes.
+- Deployment query strings and `/_next/` prefixes are normalized before deduplication. Shared files count once per route; each route is measured independently, with no misleading cross-route total.
+- Legacy `nomodule` polyfills are measured separately, outside the modern initial budget. CSS, source maps, images, external scripts, HTML/RSC payloads and async-only chunks absent from `entryJSFiles` are excluded.
+- This report makes no claims about execution cost, LCP, hydration time or real-user performance.
+
+## Initial limits
+
+The first limits are **baseline bytes × 1.15, rounded upward to the next 10 KiB (10,240 bytes)** independently for raw and gzip. They are provisional size alerts, not validated speed targets. Baseline: existing local production build `build-TfctsWXpff2fKS`, Next 16.3.4; its source commit was not inferred.
+
+| Route | Baseline raw bytes | Baseline gzip bytes | Raw limit | Gzip limit |
+| --- | ---: | ---: | ---: | ---: |
+| `/me` | 767156 | 238571 | 890880 | 276480 |
+| `/news` | 765367 | 237599 | 880640 | 276480 |
+| `/events` | 765851 | 237964 | 890880 | 276480 |
+| `/search` | 765851 | 237964 | 890880 | 276480 |
+| `/admin/catalog` | 1654898 | 492619 | 1904640 | 573440 |
+| `/admin/studio/furni` | 1241312 | 391541 | 1433600 | 450560 |
+
+Configured limits are positive integer bytes; `null` explicitly means observe-only. `scripts/performance-budgets.json` remains `mode: informational`. Exceeding a limit produces `over-budget` and a warning, with exit code 0. Missing production `BUILD_ID`, unsupported manifests, missing routes or missing referenced assets produce `unavailable` with a reason and **no partial/zero total**, also exit code 0. Malformed budget configuration or an unwritable output directory fails the command. This keeps initial CI reporting non-blocking while preventing invalid configuration from quietly disabling limits.
+
+Synthetic tests cover shared-chunk deduplication, exact byte/gzip calculations, route bootstrap selection, missing data, safe parsing and CLI exit behavior. Run `pnpm exec vitest run --coverage.enabled=false scripts/performance-report.test.mjs`.
+

docs/superpowers/plans/2026-09-13-security-followups.md

@@ -0,0 +1,16 @@
+# Security and operational reliability implementation plan
+
+Goal: finish the five approved follow-ups with independently verified commits.
+Architecture: share comment policy between session and bearer entrypoints; opt-in same-host proxy configuration; run real news browser checks against the already-built candidate in disposable services; correlate existing diagnostics with deliveries; verify database and persistent-file backup restoration in isolation.
+Stack: existing Next, MariaDB, Redis, Playwright, Testcontainers and Docker; no new dependencies.
+Design: user-approved numbered proposal in this task, 2026-09-13.
+
+Global constraints: preserve current public/HK UX and ACL; no production test content or proxy/firewall changes; no credentials in output; root owns Git on canonical main. Complete each block's checks before an exact-file commit and push. Confirm final CI, container publication and live release.
+
+1. Comments — src/actions/article-comments.ts, API comment route and shared policy/tests. Add regression cases for hidden/future articles, moderation, cross-channel limit and safe failures; reproduce them, implement, run focused and integration checks. Publicly available article predicate is checked on both entrypoints.
+2. Proxy — deployment/proxy templates and installation guide/tests. Override must survive installer/update/rollback, force loopback and replace incoming identity headers. Validate the merged Compose config and Nginx syntax; do not apply to the host.
+3. Real news — e2e/news-real runner/fixture plus ci-deploy gate and harness tests. Start only disposable MariaDB/Redis and the local candidate image; real staff login, draft, preview, publish and anonymous read. Fail before live migration/cutover on any error, clean all fixture resources. Require successful CI execution.
+4. Diagnostics — carry persisted operation/delivery identifiers into error records; link filtered deliveries and diagnostics with permission checks. Preserve request correlation separately. Tests cover exact matching, hostile IDs, permissions and retry outcomes.
+5. Recovery — backup creation and isolated restore drill for database plus explicit persistent directories. Keep credentials off argv/logs, reject unsafe paths and incomplete/tampered artifacts. Test real database restore and file checksums with disposable data, record limits for cross-service consistency. Never overwrite production during a drill.
+
+Status: all five blocks implemented and locally checked. Required final gates: CI real database/proxy/backup suites, candidate news browser journey, deployment/container completion and live release verification. Extra scheduler deadlock discovered in the real concurrency test is fixed with bounded transaction retries. Evidence and boundaries accompany each delivered block.

docs/testing/database-integration.md

@@ -0,0 +1,23 @@
+# Real database integration tests
+
+Run `pnpm test:integration` on a Docker-capable host. Missing Docker or failed container setup fails the suite. CI runs this check before deployment.
+
+Sixteen database tests exercise the production database commands, news actions, public article query and delivery worker against MariaDB 11.4.5 and Redis 7.4.2:
+
+- Migration CLI replay/status, committed catalog bulk edits and undo history, complete rollback after an audit insert fails, and competing catalog previews.
+- Real Redis expiry metadata and cache-key isolation, concurrent request idempotency, operation/outbox rollback, and exclusive delivery claims.
+- Concurrent duplicate draft creation and publication produce one article, one revision, one audit update and one effect per operation. The public query changes from cached absence to the full published content, including Unicode and a body larger than a TEXT column.
+- A database trigger rejects the publication effect after the article, revision and audit writes. The transaction restores all preceding state; the identical request can then retry successfully without duplicate history.
+- A trigger rejects the second scheduled-publication effect. Both article updates and both operations roll back, including the first queued effect.
+- Competing scheduler ticks publish each due article once, preserve future articles and drafts, retain an unsigned bigint ID beyond JavaScript's safe integer range, and attribute a legacy authorless article to the system actor.
+- A real Redis client disconnect leaves a publication committed and readable directly from MariaDB. The worker records a pending failed attempt. Reconnecting retains the stale cached absence until a successful outbox retry rotates the cache revision; the public query then returns the published article. The test advances only the queued retry timestamp to avoid sleeping.
+
+Each execution starts disposable containers with random exposed ports and generated passwords. No production URLs, volumes or credentials are used. The real migration CLI is copied beneath a temporary isolated fixture root so its environment loader cannot read the checkout environment file. Cleanup attempts all connections and containers even if a previous cleanup fails. The fixture inspection connection reads timestamps as UTC; the application keeps its production connection settings and host timezone. Each test receives a fresh news-cache revision, and the disconnect test reconnects its client in a `finally` block.
+
+Only authorization/session lookup, translation lookup, Next.js revalidation/redirects, and the external publication webhook are mocked for the news actions. MariaDB, Drizzle, transactions, article revisions, history, operation deduplication, outbox claims/retries, Redis caching, the publication scheduler, public article lookup and the news delivery handler use their production implementations.
+
+The fixture models the emulator's catalog/audit baseline plus the legacy article columns. Real migrations 0025-0029 and 0031 supply publication, editorial recovery, catalog packages, history and operations tables. This does not certify every historical emulator schema or migration.
+
+These are application-service integration tests, not browser or HTTP end-to-end tests: they do not start a Next.js server, render the news page, verify login/ACL behavior, or send external webhooks. The cache outage test closes and restores the actual application Redis connection; it does not stop the Redis server or model a multi-host network partition. Passing TypeScript or unit tests without Docker is not a passing result for this suite.
+
+Public comment pagination and reaction aggregation are covered by unit tests using the production Drizzle query builder with a substituted database transport, plus server-rendered page tests with substituted service results. This integration fixture does not create users or article-reactions tables and does not execute the public pagination and aggregation queries against MariaDB; its article-comments table is used for submission tests. Comment submission now additionally uses real MariaDB and Redis to verify publication eligibility, filtering and the shared quota across the actual form/API handlers, with authentication replaced at the boundary. The article-cache upgrade test verifies that legacy cached absence is ignored under the versioned key; it is a unit test, separate from the real Redis publication and delivery checks above.

docs/testing/news-e2e.md

@@ -0,0 +1,38 @@
+# Real news browser gate
+
+Run `pnpm test:news:real` with `NEWS_E2E_IMAGE=epicnext-cms:<candidate-tag>`. Docker CLI, a working Docker daemon, the OpenSSL CLI with `-addext` support, installed project dependencies and Playwright Chromium are required. The runner deliberately fails when the image or Docker is unavailable. It never silently skips the browser journey.
+
+`NEWS_E2E_RELEASE=<full-commit-sha>` additionally verifies the image revision label. The runner resolves the local image to its immutable ID before starting it. It does not build or pull the application image. MariaDB 11.4.5 and Redis 7.4.2 Alpine are disposable Testcontainers dependencies and may be pulled when absent.
+
+The deployment script runs this gate after building the candidate and extracting its performance report, before live database migrations and container cutover. The general Playwright suite excludes `e2e/news-real`; this suite has its own configuration and requires the runner.
+
+## What the browser proves
+
+One Chromium journey exercises the candidate's normal Docker entrypoint and standalone Next server:
+
+1. An anonymous request to the staff editor reaches the login page.
+2. The browser signs in through the actual login form, credential precheck and Auth.js handler. The test verifies the real Secure/HttpOnly session cookie and database login record.
+3. A rank 7 editor, below an occupied rank 9 owner, accesses news through three explicit ACL grants: `admin.dashboard`, `admin.news.view` and `admin.news.edit`.
+4. The browser types Unicode content into the bundled TinyMCE editor and saves a draft through the real server action. The persisted HTML must equal what the form submitted.
+5. An independent anonymous browser sees the not-found screen; the public articles API returns an empty list. Redis contains the cached null article. Next can stream a not-found screen with HTTP 200, so this check verifies the rendered 404 screen as well as absence from the API.
+6. The editor reopens and previews the saved draft in the real preview iframe. Its title, summary and rendered body match; it remains a draft with no article revision created by previewing.
+7. Publishing through the editor produces one article, a publication timestamp, one previous-draft revision, a before/after audit entry, two completed operation results and two news-refresh outbox entries.
+8. The anonymous page and API immediately show the article, using a new shared Redis cache revision. The browser remains signed out.
+
+No authentication, application HTTP responses, mutations, database calls or cache calls are mocked. The browser blocks resources outside the local fixture origin, such as external avatars. This does not replace any application response. A local HTTPS edge passes requests to Next and sets trusted forwarding headers, allowing the production Secure-cookie behavior to run normally.
+
+The fresh browser contexts retain normal application service-worker registration. The application worker does not cache article or authentication responses. Playwright's worker-blocking injection is avoided because it throws inside the sandboxed preview; browser errors are still checked without filtering. The preview is closed through its Close button, since keyboard events inside its sandbox do not reach the parent dialog.
+
+## Isolation and cleanup
+
+- Each run creates a random Docker network and fresh MariaDB, Redis and candidate containers. All mapped ports are allocated dynamically. The HTTPS listener binds only to `127.0.0.1`.
+- No production container, database, volume or credentials are reused. Container configuration is explicit. Child processes receive a small environment whitelist; checkout `.env` and installation service credentials are not forwarded.
+- The database uses the current ORM column definitions for 29 tables needed by login, site/admin layouts and news. Unique constraints and composite primary keys are preserved. The emulator-owned `permission_ranks` fixture provides the rank authority columns this flow queries. Real CMS migrations 0026 and 0031 create the recovery/revision and operation/outbox tables. This is a focused fixture, not a replacement for the emulator's complete schema or migration coverage.
+- Passwords, Redis credentials and the Auth.js secret are generated per run. The owner has an unknown random password and is never used to bypass ACL checks. Email verification is enabled with a verified fixture staff account. CAPTCHA and forced staff 2FA use their ordinary disabled installation settings; their challenges are outside this flow.
+- OpenSSL generates a fresh localhost certificate and private key in the OS temporary directory for each run. The certificate lasts one day and covers `127.0.0.1` and `localhost`. Playwright trusts this self-signed endpoint only in this suite. No certificate or key is committed or copied into build artifacts; cleanup removes both with the temporary credentials.
+- Credentials used by the test worker are stored in an OS temporary directory with a mode-0600 file, then removed. Cleanup stops only containers and the network created by this runner; Testcontainers also registers them with its resource reaper.
+- Failure artifacts are under `test-results/news-real` and `playwright-report/news-real`. Server logs redact generated passwords/secrets. Playwright traces can contain the short-lived fixture login/session data; all associated services are destroyed after the run.
+
+This browser gate checks the synchronous editor/publication path and durable delivery intent. Scheduler concurrency, rollback, duplicate requests, worker delivery and Redis outage/recovery remain covered by `pnpm test:integration`. It does not claim to test emulator connectivity, external notifications, CAPTCHA/2FA challenges or production data.
+
+The local workstation currently has no working Docker daemon. Type checks, lint and fixture/bootstrap checks can run there; a passing real browser result must come from the Docker-capable CI gate.

drizzle/drafts/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "mysql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "5",
+      "when": 1788791201804,
+      "tag": "0000_premium_spirit",
+      "breakpoints": true
+    }
+  ]
+}

drizzle/migrations/0026_article_editor_recovery.sql

@@ -0,0 +1,16 @@
+CREATE TABLE IF NOT EXISTS website_article_drafts (
+ user_id BIGINT UNSIGNED NOT NULL,
+ article_key VARCHAR(32) NOT NULL,
+ version INT UNSIGNED NOT NULL,
+ payload LONGTEXT NOT NULL,
+ updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ PRIMARY KEY (user_id, article_key)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+CREATE TABLE IF NOT EXISTS website_article_revisions (
+ id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
+ article_id BIGINT UNSIGNED NOT NULL,
+ user_id BIGINT UNSIGNED NOT NULL,
+ payload LONGTEXT NOT NULL,
+ created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ INDEX article_history (article_id, id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

drizzle/migrations/0027_catalog_packages.sql

@@ -0,0 +1,10 @@
+CREATE TABLE IF NOT EXISTS website_catalog_packages (
+ id VARCHAR(36) NOT NULL PRIMARY KEY,
+ name VARCHAR(128) NOT NULL,
+ version INT UNSIGNED NOT NULL,
+ status VARCHAR(16) NOT NULL,
+ mode VARCHAR(16) NOT NULL,
+ payload LONGTEXT NOT NULL,
+ updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ INDEX package_recent (updated_at, id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

drizzle/migrations/0028_history_snapshots.sql

@@ -0,0 +1,2 @@
+-- Preserve complete before/after snapshots for long news articles.
+ALTER TABLE admin_audit_log MODIFY COLUMN `before` MEDIUMTEXT NULL, MODIFY COLUMN `after` MEDIUMTEXT NULL;

drizzle/migrations/0029_admin_table_views.sql

@@ -0,0 +1,7 @@
+CREATE TABLE IF NOT EXISTS website_admin_table_views (
+ user_id INT NOT NULL,
+ path VARCHAR(191) NOT NULL,
+ name VARCHAR(60) NOT NULL,
+ state TEXT NOT NULL,
+ PRIMARY KEY (user_id, path, name)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

drizzle/migrations/0030_profile_privacy.sql

@@ -0,0 +1,9 @@
+CREATE TABLE IF NOT EXISTS `website_profile_privacy` (
+ `user_id` int NOT NULL,
+ `wallet` boolean NOT NULL DEFAULT false,
+ `online` boolean NOT NULL DEFAULT true,
+ `friends` boolean NOT NULL DEFAULT true,
+ `photos` boolean NOT NULL DEFAULT true,
+ `registered` boolean NOT NULL DEFAULT true,
+ PRIMARY KEY (`user_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

drizzle/migrations/0031_operations_outbox.sql

@@ -0,0 +1,25 @@
+CREATE TABLE IF NOT EXISTS cms_operations (
+ id CHAR(36) CHARACTER SET ascii COLLATE ascii_bin PRIMARY KEY,
+ actor_id INT NOT NULL,
+ kind VARCHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
+ request_key CHAR(36) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
+ request_hash CHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
+ result_json MEDIUMTEXT NULL,
+ created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+ UNIQUE KEY operation_request (actor_id,kind,request_key)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+CREATE TABLE IF NOT EXISTS cms_outbox (
+ id CHAR(36) CHARACTER SET ascii COLLATE ascii_bin PRIMARY KEY,
+ operation_id CHAR(36) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
+ topic VARCHAR(64) NOT NULL,
+ status VARCHAR(16) NOT NULL DEFAULT 'pending',
+ attempts INT NOT NULL DEFAULT 0,
+ available_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+ lease_until DATETIME(3) NULL,
+ lease_token CHAR(36) CHARACTER SET ascii COLLATE ascii_bin NULL,
+ last_error VARCHAR(255) NULL,
+ created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+ UNIQUE KEY operation_effect (operation_id,topic),
+ KEY delivery_pending (status,available_at),
+ KEY delivery_lease (status,lease_until)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

drizzle/migrations/0032_notification_state.sql

@@ -0,0 +1,13 @@
+CREATE TABLE IF NOT EXISTS `website_notification_reads` (
+ `user_id` int NOT NULL,
+ `event_key` varchar(128) NOT NULL,
+ `read_at` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ PRIMARY KEY (`user_id`, `event_key`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+CREATE TABLE IF NOT EXISTS `website_notification_preferences` (
+ `user_id` int NOT NULL,
+ `support` boolean NOT NULL DEFAULT true,
+ `friends` boolean NOT NULL DEFAULT true,
+ `events` boolean NOT NULL DEFAULT true,
+ PRIMARY KEY (`user_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

drizzle/migrations/0033_referrals_daily_rewards.sql

@@ -0,0 +1,154 @@
+-- 0033_referrals_daily_rewards.sql
+-- Referral attribution tables (mirror the live-DB shape used by the existing
+-- referral claim flow in src/actions/referral.ts) plus the CMS-owned daily
+-- login reward schedule and claim ledger. All CREATE statements are idempotent
+-- (IF NOT EXISTS) so fresh installs get the tables and existing hotels keep
+-- whatever rows they already have.
+
+CREATE TABLE IF NOT EXISTS `user_referrals` (
+    `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+    `user_id` INT NOT NULL,
+    `referrals_total` BIGINT UNSIGNED NOT NULL DEFAULT 0,
+    `created_at` TIMESTAMP NULL,
+    `updated_at` TIMESTAMP NULL,
+    PRIMARY KEY (`id`),
+    KEY `user_referrals_user_idx` (`user_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+CREATE TABLE IF NOT EXISTS `referrals` (
+    `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+    `user_id` INT NOT NULL,
+    `referred_user_id` BIGINT UNSIGNED NOT NULL,
+    `referred_user_ip` VARCHAR(255) NOT NULL,
+    `created_at` TIMESTAMP NULL,
+    `updated_at` TIMESTAMP NULL,
+    PRIMARY KEY (`id`),
+    KEY `referrals_user_idx` (`user_id`),
+    KEY `referrals_referred_user_idx` (`referred_user_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+CREATE TABLE IF NOT EXISTS `claimed_referral_logs` (
+    `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+    `user_id` INT NOT NULL,
+    `ip_address` VARCHAR(255) NOT NULL,
+    `created_at` TIMESTAMP NULL,
+    `updated_at` TIMESTAMP NULL,
+    PRIMARY KEY (`id`),
+    KEY `claimed_referral_logs_user_idx` (`user_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- Daily login reward schedule: one row per streak day. The cycle repeats after
+-- the highest day (day 1 of the cycle is used for any missing day).
+CREATE TABLE IF NOT EXISTS `website_daily_rewards` (
+    `id` INT UNSIGNED NOT NULL AUTO_INCREMENT,
+    `day` INT UNSIGNED NOT NULL DEFAULT 1,
+    `currency` VARCHAR(20) NOT NULL DEFAULT 'credits',
+    `amount` INT NOT NULL DEFAULT 0,
+    `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `website_daily_rewards_day_uk` (`day`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- Daily reward claims ledger; one row per user per claim date.
+CREATE TABLE IF NOT EXISTS `website_daily_reward_claims` (
+    `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+    `user_id` INT NOT NULL,
+    `claim_date` DATE NOT NULL,
+    `streak` INT UNSIGNED NOT NULL DEFAULT 1,
+    `reward_day` INT UNSIGNED NOT NULL DEFAULT 1,
+    `currency` VARCHAR(20) NOT NULL DEFAULT 'credits',
+    `amount` INT NOT NULL DEFAULT 0,
+    `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `daily_claim_user_date_uk` (`user_id`, `claim_date`),
+    KEY `daily_claim_created_idx` (`created_at`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- Seed a sensible 7-day reward schedule only when the table is still empty.
+INSERT INTO `website_daily_rewards` (`day`, `currency`, `amount`)
+SELECT 1, 'duckets', 60
+FROM DUAL
+WHERE NOT EXISTS (SELECT 1 FROM `website_daily_rewards`);
+INSERT INTO `website_daily_rewards` (`day`, `currency`, `amount`)
+SELECT 3, 'credits', 50
+FROM DUAL
+WHERE (SELECT COUNT(*) FROM `website_daily_rewards`) = 1
+  AND NOT EXISTS (SELECT 1 FROM `website_daily_rewards` WHERE `day` = 3);
+INSERT INTO `website_daily_rewards` (`day`, `currency`, `amount`)
+SELECT 5, 'diamonds', 2
+FROM DUAL
+WHERE (SELECT COUNT(*) FROM `website_daily_rewards`) = 2
+  AND NOT EXISTS (SELECT 1 FROM `website_daily_rewards` WHERE `day` = 5);
+
+-- Referral + daily reward configuration defaults (never overwrite an existing
+-- value — operators tune these keys in the admin panel).
+INSERT INTO `website_settings` (`key`, `value`, `comment`)
+SELECT 'referrals_block_same_ip', '1', 'Block referral attribution when the new account shares the inviter IP'
+FROM DUAL
+WHERE NOT EXISTS (SELECT 1 FROM `website_settings` WHERE `key` = 'referrals_block_same_ip');
+INSERT INTO `website_settings` (`key`, `value`, `comment`)
+SELECT 'daily_reward_enabled', '1', 'Enable the daily login reward claims on /me'
+FROM DUAL
+WHERE NOT EXISTS (SELECT 1 FROM `website_settings` WHERE `key` = 'daily_reward_enabled');
+
+-- New ACL slugs backing the /admin/referrals + /admin/daily-rewards modules.
+INSERT INTO `acl_permissions` (`slug`, `title`) VALUES
+  ('admin.referrals.view', 'View referrals'),
+  ('admin.referrals.edit', 'Edit referrals'),
+  ('admin.dailyrewards.view', 'View daily login rewards'),
+  ('admin.dailyrewards.edit', 'Edit daily login rewards')
+ON DUPLICATE KEY UPDATE `title` = VALUES(`title`);
+
+-- Grant the new slugs to the same roles that already open the admin panel.
+INSERT INTO `acl_model_permissions` (`model_type`, `model_id`, `permission_id`)
+SELECT 'Role', ar.id, ap.id
+FROM `acl_roles` ar
+JOIN `acl_permissions` ap ON ap.slug IN (
+  'admin.referrals.view', 'admin.referrals.edit',
+  'admin.dailyrewards.view', 'admin.dailyrewards.edit'
+)
+WHERE EXISTS (
+  SELECT 1
+  FROM `acl_model_permissions` amp
+  JOIN `acl_permissions` apdash ON apdash.id = amp.permission_id
+  WHERE amp.model_type = 'Role'
+    AND amp.model_id = ar.id
+    AND apdash.slug = 'admin.dashboard'
+)
+AND NOT EXISTS (
+  SELECT 1
+  FROM `acl_model_permissions` amp2
+  WHERE amp2.model_type = 'Role'
+    AND amp2.model_id = ar.id
+    AND amp2.permission_id = ap.id
+);
+
+-- Safety net matching the 0018 seed: ranks >= 6 view, ranks >= 7 edit.
+INSERT INTO `acl_model_permissions` (`model_type`, `model_id`, `permission_id`)
+SELECT 'Role', ar.id, ap.id
+FROM `permission_ranks` pr
+JOIN `acl_roles` ar ON ar.slug = CONCAT('rank_', pr.id)
+JOIN `acl_permissions` ap ON ap.slug IN ('admin.referrals.view', 'admin.dailyrewards.view')
+WHERE pr.id >= 6
+AND NOT EXISTS (
+  SELECT 1
+  FROM `acl_model_permissions` amp
+  WHERE amp.model_type = 'Role'
+    AND amp.model_id = ar.id
+    AND amp.permission_id = ap.id
+);
+
+INSERT INTO `acl_model_permissions` (`model_type`, `model_id`, `permission_id`)
+SELECT 'Role', ar.id, ap.id
+FROM `permission_ranks` pr
+JOIN `acl_roles` ar ON ar.slug = CONCAT('rank_', pr.id)
+JOIN `acl_permissions` ap ON ap.slug IN ('admin.referrals.edit', 'admin.dailyrewards.edit')
+WHERE pr.id >= 7
+AND NOT EXISTS (
+  SELECT 1
+  FROM `acl_model_permissions` amp
+  WHERE amp.model_type = 'Role'
+    AND amp.model_id = ar.id
+    AND amp.permission_id = ap.id
+);

e2e/news-real/news.spec.ts

@@ -0,0 +1,302 @@
+import { readFile } from "node:fs/promises";
+import { type BrowserContext, expect, test } from "@playwright/test";
+import Redis from "ioredis";
+import mysql, {
+	type ConnectionOptions,
+	type RowDataPacket,
+} from "mysql2/promise";
+
+interface Fixture {
+	username: string;
+	userId: number;
+	password: string;
+	database: ConnectionOptions;
+	redis: { host: string; port: number; password: string };
+}
+
+async function onlyLocalResources(context: BrowserContext, origin: string) {
+	// External avatars/telemetry are outside this isolated hotel. All application
+	// documents, scripts, forms, API requests and auth responses remain untouched.
+	await context.route("**/*", (route) => {
+		if (new URL(route.request().url()).origin === origin)
+			return route.continue();
+		return route.abort("blockedbyclient");
+	});
+}
+
+test("staff signs in, saves a draft, previews it and publishes to anonymous readers", async ({
+	page,
+	context,
+	browser,
+	baseURL,
+}, testInfo) => {
+	if (!baseURL || !process.env.NEWS_E2E_FIXTURE)
+		throw Error("Disposable fixture is required");
+	const fixture = JSON.parse(
+		await readFile(process.env.NEWS_E2E_FIXTURE, "utf8"),
+	) as Fixture;
+	const database = await mysql.createConnection({
+		...fixture.database,
+		timezone: "Z",
+		charset: "utf8mb4",
+		supportBigNumbers: true,
+		bigNumberStrings: true,
+	});
+	const redis = new Redis({
+		...fixture.redis,
+		maxRetriesPerRequest: 1,
+		connectTimeout: 5_000,
+	});
+	const anonymous = await browser.newContext({
+		baseURL,
+		locale: "en-US",
+		ignoreHTTPSErrors: true,
+	});
+	const reader = await anonymous.newPage();
+	const errors: string[] = [];
+	page.on("pageerror", (error) => errors.push(error.message));
+	reader.on("pageerror", (error) => errors.push(error.message));
+	const rows = async (sql: string, params: string[] = []) =>
+		(await database.query<RowDataPacket[]>(sql, params))[0];
+	const title = "Notizia browser: città e novità 🎉";
+	const publicTitle = reader.locator(
+		".content-card:has(.article-body) .content-card-title",
+	);
+	const slug = "browser-news-real";
+	const summary =
+		"Una notizia creata e pubblicata attraverso il pannello reale.";
+	const body = "È una prova reale: caffè, città e 🎉. Salvata dal browser.";
+	let articleId = "";
+	let submittedHtml = "";
+	let draftRevision: string | null = null;
+	try {
+		await onlyLocalResources(context, baseURL);
+		await onlyLocalResources(anonymous, baseURL);
+		await redis.ping();
+		await test.step("real authentication and staff ACL", async () => {
+			await page.goto("/admin/articles/new");
+			await expect(page).toHaveURL(/\/login(?:\?|$)/);
+			expect(await rows("SELECT user_id FROM website_login_logs")).toHaveLength(
+				0,
+			);
+			await page
+				.locator('input[autocomplete="username"]')
+				.fill(fixture.username);
+			await page
+				.locator('input[autocomplete="current-password"]')
+				.fill(fixture.password);
+			await page
+				.locator('input[autocomplete="current-password"]')
+				.press("Enter");
+			await expect(page).toHaveURL(/\/me(?:\?|$)/);
+			const session = await context.request
+				.get("/api/auth/session")
+				.then((response) => response.json());
+			expect(session.user).toMatchObject({
+				id: String(fixture.userId),
+				name: fixture.username,
+				rank: 7,
+			});
+			expect(
+				(await context.cookies()).some(
+					(cookie) =>
+						cookie.name.startsWith("__Secure-authjs.session-token") &&
+						cookie.secure &&
+						cookie.httpOnly,
+				),
+			).toBe(true);
+			expect(await rows("SELECT user_id FROM website_login_logs")).toEqual([
+				expect.objectContaining({ user_id: fixture.userId }),
+			]);
+			// The editor is below the highest occupied rank: access requires real ACL grants.
+			expect(
+				(await rows("SELECT MAX(rank) AS highest FROM users"))[0].highest,
+			).toBe(9);
+			await page.goto("/admin/articles/new");
+			await expect(page.locator('input[name="title"]')).toBeVisible();
+		});
+		await test.step("save the draft using the real rich text editor and server action", async () => {
+			const form = page.locator('form:has(input[name="title"])');
+			await form.locator('input[name="title"]').fill(title);
+			await form.locator('input[name="slug"]').fill(slug);
+			await form.locator('[name="shortStory"]').fill(summary);
+			await form
+				.locator('input[name="image"]')
+				.fill("/assets/images/EnterHubbly.png");
+			await form.locator('select[name="status"]').selectOption("draft");
+			const editor = form
+				.frameLocator("iframe.tox-edit-area__iframe")
+				.locator('body[contenteditable="true"]');
+			await expect(editor).toBeVisible();
+			await editor.fill(body);
+			await editor.press("End");
+			await expect(form.locator('textarea[name="fullStory"]')).toHaveValue(
+				/Salvata dal browser/,
+			);
+			submittedHtml = await form
+				.locator('textarea[name="fullStory"]')
+				.inputValue();
+			await form.locator('button[type="submit"]').click();
+			await expect(page).toHaveURL(`${baseURL}/admin/articles`);
+			const articles = await rows("SELECT * FROM website_articles");
+			expect(articles).toHaveLength(1);
+			expect(articles[0]).toMatchObject({
+				title,
+				slug,
+				short_story: summary,
+				status: "draft",
+				user_id: fixture.userId,
+				published_at: null,
+				publish_at: null,
+			});
+			expect(articles[0].full_story).toBe(submittedHtml);
+			articleId = String(articles[0].id);
+			expect(await rows("SELECT kind, actor_id FROM cms_operations")).toEqual([
+				expect.objectContaining({
+					kind: "news.create",
+					actor_id: fixture.userId,
+				}),
+			]);
+		});
+		await test.step("anonymous readers and the shared cache still see no published article", async () => {
+			const response = await reader.goto(`/news/${slug}`);
+			expect(response?.status()).toBeLessThan(500);
+			// Next can stream not-found markup with HTTP 200; assert the actual 404 screen.
+			await expect(reader.locator(".error-screen-code")).toHaveText("404");
+			await expect(publicTitle).toHaveCount(0);
+			const listing = await anonymous.request
+				.get("/api/articles")
+				.then((response) => response.json());
+			expect(listing.data).toEqual([]);
+			expect(listing.meta.total).toBe(0);
+			draftRevision = await redis.get("cms:news:revision");
+			expect(draftRevision).not.toBeNull();
+			expect(
+				await redis.get(`news:${draftRevision}:article:v2:slug:${slug}`),
+			).toBe("null");
+		});
+		await test.step("preview the persisted draft without publishing it", async () => {
+			await page
+				.locator(`a[href="/admin/articles/${articleId}"]`)
+				.first()
+				.click();
+			const form = page.locator('form:has(input[name="title"])');
+			await expect(form.locator('input[name="title"]')).toHaveValue(title);
+			await expect(form.locator('select[name="status"]')).toHaveValue("draft");
+			await expect(
+				form.frameLocator("iframe.tox-edit-area__iframe").locator("body"),
+			).toContainText(body);
+			await form.getByRole("button", { name: "Preview", exact: true }).click();
+			const preview = page.getByRole("dialog").frameLocator("iframe");
+			await expect(
+				preview.getByRole("heading", { name: title, exact: true }),
+			).toBeVisible();
+			await expect(preview.locator("body")).toContainText(summary);
+			await expect(preview.locator("body")).toContainText(body);
+			expect(await rows("SELECT status FROM website_articles")).toEqual([
+				{ status: "draft" },
+			]);
+			expect(
+				await rows("SELECT id FROM website_article_revisions"),
+			).toHaveLength(0);
+			// Preview autofocus enters its sandboxed iframe, whose Escape event cannot reach the dialog.
+			await page
+				.getByRole("dialog")
+				.getByRole("button", { name: "Close", exact: true })
+				.click();
+			await expect(page.getByRole("dialog")).toHaveCount(0);
+		});
+		await test.step("publish once and persist revision, audit and delivery intent", async () => {
+			const form = page.locator('form:has(input[name="title"])');
+			await form.locator('select[name="status"]').selectOption("published");
+			await form.locator('button[type="submit"]').click();
+			await expect(page).toHaveURL(`${baseURL}/admin/articles`);
+			const articles = await rows("SELECT * FROM website_articles");
+			expect(articles).toHaveLength(1);
+			expect(articles[0]).toMatchObject({
+				status: "published",
+				user_id: fixture.userId,
+				slug,
+				title,
+			});
+			expect(articles[0].published_at).toBeInstanceOf(Date);
+			const revisions = await rows(
+				"SELECT article_id, user_id, payload FROM website_article_revisions",
+			);
+			expect(revisions).toHaveLength(1);
+			expect(String(revisions[0].article_id)).toBe(articleId);
+			expect(Number(revisions[0].user_id)).toBe(fixture.userId);
+			expect(JSON.parse(revisions[0].payload)).toMatchObject({
+				title,
+				status: "draft",
+			});
+			const audit = await rows(
+				"SELECT user_id, `before`, `after` FROM admin_audit_log WHERE target='news'",
+			);
+			expect(audit).toHaveLength(1);
+			expect(audit[0].user_id).toBe(fixture.userId);
+			expect(JSON.parse(audit[0].before).status).toBe("draft");
+			expect(JSON.parse(audit[0].after).status).toBe("published");
+			const operations = await rows(
+				"SELECT kind, actor_id, result_json FROM cms_operations ORDER BY kind",
+			);
+			expect(operations.map((operation) => operation.kind)).toEqual([
+				"news.create",
+				"news.update",
+			]);
+			for (const operation of operations) {
+				expect(operation.actor_id).toBe(fixture.userId);
+				expect(JSON.parse(operation.result_json)).toMatchObject({ ok: true });
+			}
+			const effects = await rows("SELECT topic FROM cms_outbox");
+			expect(effects).toEqual([
+				{ topic: "news.refresh" },
+				{ topic: "news.refresh" },
+			]);
+			expect(await redis.get("cms:news:revision")).not.toBe(draftRevision);
+		});
+		await test.step("anonymous pages and API read the newly published content", async () => {
+			const response = await reader.reload();
+			expect(response?.status()).toBe(200);
+			await expect(publicTitle).toHaveText(title);
+			await expect(publicTitle).toBeVisible();
+			await expect(reader.locator(".article-body")).toContainText(body);
+			await expect(reader.locator(".error-screen-code")).toHaveCount(0);
+			const listing = await anonymous.request
+				.get("/api/articles")
+				.then((response) => response.json());
+			expect(listing.data).toHaveLength(1);
+			expect(listing.data[0]).toMatchObject({
+				id: articleId,
+				title,
+				slug,
+				shortStory: summary,
+			});
+			expect(listing.meta.total).toBe(1);
+			const revision = await redis.get("cms:news:revision");
+			const cached = await redis.get(
+				`news:${revision}:article:v2:slug:${slug}`,
+			);
+			expect(JSON.parse(cached ?? "null")).toMatchObject({
+				id: articleId,
+				title,
+				slug,
+			});
+			expect(
+				(await anonymous.cookies()).some((cookie) =>
+					cookie.name.includes("session-token"),
+				),
+			).toBe(false);
+			expect(errors).toEqual([]);
+		});
+	} finally {
+		if (errors.length)
+			await testInfo.attach("browser-errors", {
+				body: JSON.stringify(errors, null, 2),
+				contentType: "application/json",
+			});
+		await anonymous.close().catch(() => {});
+		await database.end();
+		redis.disconnect();
+	}
+});

e2e/news-real/playwright.config.ts

@@ -0,0 +1,38 @@
+import { defineConfig, devices } from "@playwright/test";
+
+if (!process.env.NEWS_E2E_FIXTURE || !process.env.NEWS_E2E_BASE_URL)
+	throw Error(
+		"Run this suite with pnpm test:news:real; it requires disposable services.",
+	);
+
+export default defineConfig({
+	testDir: ".",
+	testMatch: "news.spec.ts",
+	fullyParallel: false,
+	workers: 1,
+	retries: 0,
+	timeout: 240_000,
+	expect: { timeout: 15_000 },
+	outputDir: "../../test-results/news-real",
+	reporter: [
+		["list"],
+		[
+			"html",
+			{ outputFolder: "../../playwright-report/news-real", open: "never" },
+		],
+	],
+	use: {
+		baseURL: process.env.NEWS_E2E_BASE_URL,
+		locale: "en-US",
+		ignoreHTTPSErrors: true,
+		trace: "retain-on-failure",
+		screenshot: "only-on-failure",
+		video: "off",
+		launchOptions: {
+			executablePath: process.env.UI_TEST_BROWSER_PATH || undefined,
+		},
+	},
+	projects: [
+		{ name: "chromium-real-news", use: { ...devices["Desktop Chrome"] } },
+	],
+});

e2e/news-real/run.ts

@@ -0,0 +1,387 @@
+import { execFile, spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { once } from "node:events";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { request as httpRequest } from "node:http";
+import { createServer, type Server } from "node:https";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import mysql, { type Connection } from "mysql2/promise";
+import {
+	GenericContainer,
+	Network,
+	type StartedNetwork,
+	type StartedTestContainer,
+	Wait,
+} from "testcontainers";
+import { STAFF_ID, STAFF_USERNAME, seedDatabase } from "./schema";
+
+const root = fileURLToPath(new URL("../../", import.meta.url));
+const execute = promisify(execFile);
+const image = process.env.NEWS_E2E_IMAGE;
+const release = process.env.NEWS_E2E_RELEASE;
+if (!image)
+	throw Error(
+		"NEWS_E2E_IMAGE is required: build the candidate image before running this test. Docker is mandatory.",
+	);
+if (!/^epicnext-cms:[a-zA-Z0-9_.-]+$/.test(image))
+	throw Error("NEWS_E2E_IMAGE must name a local epicnext-cms candidate tag.");
+if (release && !/^[0-9a-f]{40}$/.test(release))
+	throw Error("NEWS_E2E_RELEASE must be a full commit SHA.");
+
+// Never propagate checkout .env, NODE_OPTIONS, installation DB URLs or service tokens.
+const inherited = (names: string[]): NodeJS.ProcessEnv => ({
+	NODE_ENV: "test",
+	...Object.fromEntries(
+		names.flatMap((name) =>
+			process.env[name] === undefined ? [] : [[name, process.env[name]]],
+		),
+	),
+});
+const hostEnv = inherited([
+	"PATH",
+	"Path",
+	"SystemRoot",
+	"ComSpec",
+	"TEMP",
+	"TMP",
+	"TMPDIR",
+	"HOME",
+	"USERPROFILE",
+	"LOCALAPPDATA",
+]);
+const dockerEnv = {
+	...hostEnv,
+	...inherited([
+		"DOCKER_HOST",
+		"DOCKER_CONTEXT",
+		"DOCKER_CONFIG",
+		"DOCKER_CERT_PATH",
+		"DOCKER_TLS_VERIFY",
+	]),
+};
+const secrets = Array.from({ length: 4 }, () =>
+	randomBytes(32).toString("hex"),
+);
+const [databasePassword, redisPassword, staffPassword, authSecret] = secrets;
+const redact = (text: string) =>
+	secrets.reduce(
+		(value, secret) => value.replaceAll(secret, "[fixture secret]"),
+		text,
+	);
+const abort = new AbortController();
+const onSignal = () => abort.abort();
+process.once("SIGINT", onSignal);
+process.once("SIGTERM", onSignal);
+let network: StartedNetwork | undefined;
+let maria: StartedTestContainer | undefined;
+let redis: StartedTestContainer | undefined;
+let app: StartedTestContainer | undefined;
+let database: Connection | undefined;
+let proxy: Server | undefined;
+let temporary: string | undefined;
+let logs = "";
+
+try {
+	// Resolve the existing image before Testcontainers; starting by immutable ID cannot pull a tag.
+	const inspected = await execute(
+		"docker",
+		["image", "inspect", image, "--format", "{{json .}}"],
+		{ env: dockerEnv, timeout: 15_000 },
+	);
+	const candidate = JSON.parse(inspected.stdout) as {
+		Id: string;
+		Config: { Labels?: Record<string, string> };
+	};
+	if (!/^sha256:[0-9a-f]{64}$/.test(candidate.Id))
+		throw Error("Candidate image identity is invalid");
+	if (
+		release &&
+		candidate.Config.Labels?.["org.opencontainers.image.revision"] !== release
+	)
+		throw Error("Candidate image revision does not match NEWS_E2E_RELEASE");
+	abort.signal.throwIfAborted();
+	temporary = await mkdtemp(join(tmpdir(), "epicnext-news-e2e-"));
+	// Fresh local-only TLS material never enters the repository or build artifacts.
+	await execute(
+		"openssl",
+		[
+			"req",
+			"-x509",
+			"-newkey",
+			"rsa:2048",
+			"-nodes",
+			"-keyout",
+			join(temporary, "localhost.key"),
+			"-out",
+			join(temporary, "localhost.crt"),
+			"-days",
+			"1",
+			"-subj",
+			"/CN=localhost",
+			"-addext",
+			"subjectAltName=IP:127.0.0.1,DNS:localhost",
+		],
+		{ cwd: temporary, env: hostEnv, timeout: 30_000, signal: abort.signal },
+	);
+	console.log("News browser gate: starting isolated MariaDB and Redis");
+	network = await new Network().start();
+	const services = await Promise.allSettled([
+		new GenericContainer("mariadb:11.4.5")
+			.withNetwork(network)
+			.withNetworkAliases("news-db")
+			.withEnvironment({
+				MARIADB_ROOT_PASSWORD: randomBytes(32).toString("hex"),
+				MARIADB_DATABASE: "news_e2e",
+				MARIADB_USER: "news_e2e",
+				MARIADB_PASSWORD: databasePassword,
+			})
+			.withExposedPorts(3306)
+			.withHealthCheck({
+				test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"],
+				interval: 1000,
+				timeout: 5000,
+				retries: 60,
+				startPeriod: 1000,
+			})
+			.withWaitStrategy(Wait.forHealthCheck())
+			.withStartupTimeout(120_000)
+			.start()
+			.then((container) => {
+				maria = container;
+			}),
+		new GenericContainer("redis:7.4.2-alpine")
+			.withNetwork(network)
+			.withNetworkAliases("news-redis")
+			.withCommand(["redis-server", "--requirepass", redisPassword])
+			.withExposedPorts(6379)
+			.withWaitStrategy(Wait.forLogMessage("Ready to accept connections"))
+			.withStartupTimeout(60_000)
+			.start()
+			.then((container) => {
+				redis = container;
+			}),
+	]);
+	for (const service of services)
+		if (service.status === "rejected") throw service.reason;
+	if (!maria || !redis) throw Error("Disposable services did not start");
+	abort.signal.throwIfAborted();
+	database = await mysql.createConnection({
+		host: maria.getHost(),
+		port: maria.getMappedPort(3306),
+		user: "news_e2e",
+		password: databasePassword,
+		database: "news_e2e",
+		charset: "utf8mb4",
+		timezone: "Z",
+		supportBigNumbers: true,
+		bigNumberStrings: true,
+	});
+	await seedDatabase(database, staffPassword);
+	await database.end();
+	database = undefined;
+
+	let upstream: URL | undefined;
+	let origin = "";
+	proxy = createServer(
+		{
+			cert: await readFile(join(temporary, "localhost.crt")),
+			key: await readFile(join(temporary, "localhost.key")),
+		},
+		(request, response) => {
+			if (!upstream || request.headers.host !== new URL(origin).host) {
+				response.writeHead(503);
+				response.end();
+				return;
+			}
+			// A real local TLS edge, with the same forwarded-host/proto contract as deployment.
+			const headers = { ...request.headers };
+			delete headers["cf-connecting-ip"];
+			delete headers["x-real-client-ip"];
+			headers["x-forwarded-for"] = "127.0.0.1";
+			headers["x-real-ip"] = "127.0.0.1";
+			headers["x-forwarded-host"] = new URL(origin).host;
+			headers["x-forwarded-proto"] = "https";
+			const forwarded = httpRequest(
+				{
+					hostname: upstream.hostname,
+					port: upstream.port,
+					path: request.url,
+					method: request.method,
+					headers,
+				},
+				(received) => {
+					response.writeHead(received.statusCode ?? 502, received.headers);
+					received.pipe(response);
+				},
+			);
+			forwarded.on("error", () => {
+				if (!response.headersSent) response.writeHead(502);
+				response.end();
+			});
+			request.on("aborted", () => forwarded.destroy());
+			request.pipe(forwarded);
+		},
+	);
+	proxy.listen(0, "127.0.0.1");
+	await once(proxy, "listening");
+	const address = proxy.address();
+	if (!address || typeof address === "string")
+		throw Error("Local TLS listener is unavailable");
+	origin = `https://127.0.0.1:${address.port}`;
+	console.log("News browser gate: starting the production candidate image");
+	app = await new GenericContainer(candidate.Id.slice("sha256:".length))
+		.withNetwork(network)
+		.withEnvironment({
+			NODE_ENV: "production",
+			HOSTNAME: "0.0.0.0",
+			PORT: "3002",
+			DATABASE_URL: `mysql://news_e2e:${databasePassword}@news-db:3306/news_e2e`,
+			REDIS_URL: `redis://:${redisPassword}@news-redis:6379/0`,
+			HOTEL_NAME: "News browser fixture",
+			AUTH_SECRET: authSecret,
+			APP_URL: origin,
+			NEXT_PUBLIC_APP_URL: origin,
+			AUTH_URL: origin,
+			RCON_HOST: "127.0.0.1",
+			RCON_PORT: "9",
+			RCON_TIMEOUT_MS: "100",
+			RCON_MAX_RETRIES: "1",
+			IMAGING_UPSTREAM_URL: "http://127.0.0.1:9",
+			LOG_LEVEL: "warn",
+		})
+		.withExposedPorts(3002)
+		.withWaitStrategy(Wait.forHttp("/api/health", 3002).forStatusCode(200))
+		.withStartupTimeout(120_000)
+		.withLogConsumer((stream) =>
+			stream.on("data", (chunk: Buffer) => {
+				logs = (logs + chunk.toString()).slice(-2_000_000);
+			}),
+		)
+		.start();
+	upstream = new URL(`http://${app.getHost()}:${app.getMappedPort(3002)}`);
+	abort.signal.throwIfAborted();
+	const health = (await fetch(new URL("/api/health", upstream), {
+		signal: AbortSignal.timeout(10_000),
+	}).then((response) => response.json())) as {
+		status?: string;
+		database?: boolean;
+		redis?: boolean;
+	};
+	if (
+		health.status !== "ok" ||
+		health.database !== true ||
+		health.redis !== true
+	)
+		throw Error("Candidate health does not confirm both disposable services");
+	const fixturePath = join(temporary, "fixture.json");
+	await writeFile(
+		fixturePath,
+		JSON.stringify({
+			username: STAFF_USERNAME,
+			userId: STAFF_ID,
+			password: staffPassword,
+			database: {
+				host: maria.getHost(),
+				port: maria.getMappedPort(3306),
+				user: "news_e2e",
+				password: databasePassword,
+				database: "news_e2e",
+			},
+			redis: {
+				host: redis.getHost(),
+				port: redis.getMappedPort(6379),
+				password: redisPassword,
+			},
+		}),
+		{ mode: 0o600 },
+	);
+	console.log(
+		"News browser gate: login, draft, preview, publish and anonymous read",
+	);
+	const child = spawn(
+		process.execPath,
+		[
+			resolve(root, "node_modules/@playwright/test/cli.js"),
+			"test",
+			"--config",
+			"e2e/news-real/playwright.config.ts",
+		],
+		{
+			cwd: root,
+			env: {
+				...hostEnv,
+				...inherited([
+					"DISPLAY",
+					"XAUTHORITY",
+					"PLAYWRIGHT_BROWSERS_PATH",
+					"UI_TEST_BROWSER_PATH",
+					"CI",
+				]),
+				NEWS_E2E_FIXTURE: fixturePath,
+				NEWS_E2E_BASE_URL: origin,
+			},
+			stdio: "inherit",
+			signal: abort.signal,
+		},
+	);
+	const [code] = (await once(child, "exit")) as [number | null];
+	if (code !== 0)
+		throw Error(`Real news browser suite failed (exit ${code ?? "signal"})`);
+	console.log("News browser gate passed");
+} catch (error) {
+	console.error(
+		redact(
+			error instanceof Error ? (error.stack ?? error.message) : String(error),
+		),
+	);
+	process.exitCode = 1;
+} finally {
+	// Stop only objects created by this run. Testcontainers' resource reaper also owns them.
+	const cleanups: Array<[string, () => Promise<unknown>]> = [
+		[
+			"TLS proxy",
+			async () => {
+				proxy?.closeAllConnections();
+				if (proxy)
+					await new Promise<void>((done) => proxy?.close(() => done()));
+			},
+		],
+		["candidate", async () => app?.stop({ timeout: 10_000 })],
+		["database connection", async () => database?.end()],
+		["Redis", async () => redis?.stop()],
+		["MariaDB", async () => maria?.stop()],
+		["network", async () => network?.stop()],
+		[
+			"temporary credentials",
+			async () => {
+				if (!temporary) return;
+				if (
+					dirname(resolve(temporary)) !== resolve(tmpdir()) ||
+					!basename(temporary).startsWith("epicnext-news-e2e-")
+				)
+					throw Error(
+						"Temporary credentials path escaped the fixture directory",
+					);
+				await rm(temporary, { recursive: true, force: true });
+			},
+		],
+	];
+	for (const [name, cleanup] of cleanups) {
+		try {
+			await cleanup();
+		} catch (error) {
+			console.error(`Cleanup failed for ${name}: ${redact(String(error))}`);
+			process.exitCode = 1;
+		}
+	}
+	await mkdir(resolve(root, "test-results/news-real"), { recursive: true });
+	await writeFile(
+		resolve(root, "test-results/news-real/server.log"),
+		redact(logs),
+	);
+	process.removeListener("SIGINT", onSignal);
+	process.removeListener("SIGTERM", onSignal);
+}

e2e/news-real/schema.ts

@@ -0,0 +1,195 @@
+import { randomBytes } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { is, SQL } from "drizzle-orm";
+import {
+	getTableConfig,
+	MySqlDialect,
+	type MySqlTable,
+} from "drizzle-orm/mysql-core";
+import { bcrypt } from "hash-wasm";
+import mysql, { type Connection } from "mysql2/promise";
+import { splitSqlStatements } from "../../scripts/sql-statements";
+import * as schema from "../../src/db/schema";
+
+export const STAFF_ID = 7;
+export const STAFF_USERNAME = "NewsEditor";
+
+// Use the actual ORM definitions for the emulator tables this browser journey reads.
+// CMS recovery/outbox tables below come from the shipped migrations themselves.
+const tables: MySqlTable[] = [
+	schema.User,
+	schema.Ban,
+	schema.WebsiteSetting,
+	schema.WebsiteLanguages,
+	schema.AclRole,
+	schema.AclPermission,
+	schema.AclModelRole,
+	schema.AclModelPermission,
+	schema.WebsiteArticles,
+	schema.WebsiteArticleComments,
+	schema.WebsiteArticleReactions,
+	schema.WebsiteLoginLogs,
+	schema.AdminAuditLog,
+	schema.StaffActivities,
+	schema.WebsiteIpBlacklist,
+	schema.WebsiteIpWhitelist,
+	schema.AlertLogs,
+	schema.ThemeScope,
+	schema.ThemeScopeValue,
+	schema.UsersCurrency,
+	schema.MessengerFriendrequests,
+	schema.MessengerFriendships,
+	schema.MessengerOffline,
+	schema.Rooms,
+	schema.UsersBadges,
+	schema.UsersSettings,
+	schema.UserReferrals,
+	schema.WebsiteEvent,
+	schema.WebsiteEventType,
+];
+const identifier = (name: string) => `\`${name.replaceAll("`", "``")}\``;
+
+export function fixtureStatements(): string[] {
+	const dialect = new MySqlDialect();
+	return tables.map((table) => {
+		const config = getTableConfig(table);
+		// Fail on new constraints instead of silently reducing the fixture's integrity.
+		if (
+			config.foreignKeys.length ||
+			config.checks.length ||
+			config.uniqueConstraints.length
+		)
+			throw Error(`Fixture requires explicit constraints for ${config.name}`);
+		const columns = config.columns.map((column) => {
+			let ddl = `${identifier(column.name)} ${column.getSQLType()}`;
+			ddl += column.notNull ? " NOT NULL" : " NULL";
+			if ("autoIncrement" in column && column.autoIncrement)
+				ddl += " AUTO_INCREMENT";
+			if (column.primary) ddl += " PRIMARY KEY";
+			if (column.isUnique) ddl += " UNIQUE";
+			if (column.default !== undefined) {
+				if (is(column.default, SQL)) {
+					const query = dialect.sqlToQuery(column.default);
+					if (query.params.length)
+						throw Error(
+							`Fixture requires parameterized default for ${config.name}.${column.name}`,
+						);
+					ddl += ` DEFAULT ${query.sql}`;
+				} else if (
+					typeof column.default === "string" ||
+					typeof column.default === "number" ||
+					typeof column.default === "boolean" ||
+					column.default === null
+				)
+					ddl += ` DEFAULT ${mysql.escape(column.default)}`;
+				else
+					throw Error(
+						`Fixture requires explicit default for ${config.name}.${column.name}`,
+					);
+			} else if (!column.notNull) ddl += " DEFAULT NULL";
+			return ddl;
+		});
+		for (const key of config.primaryKeys)
+			columns.push(
+				`PRIMARY KEY (${key.columns.map((column) => identifier(column.name)).join(", ")})`,
+			);
+		for (const index of config.indexes) {
+			if (!index.config.unique) continue;
+			const names = index.config.columns.map((column) => {
+				if (is(column, SQL))
+					throw Error(`Fixture requires expression index for ${config.name}`);
+				return identifier(column.name);
+			});
+			columns.push(
+				`UNIQUE KEY ${identifier(index.config.name)} (${names.join(", ")})`,
+			);
+		}
+		return `CREATE TABLE ${identifier(config.name)} (${columns.join(",\n")}) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`;
+	});
+}
+
+export async function seedDatabase(
+	connection: Connection,
+	staffPassword: string,
+) {
+	for (const statement of fixtureStatements())
+		await connection.query(statement);
+	// Rank metadata belongs to the emulator and is queried as raw SQL by authorization.
+	await connection.query(
+		"CREATE TABLE permission_ranks (id INT PRIMARY KEY, rank_name VARCHAR(255) NOT NULL) ENGINE=InnoDB",
+	);
+	await connection.query(
+		"INSERT INTO permission_ranks (id, rank_name) VALUES (1, 'Member'), (7, 'Editor'), (9, 'Owner')",
+	);
+	for (const migration of [
+		"0026_article_editor_recovery.sql",
+		"0031_operations_outbox.sql",
+	]) {
+		const contents = await readFile(
+			new URL(`../../drizzle/migrations/${migration}`, import.meta.url),
+			"utf8",
+		);
+		for (const statement of splitSqlStatements(contents))
+			await connection.query(statement);
+	}
+	const password = await bcrypt({
+		password: staffPassword,
+		salt: randomBytes(16),
+		costFactor: 12,
+		outputType: "encoded",
+	});
+	const ownerPassword = await bcrypt({
+		password: randomBytes(32).toString("hex"),
+		salt: randomBytes(16),
+		costFactor: 12,
+		outputType: "encoded",
+	});
+	await connection.query(
+		"INSERT INTO users (id, username, password, rank, account_created, ip_register, ip_current, mail, mail_verified) VALUES (?, ?, ?, 7, ?, '127.0.0.1', '127.0.0.1', '[email protected]', '1'), (9, 'FixtureOwner', ?, 9, ?, '127.0.0.1', '127.0.0.1', '[email protected]', '1')",
+		[
+			STAFF_ID,
+			STAFF_USERNAME,
+			password,
+			Math.floor(Date.now() / 1000),
+			ownerPassword,
+			Math.floor(Date.now() / 1000),
+		],
+	);
+	await connection.query(
+		"INSERT INTO acl_roles (id, slug, title) VALUES (1, 'news_editor', 'News editor')",
+	);
+	await connection.query(
+		"INSERT INTO acl_model_roles (model_type, model_id, role_id) VALUES ('User', ?, 1)",
+		[STAFF_ID],
+	);
+	for (const [index, slug] of [
+		"admin.dashboard",
+		"admin.news.view",
+		"admin.news.edit",
+	].entries()) {
+		await connection.query(
+			"INSERT INTO acl_permissions (id, slug, title) VALUES (?, ?, ?)",
+			[index + 1, slug, slug],
+		);
+		await connection.query(
+			"INSERT INTO acl_model_permissions (model_type, model_id, permission_id) VALUES ('Role', 1, ?)",
+			[index + 1],
+		);
+	}
+	for (const [key, value] of Object.entries({
+		hotel_name: "News browser fixture",
+		captcha_provider: "none",
+		require_email_verification: "1",
+		force_staff_2fa: "0",
+		maintenance_enabled: "0",
+		abuse_guard_enabled: "0",
+		radio_enabled: "0",
+	}))
+		await connection.query(
+			"INSERT INTO website_settings (`key`, value) VALUES (?, ?)",
+			[key, value],
+		);
+	await connection.query(
+		"INSERT INTO website_languages (country_code, language) VALUES ('en', 'English')",
+	);
+}

e2e/smoke.spec.ts

@@ -1,13 +1,27 @@
 import { expect, test } from "@playwright/test";
 
-test("health endpoint is reachable", async ({ request }) => {
-	const res = await request.get("/api/health");
-	expect(res.ok()).toBeTruthy();
-	const body = await res.json();
-	expect(body).toHaveProperty("status");
+// Read-only production checks. Content mutation tests belong to a seeded staging DB.
+test("login remains usable on a narrow viewport", async ({ page }) => {
+	await page.setViewportSize({ width: 390, height: 720 });
+	const response = await page.goto("/login");
+	expect(response?.ok()).toBe(true);
+	await expect(page.locator('input[type="password"]').first()).toBeVisible();
+	await expect(page.locator('button[type="submit"]').first()).toBeVisible();
+	expect(
+		await page.evaluate(
+			() => document.documentElement.scrollWidth <= innerWidth + 1,
+		),
+	).toBe(true);
+	await expect(page.locator("body")).not.toContainText("Application error");
 });
-
-test("homepage renders", async ({ page }) => {
-	await page.goto("/");
-	await expect(page).toHaveTitle(/.+/);
+test("public news is rendered without a server error", async ({ page }) => {
+	const response = await page.goto("/news");
+	expect(response?.ok()).toBe(true);
+	await expect(page.locator("main").first()).toBeVisible();
+	await expect(page.locator("body")).not.toContainText("Application error");
+});
+test("staff page is available", async ({ page }) => {
+	const response = await page.goto("/staff");
+	expect(response?.ok()).toBe(true);
+	await expect(page.locator("main").first()).toBeVisible();
 });

e2e/ui/README.md

@@ -0,0 +1,10 @@
+# Isolated UI regression checks
+
+Run `pnpm test:ui` after `pnpm install --frozen-lockfile` and `pnpm exec playwright install chromium`.
+The fixture server bundles real CMS components with local HTTP/server-action fixtures. It does not use the database or production credentials. Production smoke tests remain in the separate `pnpm test:e2e` command.
+
+The suite covers accessible settings switches, news editor/preview, support-table filters, import history, attachment recovery and news/event recovery. Axe checks WCAG A/AA rules. The sandboxed preview cannot execute Axe; its accessible name and keyboard exit are checked separately. Automated checks do not replace a full accessibility audit.
+
+Visual references are committed under `__screenshots__/<platform>/<viewport>`. Normal runs compare references and must not update them. For an intentional UI change, use `pnpm test:ui:update`, inspect every changed PNG and commit only accepted references. Keep the Playwright browser version aligned with the lockfile. Linux references must be captured on the Linux runner; Windows references are not interchangeable.
+
+Fixtures contain synthetic data only. Do not add production requests, environment secrets, ignored local documents or database access to tests. CI retains test reports and failures as the `ui-results` artifact.

e2e/ui/attachment-recovery.spec.ts

@@ -0,0 +1,109 @@
+import { expect, test } from "@playwright/test";
+
+const attachmentId = "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb";
+const file = {
+	name: "fixture_chair.nitro",
+	mimeType: "application/octet-stream",
+	buffer: Buffer.from("isolated upload fixture"),
+};
+
+test.beforeEach(async ({ page }) => {
+	await page.goto("/admin/attachment-harness");
+	await page
+		.getByText("Attach original file and resume", { exact: true })
+		.click();
+});
+
+test("attachment upload and double-click resume send one retry and refresh history", async ({
+	page,
+}) => {
+	let retries = 0;
+	await page.route("**/api/admin/studio/import-attachment", async (route) => {
+		expect(route.request().method()).toBe("POST");
+		expect(route.request().postData()).toContain('name="classname"');
+		expect(route.request().postData()).toContain("fixture_chair");
+		expect(route.request().postData()).toContain(
+			'filename="fixture_chair.nitro"',
+		);
+		await route.fulfill({ json: { ok: true, attachmentId } });
+	});
+	await page.route("**/api/admin/studio/import-jobs", async (route) => {
+		retries++;
+		expect(route.request().method()).toBe("PATCH");
+		expect(route.request().postDataJSON()).toEqual({
+			id: "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
+			action: "retry",
+			attachments: { fixture_chair: attachmentId },
+		});
+		await new Promise((resolve) => setTimeout(resolve, 150));
+		await route.fulfill({ json: { ok: true } });
+	});
+	await page.getByLabel("Choose the original .nitro file").setInputFiles(file);
+	await expect(
+		page.getByText("Matching original file attached", { exact: true }),
+	).toBeVisible();
+	await page
+		.getByRole("button", {
+			name: "Resume failed imports with this file",
+			exact: true,
+		})
+		.dblclick();
+	await expect(page.getByLabel("Resumed count")).toHaveText("1");
+	expect(retries).toBe(1);
+	await expect(
+		page.getByRole("button", {
+			name: "Resume failed imports with this file",
+			exact: true,
+		}),
+	).toHaveCount(0);
+});
+
+for (const scenario of [
+	{
+		name: "owner rejection",
+		status: 403,
+		code: "forbidden",
+		message: "Could not attach the file.",
+	},
+	{
+		name: "mismatched furniture",
+		status: 400,
+		code: "mismatchedFile",
+		message: "This file belongs to different furniture.",
+	},
+	{
+		name: "network failure",
+		status: 0,
+		code: "",
+		message: "Network connection failed",
+	},
+])
+	test(`attachment ${scenario.name} shows readable error without enabling resume`, async ({
+		page,
+	}) => {
+		let retries = 0;
+		await page.route("**/api/admin/studio/import-jobs", async (route) => {
+			retries++;
+			await route.fulfill({ json: { ok: true } });
+		});
+		await page.route("**/api/admin/studio/import-attachment", (route) =>
+			scenario.status
+				? route.fulfill({
+						status: scenario.status,
+						json: { ok: false, code: scenario.code },
+					})
+				: route.abort("failed"),
+		);
+		await page
+			.getByLabel("Choose the original .nitro file")
+			.setInputFiles(file);
+		await expect(page.getByRole("alert")).toContainText(scenario.message);
+		await expect(
+			page.getByRole("button", {
+				name: "Resume failed imports with this file",
+				exact: true,
+			}),
+		).toHaveCount(0);
+		await expect(page.getByLabel("Resumed count")).toHaveText("0");
+		expect(retries).toBe(0);
+	});

e2e/ui/catalog-live-update.spec.ts

@@ -0,0 +1,143 @@
+import { expect, type Page, test } from "@playwright/test";
+
+/**
+ * The guarantee this file exists to guard: an import that finishes outside this
+ * page — the job worker, another tab, another browser — puts the new categories
+ * on screen without a reload. Every earlier test in this suite asserted only
+ * that no page errors were thrown, so a regression back to "refresh the page to
+ * see it" would have gone unnoticed.
+ */
+
+function node(id: number, caption: string, itemCount = 0) {
+	return {
+		id,
+		caption,
+		parentId: -1,
+		depth: 0,
+		orderNum: id,
+		enabled: "1",
+		visible: "1",
+		iconImage: 0,
+		iconColor: 0,
+		pageLayout: "default_3x3",
+		childCount: 0,
+		itemCount,
+	};
+}
+
+/** The catalog as the server would report it; specs move it forward mid-test. */
+const catalog = {
+	revision: "rev-1",
+	pages: [node(1, "Root")],
+	treeStatus: 200,
+};
+
+async function mockStudio(page: Page) {
+	await page.route("**/api/**", async (route) => {
+		const url = new URL(route.request().url());
+		if (url.pathname === "/api/admin/catalog/revision")
+			return route.fulfill({ json: { ok: true, revision: catalog.revision } });
+		if (
+			url.pathname === "/api/admin/catalog/tree" &&
+			url.searchParams.get("mode") === "full"
+		)
+			return route.fulfill({
+				status: catalog.treeStatus,
+				json: {
+					ok: catalog.treeStatus === 200,
+					pages: catalog.pages,
+					totals: null,
+					revision: catalog.revision,
+				},
+			});
+		if (url.pathname.endsWith("/inspect"))
+			return route.fulfill({ json: { items: [] } });
+		if (url.pathname.endsWith("/source-assets"))
+			return route.fulfill({ json: { items: [] } });
+		if (url.pathname.endsWith("/furni"))
+			return route.fulfill({
+				json: url.searchParams.has("action")
+					? { totalInDb: 0, inCatalog: 0, notInCatalog: 0, missingNitro: 0 }
+					: {
+							items: [],
+							meta: {
+								currentPage: 1,
+								lastPage: 1,
+								total: 0,
+								perPage: 100,
+							},
+						},
+			});
+		if (url.pathname.endsWith("/clone"))
+			return route.fulfill({ json: { sources: [] } });
+		if (url.pathname.endsWith("/import-jobs"))
+			return route.fulfill({ json: { ok: true, jobs: [], nextCursor: null } });
+		return route.fulfill({
+			status: 404,
+			json: { error: "Unknown fixture endpoint" },
+		});
+	});
+}
+
+test.beforeEach(() => {
+	catalog.revision = "rev-1";
+	catalog.pages = [node(1, "Root")];
+	catalog.treeStatus = 200;
+});
+
+test("a write announced by another tab lands in the mounted categories", async ({
+	page,
+}, testInfo) => {
+	test.skip(
+		(testInfo.project.use.viewport?.width ?? 0) < 1024,
+		"the category rail is collapsed on narrow viewports",
+	);
+	await mockStudio(page);
+	const navigations: string[] = [];
+	page.on("framenavigated", (frame) => {
+		if (frame === page.mainFrame()) navigations.push(frame.url());
+	});
+
+	await page.goto("/admin/studio-harness");
+	await expect(page.getByRole("button", { name: /^Root/ })).toBeVisible();
+	const navigationsAfterLoad = navigations.length;
+
+	// An import finished elsewhere: the catalog moved on, so the tree route now
+	// answers with the imported category.
+	catalog.revision = "rev-2";
+	catalog.pages = [...catalog.pages, node(2, "Imported Furniture", 3)];
+	await page.evaluate((revision) => {
+		const channel = new BroadcastChannel("atom-cms-catalog");
+		channel.postMessage({ revision });
+		channel.close();
+	}, catalog.revision);
+
+	await expect(
+		page.getByRole("button", { name: /Imported Furniture/ }),
+	).toBeVisible();
+	// The page was never navigated or reloaded: the tree updated in place.
+	expect(navigations).toHaveLength(navigationsAfterLoad);
+});
+
+test("a failed refresh keeps the categories and says it is stale", async ({
+	page,
+}, testInfo) => {
+	test.skip(
+		(testInfo.project.use.viewport?.width ?? 0) < 1024,
+		"the category rail is collapsed on narrow viewports",
+	);
+	await mockStudio(page);
+	await page.goto("/admin/studio-harness");
+	await expect(page.getByRole("button", { name: /^Root/ })).toBeVisible();
+
+	catalog.treeStatus = 500;
+	catalog.revision = "rev-2";
+	await page.evaluate((revision) => {
+		const channel = new BroadcastChannel("atom-cms-catalog");
+		channel.postMessage({ revision });
+		channel.close();
+	}, catalog.revision);
+
+	await expect(page.getByRole("button", { name: "Retry" })).toBeVisible();
+	await expect(page.getByRole("button", { name: /^Root/ })).toBeVisible();
+});

e2e/ui/deliveries.spec.ts

@@ -0,0 +1,129 @@
+import { expect, test } from "@playwright/test";
+
+test("deliveries explain outcomes without exposing unauthorized content or raw metadata", async ({
+	page,
+}, testInfo) => {
+	const errors: string[] = [];
+	page.on("pageerror", (error) => errors.push(error.message));
+	await page.goto("/admin/deliveries-harness");
+	const review = page.getByRole("region", { name: "Delivery review" });
+	const cards = review.getByRole("article");
+	await expect(cards).toHaveCount(6);
+	const news = cards.nth(0);
+	await expect(news.getByRole("heading", { level: 2 })).toContainText(
+		"Community update: SummerFestival",
+	);
+	await expect(news.getByText("Waiting", { exact: true })).toBeVisible();
+	await expect(
+		news.getByText(
+			"The content is saved. This update runs in the background.",
+			{ exact: true },
+		),
+	).toBeVisible();
+	await expect(news.getByRole("status")).toContainText(
+		"The news cache could not be refreshed.",
+	);
+	await expect(news.getByRole("status")).toContainText(
+		"Next automatic attempt: Jan 1, 2030, 12:05 PM",
+	);
+	await expect(
+		news.getByRole("link", { name: "Open content", exact: true }),
+	).toHaveAttribute("href", "/admin/articles/9007199254740993");
+	await expect(
+		news.getByRole("link", { name: "Service diagnostics", exact: true }),
+	).toHaveAttribute(
+		"href",
+		"/admin/devops/cms-errors?q=4f3df172-f1ca-4c26-a23e-cb4e6c13e9f2",
+	);
+	const failed = cards.nth(1);
+	await expect(
+		failed.getByRole("heading", { name: "9 catalog offers", exact: true }),
+	).toBeVisible();
+	await expect(
+		failed.getByText("Needs attention", { exact: true }),
+	).toBeVisible();
+	await expect(failed.getByRole("status")).toContainText(
+		"Check the emulator connection.",
+	);
+	await expect(failed.getByRole("status")).toContainText(
+		"Automatic attempts are exhausted.",
+	);
+	await expect(
+		failed.getByRole("link", { name: "Open content", exact: true }),
+	).toHaveAttribute("href", "/admin/catalog");
+	await expect(
+		failed.getByRole("button", { name: "Retry delivery", exact: true }),
+	).toBeVisible();
+	for (const card of [cards.nth(2), cards.nth(3)]) {
+		await expect(
+			card.getByRole("heading", {
+				name: "Content details unavailable",
+				exact: true,
+			}),
+		).toBeVisible();
+		await expect(
+			card.getByRole("link", { name: "Open content", exact: true }),
+		).toHaveCount(0);
+		await expect(
+			card.getByRole("button", { name: "Retry delivery", exact: true }),
+		).toHaveCount(0);
+	}
+	const unknown = cards.nth(4);
+	await expect(
+		unknown.getByText("Other background update", { exact: true }),
+	).toBeVisible();
+	await expect(
+		unknown.getByText("Unknown status", { exact: true }),
+	).toBeVisible();
+	await expect(unknown).toContainText("Time unavailable");
+	await expect(unknown).toContainText("System");
+	await expect(cards.nth(5)).toContainText(
+		"Check the Git export history for the final result; disabled export does not publish files.",
+	);
+	await expect(review).not.toContainText(
+		/RESTRICTED_NEWS_TITLE|SERIALIZED_METADATA_SECRET|INTERNAL_FILE_PATH_SECRET|UNKNOWN_OPERATION_SECRET|489 catalog offers|resultJson|articleId/,
+	);
+	await expect(review.locator("details[open]")).toHaveCount(0);
+	await expect(
+		news.getByText("Operation: operation-authorized-news-1234567890", {
+			exact: true,
+		}),
+	).toBeHidden();
+	await expect(
+		news.getByText("Delivery: delivery-authorized-news-1234567890", {
+			exact: true,
+		}),
+	).toBeHidden();
+	await news.locator("summary").click();
+	await expect(
+		news.getByText("Operation: operation-authorized-news-1234567890", {
+			exact: true,
+		}),
+	).toBeVisible();
+	await expect(
+		news.getByText("Delivery: delivery-authorized-news-1234567890", {
+			exact: true,
+		}),
+	).toBeVisible();
+	await news.locator("summary").click();
+	await expect(
+		news.getByText("Operation: operation-authorized-news-1234567890", {
+			exact: true,
+		}),
+	).toBeHidden();
+	expect(
+		await page.evaluate(
+			() => document.documentElement.scrollWidth <= window.innerWidth,
+		),
+	).toBe(true);
+	const title = news.getByRole("heading", { level: 2 });
+	expect(
+		await title.evaluate((node) => node.scrollWidth <= node.clientWidth),
+	).toBe(true);
+	await page.evaluate(() => window.scrollTo(0, 0));
+	await testInfo.attach("delivery-cards", {
+		body: await page.screenshot({ fullPage: true }),
+		contentType: "image/png",
+	});
+	expect(errors).toEqual([]);
+});

e2e/ui/draft-recovery.spec.ts

@@ -0,0 +1,169 @@
+import { expect, test } from "@playwright/test";
+
+const key = "cms:draft:v1:7:article:new";
+test("browser draft survives session failure and reload, restores explicitly and clears only after save", async ({
+	page,
+}) => {
+	await page.route("**/fixture/actions/load-recovery", (route) =>
+		route.fulfill({ status: 401, body: "expired" }),
+	);
+	await page.route("**/fixture/actions/article", (route) =>
+		route.fulfill({
+			contentType: "application/json",
+			body: JSON.stringify({ ok: false, error: "Session expired" }),
+		}),
+	);
+	await page.goto("/admin/articles/recovery");
+	const title = page.locator('input[name="title"]');
+	await title.fill("Keep this unfinished article");
+	await expect
+		.poll(() => page.evaluate((k) => localStorage.getItem(k), key))
+		.toContain("Keep this unfinished article");
+	await page.getByRole("button", { name: "Save article", exact: true }).click();
+	await expect(page.getByRole("alert")).toContainText("Session expired");
+	expect(await page.evaluate((k) => localStorage.getItem(k), key)).toContain(
+		"Keep this unfinished article",
+	);
+	page.on("dialog", (dialog) => dialog.accept());
+	await page.reload();
+	await expect(title).toHaveValue("Community update");
+	await page
+		.getByRole("button", { name: "Restore browser copy", exact: true })
+		.click();
+	await expect(title).toHaveValue("Keep this unfinished article");
+	await page.unroute("**/fixture/actions/article");
+	await page.route("**/fixture/actions/article", (route) =>
+		route.fulfill({
+			contentType: "application/json",
+			body: JSON.stringify({ ok: true }),
+		}),
+	);
+	await page.getByRole("button", { name: "Save article", exact: true }).click();
+	await expect
+		.poll(() => page.evaluate((k) => localStorage.getItem(k), key))
+		.toBeNull();
+	await page.reload();
+	await expect(
+		page.getByRole("button", { name: "Restore browser copy", exact: true }),
+	).toHaveCount(0);
+});
+test("pending recovery does not overwrite current edits and discard preserves them", async ({
+	page,
+}) => {
+	await page.goto("/admin/articles/recovery");
+	const title = page.locator('input[name="title"]');
+	await title.fill("Older draft");
+	await expect
+		.poll(() => page.evaluate((k) => localStorage.getItem(k), key))
+		.toContain("Older draft");
+	page.on("dialog", (dialog) => dialog.accept());
+	await page.reload();
+	await title.fill("New current edits");
+	await page
+		.getByRole("button", { name: "Discard browser copy", exact: true })
+		.click();
+	await expect(title).toHaveValue("New current edits");
+	await expect
+		.poll(() => page.evaluate((k) => localStorage.getItem(k), key))
+		.toContain("New current edits");
+});
+test("unavailable browser storage leaves the form editable", async ({
+	page,
+}) => {
+	await page.addInitScript(() => {
+		Storage.prototype.setItem = () => {
+			throw Error("quota");
+		};
+	});
+	await page.goto("/admin/articles/recovery");
+	await page.locator('input[name="title"]').fill("Still editable");
+	await expect(
+		page.getByText("Browser recovery is unavailable.", { exact: false }),
+	).toBeVisible();
+	await expect(page.locator('input[name="title"]')).toHaveValue(
+		"Still editable",
+	);
+});
+test("saving while recovery is pending enables recovery for subsequent edits", async ({
+	page,
+}) => {
+	await page.route("**/fixture/actions/article", (route) =>
+		route.fulfill({
+			contentType: "application/json",
+			body: JSON.stringify({ ok: true }),
+		}),
+	);
+	await page.goto("/admin/articles/recovery");
+	const title = page.locator('input[name="title"]');
+	await title.fill("Previous browser draft");
+	await expect
+		.poll(() => page.evaluate((k) => localStorage.getItem(k), key))
+		.toContain("Previous browser draft");
+	page.on("dialog", (dialog) => dialog.accept());
+	await page.reload();
+	await expect(
+		page.getByRole("button", { name: "Restore browser copy", exact: true }),
+	).toBeVisible();
+	await page.getByRole("button", { name: "Save article", exact: true }).click();
+	await expect
+		.poll(() => page.evaluate((k) => localStorage.getItem(k), key))
+		.toBeNull();
+	await title.fill("Edits after successful save");
+	await expect
+		.poll(() => page.evaluate((k) => localStorage.getItem(k), key))
+		.toContain("Edits after successful save");
+});
+test("unmount flush retains an edit before the autosave interval", async ({
+	page,
+}) => {
+	await page.goto("/admin/articles/recovery");
+	await page.clock.install();
+	await page.clock.pauseAt(new Date());
+	await page.locator('input[name="title"]').fill("Immediate final edit");
+	await page
+		.getByRole("button", { name: "Close editor fixture", exact: true })
+		.click();
+	expect(await page.evaluate((k) => localStorage.getItem(k), key)).toContain(
+		"Immediate final edit",
+	);
+});
+test("event title and dates recover after reload and clear after successful update", async ({
+	page,
+}) => {
+	const eventKey = "cms:draft:v1:7:event:12";
+	await page.route("**/fixture/actions/update-event", (route) =>
+		route.fulfill({
+			contentType: "application/json",
+			body: JSON.stringify({ ok: true, data: { id: 12 } }),
+		}),
+	);
+	await page.goto("/admin/events/recovery");
+	const title = page.locator("#title");
+	const dates = page.locator('input[type="datetime-local"]');
+	await title.fill("Recovered community event");
+	await dates.nth(0).fill("2030-02-03T14:30");
+	await dates.nth(1).fill("2030-02-03T16:00");
+	await expect
+		.poll(() => page.evaluate((k) => localStorage.getItem(k), eventKey))
+		.toContain("2030-02-03T14:30:00.000Z");
+	page.on("dialog", (dialog) => dialog.accept());
+	await page.reload();
+	await expect(title).toHaveValue("Original event");
+	await page
+		.getByRole("button", { name: "Restore browser copy", exact: true })
+		.click();
+	await expect(title).toHaveValue("Recovered community event");
+	await expect(dates.nth(0)).toHaveValue("2030-02-03T14:30");
+	await expect(dates.nth(1)).toHaveValue("2030-02-03T16:00");
+	const save = page.waitForRequest("**/fixture/actions/update-event");
+	await page.locator('button[type="submit"]').click();
+	expect((await save).postDataJSON()).toMatchObject({
+		id: 12,
+		title: "Recovered community event",
+		startsAt: "2030-02-03T14:30:00.000Z",
+		endsAt: "2030-02-03T16:00:00.000Z",
+	});
+	await expect
+		.poll(() => page.evaluate((k) => localStorage.getItem(k), eventKey))
+		.toBeNull();
+});

e2e/ui/fixture-server.mjs

@@ -0,0 +1,230 @@
+import { readFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import tailwind from "@tailwindcss/postcss";
+import { build } from "esbuild";
+import postcss from "postcss";
+
+const root = path.resolve(
+	path.dirname(fileURLToPath(import.meta.url)),
+	"../..",
+);
+const fixtures = path.join(root, "e2e/ui/fixtures");
+const port = Number(process.env.UI_TEST_PORT || 3107);
+if (!Number.isInteger(port) || port < 1024 || port > 65535)
+	throw Error("Invalid UI_TEST_PORT");
+const actions = new Set([
+	"@/actions/catalog",
+	"@/actions/import-furni",
+	"@/actions/events",
+	"@/actions/admin-settings",
+	"@/actions/admin-table-views",
+	"@/actions/article-recovery",
+	"@/actions/admin-media",
+]);
+const bundle = await build({
+	entryPoints: [path.join(fixtures, "entry.tsx")],
+	bundle: true,
+	write: false,
+	outdir: path.join(root, "test-results/ui-fixture"),
+	format: "iife",
+	jsx: "automatic",
+	alias: { "@": path.join(root, "src") },
+	define: { "process.env.NODE_ENV": '"production"' },
+	plugins: [
+		{
+			name: "server-contracts",
+			setup(build) {
+				build.onResolve(
+					{ filter: /^next\/navigation$|^next\/link$|^@\/actions\// },
+					(args) => {
+						if (args.path === "next/navigation")
+							return { path: path.join(fixtures, "navigation.ts") };
+						if (args.path === "next/link")
+							return { path: path.join(fixtures, "next-link.tsx") };
+						if (actions.has(args.path))
+							return { path: path.join(fixtures, "server-actions.ts") };
+						throw Error(`Unexpected server action in UI fixture: ${args.path}`);
+					},
+				);
+				build.onResolve(
+					{ filter: /^@\/lib\/db$|^mysql2|^next\/headers$/ },
+					(args) => {
+						throw Error(
+							`Database or server dependency forbidden in UI fixture: ${args.path}`,
+						);
+					},
+				);
+			},
+		},
+	],
+});
+const globalCss = (
+	await postcss([tailwind({ base: root })]).process(
+		await readFile(path.join(root, "src/app/globals.css"), "utf8"),
+		{ from: path.join(root, "src/app/globals.css") },
+	)
+).css;
+const css =
+	globalCss +
+	"\n" +
+	bundle.outputFiles
+		.filter((file) => file.path.endsWith(".css"))
+		.map((file) => file.text)
+		.join("\n");
+const js = bundle.outputFiles.find((file) => file.path.endsWith(".js")).text;
+const html =
+	'<!doctype html><html lang="en" class="dark"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="csrf-token" content="' +
+	"a".repeat(64) +
+	'"><title>UI verification fixture</title><link rel="stylesheet" href="/fixture/styles.css"></head><body><div id="root"></div><script src="/fixture/app.js"></script></body></html>';
+const cover =
+	'<svg xmlns="http://www.w3.org/2000/svg" width="720" height="160" viewBox="0 0 720 160"><rect width="720" height="160" fill="#334155"/><circle cx="620" cy="80" r="48" fill="#f59e0b"/></svg>';
+const jobs = new Map();
+const views = [];
+const json = (res, value, status = 200) => {
+	res.writeHead(status, {
+		"content-type": "application/json",
+		"cache-control": "no-store",
+	});
+	res.end(JSON.stringify(value));
+};
+const server = createServer(async (req, res) => {
+	try {
+		const url = new URL(req.url, "http://127.0.0.1");
+		if (url.pathname === "/fixture/reset") {
+			jobs.clear();
+			views.length = 0;
+			return json(res, { ok: true });
+		}
+		if (url.pathname === "/health") return json(res, { ready: true });
+		if (url.pathname === "/fixture/styles.css") {
+			res.setHeader("content-type", "text/css");
+			return res.end(css);
+		}
+		if (url.pathname === "/fixture/app.js") {
+			res.setHeader("content-type", "application/javascript");
+			return res.end(js);
+		}
+		if (url.pathname === "/fixture/cover.svg") {
+			res.setHeader("content-type", "image/svg+xml");
+			return res.end(cover);
+		}
+		if (url.pathname.startsWith("/vendor/tinymce/")) {
+			const assetRoot = path.join(root, "node_modules/tinymce");
+			const asset = path.resolve(
+				assetRoot,
+				url.pathname.slice("/vendor/tinymce/".length),
+			);
+			if (!asset.startsWith(assetRoot + path.sep)) {
+				res.writeHead(400);
+				return res.end();
+			}
+			res.setHeader(
+				"content-type",
+				asset.endsWith(".css")
+					? "text/css"
+					: asset.endsWith(".js")
+						? "application/javascript"
+						: asset.endsWith(".woff")
+							? "font/woff"
+							: "application/octet-stream",
+			);
+			return res.end(await readFile(asset));
+		}
+		let body = {};
+		if (req.method === "POST" || req.method === "PATCH") {
+			const chunks = [];
+			let size = 0;
+			for await (const chunk of req) {
+				size += chunk.length;
+				if (size > 1000000) throw Error("Fixture payload too large");
+				chunks.push(chunk);
+			}
+			body = JSON.parse(Buffer.concat(chunks).toString() || "{}");
+		}
+		if (url.pathname === "/api/admin/studio/import-jobs") {
+			if (req.method === "PATCH") {
+				const job = jobs.get(body.id);
+				if (job) job.state = "cancelled";
+				return json(res, { ok: true, job });
+			}
+			return json(res, {
+				ok: true,
+				jobs: [...jobs.values()],
+				nextCursor: null,
+			});
+		}
+		if (url.pathname === "/api/admin/import/official/sync-all") {
+			if (!jobs.has(body.id))
+				jobs.set(body.id, {
+					id: body.id,
+					userId: 7,
+					createdAt: "2030-01-01T12:00:00.000Z",
+					updatedAt: "2030-01-01T12:00:00.000Z",
+					state: "queued",
+					translate: false,
+					syncKind: "official",
+					items: [
+						{
+							id: 0,
+							classname: "fixture_chair",
+							name: "Fixture chair",
+							description: "",
+							type: "flooritem",
+							category: "other",
+							revision: 1,
+							state: "pending",
+						},
+					],
+				});
+			await new Promise((resolve) => setTimeout(resolve, 150));
+			return json(res, { ok: true, job: jobs.get(body.id) });
+		}
+		if (url.pathname === "/api/media") return json(res, { files: [] });
+		if (url.pathname.startsWith("/fixture/actions/")) {
+			const name = url.pathname.split("/").at(-1);
+			if (name === "load-recovery")
+				return json(res, { version: 0, draft: null, revisions: [] });
+			if (name === "autosave" || name === "clear-recovery")
+				return json(res, { ok: true, version: 1 });
+			if (name === "list-views")
+				return json(res, { ok: true, data: { views } });
+			if (name === "save-view") {
+				views.push(body.view ?? body);
+				return json(res, { ok: true });
+			}
+			return json(res, { ok: true, data: {} });
+		}
+		if (
+			[
+				"/notifications",
+				"/admin/unsaved-harness",
+				"/admin/deliveries-harness",
+				"/admin/attachment-harness",
+				"/admin/studio-harness",
+				"/admin/jobs-harness",
+				"/admin/settings",
+				"/admin/articles/new",
+				"/admin/articles/recovery",
+				"/admin/events/recovery",
+				"/admin/tickets/desk",
+				"/admin/import/official",
+			].includes(url.pathname)
+		) {
+			res.setHeader("content-type", "text/html");
+			return res.end(html);
+		}
+		res.writeHead(404);
+		res.end("Not found");
+	} catch (error) {
+		console.error(error);
+		res.writeHead(500);
+		res.end("Fixture error");
+	}
+});
+server.listen(port, "127.0.0.1", () =>
+	console.log(`Isolated UI fixture ready at http://127.0.0.1:${port}`),
+);
+for (const signal of ["SIGINT", "SIGTERM"])
+	process.on(signal, () => server.close(() => process.exit(0)));

e2e/ui/fixtures/attachment-harness.tsx

@@ -0,0 +1,18 @@
+import { useState } from "react";
+import { ImportAttachmentRecovery } from "@/components/admin/studio/import-attachment-recovery";
+export function AttachmentHarness() {
+	const [resumed, setResumed] = useState(0);
+	return (
+		<>
+			<ImportAttachmentRecovery
+				jobId="aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa"
+				classname="fixture_chair"
+				disabled={false}
+				onResumed={async () => {
+					setResumed((value) => value + 1);
+				}}
+			/>
+			<output aria-label="Resumed count">{resumed}</output>
+		</>
+	);
+}

e2e/ui/fixtures/deliveries-harness.tsx

@@ -0,0 +1,120 @@
+import { useTranslations } from "next-intl";
+import { Button } from "@/components/ui/button";
+import {
+	DeliveryCard,
+	type DeliveryCardItem,
+} from "@/features/operations/delivery-card";
+import { deliveryContext } from "@/features/operations/delivery-context";
+
+const shared: Omit<DeliveryCardItem, "id" | "operationId" | "context"> = {
+	topic: "news.refresh",
+	status: "pending",
+	attempts: 2,
+	actorId: 7,
+	createdAt: "2030-01-01T11:00:00Z",
+	availableAt: "2030-01-01T12:05:00Z",
+	hasError: true,
+};
+const records: DeliveryCardItem[] = [
+	{
+		...shared,
+		id: "delivery-authorized-news-1234567890",
+		errorId: "4f3df172-f1ca-4c26-a23e-cb4e6c13e9f2",
+		operationId: "operation-authorized-news-1234567890",
+		context: deliveryContext(
+			"news.update",
+			JSON.stringify({
+				articleId: "9007199254740993",
+				articleTitle: `Community update: ${"SummerFestival".repeat(14)}`,
+				internalNotes: "SERIALIZED_METADATA_SECRET",
+				lastError: "INTERNAL_FILE_PATH_SECRET",
+			}),
+			{ news: true, catalog: false },
+		),
+	},
+	{
+		...shared,
+		id: "delivery-failed-catalog-1234567890",
+		operationId: "operation-failed-catalog-1234567890",
+		topic: "catalog.refresh",
+		status: "failed",
+		attempts: 5,
+		context: deliveryContext("catalog.bulk.apply", '{"changedCount":9}', {
+			news: false,
+			catalog: true,
+		}),
+	},
+	{
+		...shared,
+		id: "delivery-restricted-news",
+		operationId: "operation-restricted-news",
+		hasError: false,
+		context: deliveryContext(
+			"news.update",
+			'{"articleTitle":"RESTRICTED_NEWS_TITLE","articleId":"99"}',
+			{ news: false, catalog: true },
+		),
+	},
+	{
+		...shared,
+		id: "delivery-restricted-catalog",
+		operationId: "operation-restricted-catalog",
+		topic: "catalog.refresh",
+		hasError: false,
+		context: deliveryContext("catalog.bulk.apply", '{"changedCount":489}', {
+			news: true,
+			catalog: false,
+		}),
+	},
+	{
+		...shared,
+		id: "delivery-unknown",
+		operationId: "operation-unknown",
+		topic: "future.topic",
+		status: "future.status",
+		actorId: 0,
+		createdAt: "invalid",
+		context: deliveryContext(
+			"future.operation",
+			'{"articleTitle":"UNKNOWN_OPERATION_SECRET"}',
+			{ news: true, catalog: true },
+		),
+	},
+	{
+		...shared,
+		id: "delivery-completed-export",
+		operationId: "operation-completed-export",
+		topic: "catalog.export.request",
+		status: "done",
+		hasError: false,
+		context: deliveryContext("catalog.bulk.apply", '{"changedCount":4}', {
+			news: false,
+			catalog: true,
+		}),
+	},
+];
+
+export function DeliveriesHarness() {
+	const t = useTranslations("pages.admin.deliveries");
+	return (
+		<section aria-label="Delivery review" className="min-w-0 space-y-4">
+			<p>{t("scope")}</p>
+			<ul className="space-y-3">
+				{records.map((item) => (
+					<li key={item.id}>
+						<DeliveryCard
+							item={item}
+							retry={
+								item.status === "failed" ? (
+									<Button type="button" variant="outline">
+										{t("retry")}
+									</Button>
+								) : undefined
+							}
+						/>
+					</li>
+				))}
+			</ul>
+		</section>
+	);
+}

e2e/ui/fixtures/entry.tsx

@@ -0,0 +1,180 @@
+import { NextIntlClientProvider } from "next-intl";
+import { useState } from "react";
+import { createRoot } from "react-dom/client";
+import { Toaster } from "sonner";
+import { EventForm } from "@/app/admin/events/event-form";
+import { CmsSettingsForm } from "@/app/admin/settings/cms-settings-form";
+import { TicketsTable } from "@/app/admin/tickets/tickets-table";
+import { ArticleForm } from "@/components/admin/article-form";
+import { FurnitureSyncQueue } from "@/components/admin/studio/furniture-sync-queue";
+import { OrganizeImportsLauncher } from "@/components/admin/studio/organize-imports-launcher";
+import { StudioClient } from "@/components/admin/studio/studio-client";
+import { NotificationCenter } from "@/features/notifications/notification-center";
+import type { ArticleSaveResult } from "@/lib/article-input";
+import { buildFurniImportSource } from "@/lib/habbo-gamedata-hotel";
+import { themePaletteCss } from "@/lib/theme-css";
+import { PRESETS } from "@/lib/theme-presets";
+import messages from "@/messages/en.json";
+import { AttachmentHarness } from "./attachment-harness";
+import { DeliveriesHarness } from "./deliveries-harness";
+import { FurnitureJobsHarness } from "./furniture-jobs-harness";
+import { fixtureAction } from "./server-actions";
+import { UnsavedHarness } from "./unsaved-harness";
+
+const theme = document.createElement("style");
+theme.textContent = themePaletteCss(
+	":root.dark",
+	PRESETS["Atom (golden)"].dark,
+);
+document.head.appendChild(theme);
+const route = window.location.pathname;
+if (route.includes("notifications")) {
+	document.documentElement.classList.add("app");
+	document.body.classList.add("site-bg");
+	document.body.style.backgroundColor = "var(--color-background)";
+}
+const root = document.getElementById("root");
+if (!root) throw Error("Fixture root missing");
+const rows = [
+	{
+		id: 1,
+		subject: "Account assistance",
+		creator: "SampleMember",
+		creatorId: 7,
+		category: "general",
+		messages: 2,
+		status: "open",
+		priority: "normal",
+		assignee: "Moderator",
+		date: "01/01/2030",
+		awaitingStaff: true,
+		replyAgeMinutes: 90,
+	},
+	{
+		id: 2,
+		subject: "Event question",
+		creator: "AnotherMember",
+		creatorId: 8,
+		category: "events",
+		messages: 1,
+		status: "waiting",
+		priority: "high",
+		assignee: "—",
+		date: "01/01/2030",
+		awaitingStaff: false,
+		replyAgeMinutes: 15,
+	},
+];
+const saveArticle = async (form: FormData): Promise<ArticleSaveResult> =>
+	fixtureAction("article", Object.fromEntries(form));
+
+function ArticleFixture() {
+	const [visible, setVisible] = useState(true);
+	return (
+		<>
+			{route.includes("recovery") && (
+				<button type="button" onClick={() => setVisible(false)}>
+					Close editor fixture
+				</button>
+			)}
+			{visible && (
+				<ArticleForm
+					userId={route.includes("recovery") ? "7" : undefined}
+					action={saveArticle}
+					articleKey="new"
+					defaultValues={{
+						title: "Community update",
+						slug: "community-update",
+						image: "/fixture/cover.svg",
+						shortStory: "A short update for the community.",
+						fullStory:
+							"<p>Join the upcoming event and explore the hotel together.</p>",
+						status: "draft",
+					}}
+				/>
+			)}
+		</>
+	);
+}
+
+createRoot(root).render(
+	<NextIntlClientProvider
+		locale="en"
+		timeZone="UTC"
+		now={new Date("2030-01-01T12:00:00Z")}
+		messages={messages}
+	>
+		<main
+			data-admin={route.includes("notifications") ? undefined : ""}
+			className={
+				route.includes("notifications")
+					? "min-w-0 mx-auto max-w-7xl px-3 py-3 md:px-6 md:py-6"
+					: "min-w-0 mx-auto max-w-6xl p-5"
+			}
+		>
+			<h1
+				hidden={route.includes("notifications")}
+				className="mb-5 text-2xl font-bold"
+			>
+				{route.includes("settings")
+					? "CMS settings"
+					: route.includes("tickets")
+						? "Support desk"
+						: route.includes("articles")
+							? "News editor"
+							: route.includes("deliveries-harness")
+								? "Background updates"
+								: "Furniture synchronization"}
+			</h1>
+			{route.includes("notifications") ? (
+				<NotificationCenter userId={7} />
+			) : route.includes("deliveries-harness") ? (
+				<DeliveriesHarness />
+			) : route.includes("unsaved-harness") ? (
+				<UnsavedHarness />
+			) : route.includes("studio-harness") ? (
+				<>
+					<OrganizeImportsLauncher />
+					<StudioClient
+						source={buildFurniImportSource("it")}
+						defaultTranslate={false}
+					/>
+				</>
+			) : route.includes("attachment-harness") ? (
+				<AttachmentHarness />
+			) : route.includes("events/recovery") ? (
+				<EventForm
+					userId="7"
+					eventTypes={[
+						{ id: 1, name: "Community", slug: "community", color: "#123456" },
+					]}
+					defaultValues={{
+						id: 12,
+						title: "Original event",
+						description: "Event details",
+						typeId: 1,
+						status: "draft",
+						isRecurring: 0,
+						startsAt: new Date("2030-01-01T12:00:00Z"),
+					}}
+				/>
+			) : route.includes("jobs-harness") ? (
+				<FurnitureJobsHarness />
+			) : route.includes("settings") ? (
+				<CmsSettingsForm
+					canEdit
+					values={{ default_dark: "0", cms_hotel_name: "Example Hotel" }}
+				/>
+			) : route.includes("tickets") ? (
+				<TicketsTable
+					data={{ rows, total: 2, page: 1, perPage: 20, lastPage: 1 }}
+				/>
+			) : route.includes("articles") ? (
+				<ArticleFixture />
+			) : (
+				<FurnitureSyncQueue kind="official" />
+			)}
+		</main>
+		<Toaster />
+	</NextIntlClientProvider>,
+);

e2e/ui/fixtures/furniture-jobs-harness.tsx

@@ -0,0 +1,66 @@
+import { useState } from "react";
+import { FurnitureJobHistory } from "@/components/admin/studio/furniture-jobs";
+import { useFurnitureJobs } from "@/components/admin/studio/use-furniture-jobs";
+import { furnitureJobFixture } from "../../../src/test/furniture-jobs-fixtures";
+
+export function FurnitureJobsHarness() {
+	const [completions, setCompletions] = useState(0);
+	const [submitted, setSubmitted] = useState<string>("");
+	const history = useFurnitureJobs(
+		() => setCompletions((value) => value + 1),
+		true,
+		7,
+	);
+	return (
+		<section aria-label="Import history hook">
+			<button
+				type="button"
+				disabled={history.busy}
+				onClick={async () =>
+					setSubmitted(
+						String(
+							await history.submit(furnitureJobFixture.items, {
+								translate: false,
+							}),
+						),
+					)
+				}
+			>
+				Submit import
+			</button>
+			<output aria-label="Submitted">{submitted}</output>
+			<button
+				type="button"
+				onClick={() => {
+					void history.refresh();
+					void history.refresh();
+				}}
+			>
+				Refresh twice
+			</button>
+			<button
+				type="button"
+				disabled={history.loading || !history.nextCursor}
+				onClick={() => void history.navigate("next")}
+			>
+				Next page
+			</button>
+			<button
+				type="button"
+				disabled={history.loading || history.page === 1}
+				onClick={() => void history.navigate("previous")}
+			>
+				Previous page
+			</button>
+			{window.location.search.includes("progress") && (
+				<FurnitureJobHistory state={history} expanded />
+			)}
+			<output aria-label="Page">{history.page}</output>
+			<output aria-label="Completions">{completions}</output>
+			<output aria-label="Loading">{String(history.loading)}</output>
+			<output aria-label="Jobs">
+				{history.jobs.map((job) => `${job.id}:${job.state}`).join(",")}
+			</output>
+		</section>
+	);
+}

e2e/ui/fixtures/navigation.ts

@@ -0,0 +1,13 @@
+const router = {
+	push: (url: string) => {
+		window.location.href = url;
+	},
+	replace: (url: string) => {
+		window.location.replace(url);
+	},
+	refresh: () => {},
+};
+export const useRouter = () => router;
+export const usePathname = () => window.location.pathname;
+export const useSearchParams = () =>
+	new URLSearchParams(window.location.search);

e2e/ui/fixtures/next-link.tsx

@@ -0,0 +1,7 @@
+import type { AnchorHTMLAttributes } from "react";
+export default function FixtureLink({
+	prefetch: _prefetch,
+	...props
+}: AnchorHTMLAttributes<HTMLAnchorElement> & { prefetch?: boolean }) {
+	return <a {...props} />;
+}

e2e/ui/fixtures/server-actions.ts

@@ -0,0 +1,37 @@
+export async function fixtureAction(name: string, input: unknown = {}) {
+	const response = await fetch(`/fixture/actions/${name}`, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify(input),
+	});
+	if (!response.ok) throw Error(`Fixture action failed: ${response.status}`);
+	return response.json();
+}
+export const saveManagedSettings = (input: unknown) =>
+	fixtureAction("settings", input);
+export const listTableViews = (input: unknown) =>
+	fixtureAction("list-views", input);
+export const saveTableView = (input: unknown) =>
+	fixtureAction("save-view", input);
+export const deleteTableView = (input: unknown) =>
+	fixtureAction("delete-view", input);
+export const loadArticleRecovery = (key: unknown) =>
+	fixtureAction("load-recovery", { key });
+export const autosaveArticle = (...input: unknown[]) =>
+	fixtureAction("autosave", input);
+export const clearArticleRecovery = (...input: unknown[]) =>
+	fixtureAction("clear-recovery", input);
+export const uploadMediaAndReturn = () => fixtureAction("upload");
+
+export const createEvent = (input: unknown) =>
+	fixtureAction("create-event", input);
+export const updateEvent = (input: unknown) =>
+	fixtureAction("update-event", input);
+
+export const deleteImportedFurni = (input: unknown) =>
+	fixtureAction("delete-imported-furni", input);
+export const setFurnidataTranslateEnabled = (input: unknown) =>
+	fixtureAction("furnidata-translation", input);
+
+export const organizeImportFurni = (input: unknown) =>
+	fixtureAction("organize-import-furni", input);

e2e/ui/fixtures/unsaved-harness.tsx

@@ -0,0 +1,70 @@
+import { useState } from "react";
+import { PrefixDialog } from "@/app/admin/prefixes/prefix-dialog";
+import {
+	confirmUnsavedNavigation,
+	useUnsavedChanges,
+} from "@/hooks/use-unsaved-changes";
+export function UnsavedHarness() {
+	const [value, setValue] = useState("");
+	const [open, setOpen] = useState(false);
+	const [failSave, setFailSave] = useState(false);
+	const [saved, setSaved] = useState(false);
+	const [navigated, setNavigated] = useState(false);
+	const guard = useUnsavedChanges(value !== "", "Discard unsaved changes?");
+	return (
+		<>
+			<label>
+				Working value
+				<input
+					aria-label="Working value"
+					value={value}
+					onChange={(event) => setValue(event.target.value)}
+				/>
+			</label>
+			<a href="/admin/unsaved-destination">Leave editor</a>
+			<a href="#same-page">Same page</a>
+			<a href="mailto:[email protected]">Email</a>
+			<button
+				type="button"
+				onClick={() => {
+					if (confirmUnsavedNavigation()) setNavigated(true);
+				}}
+			>
+				Programmatic navigation
+			</button>
+			<button
+				type="button"
+				onClick={() => {
+					guard.markSaved();
+					setValue("");
+					setSaved(true);
+				}}
+			>
+				Save working value
+			</button>
+			{saved && <p>Working value saved</p>}
+			{navigated && <p>Navigation allowed</p>}
+			<button type="button" onClick={() => setOpen(true)}>
+				Open prefix
+			</button>
+			<label>
+				<input
+					type="checkbox"
+					checked={failSave}
+					onChange={(event) => setFailSave(event.target.checked)}
+				/>
+				Fail prefix save
+			</label>
+			<PrefixDialog
+				isOpen={open}
+				onClose={() => setOpen(false)}
+				editPrefix={null}
+				onSave={async () => {
+					if (failSave) return false;
+					setSaved(true);
+					return true;
+				}}
+			/>
+		</>
+	);
+}

e2e/ui/furniture-jobs.spec.ts

@@ -0,0 +1,188 @@
+import { expect, test } from "@playwright/test";
+import {
+	furnitureCursorFixture,
+	furnitureJobFixture,
+} from "../../src/test/furniture-jobs-fixtures";
+
+test("history hook deduplicates refreshes, pages and reports completion once", async ({
+	page,
+}) => {
+	let requests = 0;
+	let completed = false;
+	await page.route("**/api/admin/studio/import-jobs?*", async (route) => {
+		requests++;
+		const secondPage = new URL(route.request().url()).searchParams.has(
+			"before",
+		);
+		await new Promise((resolve) => setTimeout(resolve, 100));
+		await route.fulfill({
+			json: {
+				ok: true,
+				jobs: [
+					{
+						...furnitureJobFixture,
+						id: secondPage
+							? "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
+							: furnitureJobFixture.id,
+						state: completed ? "completed" : "queued",
+					},
+				],
+				nextCursor: secondPage ? null : furnitureCursorFixture,
+			},
+		});
+	});
+	await page.goto("/admin/jobs-harness");
+	await expect(page.getByLabel("Jobs", { exact: true })).toContainText(
+		furnitureJobFixture.id,
+	);
+	await expect(page.getByLabel("Loading", { exact: true })).toHaveText("false");
+	const initial = requests;
+	await page.getByRole("button", { name: "Refresh twice" }).click();
+	await expect(page.getByLabel("Loading", { exact: true })).toHaveText("true");
+	await expect(page.getByLabel("Loading", { exact: true })).toHaveText("false");
+	expect(requests).toBe(initial + 1);
+	await page.getByRole("button", { name: "Next page" }).click();
+	await expect(page.getByLabel("Page", { exact: true })).toHaveText("2");
+	await expect(page.getByLabel("Jobs", { exact: true })).toContainText(
+		"bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
+	);
+	await page.getByRole("button", { name: "Previous page" }).click();
+	await expect(page.getByLabel("Page", { exact: true })).toHaveText("1");
+	await expect(page.getByLabel("Jobs", { exact: true })).toContainText(
+		furnitureJobFixture.id,
+	);
+	await expect(page.getByLabel("Loading", { exact: true })).toHaveText("false");
+	completed = true;
+	await page.getByRole("button", { name: "Refresh twice" }).click();
+	await expect(page.getByLabel("Loading", { exact: true })).toHaveText("true");
+	await expect(page.getByLabel("Completions", { exact: true })).toHaveText("1");
+	await expect(page.getByLabel("Loading", { exact: true })).toHaveText("false");
+	await page.getByRole("button", { name: "Refresh twice" }).click();
+	await expect(page.getByLabel("Loading", { exact: true })).toHaveText("true");
+	await expect(page.getByLabel("Loading", { exact: true })).toHaveText("false");
+	await expect(page.getByLabel("Completions", { exact: true })).toHaveText("1");
+});
+
+test("history polling pauses while hidden and refreshes on visibility return", async ({
+	page,
+}) => {
+	let requests = 0;
+	await page.clock.install();
+	await page.route("**/api/admin/studio/import-jobs?*", (route) => {
+		requests++;
+		return route.fulfill({
+			json: { ok: true, jobs: [furnitureJobFixture], nextCursor: null },
+		});
+	});
+	await page.goto("/admin/jobs-harness");
+	await expect(page.getByLabel("Jobs", { exact: true })).toContainText(
+		furnitureJobFixture.id,
+	);
+	await expect(page.getByLabel("Loading", { exact: true })).toHaveText("false");
+	await page.evaluate(() => {
+		Object.defineProperty(document, "visibilityState", {
+			configurable: true,
+			get: () => "hidden",
+		});
+		document.dispatchEvent(new Event("visibilitychange"));
+	});
+	const hiddenCount = requests;
+	await page.clock.fastForward(60000);
+	expect(requests).toBe(hiddenCount);
+	await page.evaluate(() => {
+		Object.defineProperty(document, "visibilityState", {
+			configurable: true,
+			get: () => "visible",
+		});
+		document.dispatchEvent(new Event("visibilitychange"));
+	});
+	await expect.poll(() => requests).toBe(hiddenCount + 1);
+});
+
+test("history shows the current phase and validated recovery source", async ({
+	page,
+}) => {
+	await page.route("**/api/admin/studio/import-jobs?*", (route) =>
+		route.fulfill({
+			json: {
+				ok: true,
+				jobs: [
+					{
+						...furnitureJobFixture,
+						state: "running",
+						items: [
+							{
+								...furnitureJobFixture.items[0],
+								state: "running",
+								phase: "writing_db",
+								phaseStartedAt: new Date().toISOString(),
+								recoveredSource: {
+									sourceId: "configured",
+									sourceName: "Configured source",
+									revision: 42,
+								},
+							},
+						],
+					},
+				],
+				nextCursor: null,
+			},
+		}),
+	);
+	await page.goto("/admin/jobs-harness?progress");
+	await page.locator("details details summary").click();
+	await expect(
+		page.getByText("Current phase: Saving SQL and catalog"),
+	).toBeVisible();
+	await expect(
+		page.getByText(/Bundle recovered from Configured source/),
+	).toBeVisible();
+	expect(
+		await page.evaluate(
+			() => document.documentElement.scrollWidth > innerWidth,
+		),
+	).toBe(false);
+});
+
+test("uncertain import submissions keep their identity after a page reload", async ({
+	page,
+}) => {
+	const ids: string[] = [];
+	await page.route("**/api/admin/csrf", (route) =>
+		route.fulfill({ json: { token: "a".repeat(64) } }),
+	);
+	await page.route("**/api/admin/studio/import-jobs**", async (route) => {
+		if (route.request().method() !== "POST") {
+			await route.fulfill({ json: { ok: true, jobs: [], nextCursor: null } });
+			return;
+		}
+		const body = route.request().postDataJSON();
+		ids.push(body.id);
+		if (ids.length === 1) await route.abort("failed");
+		else
+			await route.fulfill({
+				json: { ok: true, job: { ...furnitureJobFixture, id: body.id } },
+			});
+	});
+	await page.goto("/admin/jobs-harness");
+	await page
+		.getByRole("button", { name: "Submit import", exact: true })
+		.click();
+	await expect(page.getByLabel("Submitted", { exact: true })).toHaveText(
+		"false",
+	);
+	await page.reload();
+	await page
+		.getByRole("button", { name: "Submit import", exact: true })
+		.click();
+	await expect(page.getByLabel("Submitted", { exact: true })).toHaveText(
+		"true",
+	);
+	expect(ids).toHaveLength(2);
+	expect(ids[1]).toBe(ids[0]);
+	await page
+		.getByRole("button", { name: "Submit import", exact: true })
+		.click();
+	await expect.poll(() => ids.length).toBe(3);
+	expect(ids[2]).not.toBe(ids[0]);
+});

e2e/ui/news-publication.spec.ts

@@ -0,0 +1,48 @@
+import { expect, test } from "@playwright/test";
+
+test("news editor retries a lost response with the same request across reload and clears it after success", async ({
+	page,
+}) => {
+	const requests: Array<Record<string, string>> = [];
+	let succeed = false;
+	await page.route("**/fixture/actions/article", async (route) => {
+		requests.push(route.request().postDataJSON());
+		if (!succeed) await route.abort("failed");
+		else
+			await route.fulfill({
+				contentType: "application/json",
+				body: JSON.stringify({ ok: true, data: {} }),
+			});
+	});
+	await page.goto("/admin/articles/new");
+	await expect(page.locator("iframe.tox-edit-area__iframe")).toBeVisible();
+	const save = page.getByRole("button", { name: "Save article", exact: true });
+	await save.click();
+	await expect(page.getByRole("alert")).toBeVisible();
+	await save.click();
+	await expect.poll(() => requests.length).toBe(2);
+	expect(requests[1].requestKey).toBe(requests[0].requestKey);
+	await page.reload();
+	await expect(page.locator("iframe.tox-edit-area__iframe")).toBeVisible();
+	await save.click();
+	await expect.poll(() => requests.length).toBe(3);
+	expect(requests[2].requestKey).toBe(requests[0].requestKey);
+	const stored = await page.evaluate(() =>
+		sessionStorage.getItem("cms:news:request:current:new"),
+	);
+	expect(stored).not.toContain("Community update");
+	succeed = true;
+	await save.click();
+	await expect
+		.poll(() =>
+			page.evaluate(() =>
+				sessionStorage.getItem("cms:news:request:current:new"),
+			),
+		)
+		.toBeNull();
+	expect(requests[3].requestKey).toBe(requests[0].requestKey);
+	await page.locator('input[name="title"]').fill("Another article");
+	await save.click();
+	await expect.poll(() => requests.length).toBe(5);
+	expect(requests[4].requestKey).not.toBe(requests[0].requestKey);
+});

e2e/ui/notifications.spec.ts

@@ -0,0 +1,162 @@
+import { expect, test } from "@playwright/test";
+
+test.beforeEach(async ({ page }) => {
+	page.on("pageerror", (error) => {
+		throw error;
+	});
+});
+
+test("notification reads persist, new replies are unread and failed preferences stay unchanged", async ({
+	page,
+}) => {
+	let key = "support:42";
+	const readKeys = new Set<string>();
+	let fail = false;
+	await page.route("**/api/notifications**", async (route) => {
+		if (route.request().method() === "POST") {
+			if (fail)
+				return route.fulfill({ status: 503, json: { error: "Unavailable" } });
+			const body = route.request().postDataJSON();
+			if (body.action === "read") readKeys.add(body.key);
+			return route.fulfill({ json: { ok: true } });
+		}
+		return route.fulfill({
+			json: {
+				items: [
+					{
+						key,
+						category: "support",
+						title: "Your account request",
+						href: "/help/tickets/2",
+						occurredAt: "2030-01-01T12:00:00Z",
+						read: readKeys.has(key),
+					},
+				],
+				page: 1,
+				pages: 1,
+				unread: readKeys.has(key) ? 0 : 1,
+				preferences: { support: true, friends: true, events: true },
+			},
+		});
+	});
+	await page.goto("/notifications");
+	const mark = page.getByRole("button", { name: "Mark as read" });
+	await expect(mark).toBeVisible();
+	await mark.focus();
+	await expect(mark).toBeFocused();
+	await page.keyboard.press("Enter");
+	await expect(mark).toHaveCount(0);
+	await page.reload();
+	await expect(
+		page.getByText("No unread notifications", { exact: true }),
+	).toBeVisible();
+	key = "support:43";
+	await page.reload();
+	await expect(mark).toBeVisible();
+	fail = true;
+	await mark.click();
+	await expect(page.getByRole("alert")).toHaveText(
+		"The change could not be saved. Please try again.",
+	);
+	await expect(mark).toBeVisible();
+	const support = page.getByRole("checkbox", { name: "Support replies" });
+	await support.click();
+	await expect(support).toBeChecked();
+	expect(await support.evaluate((el) => getComputedStyle(el).color)).not.toBe(
+		"rgba(0, 0, 0, 0)",
+	);
+	expect(
+		await support.evaluate((el) => getComputedStyle(el).backgroundColor),
+	).not.toBe("rgba(0, 0, 0, 0)");
+	expect(
+		await page.evaluate(
+			() => document.documentElement.scrollWidth <= window.innerWidth,
+		),
+	).toBe(true);
+	await page.screenshot({
+		path: `test-results/notifications-${test.info().project.name}.png`,
+		fullPage: true,
+	});
+});
+
+test("notification service failure offers a retry and recovers to empty state", async ({
+	page,
+}) => {
+	let failing = true;
+	await page.route("**/api/notifications**", (route) =>
+		route.fulfill(
+			failing
+				? { status: 503, json: { error: "Unavailable" } }
+				: {
+						json: {
+							items: [],
+							page: 1,
+							pages: 1,
+							unread: 0,
+							preferences: { support: true, friends: true, events: true },
+						},
+					},
+		),
+	);
+	await page.goto("/notifications");
+	await expect(page.getByRole("alert")).toHaveText(
+		"Notifications are temporarily unavailable.",
+	);
+	failing = false;
+	await page.getByRole("button", { name: "Try again" }).click();
+	await expect(
+		page.getByText("No notifications in your enabled categories."),
+	).toBeVisible();
+});
+
+test("category changes persist and pagination recovers when filtering shrinks the feed", async ({
+	page,
+}) => {
+	let enabled = true;
+	await page.route("**/api/notifications**", async (route) => {
+		if (route.request().method() === "POST") {
+			enabled = route.request().postDataJSON().preferences.support;
+			return route.fulfill({ json: { ok: true } });
+		}
+		const requested = Number(
+			new URL(route.request().url()).searchParams.get("page") ?? 1,
+		);
+		const current = enabled ? Math.min(2, requested) : 1;
+		return route.fulfill({
+			json: {
+				items: enabled
+					? [
+							{
+								key: `support:${current}`,
+								category: "support",
+								title: `Reply page ${current}`,
+								href: "/help/tickets/2",
+								occurredAt: null,
+								read: false,
+							},
+						]
+					: [],
+				page: current,
+				pages: enabled ? 2 : 1,
+				unread: enabled ? 21 : 0,
+				preferences: { support: enabled, friends: true, events: true },
+			},
+		});
+	});
+	await page.goto("/notifications");
+	await page.getByRole("button", { name: "Next", exact: true }).click();
+	await expect(page.getByRole("link", { name: "Reply page 2" })).toBeVisible();
+	const support = page.getByRole("checkbox", { name: "Support replies" });
+	await support.click();
+	await expect(support).not.toBeChecked();
+	await expect(
+		page.getByText("No notifications in your enabled categories."),
+	).toBeVisible();
+	await expect(
+		page.getByRole("button", { name: "Next", exact: true }),
+	).toHaveCount(0);
+	await page.reload();
+	await expect(support).not.toBeChecked();
+	await support.click();
+	await expect(page.getByRole("link", { name: "Reply page 1" })).toBeVisible();
+});

e2e/ui/studio-workspace.spec.ts

@@ -0,0 +1,185 @@
+import { expect, type Page, test } from "@playwright/test";
+
+const items = Array.from({ length: 60 }, (_, index) => ({
+	id: index + 1,
+	classname: `chair_${index}`,
+	name: `Chair ${index}`,
+	description: "Fixture furniture",
+	type: "flooritem",
+	revision: 1,
+	category: "other",
+	alreadyImported: false,
+	nitroExists: false,
+	iconUrl: "/fixture/cover.svg",
+}));
+async function mockStudio(page: Page) {
+	await page.route("**/api/**", async (route) => {
+		const url = new URL(route.request().url());
+		if (url.pathname.endsWith("/inspect"))
+			return route.fulfill({
+				json: {
+					items: (route.request().postDataJSON().classnames as string[]).map(
+						(classname) => ({
+							classname,
+							sql: [{ id: 1, spriteId: 1, name: "Chair", type: "s" }],
+							catalog: [],
+							furnidata: [],
+							furnidataReadable: true,
+							nitro: { exists: true, bytes: 42 },
+							icon: { exists: false, bytes: 0 },
+						}),
+					),
+				},
+			});
+		if (url.pathname.endsWith("/source-assets"))
+			return route.fulfill({ json: { items: [] } });
+		if (url.pathname.endsWith("/furni"))
+			return route.fulfill({
+				json: url.searchParams.has("action")
+					? { totalInDb: 0, inCatalog: 0, notInCatalog: 0, missingNitro: 0 }
+					: {
+							items,
+							meta: {
+								currentPage: 1,
+								lastPage: 1,
+								total: items.length,
+								perPage: 100,
+							},
+						},
+			});
+		if (url.pathname.endsWith("/clone"))
+			return route.fulfill({ json: { sources: [] } });
+		if (url.pathname.endsWith("/import-jobs"))
+			return route.fulfill({ json: { ok: true, jobs: [], nextCursor: null } });
+		return route.fulfill({
+			status: 404,
+			json: { error: "Unknown fixture endpoint" },
+		});
+	});
+}
+test("closing furniture restores its scroll, focus, search, filter and selection", async ({
+	page,
+}) => {
+	await mockStudio(page);
+	await page.goto("/admin/studio-harness");
+	await page.getByRole("textbox", { name: "Search furniture" }).fill("chair");
+	await page.waitForResponse(
+		(res) => new URL(res.url()).searchParams.get("search") === "chair",
+	);
+	await page.getByRole("combobox", { name: "Furniture type" }).click();
+	await page.getByRole("option", { name: "Floor items", exact: true }).click();
+	const trigger = page.getByRole("button", {
+		name: "View Chair 30",
+		exact: true,
+	});
+	await trigger.scrollIntoViewIfNeeded();
+	await page
+		.getByRole("checkbox", { name: "Select chair_30", exact: true })
+		.check();
+	const list = page.getByTestId("studio-furniture-list");
+	const top = await list.evaluate((element) => element.scrollTop);
+	await trigger.click();
+	await page
+		.getByRole("button", { name: "Close furniture details", exact: true })
+		.click();
+	await expect(trigger).toBeFocused();
+	expect(await list.evaluate((element) => element.scrollTop)).toBe(top);
+	await expect(
+		page.getByRole("textbox", { name: "Search furniture" }),
+	).toHaveValue("chair");
+	await expect(
+		page.getByRole("combobox", { name: "Furniture type" }),
+	).toContainText("Floor");
+	await expect(
+		page.getByRole("checkbox", { name: "Select chair_30", exact: true }),
+	).toBeChecked();
+	await trigger.click();
+	await page.keyboard.press("Escape");
+	await expect(
+		page.getByRole("button", { name: "Close furniture details", exact: true }),
+	).toHaveCount(0);
+	await expect(trigger).toBeFocused();
+	await expect(
+		page.getByRole("checkbox", { name: "Select chair_30", exact: true }),
+	).toBeChecked();
+});
+test("review proposes completing existing furniture and filters actionable groups", async ({
+	page,
+}) => {
+	await mockStudio(page);
+	await page.goto("/admin/studio-harness");
+	await page
+		.getByRole("button", { name: "Import chair_0", exact: true })
+		.click();
+	const review = page.getByRole("dialog", {
+		name: "Review furniture import",
+		exact: true,
+	});
+	await expect(
+		review.getByText("Suggested: complete existing furniture", { exact: true }),
+	).toBeVisible();
+	await expect(
+		review.getByText("Missing: Catalog offer, Furnidata, Local icon"),
+	).toBeVisible();
+	await review
+		.getByRole("button", { name: "Conflicts (0)", exact: true })
+		.click();
+	await expect(
+		review.getByText("No furniture in this group.", { exact: true }),
+	).toBeVisible();
+	await review
+		.getByRole("button", { name: "To complete (1)", exact: true })
+		.click();
+	await expect(
+		review.getByText("Suggested: complete existing furniture", { exact: true }),
+	).toBeVisible();
+	await review
+		.getByRole("button", { name: "Continue to confirmation", exact: true })
+		.click();
+	await expect(
+		page
+			.getByRole("dialog", { name: "Confirm furniture import", exact: true })
+			.getByRole("button", { name: "Start import (1)", exact: true }),
+	).toBeEnabled();
+});
+
+test("an older search response cannot replace newer furniture", async ({
+	page,
+}) => {
+	await mockStudio(page);
+	await page.route("**/api/admin/import/furni?*", async (route) => {
+		const search = new URL(route.request().url()).searchParams.get("search");
+		if (!search) return route.fallback();
+		if (search === "old")
+			await new Promise((resolve) => setTimeout(resolve, 1500));
+		await route.fulfill({
+			json: {
+				items: [
+					{
+						...items[0],
+						name: search === "old" ? "Old response" : "New response",
+					},
+				],
+				meta: { currentPage: 1, lastPage: 1, total: 1, perPage: 100 },
+			},
+		});
+	});
+	await page.goto("/admin/studio-harness");
+	const search = page.getByRole("textbox", { name: "Search furniture" });
+	const oldRequest = page.waitForRequest(
+		(request) => new URL(request.url()).searchParams.get("search") === "old",
+	);
+	await search.fill("old");
+	await oldRequest;
+	await search.fill("new");
+	await expect(
+		page.getByRole("button", { name: "View New response", exact: true }),
+	).toBeVisible();
+	await page.waitForTimeout(1800);
+	await expect(
+		page.getByRole("button", { name: "View New response", exact: true }),
+	).toBeVisible();
+	await expect(
+		page.getByRole("button", { name: "View Old response", exact: true }),
+	).toHaveCount(0);
+});

e2e/ui/studio.spec.ts

@@ -0,0 +1,318 @@
+import { expect, test } from "@playwright/test";
+
+const items = [
+	{
+		id: 1,
+		classname: "fixture_chair",
+		name: "Fixture chair",
+		description: "Synthetic chair",
+		type: "flooritem",
+		revision: 1,
+		category: "other",
+		alreadyImported: true,
+		nitroExists: true,
+		iconUrl: "/fixture/cover.svg",
+	},
+	{
+		id: 2,
+		classname: "fixture_table",
+		name: "Fixture table",
+		description: "Synthetic table",
+		type: "flooritem",
+		revision: 1,
+		category: "other",
+		alreadyImported: false,
+		nitroExists: false,
+		iconUrl: "/fixture/cover.svg",
+	},
+];
+
+test("Studio opens and dismisses detail, Nitro editor and import review", async ({
+	page,
+}) => {
+	const errors: string[] = [];
+	const mutations: string[] = [];
+	let metadataRequests = 0;
+	let qualityRequests = 0;
+	page.on("pageerror", (error) => errors.push(error.message));
+	await page.route("**/api/**", async (route) => {
+		const request = route.request();
+		const url = new URL(request.url());
+		if (url.pathname === "/api/admin/studio/nitro-quality") {
+			qualityRequests++;
+			return route.fulfill({
+				json: {
+					report: {
+						scales: [32, 64].map((size) => ({
+							size,
+							state: "missing",
+							assets: [],
+							animations: [],
+							directions: [],
+							issues: [],
+						})),
+					},
+				},
+			});
+		}
+		if (url.pathname === "/api/admin/studio/inspect") {
+			const { classnames } = request.postDataJSON() as { classnames: string[] };
+			return route.fulfill({
+				json: {
+					items: classnames.map((classname) => ({
+						classname,
+						sql: [],
+						catalog: [],
+						furnidata: [],
+						furnidataReadable: true,
+						nitro: { exists: false, bytes: 0 },
+						icon: { exists: false, bytes: 0 },
+					})),
+				},
+			});
+		}
+		if (url.pathname === "/api/admin/studio/source-assets") {
+			const body = request.postDataJSON() as {
+				items: Array<{ classname: string }>;
+			};
+			return route.fulfill({
+				json: {
+					items: body.items.map(({ classname }) => ({
+						classname,
+						state: "available",
+						revision: 1,
+						alternatives: [],
+						attempts: [],
+					})),
+				},
+			});
+		}
+		if (request.method() !== "GET") {
+			mutations.push(`${request.method()} ${url.pathname}`);
+			return route.fulfill({
+				status: 405,
+				json: { error: "Fixture forbids mutations" },
+			});
+		}
+		if (url.pathname.endsWith("/nitro-editor")) {
+			metadataRequests++;
+			return route.fulfill({
+				json: {
+					metadata: {
+						name: "fixture_chair",
+						logicType: "furniture_basic",
+						visualizationType: "furniture_static",
+					},
+					flags: { canstandon: false, cansiton: false, canlayon: false },
+				},
+			});
+		}
+		if (url.pathname === "/api/admin/import/furni") {
+			return route.fulfill({
+				json:
+					url.searchParams.get("action") === "stats"
+						? { totalInDb: 1, inCatalog: 1, notInCatalog: 0, missingNitro: 0 }
+						: {
+								items,
+								meta: { currentPage: 1, lastPage: 1, total: 2, perPage: 20 },
+							},
+			});
+		}
+		if (url.pathname === "/api/admin/import/clone")
+			return route.fulfill({ json: { sources: [] } });
+		if (url.pathname === "/api/admin/studio/import-jobs")
+			return route.fulfill({ json: { ok: true, jobs: [], nextCursor: null } });
+		return route.fulfill({
+			status: 404,
+			json: { error: "Unknown fixture endpoint" },
+		});
+	});
+	await page.goto("/admin/studio-harness");
+	await expect(
+		page.getByRole("button", { name: "View Fixture chair", exact: true }),
+	).toBeVisible();
+	const history = page.getByRole("button", {
+		name: "Refresh history",
+		includeHidden: true,
+	});
+	await expect(history).toHaveCount(0);
+	await page.locator("summary").filter({ hasText: "Import history" }).click();
+	await expect(history).toBeVisible();
+	await page.locator("summary").filter({ hasText: "Import history" }).click();
+	await expect(history).toBeHidden();
+	await page.locator("summary").filter({ hasText: "Import history" }).click();
+	await expect(history).toBeVisible();
+	expect(metadataRequests).toBe(0);
+	await page
+		.getByRole("button", { name: "View Fixture chair", exact: true })
+		.click();
+	await expect(
+		page.getByRole("button", { name: "Close furniture details", exact: true }),
+	).toBeVisible();
+	await expect(
+		page.getByText("Synthetic chair", { exact: true }).first(),
+	).toBeVisible();
+	await page
+		.getByRole("button", { name: "Close furniture details", exact: true })
+		.click();
+	await expect(
+		page.getByRole("button", { name: "Close furniture details", exact: true }),
+	).toHaveCount(0);
+	await page
+		.getByRole("button", { name: "Edit nitro fixture_chair", exact: true })
+		.click();
+	const editor = page.getByRole("dialog", { name: "Edit Nitro", exact: true });
+	await expect(editor).toBeVisible();
+	await expect(
+		editor.getByRole("switch", { name: "Can Sit On", exact: true }),
+	).toBeVisible();
+	expect(metadataRequests).toBe(1);
+	expect(qualityRequests).toBe(0);
+	await editor.getByRole("tab", { name: "32 / 64", exact: true }).click();
+	await expect(
+		editor.getByRole("button", { name: "Preview generation", exact: true }),
+	).toBeVisible();
+	await expect(
+		editor.getByText("Scale 32 · Not included", { exact: true }),
+	).toBeVisible();
+	expect(qualityRequests).toBe(1);
+	await editor.getByRole("tab", { name: "Visual", exact: true }).click();
+	await expect(
+		editor.getByRole("switch", { name: "Can Sit On", exact: true }),
+	).toBeVisible();
+
+	await editor.getByRole("button", { name: "Cancel", exact: true }).click();
+	await expect(editor).toHaveCount(0);
+	await page
+		.getByRole("button", { name: "Import fixture_table", exact: true })
+		.click();
+	const review = page.getByRole("dialog", {
+		name: "Review furniture import",
+		exact: true,
+	});
+	await expect(review).toBeVisible();
+	await expect(
+		review.getByText("Fixture table", { exact: true }),
+	).toBeVisible();
+	await expect(
+		review.getByRole("button", {
+			name: "Continue to confirmation",
+			exact: true,
+		}),
+	).toBeEnabled();
+	await review.getByRole("button", { name: "Cancel", exact: true }).click();
+	await expect(review).toHaveCount(0);
+	expect(mutations).toEqual([]);
+	expect(errors).toEqual([]);
+});
+
+test("Studio loads organize imports on demand and preserves the dialog on reopen", async ({
+	page,
+}, testInfo) => {
+	const errors: string[] = [];
+	const mutations: string[] = [];
+	let organizeRequests = 0;
+	page.on("pageerror", (error) => errors.push(error.message));
+	await page.route("**/fixture/actions/**", async (route) => {
+		mutations.push(route.request().url());
+		await route.fulfill({
+			status: 405,
+			json: { error: "No mutations expected" },
+		});
+	});
+	await page.route("**/api/**", async (route) => {
+		const request = route.request();
+		const url = new URL(request.url());
+		if (request.method() !== "GET") {
+			mutations.push(`${request.method()} ${url.pathname}`);
+			return route.fulfill({
+				status: 405,
+				json: { error: "No mutations expected" },
+			});
+		}
+		if (url.pathname === "/api/admin/import/organize") {
+			organizeRequests++;
+			return route.fulfill({
+				json: {
+					groups: [
+						{
+							name: "Fixture imports",
+							icon: 1,
+							layout: "default_3x3",
+							total: 1,
+							moved: 0,
+							added: 1,
+							thumbs: [],
+							items: [
+								{
+									itemId: 1,
+									catalogItemId: null,
+									alreadyPlaced: false,
+									itemName: "fixture_table",
+									publicName: "Fixture Table",
+									spriteId: 0,
+									type: "s",
+									interactionType: "default",
+									sourcePageCaption: null,
+								},
+							],
+						},
+					],
+					importRootPageId: null,
+					importRootCaption: null,
+				},
+			});
+		}
+		if (url.pathname === "/api/admin/catalog/tree")
+			return route.fulfill({ json: { pages: [] } });
+		if (url.pathname === "/api/admin/import/furni")
+			return route.fulfill({
+				json:
+					url.searchParams.get("action") === "stats"
+						? { totalInDb: 0, inCatalog: 0, notInCatalog: 0, missingNitro: 0 }
+						: {
+								items: [],
+								meta: { currentPage: 1, lastPage: 1, total: 0, perPage: 20 },
+							},
+			});
+		if (url.pathname === "/api/admin/import/clone")
+			return route.fulfill({ json: { sources: [] } });
+		if (url.pathname === "/api/admin/studio/import-jobs")
+			return route.fulfill({ json: { ok: true, jobs: [], nextCursor: null } });
+		return route.fulfill({
+			status: 404,
+			json: { error: "Unknown fixture endpoint" },
+		});
+	});
+	await page.goto("/admin/studio-harness");
+	const trigger = page.getByRole("button", {
+		name: "Organize imports",
+		exact: true,
+	});
+	await expect(trigger).toBeVisible();
+	expect(organizeRequests).toBe(0);
+	await trigger.click();
+	const dialog = page.getByRole("dialog", { name: /^Organize imports/ });
+	await expect(dialog).toBeVisible();
+	const filter = dialog.getByPlaceholder("Filter import groups...");
+	await expect(filter).toBeVisible();
+	await expect(dialog.locator('input[value="Fixture imports"]')).toBeVisible();
+	await filter.fill("Fixture");
+	expect(organizeRequests).toBe(1);
+	await testInfo.attach("organize-imports", {
+		body: await page.screenshot(),
+		contentType: "image/png",
+	});
+	await dialog.getByRole("button", { name: "Cancel", exact: true }).click();
+	await expect(dialog).toHaveCount(0);
+	await expect(trigger).toBeFocused();
+	await trigger.click();
+	await expect(dialog).toBeVisible();
+	await expect(filter).toHaveValue("Fixture");
+	await expect.poll(() => organizeRequests).toBe(2);
+	await page.keyboard.press("Escape");
+	await expect(dialog).toHaveCount(0);
+	await expect(trigger).toBeFocused();
+	expect(mutations).toEqual([]);
+	expect(errors).toEqual([]);
+});

e2e/ui/unsaved-changes.spec.ts

@@ -0,0 +1,117 @@
+import { expect, test } from "@playwright/test";
+
+test.beforeEach(async ({ page }) => {
+	await page.goto("/admin/unsaved-harness");
+});
+test("cancelled programmatic navigation preserves changes and save clears protection", async ({
+	page,
+}) => {
+	await page.getByLabel("Working value").fill("Keep this");
+	page.once("dialog", (dialog) => dialog.dismiss());
+	await page.getByRole("button", { name: "Programmatic navigation" }).click();
+	await expect(page.getByText("Navigation allowed")).toHaveCount(0);
+	await expect(page.getByLabel("Working value")).toHaveValue("Keep this");
+	await page.getByRole("button", { name: "Save working value" }).click();
+	let prompts = 0;
+	page.on("dialog", async (dialog) => {
+		prompts++;
+		await dialog.dismiss();
+	});
+	await page.getByRole("button", { name: "Programmatic navigation" }).click();
+	await expect(page.getByText("Navigation allowed")).toBeVisible();
+	expect(prompts).toBe(0);
+});
+test("cancelled link navigation and same-page anchors preserve the editor", async ({
+	page,
+}) => {
+	await page.getByLabel("Working value").fill("Keep this");
+	let prompts = 0;
+	page.on("dialog", async (dialog) => {
+		prompts++;
+		await dialog.dismiss();
+	});
+	await page.getByRole("link", { name: "Leave editor" }).click();
+	await expect(page).toHaveURL(/unsaved-harness$/);
+	await page.getByRole("link", { name: "Same page" }).click();
+	await expect(page).toHaveURL(/#same-page$/);
+	expect(prompts).toBe(1);
+});
+test("prefix cancel and Escape preserve edits; accepting discard resets reopening", async ({
+	page,
+}) => {
+	await page.getByRole("button", { name: "Open prefix" }).click();
+	await page
+		.getByRole("textbox", { name: "Prefix text", exact: true })
+		.fill("VIP");
+	page.once("dialog", (dialog) => dialog.dismiss());
+	await page.getByRole("button", { name: "Cancel", exact: true }).click();
+	await expect(
+		page.getByRole("textbox", { name: "Prefix text", exact: true }),
+	).toHaveValue("VIP");
+	page.once("dialog", (dialog) => dialog.dismiss());
+	await page.keyboard.press("Escape");
+	await expect(page.getByRole("dialog")).toBeVisible();
+	page.once("dialog", (dialog) => dialog.accept());
+	await page.getByRole("button", { name: "Cancel", exact: true }).click();
+	await expect(page.getByRole("dialog")).toHaveCount(0);
+	await page.getByRole("button", { name: "Open prefix" }).click();
+	await expect(
+		page.getByRole("textbox", { name: "Prefix text", exact: true }),
+	).toHaveValue("");
+});
+test("successful prefix save closes without a discard prompt", async ({
+	page,
+}) => {
+	await page.getByRole("button", { name: "Open prefix" }).click();
+	await page
+		.getByRole("textbox", { name: "Username", exact: true })
+		.fill("Alice");
+	await page
+		.getByRole("textbox", { name: "Prefix text", exact: true })
+		.fill("VIP");
+	let prompts = 0;
+	page.on("dialog", async (dialog) => {
+		prompts++;
+		await dialog.dismiss();
+	});
+	await page.getByRole("button", { name: "Save", exact: true }).click();
+	await expect(page.getByRole("dialog")).toHaveCount(0);
+	expect(prompts).toBe(0);
+});
+test("supported browser back can be cancelled without changing the address or draft", async ({
+	page,
+}) => {
+	test.skip(
+		!(await page.evaluate(() => "navigation" in window)),
+		"Navigation API unavailable",
+	);
+	await page.evaluate(() =>
+		history.pushState({}, "", "/admin/unsaved-harness?step=2"),
+	);
+	await page.getByLabel("Working value").fill("Keep this");
+	const prompt = page.waitForEvent("dialog");
+	await page.evaluate(() => history.back());
+	await (await prompt).dismiss();
+	await expect(page).toHaveURL(/step=2$/);
+	await expect(page.getByLabel("Working value")).toHaveValue("Keep this");
+});
+
+test("failed prefix save keeps the editor and dirty protection", async ({
+	page,
+}) => {
+	await page.getByLabel("Fail prefix save").check();
+	await page.getByRole("button", { name: "Open prefix" }).click();
+	await page
+		.getByRole("textbox", { name: "Username", exact: true })
+		.fill("Alice");
+	await page
+		.getByRole("textbox", { name: "Prefix text", exact: true })
+		.fill("VIP");
+	await page.getByRole("button", { name: "Save", exact: true }).click();
+	await expect(page.getByRole("dialog")).toBeVisible();
+	page.once("dialog", (dialog) => dialog.dismiss());
+	await page.getByRole("button", { name: "Cancel", exact: true }).click();
+	await expect(
+		page.getByRole("textbox", { name: "Prefix text", exact: true }),
+	).toHaveValue("VIP");
+});

e2e/ui/workflows.spec.ts

@@ -0,0 +1,162 @@
+import AxeBuilder from "@axe-core/playwright";
+import { expect, type Page, test } from "@playwright/test";
+
+async function accessible(page: Page, sandboxPreview = false) {
+	const builder = new AxeBuilder({ page });
+	// A sandbox without allow-scripts cannot run axe; its accessible name is asserted separately.
+	if (sandboxPreview) builder.exclude("iframe[sandbox]");
+	const result = await builder
+		.withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"])
+		.analyze();
+	expect(
+		result.violations.map(({ id, impact, nodes }) => ({
+			id,
+			impact,
+			nodes: nodes.map((node) => ({
+				target: node.target,
+				summary: node.failureSummary,
+			})),
+		})),
+	).toEqual([]);
+}
+
+test.beforeEach(async ({ page, baseURL, request }) => {
+	await request.post("/fixture/reset");
+	await page.clock.setFixedTime(new Date("2030-01-01T12:00:00Z"));
+	await page.route("**/*", (route) =>
+		new URL(route.request().url()).origin === baseURL
+			? route.continue()
+			: route.abort(),
+	);
+	page.on("pageerror", (error) => {
+		throw error;
+	});
+});
+
+test("settings switches have names and remain keyboard operable", async ({
+	page,
+}) => {
+	await page.goto("/admin/settings");
+	const toggle = page.getByRole("switch", {
+		name: "Dark mode by default",
+		exact: true,
+	});
+	await expect(toggle).not.toBeChecked();
+	await toggle.focus();
+	await page.keyboard.press("Space");
+	await expect(toggle).toBeChecked();
+	await accessible(page);
+	const group = page.locator("section").filter({ has: toggle });
+	await expect(group).toHaveScreenshot("settings-switches.png");
+	const response = page.waitForResponse((response) =>
+		response.url().endsWith("/fixture/actions/settings"),
+	);
+	await page
+		.getByRole("button", { name: "Save settings", exact: true })
+		.click();
+	expect((await response).ok()).toBe(true);
+	await expect(
+		page.getByRole("button", { name: "Save settings", exact: true }),
+	).toBeDisabled();
+});
+
+test("article form and preview dialog pass accessibility with focus return", async ({
+	page,
+}) => {
+	await page.goto("/admin/articles/new");
+	await expect(page.locator("iframe.tox-edit-area__iframe")).toBeVisible();
+	await expect
+		.poll(() =>
+			page
+				.locator("form")
+				.evaluate((form) => form.scrollWidth <= form.clientWidth),
+		)
+		.toBe(true);
+	await accessible(page);
+	await page.locator('input[name="title"]').fill("Accessible community update");
+	const preview = page.getByRole("button", { name: "Preview", exact: true });
+	await preview.click();
+	const dialog = page.getByRole("dialog");
+	await expect(dialog).toBeVisible();
+	await expect(dialog).toHaveAccessibleName("Article preview");
+	await expect(dialog.locator("iframe")).toHaveAttribute("title", /.+/);
+	await accessible(page, true);
+	await expect(dialog).toHaveScreenshot("article-preview.png");
+	// Keyboard events inside the sandbox do not bubble to the parent dialog.
+	await page.keyboard.press("Tab");
+	await expect(
+		dialog.getByRole("button", { name: "Close", exact: true }),
+	).toBeFocused();
+	await page.keyboard.press("Escape");
+	await expect(dialog).not.toBeVisible();
+	await expect(preview).toBeFocused();
+	await expect(page.getByRole("main")).toHaveScreenshot("article-form.png");
+});
+
+test("support table filters and saved-view popover stay accessible", async ({
+	page,
+}) => {
+	await page.goto("/admin/tickets/desk");
+	await expect(
+		page.getByRole("link", { name: "Account assistance" }),
+	).toBeVisible();
+	await accessible(page);
+	await expect(page.getByRole("main")).toHaveScreenshot("ticket-table.png");
+	await page
+		.getByRole("button", { name: "Assigned to me", exact: true })
+		.click();
+	await expect(page).toHaveURL(/filter_assignee=mine/);
+	await page.getByRole("button", { name: "Saved views", exact: true }).click();
+	await expect(page.getByRole("textbox", { name: "View name" })).toBeVisible();
+	await accessible(page);
+	await expect(page.getByRole("main")).toHaveScreenshot(
+		"ticket-saved-views.png",
+	);
+});
+
+test("queued synchronization survives reload without duplicate submission", async ({
+	page,
+}) => {
+	await page.goto("/admin/import/official");
+	const requests: string[] = [];
+	page.on("request", (request) => {
+		if (request.method() === "POST" && request.url().endsWith("/sync-all"))
+			requests.push(request.postData() || "");
+	});
+	await page
+		.getByRole("button", { name: "Start synchronization", exact: true })
+		.dblclick();
+	await expect(
+		page.getByRole("status").filter({ hasText: "Synchronization saved" }),
+	).toBeVisible();
+	expect(requests).toHaveLength(1);
+	await page.reload();
+	await page.locator("details details > summary").first().click();
+	await expect(page.getByText("fixture_chair", { exact: true })).toBeVisible();
+	await accessible(page);
+	await expect(page.getByRole("main")).toHaveScreenshot("sync-history.png");
+});
+
+test("article editor fits a narrow mobile card without horizontal overflow", async ({
+	page,
+}) => {
+	await page.setViewportSize({ width: 360, height: 844 });
+	await page.goto("/admin/articles/new");
+	await expect(page.locator("iframe.tox-edit-area__iframe")).toBeVisible();
+	await expect
+		.poll(() =>
+			page
+				.locator("form")
+				.evaluate((form) => form.scrollWidth <= form.clientWidth),
+		)
+		.toBe(true);
+	await expect
+		.poll(() =>
+			page.evaluate(
+				() =>
+					document.documentElement.scrollWidth <=
+					document.documentElement.clientWidth,
+			),
+		)
+		.toBe(true);
+});