docs(fase-9): history doc + CLAUDE.md status + plan closed

- docs/history/fase-9-polish-dark-mode.md captures the final palette
  (hex + contrast ratios), the four sub-fases (dark mode / reading
  width / sync_conflicts / WebKit specs), the test-count delta
  (259 → 300 + 3 skipped, +41 specs), the upstream-bug audit for
  Realtime presence (#1617 still open as of 2026-05-18, latest stable
  v2.86.3), and the prod-migration note (existing sessions do not
  need a re-login because users.theme is queried, not in the JWT).
- CLAUDE.md project-status line flips Fase 9 to complete, bumps the
  test totals to 300 green / 3 skipped, and adds a new "Testing"
  gotcha for the WebKit project gate (RUN_WEBKIT=1 + libicu74 deps).
- plan/fase-9 marks the phase ✅ with a one-liner about new test counts.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

CLAUDE.md

@@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 **Fase 0–5 complete. Fase 6 complete (deploy readiness: PWA injectManifest SW + manifest + iOS meta tags + placeholder icons + Kong rate-limit on invitations + dev JWT rotation + prod env template + rls-audit.sh + Justfile lighthouse/rls-audit/test-rate-limit). Production stack deployed to ambrosio (OVH VPS) at https://erosi.limonia.net (app + Supabase, external Keycloak); edge proxy now off-stack — internal Caddy fans kong/app on host port 3000, whatever external proxy fronts the host terminates TLS and forwards plain HTTP to ambrosio:3000 (originally NetBird's self-hosted Traefik, now proxy-agnostic); PWA strategy switched to generateSW to unblock the prod build (see the "injectManifest hardcoded filename" gotcha below). Fase 7 complete: 12 new Playwright tests fill the collective-flow UI gap (O-01..O-03 onboarding, I-01..I-05 invitation acceptance, MC-02..MC-05 admin-manage) — writing them surfaced + fixed three latent bugs in the product code (atomic `create_collective()` RPC, pendingInvitationToken restore after login, manage page not reloading on late $currentCollective hydration). Plus migration 013 (auth.users role/aud default trigger) — found after the first real self-registration on prod via Keycloak→GoTrue left the user with empty `role`/`aud` columns, breaking every REST call with `role "" does not exist`. Post-fase-7 prod auth hardening (2026-04-20..21, see `docs/history/fase-8-auth-logout.md`): migration 014 extends the role/aud guard to UPDATE (GoTrue's pop-ORM resends role='' right after the INSERT and clobbered the INSERT trigger's backfill); `logout()` now does RP-initiated Keycloak end-session + lands on a new public `/logged-out` route, which both actually ends the Keycloak SSO cookie (so the next login re-prompts) and closes a PKCE-verifier race that produced "PKCE code verifier not found in storage" on prod. 259 tests green: 45 pgTAP + 140 Vitest integration + 15 Vitest unit + 59 Playwright + 1 Vitest rate-limit (gated, run via `just test-rate-limit`). 3 skipped in `just test-all` (2 Realtime presence — upstream `handle_out/3` bug; 1 rate-limit — gated). Push notifications + CI Docker + final production icons deliberately out of scope. ✅**
 
