kvitt/PLAN-W0.md

PLAN-W0: Web foundation

Status: running since 2026-10-21 from the orchestrator's brief (written before this plan). Where the running agent's brief and this plan differ, the brief governs this run and the W0 report records the difference; the plan is what a rerun or a W0b follow-up uses.

1. Goal

Create the web client's foundation in web/ (SPEC §15, D-129 to D-134): a Vite + React 19 + TypeScript project with the design tokens, the layout shell, the router with every route, login and the token store, the API client and the household snapshot, i18n, formatting, the shared components, the money functions passing the vectors, the test setup and the web gate. After W0 lands, W1 to W5 build their pages in parallel inside their own feature folders and take everything shared from W0.

2. Read first

1. SPEC §15 (all of it), FR-21, §8.2, §8.3, §8.5 (the D-130 paragraph), §14.3.1, §14.3.2, §14.4.1 to §14.4.3, §14.4.6, §14.4.8, §9.8 Formatting, §9.6 Limits, §9.9, §13.1, §13.3 (rows S-1, S-18), §14.5.2 and §14.5.5.
2. docs/ux/design-spec.md §1, §2 (all tokens), §3.1 to §3.6 (rules, money and words, people, categories, ledger, balance), and S-1 and S-18 in §4.
3. docs/ux/strings.csv (keys and texts for the shared strings, S-1 and S-18).
4. contracts/openapi.yaml, contracts/test-vectors/{compute_split,compute_balances,propose_allocation,validate_settlement,over_settled_accounts}.json, contracts/examples/ (wire shapes).
5. docs/decisions.md D-129 to D-134, D-110, D-117, D-126.
6. CLAUDE.md (Orchestration, Anti-patterns, Execution protocols).

3. Already established

