Budget v3 page + cents migration + warm shell

[raycashmore]

Summary

Implements the v3 Budget app page (KPIs, restyled chart, monthly breakdown, click-through monthly detail overlay) inside a restyled warm-bordered shared shell, with money stored as integer minor units and the seed pipeline fixed.

Three phases, 32 commits. See docs/superpowers/plans/2026-05-16-budget-page.md for the implementation plan.

Phase 0 — Foundation

• Warm token palette + DM Sans / DM Serif Display fonts in @repo/tokens.
• Restyled shared AppFrame / Sidebar / Header (cream outer page, dark #2D2D2D rounded inner shell, 96px sidebar with square tiles). Home app inherits the new look.
• Money fields migrated to integer minor units (cents/pence). Added toCents / fromCents helpers. Three rate-boundary derivations (superPensionAud, ukTotalAud, tradingInt2 * usdAud) now round to integers. Client formatCurrency takes cents.
• Seed script re-homed in packages/convex/scripts/, env-aware via .env.local, exposed as pnpm seed / pnpm seed:clear. Database reseeded from CREAM.xlsx (xlsx is gitignored).

Phase 1 — Convex queries

• getBudgetPageSummary({ period }) — four KPI values (Avg spend, Avg income, Savings rate in basis points, Net gain) with deltas vs prior period of equal length.
• getMonthlyBreakdown({ limit? }) — budget rows joined with mortgage via match-or-carry-forward.
• getMonthlyDetail({ date }) — single month's income / spend / mortgage detail for the overlay.
• Each query factored over a pure helper (summarizeBudgetForPeriod, joinBudgetWithMortgage, shapeMonthDetail) with Vitest red-green-commit. 25 unit tests in @repo/convex.

Phase 2 — Page composition

• New components: KpiCard, BudgetKpiCards, BudgetBreakdownTable, InsightsPanel (placeholder reserving the right column), MonthlyDetailOverlay (portal + scrim + Escape + focus), MonthIncomeSection, MonthSpendSection (credit-card categories stubbed; real lumped totals), MonthMortgageSection.
• Existing visx chart restyled to warm palette (peach spend bars + sage sink-or-swim bars, restyled tooltip). Period state lifted to page.
• TimePeriod widened from 1Y/3Y/5Y/ALL to 3M/6M/12M/ALL to match design.
• BudgetPage orchestrates four queries + overlay state in a two-column layout with mobile reflow.
• Browser-verified at 1440×1024, 1024×768, 390×844 against Pencil frames a6m9ik and QPjOt via Playwright MCP. Three small fixes shipped during verification (breakdown row limit honors period, overlay typography aligned to design, mobile breakdown table now horizontally scrollable).

Out of scope (explicit)

• Insights generation — right column shows placeholder.
• Mobile-specific chrome — bottom tab bar / bottom-sheet overlay deferred; mobile is responsive-only.
• Credit-card transaction categories in the overlay — stubbed with —; real lumped totals shown.
• Month-over-month trend rows on overlay mini-cards — landed separately on claude/xenodochial-curie-8a0898, not merged here. Optional follow-up.

Test Plan

• pnpm check-types — clean across all packages.
• pnpm lint — 0 errors (pre-existing any warnings in @repo/convex unchanged).
• pnpm test — 40 tests pass (25 in @repo/convex, 15 in budget).
• pnpm convex + pnpm --filter budget dev, then load http://localhost:3001/:
  • Warm shell renders (cream margin, dark rounded inner, 96px sidebar).
  • Four KPI cards show real numbers with directional delta arrows.
  • "Income vs Spending" chart renders with sage/peach bars + sage/orange MA lines + warm tooltip on hover.
  • Period filter pills (3 mo / 6 mo / 12 mo / All) change the KPI values and the breakdown row count.
  • Monthly breakdown table rows hover; clicking a row opens the overlay.
  • Overlay shows month label, three colored summary mini-cards, and three section panels (income/spend/mortgage). Escape and scrim-click close it.
  • Resize to 1024×768 — two-column layout still works.
  • Resize to 390×844 — sidebar hides, content stacks, breakdown table scrolls horizontally.

🤖 Generated with Claude Code