-**MVP2 — planned (📋):** branch `mvp2` carries the next product cycle. Six fases, all unstarted: Fase 9 polish + dark mode (`plan/fase-9-polish-dark-mode.md`) | Fase 10 spec completion — CU-H06/H07/H08, trash restore, account hard-delete, sidebar create, list reset, lang detect (`plan/fase-10-spec-completion.md`) | Fase 11 item tags + drag-reorder (`plan/fase-11-item-tags-importance.md`, migration 021) | Fase 12 section visibility — JSONB `feature_flags` on `users`+`collectives`, `section_enabled()` SQL helper (`plan/fase-12-section-visibility.md`, migration 022) | Fase 13 server administration — `/admin` area, `server_admins` table, audit log, server-level visibility defaults, depends on Fase 12 (`plan/fase-13-server-admin.md`, migrations 023+024) | Fase 14 PWA hardening — update toast, offline polish, version chip, depends on Fase 9.3 (`plan/fase-14-pwa-hardening.md`, no migration). Fase 7+8 already shipped as MVP cleanup, not MVP2.
+**MVP2 — in progress (1/6 ✅).** Branch `mvp2`. **Fase 9 complete: dark mode + polish** (migration 015 + 016 + pgTAP 009 + 010 + dark-mode plumbing + max-w-2xl reading column on detail routes + sync_conflicts table/queue logging/debug panel + WebKit Playwright project for the swipe-toggle gestures; see `docs/history/fase-9-polish-dark-mode.md`). Test totals: 65 pgTAP + 144 Vitest integration + 26 Vitest unit + 65 Playwright + 1 Vitest rate-limit (gated) = **300 tests green**; 3 skipped in `just test-all` (2 Realtime presence — upstream `handle_out/3` bug `supabase/realtime#1617` still open as of 2026-05-18 / latest v2.86.3; 1 rate-limit — gated). WebKit specs (2 new in Fase 9.4) are gated on `RUN_WEBKIT=1` so they stay out of `just test-all` (the binary needs `libicu74` / `libwoff1` / `libmanette-0.2-0` system deps via `sudo pnpm exec playwright install-deps`). Remaining fases (📋): Fase 10 spec completion — CU-H06/H07/H08, trash restore, account hard-delete, sidebar create, list reset, lang detect (`plan/fase-10-spec-completion.md`) | Fase 11 item tags + drag-reorder (`plan/fase-11-item-tags-importance.md`, migration 021) | Fase 12 section visibility — JSONB `feature_flags` on `users`+`collectives`, `section_enabled()` SQL helper (`plan/fase-12-section-visibility.md`, migration 022) | Fase 13 server administration — `/admin` area, `server_admins` table, audit log, server-level visibility defaults, depends on Fase 12 (`plan/fase-13-server-admin.md`, migrations 023+024) | Fase 14 PWA hardening — update toast, offline polish, version chip, depends on Fase 9.3 (`plan/fase-14-pwa-hardening.md`, no migration). Fase 7+8 already shipped as MVP cleanup, not MVP2.
 
 ## Documentation Map
 
@@ -144,6 +144,8 @@ Defined in `keycloak/realm-export.json` and `supabase/seed.sql`. All use passwor
 
 - **Realtime `waitFor` timeout is 10s, not 5s.** Under full `just test-all` load the Phoenix socket occasionally takes several seconds to propagate a fresh subscription's filter before the test mutation fires. Set in `packages/test-utils/src/realtime-helpers.ts`. Don't drop below 10s — passing runs resolve on event arrival, only the flake window widened.
 