• Stack (D-131): Vite, React 19, TypeScript strict, React Router 7, TanStack Query 5, openapi-typescript into web/src/api/schema.d.ts (generated, committed) with openapi-fetch, Recharts (a dependency for W4; W0 need not use it), Vitest with Testing Library (jsdom), ESLint (flat config) and Prettier, plain CSS modules. npm with a committed package-lock.json. Each library at its latest stable version, confirmed from its official documentation or the npm registry at implementation time (CLAUDE.md "Fast-moving APIs").
• Vite base is /app/; the build output is web/dist/, which W7's Dockerfile stage copies to /app in the image (§15.4). The page references only its own files (no CDN, no web font, no external script, AC-21.12); index.html names an icon under /app/ (a browser's automatic /favicon.ico is closed by the gate from outside).
• Source layout (§15.3): web/src/app/ (entry, providers, router, shell, shortcuts), web/src/api/ (schema, client, token store, snapshot, writes), web/src/i18n/, web/src/design/ (tokens, global CSS), web/src/components/, web/src/lib/ (formatting, lib/domain/ money functions, utilities), web/src/features/<name>/. W0 owns all of it except the feature folders of W1 to W5, in which it creates only a placeholder page per route (D-004's shell rule).
• Routes (§15.3): /app/ Home (W1), /app/login (W0), /app/accounts/:id (W1), /app/expenses/new and /app/expenses/:id (W2), /app/search (W2), /app/settle (W3), /app/settlements/:id (W3), /app/analytics, /app/analytics/:groupKind/:groupId, /app/insights (W4), /app/settings/* (W5). Each feature folder exports its route element(s) from web/src/features/<name>/index.ts(x); the router imports only those exports, so a feature plan replaces its placeholder without touching web/src/app/. Sub-routes below a feature's path are the feature's own (nested <Routes> or route objects it exports).
• Login (§15.2): code field (§8.3 normalisation, groups of 4, a pasted /i/<CODE> link fills it), optional name field, E-3 with device name Web · <browser>; token in localStorage; every API call sends Authorization: Bearer, X-Kvitt-Protocol: 1, X-Kvitt-App-Version and X-Kvitt-App-Version-Name (from the build: version code git rev-list --count HEAD, name at most 32 characters, both injected by Vite at build time, fixed values in tests); a 401 clears the token and routes to /app/login (with the S-18 text for device_revoked); after a partner accept the first page is /app/settings/profile.
• Household snapshot (§15.5): pulls GET /sync from 0 in pages (limit 1000) until has_more is false, keeps rows by server_version in memory (TanStack Query cache), pulls from its cursor on window focus and after every write, drops and re-pulls on a new epoch or 409 cursor_ahead; selectors for users, accounts, categories, templates, expenses, settlements and audit entries (non-deleted and deleted). Writes: a helper for one POST /sync mutation (UUIDv7 ids, mutation_id, updated_at from the browser clock) returning accepted or rejected with the §14.4.6 reason; a helper for REST writes that applies the returned row. No persistence beyond the token and the language; no IndexedDB.
• Money (§15.3): web/src/lib/domain/ ports computeSplit, computeBalances, proposeAllocation, validateSettlement, overSettledAccounts with number öre (all values stay far inside 2^53, §9.6) and pass the five vector files through a Vitest test that reads ../contracts/test-vectors/*.json (error tokens as §14.5.3). The analytics and suggestion vectors are W4's and W2's.
• Formatting (§9.8): money (1 234,50 kr, signs and words as the app), dates, months, ISO weeks, relative time, in sv and en, with the same outputs as :core:design's formatters for the same inputs (port the tables of D-065; tests per case).
• i18n: web/src/i18n/{sv,en}.json for shared strings; each feature keeps web/src/features/<name>/i18n/{sv,en}.json, loaded by W0's loader (for example import.meta.glob) so a feature adds strings without editing W0's files; keys from docs/ux/strings.csv where the string exists there, otherwise web_ keys; named placeholders; a test fails on a key missing from either language. Language: browser preference, overridden by a stored choice (§15.3).
• Shell (§15.6): sidebar from 720 px, bottom bar under it; destinations Home, Analytics, Insights, Search, Settings; a New expense button; keyboard shortcuts N → /app/expenses/new, / → /app/search, ? → W-20 help dialog, Esc closes dialogs (none while typing in a field, except Esc); instant navigation.
• Shared components (design-spec §3 anatomy, web form): buttons, text and amount fields, select, date field, dialog with Esc, confirm dialog, segmented control, avatar (picture from E-11 as a blob: URL, initials otherwise, AC-4.5), category icon tile and colour, account chip, balance header, ledger row (expense and settlement, §9.2 effect line), month header, empty, loading and error states, snackbar/toast, page layout, and the expense editor fields of design-spec §3.7 (amount field, category grid and quick row, the four option rows, the split mode control with live shares from computeSplit), shared by W-5 (W2) and W-16 (W5) as D-019 shares them on the phone. Each with a Testing Library test.
• Design tokens (design-spec §2) as CSS custom properties for light and dark (prefers-color-scheme), system font stack, font-variant-numeric: tabular-nums for amounts, Material Symbols as bundled SVG (Apache-2.0; licence noted in the report), focus rings visible, contrast as §13.1.
• Development server: npm run dev serves /app/ and forwards API paths to the server named by an environment variable (default http://localhost:8080), documented in web/README.md.
• The web gate: npm run check = tsc --noEmit, eslint ., vitest run, vite build, and npm run gen:api followed by a check that web/src/api/schema.d.ts is unchanged. Prettier formatting is checked inside ESLint or as its own step of check.

4. Owned paths

From SPEC §14.7: web/** except web/src/features/{home,accounts,expenses,search,export,settle,analytics,settings}/** (W1 to W5), in which W0 creates only the placeholder pages and index.ts(x) exports. web/src/features/auth/** (W-1) is W0's. Nothing outside web/; W7 runs in parallel in server/**, contracts/**, .gitea/**, infra/build-images.sh, infra/dev/**.

5. Deliverables

• web/package.json (scripts dev, build, test, lint, gen:api, check), package-lock.json, vite.config.ts, tsconfig*.json, eslint.config.js, Prettier config, index.html, .gitignore (node_modules/, dist/), web/README.md (commands, dev proxy, layout, how a feature adds strings and routes).
• web/src/api/schema.d.ts generated from contracts/openapi.yaml; the client, token store, snapshot, writes; tests with a fetch stub over contracts/examples/ responses.
• web/src/lib/domain/ with the vector test; web/src/lib/format/ with tests.
• web/src/design/, web/src/components/, web/src/i18n/, web/src/app/ (router with every route, shell, shortcuts, W-20), web/src/features/auth/ (W-1), placeholder pages in the W1 to W5 folders.

6. Steps

1. Worktree. From the main checkout /Users/jhag/projects/kvitt: git worktree add .claude/worktrees/agent-w0 -b agent-w0 main, then in it git reset --hard main and tools/install-git-hooks.sh. No git-ignored files are needed.
2. Read §2 in order. Confirm SPEC v0.28 is on main (§15 exists); if not, work from the brief and say so.
3. Scaffold with the latest stable versions; record each with its source. npm audit result in the report.
4. Generated types and the freshness check; the API client, token store, snapshot and writes.
5. Money functions and the vector test; formatting.
6. Tokens, shared components, i18n, shell, router, shortcuts, login.
7. Manual check (optional, no owner data): a throwaway server from the worktree (server/README.md; a temporary KVITT_DATA_DIR, KVITT_PUBLIC_URL=http://localhost:8080, bootstrap for an admin_setup code), npm run dev, log in, see the shell and the placeholders. Never pair against the owner's development stack or the Pi.
8. Gate (§7). Commit on agent-w0, git rebase main; if contracts/openapi.yaml changed on main (W7), run npm run gen:api and commit; rerun the gate. Never merge, push or remove the worktree.

7. Gate

The web gate (SPEC §15.3, D-131), from web/: npm run check. Green means every step passed in this session; the report quotes the Vitest summary (files and tests) and the vite build size lines. Also python3 tools/contracts-check.py (unchanged contracts, 134 checks).

8. HUMAN steps

From SPEC §11.2: none.

9. Out of scope

• The pages of W1 to W5 beyond placeholders; the analytics and suggestion ports (W4, W2).
• Anything in server/**, contracts/**, infra/**, .gitea/** (W7); CLAUDE.md (the orchestrator adds the third gate).
• A service worker, a manifest, offline storage (§15.1).

10. Report

• Branch agent-w0, head commit after rebasing on main.
• Gate output lines; Vitest counts; build sizes; npm audit.
• Libraries and versions with sources; the Material Symbols package and licence.
• The module map W1 to W5 depend on: each shared module's path and exports (snapshot selectors, write helpers, components, formatters, i18n loader, route export convention), exactly as built.
• Web-only string keys added (web_…) with en and sv.
• Proposed decision entries and spec text (numbered from the brief), TODO(spec) occurrences, open questions with SPEC section numbers.
• Proposed text for CLAUDE.md "Build and verify" if it differs from SPEC §15.3.

11. Numbering

Decision ids and the spec version are assigned in the start prompt; use TODO(spec) if none was given.