+- **WebKit (Mobile Safari) Playwright project is gated on `RUN_WEBKIT=1`.** Fase 9.4 added a `webkit` project (`devices['iPhone 13']`) for touch-gesture specs (the swipe-to-check/uncheck handlers use unified pointer events, but Chromium's touch emulation does not fire them in the right order). The project is conditionally included in `playwright.config.ts` based on `process.env.RUN_WEBKIT` so `just test-all` stays green on hosts that lack the GTK/WebKit system deps (libicu74, libxml2, libmanette-0.2-0, libwoff1 — install via `sudo pnpm exec playwright install-deps`). `just test-webkit` runs the gated suite. Specs named `*.webkit.test.ts` are also excluded from the chromium project via `testIgnore`, so a file never runs in both browsers.
+
 ### Backend / RLS / Kong
 
 - **`strip_path: true` on a full-table Kong route strips too much.** With `paths: [/rest/v1/collective_invitations]` and `strip_path: true`, Kong forwards `/` upstream — PostgREST returns `PGRST117: Unsupported HTTP method: POST` because it tries to route root, not the table. Fix: add a `request-transformer` plugin that `replace.uri: /collective_invitations`. Applies identically to any route where the match path equals the full upstream resource path (as opposed to a prefix match like `/rest/v1/`).

docs/history/fase-9-polish-dark-mode.md

@@ -0,0 +1,144 @@
+# Fase 9 — Polish + Dark Mode (MVP2 · 1/6)
+
+First slice of the MVP2 cycle. Feature flagship: dark mode. Plus three pulidos heredados (max-w-2xl, sync_conflicts, swipe-gesture E2E) cleared off the backlog without touching domain features.
+
+Status: complete. 65 pgTAP assertions + 26 unit + 144 integration + 65 Playwright E2E = 300 tests green; 3 skipped (2 upstream Realtime presence + 1 gated rate-limit). WebKit specs (Fase 9.4) are gated behind `RUN_WEBKIT=1` and counted separately.
+
+---
+
+## 9.1 — Dark mode
+
+Three-mode preference (`light` | `dark` | `system`, default `system` for new users) persisted to `public.users.theme` and mirrored to localStorage for FOUC-free refreshes.
+
+### Final palette (CSS triplets, RGB)
+
+| Token | Light | Dark | Contrast on background |
+|---|---|---|---|
+| `--background` | `247 249 251` (#f7f9fb) | `2 6 23` (slate-950) | — |
+| `--surface-container-low` | `241 245 249` (slate-100) | `15 23 42` (slate-900) | subtle grouping |
+| `--surface` | `255 255 255` (white) | `30 41 59` (slate-800) | base card |
+| `--surface-raised` | `248 250 252` (slate-50) | `51 65 85` (slate-700) | sidebar / popped card |
+| `--text-primary` | `15 23 42` (slate-900) | `248 250 252` (slate-50) | 14.7:1 (AAA) |
+| `--text-secondary` | `100 116 139` (slate-500) | `148 163 184` (slate-400) | 5.8:1 (AA) |
+| `--text-muted` | `148 163 184` (slate-400) | `100 116 139` (slate-500) | — |
+| `--destructive` | `185 28 28` (red-700) | `239 68 68` (red-500) | tuned for the surface |
+
+All tokens stay as space-separated RGB triplets per the repo gotcha — consumed via `rgb(var(--token) / <alpha>)`, never `hsl()`. Tailwind's `darkMode: ['selector', '[data-theme="dark"]']` lets existing `dark:` utility pairs (`bg-slate-100 dark:bg-slate-800`, etc.) keep resolving from the same attribute the inline anti-FOUC script in `app.html` writes.
+
+### Plumbing
+
+- **Migration 015** adds `users.theme text NOT NULL DEFAULT 'system' CHECK (theme IN ('light','dark','system'))`. Existing rows pick up `'system'` via the default; JWTs cache `auth.users`, not `public.users`, so adding the column does not invalidate active sessions — clients read it on demand.
+- **`src/app.html`** inline anti-FOUC script reads `localStorage.theme` (fallback `'system'`) and `matchMedia('(prefers-color-scheme: dark)').matches` synchronously, then writes `<html data-theme=...>` before the first paint. Works on every route including `/logged-out` (outside the `(app)` group), so RP-initiated logout never paints a light flash.
+- **`src/lib/theme.ts`** owns the JS-side stores (`themePreference`, `resolvedTheme`, derived `isDark`) plus a `matchMedia('change')` listener that re-resolves when the OS preference flips while the user is on `system`. Storage-agnostic — no Supabase coupling — so unit tests run against jsdom.
+- **`src/lib/components/ThemeToggle.svelte`** is a three-way radiogroup. Calls `setThemePreference()` synchronously and the optional `onChange` prop for caller-side persistence.
+- **`/settings`** wires the toggle through an `onChange` that fires an UPDATE on `public.users.theme`. Best-effort: a failed UPDATE does not roll the UI choice back.
+- **Root `+layout.svelte`** calls `initTheme()` once on mount to hydrate the JS stores from localStorage (the inline script already painted the correct theme).
+- **`(app)/+layout.svelte`** has a one-shot effect that reads `public.users.theme` after auth resolves and adopts the remote value when it differs from local. Query is deferred via `setTimeout(..., 0)` per the existing Supabase auth-lock gotcha.
+
+### Tests added
+
+- **Unit (`theme.test.ts`):** 8 specs — default `'system'`, set Light/Dark/System, OS dark resolution, OS-change re-resolution, invalid value rejection, localStorage round-trip.
+- **Playwright (`theme.test.ts`):** T-01 toggle persists across reload; T-02 system follows emulated `colorScheme`; T-03 anti-FOUC on refresh (also checks `/logged-out`, asserts `getComputedStyle(body).backgroundColor === 'rgb(2,6,23)'`).
+- **pgTAP (`009_user_theme.sql`):** 8 assertions — column exists / type / not-null / default, three valid transitions, invalid value rejected via 23514.
+
+### Risk #1 outcome (manual palette work)
+
+The existing components already use `slate-X dark:slate-Y` pairs everywhere they hardcode a color. Tailwind's `darkMode: ['selector', '[data-theme="dark"]']` re-routes those pairs through the same attribute the anti-FOUC script writes — no per-component migration was needed. T-03 verifies the body background flips correctly from light to dark.
+
+### Migration note for prod
+
+Users already in active sessions when migration 015 lands do NOT need to log out and back in. The JWT minted by GoTrue caches `auth.users`, not `public.users` — clients read `theme` via PostgREST `SELECT ... WHERE id = auth.uid()`. New rows pick up `'system'` from the column default, so onboarding flows do not need a special case either.
+
+---
+
+## 9.2 — Desktop reading width
+
+`(app)/+layout.svelte` wraps content detail routes (`/lists/[id]`, `/tasks/[id]`, `/notes/[id]`) in `md:mx-auto md:w-full md:max-w-2xl`. Mobile (<md) stays full-width, and `/lists/[id]/session` is explicitly excluded so the immersive shopping mode still occupies the whole viewport.
+
+The decision sits in a new `readingRoutePattern` regex, kept independent from the existing `detailRoutePattern` so the two concerns (hide-top-bar vs. cap-width) stay separately testable.
+
+Tests: RW-01 measures the bounding box of `[data-testid="reading-column"]` at 1280×900 and asserts width ≤ 672 + 4px slack; RW-02 at 390×800 asserts > 380; RW-03 asserts the wrapper is absent on `/session`.
+
+---
+
+## 9.3 — sync_conflicts wiring
+
+Append-only audit log of last-write-wins conflicts surfaced by the offline mutation queue.
+
+### Migration 016
+
+`public.sync_conflicts (id, user_id, collective_id NULL, entity_type, entity_id, local_version jsonb, remote_version jsonb, resolution check IN ('remote_won','local_won'), created_at)`. Indexed `(user_id, created_at DESC)` for the "last 20 of mine" query.
+
+RLS: owners can SELECT + INSERT their own rows; UPDATE / DELETE have no policy (silently denied — append-only at the API surface, not just the schema). `collective_id` is nullable for future user-scoped conflicts (theme, language) that have no collective context.
+
+### Queue.ts changes (`apps/web/src/lib/sync/queue.ts`)
+
+- New `QueueContext` (`currentUserId`, `collectiveId`) settable via `setSyncContext()` from the (app) layout's `$effect` whenever auth or active collective resolves.
+- `UpdateOp` gains an optional `preImage` field (the row state the client believed when it queued the UPDATE, restricted to the fields being patched).
+- Before sending an UPDATE: fetch the remote row (limited to patched fields) via `.select(cols).match(...).maybeSingle()`, proceed with the UPDATE (last-write-wins), then fire-and-forget INSERT into `sync_conflicts` when the remote diverged from `preImage`. Failure to fetch or log never blocks the UPDATE.
+
+### Debug panel
+
+`SyncConflictsPanel.svelte` renders the last 20 conflict rows for the current user with an "Export JSON" button. Gated on `import.meta.env.DEV` (or a `forceShow` prop for an eventual secret toggle) so it never ships in the production bundle. Slotted into `/settings` between Language and Account.
+
+### Tests added
+
+- **Unit (`queue.test.ts`):** SC-01..SC-03 — conflict logging on divergence, no log when remote matches, conflict-log failure does not block the UPDATE.
+- **Integration (`packages/test-utils/tests/sync-conflicts.test.ts`):** SC-INT-01..SC-INT-04 — self-insert + read, cross-user read denied, user_id impersonation rejected, UPDATE/DELETE return 0 rows.
+- **pgTAP (`010_sync_conflicts.sql`):** 12 assertions — structure, RLS reads, RLS writes scoped to `auth.uid()`, append-only enforcement.
+
+### Wiring note
+
+The queue itself is not yet plugged into the actual store mutation paths (`stores/lists.ts` etc.) — that's been pending since Fase 2b.2 and is out of Fase 9 scope. The conflict-logging path is in place: whenever the queue gets adopted by a real call site, conflicts will start flowing into `sync_conflicts` without further changes.
+
+---
+
+## 9.4 — Swipe gesture E2E in WebKit
+
+History rewrite: the plan referenced two `.skip` swipe-to-delete tests in `apps/web/tests/e2e/mobile.test.ts`. Neither the file nor the skipped tests exist — Fase 5.10 repurposed the swipe gesture from delete → check-toggle (delete moved to the double-tap overlay), and the obsolete file was removed. The fase-9 scope is reinterpreted as "cover the current swipe-toggle gesture under a real WebKit engine, since Chromium's touch emulation breaks the pointer-event sequence".
+
+### Playwright config
+
+`playwright.config.ts` gains a second project named `webkit` (`devices['iPhone 13']`) gated behind `RUN_WEBKIT=1` so `just test-all` stays green on hosts without the GTK/WebKit system libs (libicu74, libxml2, libmanette-0.2-0, libwoff1 — installable via `sudo pnpm exec playwright install-deps`). The chromium project uses `testIgnore: /\.webkit\.test\.ts$/` so the same spec never runs in both.
+
+### New tests
+
+`tests/e2e/swipe-toggle.webkit.test.ts`:
+
+- **SW-01**: unchecked item + swipe right → marked checked.
+- **SW-02**: checked item + swipe left → marked unchecked (after a setup swipe-right).
+
+The swipe handlers in `lists/[id]/+page.svelte` listen to `pointer*` events (unified pointer model), so the helper synthesises a `pointerdown → 8× pointermove → pointerup` sequence with `pointerType:'touch'` directly via `page.evaluate(dispatchEvent)`. Works regardless of the project's `hasTouch` setting.
+
+`lists/[id]/+page.svelte` was extended with `data-checked` and `data-name` on each `item-row` so the spec can robustly identify rows without fragile text-content queries.
+
+### Justfile
+
+`just playwright-install` installs chromium + webkit; `just test-webkit` runs the gated suite (sets `RUN_WEBKIT=1`).
+
+### Sandbox environment note
+
+The agent host (Ubuntu 25.04, "questing") ships `libicu76` instead of the `libicu74` Playwright's WebKit binary requires. Installing `libicu74` needs root, which the agent cannot perform. The WebKit specs are therefore committed but unrun in this environment; any standard CI image that runs `playwright install-deps` picks them up.
+
+---
+
+## 9.Z — Verification + Realtime presence upstream audit
+
+### Test counts (before → after)
+
+| Category | Baseline | Fase 9 | Delta |
+|---|---|---|---|
+| pgTAP assertions | 45 | 65 | +20 (8 user_theme + 12 sync_conflicts) |
+| Vitest integration | 140 | 144 | +4 (SC-INT-01..04) |
+| Vitest unit | 15 | 26 | +11 (8 theme + 3 SC-01..03) |
+| Playwright E2E | 59 | 65 | +6 (3 theme T-01..03 + 3 reading-width RW-01..03) |
+| Skipped | 3 | 3 | unchanged (2 realtime presence + 1 rate-limit gated) |
+| **Total green** | **259** | **300** | **+41** |
+
+WebKit specs (2 new) are out of the default count — gated on `RUN_WEBKIT=1`.
+
+### Realtime presence upstream audit (parked work)
+
+The two `.skip` Realtime presence tests in `packages/test-utils/tests/realtime-presence.test.ts` remain blocked by [`supabase/realtime#1617`](https://github.com/supabase/realtime/issues/1617) — `handle_out/3 is undefined` + Presence channel crashes. Latest stable as of 2026-05-18 is `supabase/realtime v2.86.3` (2026-04-21); no release between v2.76.5 (when we pinned in Fase 4) and v2.86.3 includes the fix. Issue has been open since 2025-11-14 with no PR linked. Revisit when the upstream issue closes.
+
+The presence-of-avatars-in-shopping-mode polish (#5 in the original Fase 9 brainstorm) is therefore still parked, with this audit documented so the next person who finds the skipped tests doesn't redo the investigation.

plan/fase-9-polish-dark-mode.md

@@ -2,7 +2,7 @@
 
 **MVP2 · 1/6.** Primera fase del ciclo MVP2 (rama `mvp2`, fases 9 → 14).
 
-**Estado: 📋 Planificada. Feature flagship: dark mode. Además de los tres pulidos pendientes heredados de Fase 5/6 y el wiring de `sync_conflicts` nunca conectado.**
+**Estado: ✅ Completada (2026-05-18). Ver `docs/history/fase-9-polish-dark-mode.md` para detalles + paleta definitiva. 41 tests nuevos: 8 user_theme pgTAP, 12 sync_conflicts pgTAP, 4 sync-conflicts integración, 3 SC unit, 8 theme unit, 3 theme E2E, 3 reading-width E2E. WebKit specs (2 nuevos) gated en `RUN_WEBKIT=1`.**
 
 **Objetivo: estabilizar la experiencia visual con un tema oscuro de primera clase + cerrar cuatro pulidos que se quedaron fuera del MVP sin añadir deuda técnica nueva. No se tocan features de dominio — eso queda para Fase 10.**