Recorded on 30 October 2026, unchanged since

{
  "ai": {
    "apps": [
      "Claude"
    ],
    "models": [
      "Claude Opus 5.5"
    ]
  },
  "article": "how-to-build-a-finance-dashboard-where-every-number-agrees-one-seeded-book-l",
  "author": {
    "account": "a_9d470b566acab5f65bdc"
  },
  "body": "## What it is\n\nMeridian is an enterprise finance dashboard template for Next.js and shadcn/ui: cash flow, net worth, transactions, budgets, accounts and cards, five kinds of investments, insurance and loans, and a full invoicing suite, in 22 screens with light and dark themes and a theme customizer. Every name, company and figure is invented, and all of it is computed from one seeded book, so the KPIs, the charts and the tables agree, while the investment pages tick live prices. It ships as a release ZIP (1.0.0, MIT), and you can try it at [meridian.upfork.dev](https://meridian.upfork.dev).\n\nWhat you'll learn here, with the real code: how to generate a mock book that stays consistent and derive every figure from it; how to put TanStack Query in front of it so a real API can replace it later; how to tick live prices cheaply inside a bounded walk; how to format, prefetch and load a dashboard whose every route is dynamic; how to measure a palette's contrast instead of eyeballing it; and how to test all of it. Meridian was built from 28 to 30 October 2026 in nine orchestrated phases, each by its own Claude session, with a build log and a lessons file kept as it went. Each lesson sits where it happened; the ones from setting up the toolchain and shipping the release are in a [companion article](https://upfork.dev/articles/setting-up-and-shipping-a-next-js-16-template-17-traps-with-shadcn-ui-eslint).\n\n![Meridian's Finance overview in light: insight cards, the KPI strip, revenue by stream and the report summary](/article-images/01a18e3a-0cfc-7b50-937d-bd5f43fcf5de)\n\n## The stack, and what October 2026's versions needed\n\nThe brief asked for the latest stable version of everything. What Meridian runs on:\n\n| Package | Version |\n| --- | --- |\n| next / react | 16.4.3 / 19.3.1 |\n| typescript | ~6.0.3 (7.0 is outside typescript-eslint's range) |\n| tailwindcss | 4.3.3 |\n| shadcn (CLI) / radix-ui | 4.23.0, style new-york / 1.8.1 |\n| recharts | 3.10.1 |\n| @tanstack/react-table / @tanstack/react-query | 8.21.3 / 5.105.0 |\n| nuqs | 2.10.2 |\n| react-hook-form / zod | 7.91.0 / 4.6.7 |\n| cmdk / vaul / sonner | 1.1.1 / 1.1.2 / 2.0.8 |\n| eslint / eslint-config-next | 10.13.0 / 16.4.3 |\n| @playwright/test / @axe-core/playwright | 1.64.1 / 4.14.0 |\n| pnpm / Node | 12.8.1 / 22.23.1 |\n\nTwo choices from setting that up matter below: shadcn primitives that Meridian edited carry a comment starting `Meridian:`, and the chart, form, table and checkbox primitives were written from the registry's JSON, because `chart.json` pins recharts@3.8.0 and the project has 3.10.1.\n\n## One seeded book\n\nEverything on screen comes from one in-memory book per entity: Holdings, Europe and Capital. Holdings carries the figures the design brief set; Europe (in euros, at 0.42 of Holdings' amounts) and Capital (in dollars, at 0.64) are smaller books with their own accounts, institutions, record numbers and noise. Each entity reports in its own base currency, with no FX conversion anywhere. The book is built from a fixed seed, with every date relative to today, so the demo never goes stale and looks the same on every machine and in every screenshot.\n\n### Seeded randomness, and money in cents\n\nFrom `src/lib/data/seed.ts`: mulberry32 for the numbers, and FNV-1a over the parts of a name, so each purpose gets its own stream (`createRng(\"ledger\", \"holdings\", 3)`). The builders get `ctx.rng(...parts)`, which prefixes the entity.\n\n```ts\nexport function mulberry32(seed: number) {\n  let state = seed >>> 0\n  return () => {\n    state = (state + 0x6d2b79f5) >>> 0\n    let t = state\n    t = Math.imul(t ^ (t >>> 15), t | 1)\n    t ^= t + Math.imul(t ^ (t >>> 7), t | 61)\n    return ((t ^ (t >>> 14)) >>> 0) / 4294967296\n  }\n}\n\n/** FNV-1a over the parts, so `createRng(\"ledger\", \"holdings\", 3)` is its own stream. */\nexport function hashSeed(...parts: (string | number)[]) {\n  let hash = 0x811c9dc5\n  for (const char of parts.join(\"|\")) {\n    hash ^= char.charCodeAt(0)\n    hash = Math.imul(hash, 0x01000193)\n  }\n  return hash >>> 0\n}\n```\n\nEvery total is a sum of parts, so sums are done in integer cents (`sumMoney`), and `splitMoney` hands the rounding remainder to the largest part, so the parts always add back to the total:\n\n```ts\n/**\n * Splits `total` into parts proportional to `weights`, in cents, so the parts add up to `total` exactly (the\n * rounding remainder goes to the largest part).\n */\nexport function splitMoney(total: number, weights: readonly number[]): number[] {\n  const totalCents = toCents(total)\n  const weightSum = weights.reduce((sum, weight) => sum + weight, 0) || 1\n  const cents = weights.map((weight) => Math.floor((totalCents * weight) / weightSum))\n  const remainder = totalCents - cents.reduce((sum, value) => sum + value, 0)\n  const largest = weights.indexOf(Math.max(...weights))\n  cents[largest] += remainder\n  return cents.map(fromCents)\n}\n```\n\n### The ledger is generated from the other records\n\nThe ledger is 25 months of every movement, and it is built *from* the other records rather than beside them: bills, payroll and its funding transfer, loan instalments, insurance premiums, subscriptions, invoice payments, dividends, goal contributions, card statements and surplus sweeps, plus seeded day-to-day activity. So a loan's instalments are in the ledger because the loan exists, and the invoice list's payments are the ledger's client receipts.\n\nThen one balancing row per month (a consulting payment and a wholesale order) steers income and expenses to that month's target. For the current month the target is pro-rated by the day, `fraction = min(1, day / 28)`. From `src/lib/data/build/ledger.ts`:\n\n```ts\n// Balancing rows: one consulting payment and one vendor purchase make the month land on its targets.\nconst [incomeTarget, expenseTarget] = monthTargets(k, ctx, fraction)\nconst inMonth = drafts.filter((row) => row.date >= month && row.date <= on(31) && row.status !== \"failed\")\nconst income = sumBy(inMonth.filter((row) => categoryById(row.categoryId).group === \"income\"), (row) => row.amount)\nconst expense = -sumBy(inMonth.filter((row) => categoryById(row.categoryId).group === \"expense\"), (row) => row.amount)\nconst client = inputs.clients[rng.int(0, inputs.clients.length - 1)]\n// Never let a balancing row turn into its opposite: early in a month the fixed bills alone pass the pro-rated\n// target, and older months' targets are only a trend. (On the reference day both rows sit far above the floor.)\nconst floor = ctx.amount(rng.between(450, 1200))\nconst incomeGap = Math.max(incomeTarget - income, floor)\nconst expenseGap = Math.max(expenseTarget - expense, floor)\nadd({ date: on(Math.min(18, maxDay)), time: \"15:45\", merchant: client.name, description: \"Project milestone\", categoryId: \"consulting-projects\", amount: money(incomeGap), accountId: acc(\"checking\"), method: \"Bank transfer\", status: \"completed\" })\nadd({ date: on(Math.min(19, maxDay)), time: \"10:30\", merchant: rng.pick(vendors[ctx.entityId]), description: \"Wholesale order\", categoryId: \"vendor-purchases\", amount: -money(expenseGap), accountId: acc(\"checking\"), method: \"Bank transfer\", status: \"completed\" })\n```\n\n```ts\n/** Income and expense targets of the month `k` months ago (excluding transfers), scaled to the entity. */\nfunction monthTargets(k: number, ctx: BuildContext, fraction: number): [number, number] {\n  const s = ctx.profile.scale\n  if (k === 0) return [money(34_600 * s * fraction), money(26_180 * s * fraction)]\n  if (k === 1) return [money(30_838 * s), money(28_581 * s)]\n  const rng = ctx.rng(\"targets\", k)\n  const income = 32_600 * (1 - 0.006 * (k - 2)) * rng.between(0.93, 1.07)\n  const expense = 26_300 * (1 - 0.004 * (k - 2)) * rng.between(0.94, 1.06)\n  return [money(income * s), money(expense * s)]\n}\n```\n\nThe floor is there because of a test run on a February day: early in a month the fixed bills alone pass the pro-rated target, and the \"wholesale order\" turned into its opposite, money coming in. The unit tests now assert that income rows are inflows and expense rows outflows on three dates for every entity.\n\nThe ledger is the one costly collection (2,151 rows for Holdings when first measured, built in 234 ms in Node on a quiet machine), so `src/lib/data/workspace.ts` builds it on first read. `getEntityData` caches one book per entity per day, keyed `entity|day`, and mutations change that cached book in place.\n\n```ts\n// The ledger is the one costly collection (≈2,000 rows): built on first read, so views that only need records\n// (another entity's approvals in the notification centre) never pay for it.\nlet ledger: Transaction[] | null = null\nreturn {\n  entityId,\n  currency: ctx.currency,\n  today,\n  now,\n  institutions: buildInstitutions(ctx),\n  accounts,\n  cards,\n  get transactions() {\n    ledger ??= buildLedger(ctx, { accounts, cards, loans, policies, invoices, clients, subscriptions, bills, goals, equities })\n    return ledger\n  },\n```\n\n### Every figure is a selector\n\nNo KPI is typed in. `src/lib/data/selectors/*` derive each one from the records: cash totals, flows by week, month and year, budget pace, loan schedules, positions, net worth, invoice balances. An account's balance history is computed backwards from today's balance through the ledger, so the chart always ends on the balance shown beside it. From `src/lib/data/selectors/spending.ts`:\n\n```ts\n/**\n * An account's end-of-day balance for each of the last `days` days, oldest first: today's balance minus everything\n * booked since (the history is derived from the ledger, so it always ends on the balance shown).\n */\nexport function balanceHistory(data: EntityData, accountId: string, days = 30): { date: ISODay; balance: number }[] {\n  const account = data.accounts.find((candidate) => candidate.id === accountId)\n  if (!account) return []\n  const rows = data.transactions.filter((row) => row.accountId === accountId && counts(row))\n  const points: { date: ISODay; balance: number }[] = []\n  let balance = account.balance\n  for (let offset = 0; offset < days; offset++) {\n    const date = addDays(data.today, -offset)\n    points.push({ date, balance })\n    balance = sumMoney([balance, ...rows.filter((row) => row.date === date).map((row) => -row.amount)])\n  }\n  return points.reverse()\n}\n```\n\nNet worth is assets minus liabilities, each part taken from its own page's records: the accounts, the four investment books, the loans, the credit cards and anything added by hand.\n\nWhere the brief's own figures contradicted each other, the more specific page won and the summaries followed. On 28 October Holdings shows exactly the brief's income of $34,600 and expenses of $26,180 for the month, and invoice #5099 is $3,120 + Tax (15%) $468 = $3,588. But net worth is $857,213, not the brief's $787,079 (which left a frozen reserve account out of the assets); loans outstanding are $326,010, amortised from the brief's own instalments, rates and terms; and runway is 7.9 months, liquid cash over the average monthly expenses of the last six months. One ledger can't satisfy figures that contradict each other, so the specific pages keep theirs and the roll-ups are whatever the records add up to.\n\n### Mutations move the balances\n\n`src/lib/data/store.ts` exports `dataActions`, every change the UI can make: add a transaction, freeze a card, pay an EMI, record an invoice payment, buy or sell a holding. Each returns an undo for the toast, and every payment is booked through `addTransaction`, which adds the row, re-sorts the ledger and moves the balances, so cash flow, the accounts, the transactions table and net worth move together. A premium carries its `policyId`, an EMI its `loanId`, a client payment its `invoiceId` and a trade its `holdingId`.\n\n```ts\n/**\n * Keeps today's balances true to the ledger when a row is booked or taken back (`direction` −1): an account moves by\n * the amount, a credit card's balance owed by its opposite, a debit card's linked account by the amount. Failed rows\n * never moved money. Balance histories are derived backwards from today's balance, so they stay consistent too.\n */\nfunction moveBalances(entityId: EntityId, row: Transaction, direction: 1 | -1) {\n  if (row.status === \"failed\") return\n  const data = getEntityData(entityId)\n  const delta = row.amount * direction\n  const account = data.accounts.find((candidate) => candidate.id === row.accountId)\n  if (account) {\n    account.balance = cents(account.balance + delta)\n    return\n  }\n  const card = data.cards.find((candidate) => candidate.id === row.accountId)\n  if (!card) return\n  if (card.type === \"credit\") {\n    card.balance = cents((card.balance ?? 0) - delta)\n    return\n  }\n  const linked = data.accounts.find((candidate) => candidate.id === card.linkedAccountId)\n  if (linked) linked.balance = cents(linked.balance + delta)\n}\n```\n\n### Pinned by the unit tests\n\n`tests/unit/data.spec.ts` pins two things: the brief's figures for Holdings on the reference day, and invariants for all three entities on three days (the reference day, an early-month day and a February day): the book is deterministic, totals equal the sum of their parts, every balance history ends on its balance, shares add to 100 ± 0.1, upcoming lists are sorted and in the future, invoice lines are hours × rate. The start of it:\n\n```ts\nfor (const entityId of entityIds) {\n  for (const day of [REFERENCE, new Date(\"2026-11-03T15:00:00Z\"), new Date(\"2027-02-14T15:00:00Z\")]) {\n    test(`${entityId} on ${day.toISOString().slice(0, 10)}: totals reconcile, lists are sorted, nothing upcoming is past`, () => {\n      const data = buildEntityData(entityId, day)\n\n      // deterministic\n      expect(JSON.stringify(buildEntityData(entityId, day).transactions)).toBe(JSON.stringify(data.transactions))\n\n      // ledger: sorted oldest → newest, never in the future, every group matches its category\n      const keys = data.transactions.map((row) => row.date + row.time)\n      expect(keys).toEqual([...keys].sort())\n      expect(data.transactions.every((row) => row.date <= data.today)).toBe(true)\n      expect(data.transactions.every((row) => row.group === categoryById(row.categoryId).group)).toBe(true)\n      // income rows are inflows, expense rows outflows (the balancing rows never flip sign)\n      expect(data.transactions.filter((row) => row.group === \"income\").every((row) => row.amount > 0)).toBe(true)\n      expect(data.transactions.filter((row) => row.group === \"expense\").every((row) => row.amount < 0)).toBe(true)\n```\n\n## The data layer: TanStack Query over the book\n\nThe pages never read the book directly. They use hooks (`useTransactions()`, `useLoansPage()` and so on) built on one function, `useEntityQuery`, which answers from the book after a simulated 250–600 ms, so the loading skeletons are real. The key is `[\"workspace\", entity, domain, ...params]`: every entity and filter caches apart, and any mutation invalidates them all. From `src/lib/queries/client.tsx`:\n\n```tsx\nconst fast = process.env.NEXT_PUBLIC_DEMO_FAST === \"1\"\n\n/** Simulated network latency, 250–600ms. */\nexport function latency() {\n  if (fast) return Promise.resolve()\n  return new Promise<void>((resolve) => setTimeout(resolve, 250 + Math.random() * 350))\n}\n\nexport async function fetchFromBook<T>(entityId: EntityData[\"entityId\"], select: (data: EntityData) => T): Promise<T> {\n  await latency()\n  return select(getEntityData(entityId))\n}\n\n/**\n * A query over the selected entity's book (`?entity=`). The key is [\"workspace\", entity, domain, ...params], so each\n * entity and filter caches separately and a mutation invalidates them all.\n */\nexport function useEntityQuery<T>(\n  domain: string,\n  params: readonly unknown[],\n  select: (data: EntityData) => T,\n  options: Omit<UseQueryOptions<T>, \"queryKey\" | \"queryFn\"> = {},\n) {\n  const { entityId } = useWorkspace()\n  return useQuery<T>({\n    queryKey: [queryRoot, entityId, domain, ...params],\n    queryFn: () => fetchFromBook(entityId, select),\n    // A new period, range or bucket keeps the figures on screen until the new ones arrive (§7.5: charts change without\n    // re-drawing from a skeleton). A new entity doesn't: its book is in another currency, so it shows its skeletons.\n    placeholderData: (previous, previousQuery) => (previousQuery?.queryKey[1] === entityId ? previous : undefined),\n    ...options,\n  })\n}\n```\n\n`placeholderData` keeps the old figures on screen while a new period loads, so charts change without going back to a skeleton; a new entity is in another currency, so it shows its skeletons instead. Each hook is a selector passed to that function: `useTransactions(filters)` filters the ledger by the period and the filters and returns it newest first.\n\nTo connect a real API, replace `fetchFromBook` with a fetch to your backend and point each `dataActions` call at a mutation: the hooks, the query keys and the pages stay as they are.\n\n### The period and the entity live in the URL\n\n`useWorkspace()` (src/hooks/use-workspace.ts) reads the global period, the custom range, the entity and the currency from the query string through nuqs, so a link or a reload keeps them, and defaults stay out of the URL. Every comparison uses the same days of the period before: a month so far is compared with the same days of the month before, so on 28 October expenses read −7.4% \"vs Sep 1–28\" (against the whole of September they would read −8.4%, and look like a collapse early in any month). From `src/lib/data/dates.ts`:\n\n```ts\nexport function previousRange(range: DayRange): DayRange {\n  const shift = comparisonShift(range)\n  if (shift.whole) return { from: addMonths(range.from, -shift.months), to: addDays(range.from, -1) }\n  if (shift.months) return { from: addMonths(range.from, -shift.months), to: addMonths(range.to, -shift.months) }\n  const length = diffDays(range.to, range.from) + 1\n  return { from: addDays(range.from, -length), to: addDays(range.from, -1) }\n}\n```\n\n:::lesson{title=\"nuqs parseAsIsoDate stores react-day-picker's local-midnight dates a day early anywhere east of UTC\" kind=\"not-in-docs\" by=\"ai\" packages=\"nuqs@2.10.2, react-day-picker@10.0.2, next@16.4.3\"}\n**Rule:** If a date range picked in react-day-picker lands in the URL one day early (Oct 1 → 2026-09-30) through nuqs parseAsIsoDate, use a createParser that reads and writes the local calendar day.\n**Snippet:**\n```ts\nexport const parseAsCalendarDate = createParser<Date>({\n  parse: (value) => {\n    const match = /^(\\d{4})-(\\d{2})-(\\d{2})$/.exec(value)\n    return match ? new Date(Number(match[1]), Number(match[2]) - 1, Number(match[3])) : null\n  },\n  serialize: (date) =>\n    `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, \"0\")}-${String(date.getDate()).padStart(2, \"0\")}`,\n  eq: (a, b) => a.getTime() === b.getTime(),\n})\n```\n**Check:** Playwright \"a custom period is stored as the calendar days picked, in any time zone\" clicks the 1st and 15th of the current month in the range calendar and expects `from=2026-10-01&to=2026-10-15` in the URL → passed (Chrome at UTC+3:30).\n**Applies to:** nuqs@>=2.10 <3, react-day-picker@>=10 <11\n**I assumed:** parseAsIsoDate round-trips a calendar day (\"2026-10-01\") for any Date the picker returns.\n**What happened:** probe on a machine at UTC+3:30 (Chrome 156): `parseAsIsoDate.serialize(new Date(2026, 9, 1))` → `2026-09-30`, while `parseAsIsoDate.parse(\"2026-10-01\")` gives local Oct 1. A custom period Oct 1 – Oct 15 would have been stored as `from=2026-09-30&to=2026-10-14`.\n**Why:** serialize uses `toISOString().slice(0, 10)` (UTC), and react-day-picker hands back local midnight, which is the previous UTC day east of Greenwich (west of it, parse shows the previous day instead).\n**The fix:** `parseAsCalendarDate` (snippet) in src/hooks/use-workspace.ts for `?from=` and `?to=`.\n**Evidence:** probe output above, 2026-10-28; tests/e2e/shell.spec.ts.\n:::\n\n### One DataTable\n\nEvery table in Meridian is one component on TanStack Table v8 (src/components/data-table/data-table.tsx): saved views with counts, debounced search, faceted filters, multi-column sorting with `aria-sort`, column visibility, density, row selection with an indeterminate header and a floating bulk bar, a sticky header and first column, clickable rows, phone cards, and CSV export of the filtered rows, from its toolbar or from the command palette's \"Export current table\" event (the first table that hears it answers):\n\n```tsx\nconst exportCsv = React.useCallback(() => {\n  // Filtered and sorted, before pagination: every matching row, in the order on screen. (Not\n  // getSortedRowModel().rows filtered by identity: the sorted model holds shallow copies of the rows.)\n  const sorted = table.getPrePaginationRowModel().rows\n  downloadCsv(\n    csvFileName(title, workspaceDay(today())),\n    exportColumns.map((column) => column.columnDef.meta?.label ?? column.id),\n    sorted.map((row) => exportColumns.map((column) => cellValue(row, column.id))),\n  )\n  toast(`Exported ${formatNumber(sorted.length)} ${sorted.length === 1 ? \"row\" : \"rows\"}`, { description: `${title} as CSV` })\n}, [table, title, exportColumns])\n```\n\n:::lesson{title=\"TanStack Table v8's getSortedRowModel() holds copies of the rows: an identity filter on the filtered rows finds none\" kind=\"not-in-docs\" by=\"ai\" packages=\"@tanstack/react-table@8.21.3, @tanstack/table-core@8.21.3, react@19.3.1\"}\n**Rule:** If a list built from getSortedRowModel().rows.filter(row => filtered.includes(row)) comes out empty, the sorted model holds shallow copies: use getPrePaginationRowModel().rows (filtered + sorted).\n**Snippet:**\n```ts\n- const filtered = table.getFilteredRowModel().rows\n- const rows = table.getSortedRowModel().rows.filter((row) => filtered.includes(row)) // always []\n+ const rows = table.getPrePaginationRowModel().rows // filtered and sorted, every page\n```\n**Check:** the same test → passed; the downloaded `transactions-2026-10-28.csv` has the header `Date,Merchant,Group,Category,Account,Amount,Status` and only Income rows while the Income view is active.\n**Applies to:** @tanstack/react-table@>=8 <9, @tanstack/table-core@>=8 <9\n**I assumed:** the row models are views over the same Row objects, so the sorted rows can be intersected with the filtered rows to export \"every matching row, in screen order\".\n**What happened:** the CSV export (the toolbar button and the palette's `meridian:export-table` event) wrote only the header. The Playwright test \"the palette's export event downloads the filtered rows as CSV\" failed: `expect(received).toBeGreaterThan(expected) Expected: > 10 Received: 0` (lines after the header).\n**Why:** table-core's getSortedRowModel copies every row before sorting — `const sortedData = rows.map(row => ({ ...row }))` in build/lib/utils/getSortedRowModel.js — so no sorted row is `===` a filtered row.\n**The fix:** `const rows = table.getPrePaginationRowModel().rows` — the model after filtering, grouping and sorting, before pagination.\n**Evidence:** tests/e2e/kit.spec.ts before/after; node_modules/@tanstack/table-core@8.21.3 source line quoted above.\n:::\n\n:::lesson{title=\"react-hooks 7.1 warns incompatible-library on useReactTable even with “use no memo”; for RHF, useWatch clears it\" kind=\"tools\" by=\"ai\" packages=\"eslint-plugin-react-hooks@7.1.1, eslint-config-next@16.4.3, eslint@10.13.0, @tanstack/react-table@8.21.3, react-hook-form@7.91.0\"}\n**Rule:** If `pnpm lint` warns react-hooks/incompatible-library on useReactTable, \"use no memo\" won't silence it: disable that line with a reason. For react-hook-form's watch(), use useWatch({ control, name }).\n**Snippet:**\n```tsx\nexport function DataTable<TData>(props: DataTableProps<TData>) {\n  \"use no memo\" // the table instance is mutable; keep it uncompiled if the compiler is ever enabled\n  // The lint warns even with the directive (react-hooks 7.1): the opt-out is deliberate.\n  // eslint-disable-next-line react-hooks/incompatible-library\n  const table = useReactTable({ … })\n```\n**Check:** `pnpm lint` → exit 0, nothing printed after `$ eslint` (before: 4 problems, then 1).\n**Applies to:** eslint-plugin-react-hooks@>=7.1 <8, eslint-config-next@>=16.4 <17, @tanstack/react-table@>=8 <9, react-hook-form@>=7 <8\n**I assumed:** the warning means \"the React Compiler will skip this component\", so marking the component with the opt-out directive \"use no memo\" answers it. (The compiler isn't even enabled in this project's next.config.ts.)\n**What happened:** `pnpm lint` → `warning  Compilation Skipped: Use of incompatible library … TanStack Table's useReactTable() API returns functions that cannot be memoized safely  react-hooks/incompatible-library`, and the same for react-hook-form's `watch()`. With \"use no memo\" first in DataTable, the table's warning stayed: `✖ 1 problem (0 errors, 1 warning)`.\n**Why:** the rule reports a listed library's call site whatever the directive says. UpFork lesson L-X6NA turns this rule off when the compiler is off; this one is for keeping it on: the directive doesn't answer it, and for react-hook-form useWatch, a subscribing hook, removes the flagged call.\n**The fix:** the form reads `useWatch({ control: form.control, name: \"direction\" })`; DataTable keeps \"use no memo\" (a buyer who enables the compiler gets no stale rows) and the eslint-disable line with its reason.\n**Evidence:** lint output at each step (4 problems, then 1, then 0), 2026-10-28.\n:::\n\n:::lesson{title=\"shadcn's Radix Checkbox draws a full tick for “indeterminate”: a partly selected table header looked fully selected\" kind=\"not-in-docs\" by=\"ai\" packages=\"radix-ui@1.8.1, @tanstack/react-table@8.21.3\"}\n**Rule:** If a select-all Checkbox shows a tick while only some rows are selected, shadcn's indicator always renders CheckIcon: add a MinusIcon and switch on data-[state=indeterminate].\n**Snippet:**\n```tsx\n<CheckboxPrimitive.Indicator className=\"grid place-content-center text-current\">\n-  <CheckIcon className=\"size-3.5\" />\n+  <CheckIcon className=\"size-3.5 group-data-[state=indeterminate]/checkbox:hidden\" />\n+  <MinusIcon className=\"hidden size-3.5 group-data-[state=indeterminate]/checkbox:block\" />\n</CheckboxPrimitive.Indicator>\n```\n**Check:** qa/kit-table-bulk-*-1440.png re-shot after the change shows a filled box with a dash for 2 selected rows; the kit test still selects every row with the same box (\"10 selected\") → passed.\n**Applies to:** shadcn@>=4.23 <5, radix-ui@>=1.4 <2\n**I assumed:** Radix's Checkbox handles `checked=\"indeterminate\"` end to end, so the shadcn wrapper shows a mixed state.\n**What happened:** with 2 of 10 rows selected, the DataTable header checkbox (`checked={table.getIsSomePageRowsSelected() ? \"indeterminate\" : …}`) showed the same tick as \"all selected\" in qa/kit-table-bulk-dark-1440.png. The root's fill classes only target `data-[state=checked]`, and the indicator's only child is `<CheckIcon />`.\n**Why:** Radix renders the Indicator for both checked and indeterminate; what it shows is up to the wrapper. This is the Radix counterpart of UpFork lesson L-DVXR, which found the same gap in shadcn's Base UI checkbox.\n**The fix:** `group/checkbox` on the root, `data-[state=indeterminate]:` fill classes like the checked ones, and both icons in the indicator (snippet).\n**Evidence:** screenshots before/after, 2026-10-28 (new-york-v4 checkbox.tsx from the registry).\n:::\n\n## Live prices: a bounded random walk\n\nEquities, F&O and Crypto tick; mutual funds and bonds don't, because a fund prices once a day at its NAV and a bond is marked once a day, and ticking them would show prices that don't exist. The feed is framework-free (`src/lib/live-quotes.ts`), so it is unit-tested with a fake clock.\n\nEvery 3 seconds each symbol trades with a 60% chance. If it trades, its step *s* is uniform in [−0.004, +0.004], and the new price is *p*′ = *p* × (1 + *s*). If *p*′ would leave ±3% of the opening price *a* (|*p*′ / *a* − 1| > 0.03), the step is reflected, *p*′ = *p* × (1 − *s*), and clamped to the band if that still leaves it. The step is seeded by the symbol and the tick number, so the same symbol moves the same way in every entity: it is a market quote, not a book's. The band keeps a demo left open all afternoon believable.\n\n```ts\nexport const TICK_MS = 3000\n/** The largest move in one tick, as a share (0.4%). */\nexport const MAX_STEP = 0.004\n/** How far a quote may wander from its opening price, as a share (3%). */\nexport const BAND = 0.03\n/** The chance that a symbol trades in a given tick. */\nexport const TRADE_CHANCE = 0.6\n\n/** One tick's move for a symbol: 0 when it doesn't trade, else a share in [−MAX_STEP, +MAX_STEP]. Seeded. */\nexport function walkStep(symbol: string, tick: number): number {\n  const next = mulberry32(hashSeed(\"quote\", symbol, tick))\n  if (next() >= TRADE_CHANCE) return 0\n  return (next() * 2 - 1) * MAX_STEP\n}\n\n/** The price after a step: a step that would leave the band is reflected, and the result is clamped to it. */\nexport function nextPrice(anchor: number, price: number, step: number): number {\n  const inBand = (value: number) => Math.abs(value / anchor - 1) <= BAND\n  let next = price * (1 + step)\n  if (!inBand(next)) next = price * (1 - step)\n  if (!inBand(next)) next = Math.min(anchor * (1 + BAND), Math.max(anchor * (1 - BAND), next))\n  return next\n}\n```\n\nThe timer runs only while a live component is on screen and the tab is visible; the last listener leaving stops it:\n\n```ts\nprivate update() {\n  const status: FeedStatus = this.frozen ? \"frozen\" : this.env.hidden() ? \"paused\" : \"live\"\n  const run = status === \"live\" && this.listeners.size > 0\n  if (run && !this.stop) this.stop = this.env.every(TICK_MS, () => this.tick())\n  if (!run && this.stop) {\n    this.stop()\n    this.stop = null\n  }\n  if (status !== this.status) {\n    this.status = status\n    this.version += 1\n    this.emit()\n  }\n  if (this.listeners.size === 0 && this.ticksSinceIdle > 0) {\n    this.ticksSinceIdle = 0\n    this.idleListeners.forEach((listener) => listener())\n  }\n}\n```\n\nReact reads the feed through `useSyncExternalStore` (src/hooks/use-live-quotes.ts): `useLiveQuotes(items)` registers a section's positions and returns id → live price, recomputed on each tick.\n\n### One set of numbers per tick\n\nThe KPI strip, the chart header, the distributions, the movers and the holdings table must show the same figures at every tick. So each section calls `useLiveBook` with the book's snapshot positions and the same function the data layer uses to build its figures (`equityBook`, `cryptoBook`…); the positions are repriced with the live quotes and the figures rebuilt. It is called inside each section, never at page level, so a tick re-renders the sections that show prices and not the page around them. From `src/features/investments/live.tsx`:\n\n```tsx\n/** Quotes for a book's positions; each new price is kept in the data book too (Net worth reads it). */\nfunction useQuoteItems(book: HoldingBook | \"fno\", rows: { id: string; symbol: string; price: number }[] | undefined, live: boolean) {\n  const { entityId } = useWorkspace()\n  return React.useMemo<QuoteItem[] | undefined>(\n    () => (live ? rows?.map((row) => ({ id: row.id, symbol: row.symbol, price: row.price, onPrice: (price: number) => dataActions.setQuote(entityId, book, row.id, price) })) : undefined),\n    [book, rows, live, entityId],\n  )\n}\n\n/** A book's figures at live prices (`live: false` for books priced once a day: funds at NAV). */\nexport function useLiveBook<P extends Position, B>(book: HoldingBook, positions: P[] | undefined, derive: (positions: P[]) => B, live = true): B | undefined {\n  const items = useQuoteItems(book, positions, live)\n  const prices = useLiveQuotes(items)\n  return React.useMemo(() => (positions ? derive(repricePositions(positions, prices)) : undefined), [positions, prices, derive])\n}\n```\n\n`repricePositions` (src/lib/data/selectors/investments.ts) recomputes value, P&L, day P&L and weights from quantity × price, and returns the same array when no price moved. Each new price is also written into the data book (`dataActions.setQuote`), and when the last live component leaves after prices moved, the cached figures refresh once. That is what lets Net worth value the investments at the prices last shown without ticking itself.\n\n![Equities with live prices: the holdings table's prices and day returns ticking, delayed 15 minutes](/article-images/01a18e3a-1396-7760-ab0a-f2a3f905083a)\n\n### What a tick costs\n\nMeasured on the production build in installed Chrome at 1440 px, 30 s per run (10 ticks). In the first measurement Equities spent 6.2 s of task time per 30 s against 0.37 s of script: the live dot's pulse animated `box-shadow`, and the flash animated `background-color` in every cell that moved, both repainting every frame. Both became pseudo-elements animating only opacity and transform, which the compositor runs: 6.2 s → 2.6 s (0.86 s with reduced motion). At that point a tick re-rendered about 1,460 components in 2 commits on Equities, with ~40–55 ms of script. The flash, from `src/app/globals.css`:\n\n```css\n@utility live-flash-up {\n  position: relative;\n  isolation: isolate;\n  &::before {\n    content: \"\";\n    position: absolute;\n    inset: 0;\n    z-index: -1;\n    border-radius: inherit;\n    background-color: var(--positive-soft);\n    opacity: 0;\n    animation: live-flash 600ms var(--ease-out);\n  }\n  @media (prefers-reduced-motion: reduce) {\n    &::before {\n      animation: none;\n    }\n  }\n}\n```\n\nThe rest was layout: meters and ranked bars animated their width on every tick. They now slide a full-width fill by `transform` inside a clipping track (`translateX`, not `scaleX`, which would squash the rounded end), and the holdings tables memoise the name cell and the row menu on primitives (the row menu was a full Radix menu per row, re-rendered on each tick). From `src/components/kit/meter.tsx`:\n\n```tsx\n) : (\n  // A full-width fill slid left by what is missing, inside a clipping track: the change animates `transform`\n  // (compositor only, no layout or paint per frame on live pages) and the fill keeps its rounded end.\n  <span className=\"absolute inset-0 overflow-hidden rounded-full\">\n    <span\n      className={cn(\"absolute inset-0 rounded-full transition-transform duration-(--dur-slow) ease-out\", fill)}\n      style={{ transform: `translateX(${width - 100}%)` }}\n    />\n```\n\nThat second pass, measured over 30 s of ticks on Equities: task time 3.15 → 1.54 s, script 0.66 → 0.37 s, layout 0.30 → 0.02 s, and about 693 → 570 components per commit.\n\nTests and screenshots freeze the feed: `window.__meridianFreezeQuotes = true` before the page loads stops the timer, and `window.__meridianQuotes.tick()` moves it one step. The walk itself is unit-tested over 20,000 ticks for four symbols: no step above 0.4%, no drift past 3%, and a drift past half the band, so it does use it.\n\n:::lesson{title=\"Playwright's expect() costs ~3 ms a call: 160,000 checks in a loop ran a test past 5 min; one check after it: 7 s\" kind=\"tools\" by=\"ai\" packages=\"@playwright/test@1.64.1\"}\n**Rule:** If a Playwright test checks an invariant over thousands of steps, track the worst case in the loop and call expect once after it: each expect call costs milliseconds.\n**Snippet:**\n```ts\n- for (let tick = 1; tick <= 20_000; tick++) {\n-   const next = nextPrice(anchor, price, walkStep(symbol, tick))\n-   expect(Math.abs(next / price - 1)).toBeLessThanOrEqual(MAX_STEP + 1e-12)\n-   price = next\n-   expect(Math.abs(price / anchor - 1)).toBeLessThanOrEqual(BAND + 1e-12)\n- }\n+ let widestStep = 0, widestDrift = 0\n+ for (let tick = 1; tick <= 20_000; tick++) { /* …track the maxima… */ }\n+ expect(widestStep).toBeLessThanOrEqual(MAX_STEP + 1e-12)\n+ expect(widestDrift).toBeLessThanOrEqual(BAND + 1e-12)\n```\n**Check:** `pnpm exec playwright test --config playwright.unit.config.ts tests/unit/investments.spec.ts` → \"10 passed (7.0s)\"; the whole unit suite → \"52 passed (14.0s)\".\n**Applies to:** @playwright/test@>=1.40\n**I assumed:** a synchronous `expect(x).toBeLessThanOrEqual(y)` costs about as much as the comparison, so 4 symbols × 20,000 ticks × 2 checks is nothing.\n**What happened:** `pnpm test:unit` was killed by its 400 s timeout; run alone, the spec ended with \"the walk is bounded … Error: worker process exited unexpectedly (code=143, signal=null)\" after 4.9 min while the other 8 tests had passed.\n**Why:** not traced into Playwright's source. Measured alone: 20,000 `expect(Math.abs(Math.sin(i))).toBeLessThanOrEqual(1)` calls took 58,080.8 ms, the loop without expect 9.1 ms, about 2.9 ms a call (other specs running); each expect being reported as a step is the likely cost.\n**The fix:** track `widestStep` and `widestDrift` in the loop and assert them once (plus a check that the walk uses the band).\n**Evidence:** 4.9 min and killed → 7.0 s for the spec; the micro-measurement above (a throwaway spec, deleted after); Node 22.\n:::\n\n## Formats applied app-wide\n\nEvery amount, number, percentage and date on screen goes through `src/lib/format.ts`: no `toFixed`, no string concatenation for money, the true minus sign (U+2212) for negatives, Intl formatters built once and cached (tables format thousands of cells), and date-only strings treated as calendar days, never shifted by a time zone. Prices have an adaptive precision: two decimals from 1, four from 0.01, three significant digits below that, so a coin at $0.0000121 doesn't read as $0.00.\n\nSettings → General picks the date format (month first \"Oct 31, 2026\", day first \"31 Oct 2026\", ISO \"2026-10-31\") and the number format (1,234.56 · 1.234,56 · 1 234,56). Months keep their names in every format, and amount fields take a point for decimals in all of them. The formatters read module defaults, which `applyFormatPreferences` replaces:\n\n```ts\nexport const formatDefaults = {\n  /** Numbers and money: grouping, decimal mark, where the currency symbol goes (Settings → Number format). */\n  locale: \"en-US\",\n  /** Dates (Settings → Date format). */\n  dateFormat: \"medium\" as DateOrder,\n  currency: \"USD\",\n  /** Settings → General → Timezone default: (UTC−05:00) Eastern Time — New York. Saved, not applied (README). */\n  timeZone: \"America/New_York\",\n}\n```\n\nSetting the defaults isn't enough on its own: text already on screen, and labels the selectors wrote into cached query results (insights, \"since …\" dates), would keep the old format. So `FormatPreferencesProvider` (src/components/format-preferences.tsx) sets the defaults before anything below it renders, remounts the app under a new key when they change, and invalidates the queries. The server and the hydrating render use the defaults (settings live in localStorage), so there is no hydration mismatch; saved formats take over right after hydration, with one remount, and only when they differ.\n\n```tsx\nexport function FormatPreferencesProvider({ children }: { children: React.ReactNode }) {\n  const { general } = useSettings()\n  const preferences: FormatPreferences = { locale: general.numberFormat, dateFormat: general.dateFormat }\n  const key = `${preferences.locale}|${preferences.dateFormat}`\n  applyFormatPreferences(preferences)\n\n  const client = useQueryClient()\n  const applied = React.useRef(key)\n  React.useEffect(() => {\n    if (applied.current === key) return\n    applied.current = key\n    void client.invalidateQueries({ queryKey: [queryRoot] })\n  }, [key, client])\n\n  return <React.Fragment key={key}>{children}</React.Fragment>\n}\n```\n\nTime zone and language are saved and shown, not applied: dates and \"today\" follow New York time, and the interface is English, left to right. The README says where to wire them.\n\n## Prefetch on intent\n\nEvery route in Meridian is dynamic, on purpose: the root layout reads the theme customizer's cookie, so the server renders the right mode, preset, font, density and privacy state and the first paint never flashes. From `src/app/layout.tsx`:\n\n```tsx\nexport default async function RootLayout({ children }: Readonly<{ children: React.ReactNode }>) {\n  // The customizer's choices arrive with the request, so the first paint already has the right theme, preset,\n  // font, density and privacy state. \"system\" mode is resolved before paint by next-themes' inline script.\n  const jar = await cookies()\n  const appearance = parseAppearance(jar.get(APPEARANCE_KEY)?.value)\n  const privacy = parsePrivacy(jar.get(PRIVACY_KEY)?.value)\n\n  return (\n    <html\n      lang=\"en\"\n      suppressHydrationWarning\n      className={cn(GeistSans.variable, GeistMono.variable, appearance.mode === \"dark\" && \"dark\")}\n      {...appearanceAttributes(appearance)}\n      data-privacy={privacy ? \"on\" : \"off\"}\n    >\n```\n\nEvery route also has a `loading.tsx` (next section). Together, that made the default `next/link` expensive: each link in the viewport prefetched its dynamic route up to the loading boundary, 27 RSC requests on loading Finance and 26 on Equities, from the sidebar's links plus card and row links. Meridian's links now prefetch on intent. `src/components/kit/intent-link.tsx`, a drop-in for `next/link` used for every link in `src/`, passes `prefetch={false}` until the pointer enters, the link takes keyboard focus or a finger touches it, then the default (`null`); its code is in the lesson below.\n\nMeasured on the production build at 1440 px: RSC requests on loading Finance / Equities 27 / 26 → 0 / 0, and a sidebar click to the next page's heading 475 / 438 ms → 304 / 265 ms, because hovering the link prefetched it. The test, in `tests/e2e/phase8.spec.ts`:\n\n```ts\ntest(\"links prefetch on intent, not on sight\", async ({ page }) => {\n  const rsc: string[] = []\n  page.on(\"request\", (request) => {\n    if (request.headers()[\"rsc\"] === \"1\" || request.url().includes(\"_rsc=\")) rsc.push(request.url())\n  })\n  await pageReady(page, \"/dashboard/finance\")\n  await page.waitForTimeout(1500)\n  // the 20-odd visible sidebar and card links no longer fetch their routes on load\n  expect(rsc.length, rsc.join(\"\\n\")).toBeLessThanOrEqual(2)\n  const before = rsc.length\n  await page.locator('[data-slot=\"sidebar\"] a[href^=\"/dashboard/cash-flow\"]').hover()\n  await expect.poll(() => rsc.length).toBeGreaterThan(before)\n  await page.locator('[data-slot=\"sidebar\"] a[href^=\"/dashboard/cash-flow\"]').click()\n  await expect(page.locator(\"h1\")).toHaveText(\"Cash flow\")\n})\n```\n\n:::lesson{title=\"Every visible Link prefetched its dynamic route: 27 RSC requests per page view, and prefetch=false also kills hover\" kind=\"newer\" by=\"ai\" packages=\"next@16.4.3, react@19.3.1, @playwright/test@1.64.1\"}\n**Rule:** If each page view fires ~20+ `_rsc` requests for visible links on dynamic routes, prefetch on intent: prefetch={false} until mouseenter/focus/touchstart, then null.\n**Snippet:**\n```tsx\n// before: import Link from \"next/link\" — every link in view prefetches its (dynamic) route\nexport default function IntentLink({ prefetch, onMouseEnter, onFocus, onTouchStart, ...props }: React.ComponentProps<typeof NextLink>) {\n  const [intent, setIntent] = React.useState(false)\n  return (\n    <NextLink\n      {...props}\n      prefetch={prefetch === false ? false : intent ? (prefetch ?? null) : false}\n      onMouseEnter={(event) => { setIntent(true); onMouseEnter?.(event) }}\n      onFocus={(event) => { setIntent(true); onFocus?.(event) }}\n      onTouchStart={(event) => { setIntent(true); onTouchStart?.(event) }}\n    />\n  )\n}\n```\n**Check:** tests/e2e/phase8.spec.ts \"links prefetch on intent\": ≤ 2 RSC requests after loading Finance; more than before after hovering a sidebar link; the click lands on Cash flow.\n**Applies to:** next@>=15 <17\n**I assumed:** the default Link costs little (a dashboard's routes are cheap to prefetch), and `prefetch={false}` keeps the hover prefetch, as in the Pages Router.\n**What happened:** every route is dynamic (the root layout reads the appearance cookie) and has a loading.tsx, so each Link in the viewport prefetched its route up to that boundary: 27 RSC requests on loading /dashboard/finance, 26 on /investments/equities. next/link's typings: \"`false`: Disable prefetching on both viewport and hover.\"\n**Why:** in the App Router, a dynamic route is partially prefetched (to the nearest loading.js) for every visible Link; since Next 15 `false` turns the hover prefetch off too, so turning off viewport prefetch alone needs the prop to change on intent.\n**The fix:** IntentLink (snippet, components/kit/intent-link.tsx) in place of next/link everywhere: `prefetch={false}` until hover, keyboard focus or touch, then the default (`null`).\n**Evidence:** production build at 1440: RSC requests on load 27 / 26 → 0 / 0 (Finance / Equities); sidebar click → next page's h1 475 / 438 → 304 / 265 ms, 2026-10-30.\n:::\n\n## Lazy charts\n\nRecharts is the heaviest library in the app, so it stays out of every page's first-load JavaScript. `src/components/charts/cartesian.tsx` is a set of `next/dynamic` wrappers over `cartesian-charts.tsx`, which holds the charts. The chunk is requested as soon as a page that draws charts runs its JavaScript, so it arrives while the queries are still waiting on their latency; until it does, each chart shows the same silhouette, at the same height, as its loading card, so nothing moves when it draws. The Donut keeps its legend and centre total and only its ring waits (`donut-ring.tsx`); the bond ladder is split the same way.\n\n```tsx\nconst load = () => import(\"@/components/charts/cartesian-charts\")\nif (typeof window !== \"undefined\") void load()\n\nfunction placeholder(kind: ChartSilhouette) {\n  return function ChartLoading() {\n    return <ChartSkeleton kind={kind} height={useChartHeight()} />\n  }\n}\n\nexport const TimeSeriesArea = dynamic(() => load().then((charts) => charts.TimeSeriesArea), { loading: placeholder(\"line\") })\nexport const MultiLine = dynamic(() => load().then((charts) => charts.MultiLine), { loading: placeholder(\"line\") })\nexport const GroupedBars = dynamic(() => load().then((charts) => charts.GroupedBars), { loading: placeholder(\"bars\") })\n```\n\nFirst-load JavaScript (gzip, the scripts the HTML references): Finance 643 → 510 KB, Equities 649 → 516 KB; Settings, which has no charts, stays at 477 KB. Recharts (97 KB) and the chart kit arrive in parallel. Whether that delayed the data was checked directly: in 12 runs over Finance, Net worth, Equities and Insurance, the chunk arrived 0.6–1.7 s before the data did (Finance: chunk 1.02 s, data 1.92 s). The rule that keeps it this way: no statically loaded module may import `recharts` or `ui/chart`.\n\nThe kit's presets (`TimeSeriesArea`, `MultiLine`, `GroupedBars`, `StackedBars`, `DivergingBars`, `MiniArea`) sit on shadcn's `ChartContainer`, with the Y axis as wide as its longest label, compact ticks, a \"View as table\" for every chart, and first-draw-only animation that stops under reduced motion. The Loans page's prepayment simulator draws its before and after balances with `MultiLine` on one axis, which is where the next lesson showed:\n\n![The Loans page's prepayment simulator in dark: interest and time saved, and the balance before and after on one axis](/article-images/01a18e3a-1901-7dfc-913a-416ebcc8716d)\n\n:::lesson{title=\"Recharts clipped the last X label (“Oct 2043”) with explicit ticks and interval 0; only preserve* fits edge labels\" kind=\"not-in-docs\" by=\"ai\" packages=\"recharts@3.10.1\"}\n**Rule:** If a Recharts XAxis with an explicit `ticks` list cuts its last label at the plot's edge, set interval=\"preserveStartEnd\" instead of 0: only the preserve* intervals move edge labels inside.\n**Snippet:**\n```tsx\n// before: every even tick drawn centred on its point; the last label hangs past the plot\n<XAxis dataKey=\"label\" ticks={evenTicks(data, maxXTicks)} interval={maxXTicks ? 0 : \"preserveStartEnd\"} />\n// after: the same ticks, and Recharts slides the edge labels inside\n<XAxis dataKey=\"label\" ticks={evenTicks(data, maxXTicks)} interval=\"preserveStartEnd\" />\n```\n**Check:** the simulator sheet at 1440 (qa/p8/c-emis_sheet_simulator-light-1440x1400-part.png): \"Oct 2043\" ends at the plot's right edge, fully drawn.\n**Applies to:** recharts@>=2 <4\n**I assumed:** with explicit ticks, interval={0} simply shows all of them, and Recharts keeps tick labels inside the chart as it does by default.\n**What happened:** the prepayment simulator's balance chart (MultiLine, 5 even ticks, right margin 12px) drew \"Oct 2043\" centred on the last point, half past the plot's right edge, where the sheet clipped it (screenshot review, light 1440).\n**Why:** for a numeric interval recharts/lib/cartesian/getTicks.js returns `getNumberIntervalTicks(ticks, interval)`, each label centred on its point with no fitting; for \"preserveStart\" / \"preserveStartEnd\" it measures each label and moves it in (`tickCoord = coordinate - gap`) when it would overflow.\n**The fix:** the chart kit's XAxis (MultiLine, TimeSeriesArea): `interval=\"preserveStartEnd\"` with its even `ticks`.\n**Evidence:** the review screenshot before; the shot above after; getTicks.js lines 138–141 and 172–173.\n:::\n\n## Route-level loading.tsx, and the 404 in a layout\n\nEach of the 21 routes inside the shell has a `loading.tsx` that renders `RouteSkeleton` in one of six layouts (overview, table, detail, form, settings, lists), so a navigation never shows an empty panel before the page's own skeletons take over: `transactions/loading.tsx` is one line of JSX, `<RouteSkeleton layout=\"table\" />`.\n\nThe 404 is designed and lives inside the shell, so an unknown URL keeps the sidebar and header (`src/app/not-found.tsx`):\n\n```tsx\n/** Any unknown URL (and notFound() in a page) lands here, inside the shell's inset panel (§12.23). */\nexport default async function NotFound() {\n  const jar = await cookies()\n  return (\n    <AppShell navCollapsed={parseNavState(jar.get(NAV_STATE_KEY)?.value)}>\n      <NotFoundPage />\n    </AppShell>\n  )\n}\n```\n\nA bad parameter is a 404 too: `/settings/nope` and `/invoices/view/abc`. The check sits in each segment's layout, not in its page, because of the next lesson (whose snippet is the Settings layout). From `src/app/(app)/invoices/view/[id]/layout.tsx`:\n\n```tsx\n/** An id that isn't an invoice number is a 404 — checked outside the loading boundary, so the status is 404 (lesson 7.1). */\nexport default async function InvoiceLayout({ children, params }: Props) {\n  const { id } = await params\n  const number = Number(decodeURIComponent(id).replace(/^#/, \"\"))\n  if (!Number.isInteger(number) || number <= 0) notFound()\n  return children\n}\n```\n\n:::lesson{title=\"Adding loading.tsx to a route turned its notFound() into a 200: the page now calls it after the stream has started\" kind=\"not-in-docs\" by=\"ai\" packages=\"next@16.4.3, react@19.3.1, @playwright/test@1.64.1\"}\n**Rule:** If a route with a loading.tsx answers 200 for a bad param, call notFound() in that segment's layout.tsx (outside the loading Suspense boundary), not in page.tsx.\n**Snippet:**\n```tsx\n// src/app/(app)/settings/[[...tab]]/layout.tsx — outside the route's loading.tsx boundary\nexport default async function SettingsLayout({ children, params }: { children: React.ReactNode; params: Promise<{ tab?: string[] }> }) {\n  const { tab } = await params\n  if ((tab && tab.length > 1) || !settingsTabs.some((t) => t.slug === (tab?.[0] ?? \"general\"))) notFound()\n  return children\n}\n// page.tsx: the same check there came after the 200 (loading.tsx streams first)\n```\n**Check:** `pnpm build`, then tests/e2e/phase7.spec.ts \"system pages…\": `/settings/nope` and `/invoices/view/abc` → `response.status()` 404 and the 404 page's h1; `/no-such-page` → 404.\n**Applies to:** next@>=15 <17\n**I assumed:** notFound() in a server page.tsx always gives the 404 status, as it did before the route had a loading.tsx; only the HTML would differ.\n**What happened:** after every (app) route got a loading.tsx (route-level skeletons), `page.goto(\"/settings/nope\")` returned `Expected: 404 Received: 200` — the designed 404 rendered, but with status 200. An unmatched URL (`/no-such-page`) still returned 404.\n**Why:** loading.tsx wraps page.tsx in a Suspense boundary; Next flushes the layouts and the loading fallback with a 200 before the page renders, so a notFound() thrown inside the page can only swap the HTML (Next adds a robots noindex meta), not the status already sent. The docs describe this for streaming in general; nothing on loading.js warns that it moves a page's notFound() behind the flush.\n**The fix:** the tab check moved to `settings/[[...tab]]/layout.tsx` and the invoice id check to `invoices/view/[id]/layout.tsx`: a layout renders before the loading boundary, so its notFound() lands before the first byte.\n**Evidence:** phase7.spec run 1: \"Expected: 404 Received: 200\" at `expect(unknownTab?.status()).toBe(404)`; after the layout check, rebuilt: \"2 passed (14.7s)\" with both statuses 404.\n:::\n\n## Design tokens, and contrast that is measured\n\n`src/app/globals.css` defines every colour, radius, type size and motion duration as a CSS variable, for light and dark, and maps them to Tailwind utilities (`bg-card`, `text-positive-text`, `text-kpi`, `p-card`, `h-row`). Colours are written in OKLCH, and many carry their measured contrast in a comment (light muted text is 5.28:1 on a card). The brand group of the light `:root`:\n\n```css\n/* brand (the Meridian preset; other presets override this group only) */\n--primary: oklch(0.53 0.2 266); /* #355edd  (white text 5.38:1) */\n--primary-foreground: oklch(0.99 0.005 266);\n--primary-soft: oklch(0.965 0.022 266); /* #eef4ff */\n--primary-soft-foreground: oklch(0.45 0.19 266); /* #2346bc */\n--ring: oklch(0.62 0.19 266); /* #507cf7 */\n--hero-tint: oklch(0.6 0.2 295); /* violet, the aurora's top-right glow (§6.2) */\n/* measured: at the brief's 14% the hero's top-left corner takes muted labels to 4.04–4.33:1 (by preset); 8% keeps\n   ≥4.55:1. Dark mode keeps 14%. */\n--hero-strength: 8%;\n/* measured: the brief's 60% puts big figures' symbol and cents at 4.32–4.43:1 on the hero; 65% gives ≥5.05:1 */\n--money-minor-opacity: 0.65;\n```\n\nThe four presets (Meridian, Midnight, Graphite, Aurum) swap only the brand group. Their selectors aren't tied to `<html>`, so any element can preview a preset, which is how the customizer draws its swatches; each restates its dark values under `.dark[data-preset]`, which outranks `.dark`.\n\n![The theme customizer open on Net worth, with the Aurum preset picked](/article-images/01a18e3a-1f2c-76d6-9f61-6b3528630421)\n\n### The contrast check\n\n`pnpm check:contrast` (scripts/check-contrast.mjs) reads globals.css itself, resolves every token in both modes and all four presets, converts OKLCH to sRGB, and computes the WCAG 2.2 ratio for 204 required pairs: text at 4.5:1, the focus ring at 3:1. It exits 1 on any failure. Translucent layers are composited first, because the worst case is often a blend: the hero's tinted corner under its label, or `<Money>`'s translucent cents.\n\n```js\n/** A background, either a token or `top over bottom` (a translucent layer composited on an opaque surface). */\nfunction surface(vars, spec) {\n  const [top, bottom] = spec.split(\" over \")\n  if (!bottom) return color(vars, top)\n  const t = color(vars, top)\n  const b = surface(vars, bottom)\n  return { r: t.r * t.a + b.r * (1 - t.a), g: t.g * t.a + b.g * (1 - t.a), b: t.b * t.a + b.b * (1 - t.a), a: 1 }\n}\n```\n\nThe pair lists name those blends as `top over bottom`: `[\"muted-foreground\", \"primary/hero over card\"]` is muted text on the preset colour at `--hero-strength` over the card, and `foreground/money` is a figure's cents at `--money-minor-opacity`.\n\nMeasuring changed the palette. Four token values from the brief were below AA once measured and were darkened: light tick labels (3.64 → 4.85:1), dark destructive under white text (4.20 → 5.00:1), Midnight's dark primary (3.58 → 4.78:1) and Aurum's light focus ring (3.56 → 4.20:1, non-text). The hero's tint is 8% in light mode, because the brief's 14% took muted labels in its corner down to 4.04–4.33:1 depending on the preset, and `<Money>`'s symbol and cents sit at 65% opacity, because 60% gave 4.32–4.43:1 on the hero. The final run: \"204 required pairs checked, 0 below AA\". The same maths runs live on `/dev/tokens` in the browser, and the two agree.\n\n### The token guard\n\n`pnpm check:tokens` (scripts/check-tokens.mjs) fails on a hex colour, a colour function or a Tailwind palette class anywhere under `src/`, comments included, so components can only colour through tokens. It ended at 285 files with no raw colour.\n\n```js\nconst rules = [\n  // Only the lengths a CSS hex colour can have (3, 4, 6, 8). Four plain digits are a record number, not a colour:\n  // \"Invoice #5099\" would otherwise read as #RGBA. Every other all-digit form (#000, #333333) still fails.\n  { name: \"hex colour\", pattern: /#(?!\\d{4}\\b)(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})\\b/g },\n  { name: \"colour function\", pattern: /\\b(?:oklch|oklab|lch|lab|rgba?|hsla?|hwb)\\(/g },\n  {\n    name: \"Tailwind palette class\",\n    pattern: new RegExp(`(?<![\\\\w-])(?:${colorUtilities})-(?:${palette})-\\\\d{2,3}\\\\b`, \"g\"),\n  },\n  { name: \"Tailwind palette class\", pattern: new RegExp(`(?<![\\\\w-])(?:${colorUtilities})-(?:white|black)\\\\b`, \"g\") },\n]\n```\n\n:::lesson{title=\"shadcn's `cn` reads a custom font size like `text-caption` as a colour and silently drops it\" kind=\"tools\" by=\"ai\" packages=\"cn@0.5.0, tailwindcss@4.3.3, shadcn@4.23.0, next@16.4.3\"}\n**Rule:** If a custom `--text-*` size vanishes when merged with a text colour, register it with createCn from \"cn/config\", and alias \"cn\" in tsconfig paths so shadcn's components use it too.\n**Snippet:**\n```ts\n// src/lib/utils.ts\n- export { cn } from \"cn\"\n+ import { createCn } from \"cn/config\"\n+ export const cn = createCn({\n+   extend: { classGroups: { \"font-size\": [{ text: [\"display\", \"h1\", \"h2\", \"card-title\", \"kpi\", \"body\", \"body-strong\", \"small\", \"caption\", \"overline\"] }] } },\n+ })\n```\n```jsonc\n// tsconfig.json → compilerOptions.paths\n\"cn\": [\"./src/lib/utils.ts\"]\n```\n**Check:** probe after the fix → `\"text-caption text-muted-foreground\"`, `\"text-positive-text text-display\"`, `\"p-4\"`; in Chrome, the shadcn Button with `className=\"text-caption\"` renders classes `… text-primary-foreground … text-caption` (its `text-sm` merged away), computed font-size 12px; `pnpm typecheck` and `pnpm build` pass with the alias.\n**Applies to:** cn@>=0.5 <1, tailwindcss@>=4 <5, shadcn@>=4.22 <5\n**I assumed:** a font size defined in Tailwind's theme (`--text-caption: 0.75rem` with line height, weight, tracking) merges like `text-sm`: `cn(\"text-caption\", \"text-muted-foreground\")` keeps both.\n**What happened:** in Node, `cn(\"text-caption\", \"text-muted-foreground\")` → `\"text-muted-foreground\"`, `cn(\"text-kpi\", \"text-positive-text\", \"text-display\")` → `\"text-positive-text text-display\"` and `cn(\"p-card\", \"p-4\")` → `\"p-card p-4\"` (both kept, CSS order decides). An unknown `text-x` lands in the text-colour group.\n**Why:** `cn` reproduces tailwind-merge's conflict rules, which classify classes by name, not by reading your CSS. Configuring `@/lib/utils` alone isn't enough: shadcn 4.22+ components import `{ cn } from \"cn\"` directly.\n**The fix:** `createCn` from \"cn/config\" in src/lib/utils.ts, taught the custom names (the font sizes, `spacing: [\"card\", \"row\"]`, `max-w-content`, `inset-shadow-highlight`), and tsconfig `paths` mapping the bare `\"cn\"` to that file (an exact match, so `\"cn/config\"` still resolves to the package).\n**Evidence:** Node probe before and after; `getComputedStyle` of `[data-testid=cn-alias-check]` on /dev/tokens, 2026-10-28.\n:::\n\n:::lesson{title=\"Next.js's CSS build turns oklch() tokens into a hex fallback plus lab(): the browser reports lab(), not oklch()\" kind=\"not-in-docs\" by=\"ai\" packages=\"next@16.4.3, tailwindcss@4.3.3, @tailwindcss/postcss@4.3.3\"}\n**Rule:** If getComputedStyle returns `lab(98.2% -.09 -1.13)` for a token you wrote as oklch(), the CSS build rewrote it: parse lab() (and oklab()) in any runtime colour maths.\n**Snippet:**\n```ts\nconst NUM = String.raw`(-?[\\d.]+(?:e-?\\d+)?)`\nconst LAB = new RegExp(String.raw`^lab\\(\\s*${NUM}(%?)\\s+${NUM}(%?)\\s+${NUM}(?:\\s*\\/\\s*${NUM}(%?))?\\s*\\)$`)\n// lab → XYZ (D50) → Bradford to D65 → linear sRGB → WCAG luminance\n```\n**Check:** `parseColor(\"lab(98.248% -.0918508 -1.13485)\")` and `parseColor(\"oklch(0.985 0.003 264)\")` both give #f9fafc and the same ratio against white (1.0441); the live table on /dev/tokens then shows the same ratios as the Node check over globals.css (muted-foreground on card 5.28:1, chart-axis on card 4.85:1).\n**Applies to:** next@>=16.4 <17, tailwindcss@>=4.3 <5\n**I assumed:** `getComputedStyle(document.documentElement).getPropertyValue(\"--background\")` returns the value as written in globals.css, `oklch(0.985 0.003 264)`.\n**What happened:** it returned `lab(98.248% -.0918508 -1.13485)`, so a contrast table that parsed only oklch(), rgb() and hex showed nothing. The served CSS had `:root { --background: #f9fafc; … }` and then `@supports (color: lab(0% 0 0)) { :root { --background: lab(98.248% …) } }`: 220 `lab(` and 2 `oklch(` in the stylesheet.\n**Why:** the CSS is lowered for the configured browser targets (Lightning CSS): oklch() becomes a hex fallback plus lab() behind @supports, and Chrome takes the lab() branch.\n**The fix:** `parseColor` (src/lib/contrast.ts) also reads `lab()` (CIE Lab D50 → Bradford → linear sRGB, per CSS Color 4) and `oklab()`, with numbers like `-.09` and `1e-5`.\n**Evidence:** fetched CSS chunk and probe output, 2026-10-28 (Next.js 16.4.3 with Turbopack, Chrome 156).\n:::\n\n:::lesson{title=\"Tailwind 4 generated bg-green-500 because the build brief and the token-guard script quote it as banned\" kind=\"tools\" by=\"ai\" packages=\"tailwindcss@4.3.3, @tailwindcss/postcss@4.3.3, next@16.4.3\"}\n**Rule:** If banned palette classes show up in your built CSS but no component uses them, Tailwind found them in docs or scripts: add `@source not \"../../docs\"` (and scripts, tests) to globals.css.\n**Snippet:**\n```css\n@import \"tailwindcss\";\n@source not \"../../docs\";\n@source not \"../../scripts\";\n```\n**Check:** after a reload, none of `--color-green-500`, `--color-emerald-600`, `--color-blue-500`, `.bg-green-500`, `.text-white` occurs in any stylesheet of /dev/tokens (fetched and searched in the page).\n**Applies to:** tailwindcss@>=4.1 <5\n**I assumed:** Tailwind generates utilities from the app's source files.\n**What happened:** the served CSS held `--color-green-500: lab(70.5521% -66.5147 45.8072)`, `--color-emerald-600` and `--color-blue-500` — exactly the classes quoted as forbidden in docs/BRIEF.md (§14.1) and in the comment of scripts/check-tokens.mjs.\n**Why:** Tailwind documents this as automatic source detection: it scans every non-ignored text file in the project, Markdown and scripts included. The trap is the project's own instructions. A build brief, a plan or a guard script that quotes the banned classes, common in projects built with an AI assistant, makes Tailwind generate exactly the classes they forbid.\n**The fix:** in src/app/globals.css, `@source not \"../../docs\"; @source not \"../../scripts\"; @source not \"../../tests\"; @source not \"../../qa\";`.\n**Evidence:** stylesheet search before (3 variables found) and after (0), 2026-10-28.\n:::\n\n:::lesson{title=\"shadcn's tailwind.css has its own `shimmer` (a text effect): my @utility shimmer merged into it and skeletons vanished\" kind=\"not-in-docs\" by=\"ai\" packages=\"shadcn@4.22.2, tailwindcss@4.3.3, @tailwindcss/postcss@4.3.3, next@16.4.3\"}\n**Rule:** If boxes using your own `shimmer` utility render invisible, shadcn/tailwind.css defines `shimmer` too (background-clip: text) and Tailwind merges both: give yours another name.\n**Snippet:**\n```css\n/* globals.css — after @import \"shadcn/tailwind.css\"; */\n- @utility shimmer {            /* merges with shadcn's text shimmer: background-clip: text */\n+ @utility skeleton-shimmer {\n    background-image: linear-gradient(90deg, transparent, color-mix(in oklch, var(--card) 55%, transparent), transparent);\n    background-size: 200% 100%;\n    animation: skeleton-shimmer 1.2s var(--ease-in-out) infinite;\n  }\n```\n**Check:** the rebuilt CSS's `.skeleton-shimmer{…}` rules contain no background-clip; re-shot qa/kit-kpis-light-1440.png and qa/dev-kit-dark-390.png show the loading card's two bars and the skeleton lines; the 8 re-run screenshot tests passed.\n**Applies to:** shadcn@>=4.22 <5, tailwindcss@>=4 <5\n**I assumed:** a utility declared with `@utility shimmer { … }` in my globals.css is mine; the name was free because nothing in the project used it.\n**What happened:** every skeleton (`class=\"shimmer rounded-md bg-muted …\"`) was invisible in light and dark, though it had its size and a muted `background-color`. The built CSS held four `.shimmer{…}` rules: mine and shadcn's `background-clip:text; -webkit-background-clip:text; -webkit-text-fill-color:var(--shimmer-text-fill,transparent); animation:tw-shimmer …`. Clipped to text, with no text inside, nothing painted.\n**Why:** `@import \"shadcn/tailwind.css\"`, which shadcn's variants and keyframes need, declares `@utility shimmer` (node_modules/shadcn/dist/tailwind.css, line 547 in 4.22.2). Tailwind 4 doesn't warn about a second `@utility` of the same name; it emits both under one class.\n**The fix:** renamed mine `skeleton-shimmer` (and its keyframes) and used it in the Skeleton component.\n**Evidence:** `grep -o \"\\.shimmer{[^}]*}\" .next/static/chunks/*.css` before, the `.skeleton-shimmer` rules after, 2026-10-28.\n:::\n\n## The shell\n\nEvery page lives in an inset panel that scrolls on its own under a sticky header. The sidebar is shadcn's `Sidebar variant=\"inset\" collapsible=\"icon\"`: an entity switcher, navigation with badges (\"3 pending\", \"1 overdue\") derived from the selected entity's book, groups remembered in a cookie so a closed group paints closed, and an icon rail (⌘B). The header has the period picker, a privacy toggle that blurs every amount, Ask Meridian (answers computed by the pages' selectors), notifications and the customizer; ⌘K opens a cmdk palette that navigates, runs actions (`?sheet=new`) and finds invoices, transactions and holdings.\n\n:::lesson{title=\"shadcn's own sidebar.tsx fails `next lint`: SidebarMenuSkeleton calls Math.random during render (react-hooks/purity)\" kind=\"newer\" by=\"ai\" packages=\"shadcn@4.23.0, eslint-config-next@16.4.3, eslint-plugin-react-hooks@7.1.1, eslint@10.13.0\"}\n**Rule:** If eslint-config-next 16 fails a fresh shadcn sidebar.tsx with \"Cannot call impure function during render\" on Math.random, derive the skeleton width from React.useId() instead.\n**Snippet:**\n```tsx\n- const width = React.useMemo(() => `${Math.floor(Math.random() * 40) + 50}%`, [])\n+ const id = React.useId()\n+ const width = `${50 + ([...id].reduce((sum, char) => sum + char.charCodeAt(0), 0) % 41)}%`\n```\n**Check:** `pnpm exec eslint --quiet` → no output, exit 0 (before: 3 errors, one of them this).\n**Applies to:** shadcn@>=4.23 <5, eslint-config-next@>=16.4 <17, eslint-plugin-react-hooks@>=7.1 <8\n**I assumed:** components straight from the shadcn registry pass the Next.js lint preset (the scaffold only kept the Tailwind class-order rules off components/ui).\n**What happened:** `pnpm lint` → `src/components/ui/sidebar.tsx 610:26 error Error: Cannot call impure function during render. Math.random is an impure function … react-hooks/purity`, in SidebarMenuSkeleton's `React.useMemo` that builds a random 50–90% width from `Math.floor(Math.random() * 40) + 50`.\n**Why:** eslint-plugin-react-hooks 7 (bundled by eslint-config-next 16) ships the React Compiler rules, and purity is an error in its recommended set. A random width also differs between the server render and hydration.\n**The fix:** the width comes from `React.useId()` (sum of its character codes, modulo 41, plus 50) — stable per instance, identical on server and client (snippet).\n**Evidence:** lint output before/after, 2026-10-28.\n:::\n\n:::lesson{title=\"On shadcn's icon rail, each faded group label sits over the previous group's last icon and swallows its hover and clicks\" kind=\"not-in-docs\" by=\"ai\" packages=\"shadcn@4.23.0, radix-ui@1.8.1, @playwright/test@1.64.1\"}\n**Rule:** If an icon on a collapsed shadcn Sidebar won't hover or click, the next group's label (opacity-0, -mt-8) is on top of it: add group-data-[collapsible=icon]:invisible to SidebarGroupLabel.\n**Snippet:**\n```tsx\n// components/ui/sidebar.tsx → SidebarGroupLabel\n- \"… transition-[margin,opacity] duration-200 ease-linear …\",\n- \"group-data-[collapsible=icon]:-mt-8 group-data-[collapsible=icon]:opacity-0\",\n+ \"… transition-[margin,opacity,visibility] duration-200 ease-linear …\",\n+ \"group-data-[collapsible=icon]:-mt-8 group-data-[collapsible=icon]:opacity-0 group-data-[collapsible=icon]:invisible\",\n```\n**Check:** the ⌘B test then hovered the Transactions icon on the rail and read the tooltip \"Transactions · 3 pending\" → passed.\n**Applies to:** shadcn@>=4.23 <5\n**I assumed:** an `opacity-0` label is out of the way on the rail.\n**What happened:** on the sidebar with `collapsible=\"icon\"`, `locator('a[href=\"/transactions\"]').hover()` timed out: `<div data-sidebar=\"group-label\" …>Money management</div> … subtree intercepts pointer events`. The Payments group's only icon could not be hovered (no tooltip) or clicked.\n**Why:** on the rail SidebarGroupLabel gets `-mt-8 opacity-0`; the 32px label moves up over the bottom of the group above it. Opacity doesn't stop hit-testing.\n**The fix:** `group-data-[collapsible=icon]:invisible` on the label, with `visibility` added to its transition list so it still fades out before hiding.\n**Evidence:** Playwright call log above, 2026-10-28.\n:::\n\n:::lesson{title=\"Ctrl+K opens a cmdk palette but can't close it: cmdk's vim bindings take Ctrl+K and call preventDefault\" kind=\"not-in-docs\" by=\"ai\" packages=\"cmdk@1.1.1, radix-ui@1.8.1\"}\n**Rule:** If Ctrl+K opens your cmdk palette but pressing it again inside does nothing (⌘K on a Mac works), handle the toggle before your defaultPrevented check, or pass vimBindings={false}.\n**Snippet:**\n```ts\nfunction onKeyDown(event: KeyboardEvent) {\n- if (event.defaultPrevented || event.isComposing) return\n+ if (event.isComposing) return\n  if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === \"k\") { event.preventDefault(); togglePalette(); return }\n+ if (event.defaultPrevented) return\n```\n**Check:** the same test → passed (open with Control+k, navigate, open with Meta+k, find #5099, Control+k opens, Control+k closes).\n**Applies to:** cmdk@>=1.0 <2\n**I assumed:** a window keydown listener that skips `event.defaultPrevented` events sees Ctrl+K the same way inside and outside the palette.\n**What happened:** the shell test \"⌘K and Ctrl+K open the palette…\" (Chrome 156 on Windows, shadcn's CommandDialog) failed at `await expect(palette).toBeHidden()` after a second Control+k: the dialog stayed open. Meta+k toggled fine.\n**Why:** cmdk's onKeyDown has `case \"k\": vimBindings && e.ctrlKey && prev(e)`, and prev starts with `e.preventDefault()` (it moves the selection up). vimBindings defaults to true; Ctrl+N/J/P are taken the same way.\n**The fix:** in the shell's keydown listener the ⌘K / Ctrl+K branch now runs before `if (event.defaultPrevented) return`.\n**Evidence:** node_modules/cmdk/dist/index.mjs (`case\"k\":{j&&e.ctrlKey&&se(e)` with `se=e=>{e.preventDefault(),…}`); test output before/after, 2026-10-28.\n:::\n\n:::lesson{title=\"shadcn's SidebarInset renders a `<main>`: a shell that puts its own main inside it has two main landmarks\" kind=\"not-in-docs\" by=\"ai\" packages=\"shadcn@4.22.2, next@16.4.3, react@19.3.1, @playwright/test@1.64.1\"}\n**Rule:** If `page.locator(\"main\")` hits 2 elements in a shadcn sidebar layout, SidebarInset is already a <main>: make it a div and keep your own main#main as the one main landmark.\n**Snippet:**\n```tsx\n// components/ui/sidebar.tsx — before (the shadcn registry): a landmark already\nfunction SidebarInset({ className, ...props }: React.ComponentProps<\"main\">) {\n  return <main data-slot=\"sidebar-inset\" … {...props} />\n}\n// after (marked \"Meridian:\"): a div; the shell's <main id=\"main\"> inside it is the one main\nfunction SidebarInset({ className, ...props }: React.ComponentProps<\"div\">) {\n  return <div data-slot=\"sidebar-inset\" className={cn(\"relative flex w-full flex-1 flex-col bg-background\", …, className)} {...props} />\n}\n```\n**Check:** tests/e2e/phase8.spec.ts \"every page has exactly one main landmark\": `getByRole(\"main\")` has a count of 1 on all 22 routes (the 21 pages and the 404) → passed; axe on every route: no serious or critical violation.\n**Applies to:** shadcn@>=4 <5, @playwright/test@>=1.40\n**I assumed:** `SidebarInset` was a styled wrapper, so the shell's `<main id=\"main\">` (the skip link's target) was the page's only main landmark.\n**What happened:** `expect(page.locator(\"main\")).toContainText(…)` failed: \"strict mode violation: locator('main') resolved to 2 elements: 1) <main data-slot=\"sidebar-inset\" …> 2) <main id=\"main\" tabindex=\"-1\" …>\". The axe spec (serious and critical only) had never flagged it.\n**Why:** the registry's SidebarInset takes `React.ComponentProps<\"main\">` and returns `<main data-slot=\"sidebar-inset\" …>`; shadcn's Sidebar page says to use it \"to wrap your main content\" without saying it is itself a main.\n**The fix:** SidebarInset renders a `<div>` (the edit is marked `Meridian:` in components/ui/sidebar.tsx), so the shell's `<main id=\"main\">` is the one main landmark; the header and footer became banner and contentinfo landmarks.\n**Evidence:** tests/e2e/overview.spec.ts:53 on 2026-10-28 (the error above); the final full run on 2026-10-30, 521 passed, the one-main test among them.\n:::\n\n## Sheets and forms\n\nCreating and editing happens in sheets: `FormSheet` is a 480 px sheet on desktop and a bottom drawer on phones (vaul), with react-hook-form and zod inside, and pickers built as a `Combobox` on cmdk that offers \"Create …\" for a new name. Every payment (a premium, an EMI, a prepayment, an invoice payment) goes through one `PaySheet` with a \"Pay from\" account and a total line, and books through `dataActions`, so the account it names really moves.\n\n:::lesson{title=\"cmdk: a forceMount item inside a CommandGroup still disappears when nothing else in the group matches\" kind=\"not-in-docs\" by=\"ai\" packages=\"cmdk@1.1.1, radix-ui@1.8.1, react@19.3.1\"}\n**Rule:** If a cmdk \"Create …\" item with forceMount never shows while you type a new name, its CommandGroup is hidden for having no matches: put forceMount on the group too.\n**Snippet:**\n```tsx\n- <CommandGroup>\n+ <CommandGroup forceMount>\n    <CommandItem value={`create ${query}`} forceMount onSelect={() => onCreate(query)}>\n      Create “{query}”\n    </CommandItem>\n  </CommandGroup>\n```\n**Check:** the same test then created \"Larkhaven Studio\", saved the transaction and found it by search (1 row, \"1,250.50\") → passed.\n**Applies to:** cmdk@>=1.1 <2\n**I assumed:** the item's docs say forceMount means \"forcibly rendered regardless of filtering\", so a create row in its own group appears for any search text.\n**What happened:** in the add-transaction sheet's counterparty combobox (shadcn new-york-v4 command.tsx, Chrome 156), typing a new name left an empty list. The Playwright test timed out (180 s) at `waiting for getByRole('option', { name: /Create “Larkhaven Studio”/ })`; the page snapshot showed `combobox [expanded]: Larkhaven Studio` above an empty `listbox \"Suggestions\"`.\n**Why:** cmdk decides a group's visibility from its matching items; an item that is only force-mounted doesn't make its group visible, so the item renders inside a hidden group. The Group has its own `forceMount` prop (\"Whether this group is forcibly rendered regardless of filtering\").\n**The fix:** forceMount on the group as well as the item (snippet), the row rendered only while the query is non-empty and matches no option exactly.\n**Evidence:** test output and page snapshot before, test pass after, 2026-10-28 (src/components/kit/combobox.tsx).\n:::\n\n:::lesson{title=\"shadcn's FormControl hands id and aria-* to its child via Slot: a custom input that doesn't spread them loses its label\" kind=\"not-in-docs\" by=\"ai\" packages=\"radix-ui@1.8.1, @radix-ui/react-slot@1.5.0, react-hook-form@7.91.0, @playwright/test@1.64.1\"}\n**Rule:** If getByLabel can't find a field inside a shadcn FormItem, make the component under <FormControl> accept the rest props and spread them on the real <input> (id, aria-describedby, aria-invalid).\n**Snippet:**\n```tsx\n- export function QuantityInput({ value, onChange, onBlur, invalid, decimals, unit }: { … }) {\n+ export function QuantityInput({ value, onChange, onBlur, invalid, decimals, unit, className, ...props }:\n+   Omit<React.ComponentProps<\"input\">, \"value\" | \"onChange\" | \"onBlur\"> & { … }) {\n    return (\n      <div className={…}>\n-       <input inputMode=\"decimal\" value={raw} … />\n+       <input {...props} inputMode=\"decimal\" value={raw} … />\n```\n**Check:** the same spec, rebuilt: `getByLabel(\"Quantity\").fill(\"10\")` works and \"add investment: validates, buys…\" passed; the axe run over the sheet with validation shown reports no label violation.\n**Applies to:** radix-ui@>=1.4, react-hook-form@>=7, other: shadcn/ui new-york form.tsx\n**I assumed:** a component inside <FormControl> is labelled by the <FormLabel> above it, like Input, MoneyInput and DatePicker are.\n**What happened:** `locator.fill: Test timeout of 120000ms exceeded. - waiting for getByRole('dialog', { name: 'Add investment' }).getByLabel('Quantity')`. The quantity field (an <input> with a unit after it, wrapped in a div) rendered without an id; the <label for> pointed at nothing.\n**Why:** FormControl is `<Slot.Root id={formItemId} aria-describedby=… aria-invalid=… {...props}>`: Slot merges those props into its single child element — here the QuantityInput component, whose props type didn't take them, so they never reached the <input>.\n**The fix:** QuantityInput takes the input's props (minus value, onChange, onBlur) and spreads the rest on the <input>.\n**Evidence:** the timeout above, then \"4 passed (38.4s)\" for the tests that use the field.\n:::\n\n:::lesson{title=\"react-hooks 7.1 fails lint on useCallback/useMemo whose deps it can't prove immutable (`primary?.id`, a helper's result)\" kind=\"newer\" by=\"ai\" packages=\"eslint-plugin-react-hooks@7.1.1, eslint-config-next@16.4.3, react@19.3.1\"}\n**Rule:** If lint says preserve-manual-memoization \"This dependency may be modified later\", derive the primitive first (`const id = obj?.id ?? \"\"`) or drop the manual memo: a plain function is fine.\n**Snippet:**\n```tsx\n- const primary = active.find((account) => account.primary) ?? active[0]\n- const defaults = React.useCallback((): Values => ({ …, accountId: primary?.id ?? \"\" }), [latest, primary?.id])\n- const schema = React.useMemo(() => makeSchema(earliest), [earliest])\n+ const primaryId = (active.find((account) => account.primary) ?? active[0])?.id ?? \"\"\n+ const defaults = (): Values => ({ …, accountId: primaryId })\n+ const schema = makeSchema(earliest)\n```\n**Check:** `pnpm lint` → exit 0, 0 problems; `pnpm typecheck` exit 0; the sheets' validation tests pass.\n**Applies to:** eslint-plugin-react-hooks@>=7 <8\n**I assumed:** a useCallback that builds form defaults, with every dependency listed, is lint-clean (exhaustive-deps was satisfied).\n**What happened:** `pnpm lint` → 6 errors \"Compilation Skipped: Existing memoization could not be preserved … This dependency may be modified later, which could cause the value to change unexpectedly\" on deps like `[latest, primary?.id]`; after hoisting `primaryId`, two more on `React.useMemo(() => makeSchema(earliest), [earliest])` with `earliest = addDays(latest, 1)`, while an earlier sheet's `useMemo(() => makeSchema(latest), [latest])` passes.\n**Why:** the React Compiler's validation (run by the lint rule even with the compiler off) only keeps a manual memo whose dependencies it can prove don't change after the memo; a property read through `?.` on an object from a query, or a value it treats as possibly mutable, fails that proof. Why `addDays` differs from `workspaceDay` here is not clear.\n**The fix:** hoist the primitive (`primaryId`), make the defaults plain functions, and build the schemas per render (`const schema = makeSchema(earliest)`, cheap).\n**Evidence:** lint output quoted above (6 errors → 2 → 0).\n:::\n\n:::lesson{title=\"shadcn's Drawer header stayed centred though FormSheet passed text-left: the centring is a group-data variant\" kind=\"not-in-docs\" by=\"ai\" packages=\"shadcn@4.22.2, vaul@1.1.2, cn@0.5.0, tailwindcss@4.3.3\"}\n**Rule:** If a shadcn bottom Drawer's header stays centred despite className=\"text-left\", it centres with group-data-[vaul-drawer-direction=bottom]/drawer-content:text-center: override that same variant.\n**Snippet:**\n```tsx\n// before — still centred on a bottom drawer\n<DrawerHeader className=\"border-b text-left\">\n// after\n<DrawerHeader className=\"border-b px-5 text-left group-data-[vaul-drawer-direction=bottom]/drawer-content:text-left\">\n```\n**Check:** /transactions?sheet=new at 390 px: the \"Add transaction\" title and its description start at the drawer's left padding (qa/p8/c-transactions_sheet_new-light-390-part.png).\n**Applies to:** shadcn@>=3, vaul@1\n**I assumed:** `cn(\"… group-data-[…]:text-center …\", \"text-left\")` lets the later text-left win, like any other conflicting utility.\n**What happened:** on phones FormSheet (the create / edit sheets as a full-height drawer) showed its title and description centred while the desktop sheet had them left-aligned (found in the screenshot review).\n**Why:** cn (tailwind-merge rules) only treats classes as conflicting when their variants match; `text-left` and `group-data-[vaul-drawer-direction=bottom]/drawer-content:text-center` both stay, and the variant's selector (an ancestor attribute plus the class) out-ranks the plain class.\n**The fix:** FormSheet's DrawerHeader adds `group-data-[vaul-drawer-direction=bottom]/drawer-content:text-left` (and the sheet's 20px padding).\n**Evidence:** drawer.tsx line 79's class list; the 390 px shot after the fix, 2026-10-30.\n:::\n\n## Testing: unit, smoke and axe\n\nThe last full run, once, on a fresh production build: `pnpm test:unit` 63 passed in 10.3 s, and `playwright test tests/e2e --workers=2` 521 passed, 0 failed, 0 flaky in 38.3 minutes. By spec: a11y 90, smoke 93, phase7-visual 56, responsive 44, shell 33, shell-visual 28, money-visual 28, investments-visual 28, kit-visual 20, phase7 19, money 16, overview 16, investments 13, overview-visual 12, kit 10, phase8 8, appearance 7. Playwright drives the installed Chrome and downloads no browser of its own; the unit tests run under Playwright too, without a server (`playwright.unit.config.ts`).\n\n**Smoke** visits every route in light and dark at 1440 and 390 px: the page's heading and breadcrumb, the theme class on `<html>`, no console errors, no horizontal page scroll, and a full-page screenshot to look at (tests/e2e/smoke.spec.ts):\n\n```ts\nfor (const route of routes) {\n  for (const mode of modes) {\n    for (const viewport of widths) {\n      test(`${route} renders in ${mode} at ${viewport.width}px`, async ({ page, context, baseURL }) => {\n        // the kit is the heaviest page by far (13 charts, two tables, the whole ledger on the client)\n        if (route === \"/dev/kit\") test.slow()\n        const errors = collectErrors(page)\n        await setAppearance(context, baseURL!, { mode })\n        await page.emulateMedia({ colorScheme: mode })\n        await page.setViewportSize(viewport)\n\n        await page.goto(route, { waitUntil: \"networkidle\" })\n        await expect(page.locator(\"h1\")).toBeVisible()\n        const shellRoute = shellRoutes.find((candidate) => candidate.path === route)\n        if (shellRoute) {\n          // inside the shell: its h1, the breadcrumb ending in the same page, the header and the footer\n```\n\n**axe** runs over 45 targets in both modes (90 tests): every route, and the states that only exist after a click — sheets open with their validation shown, rows selected, a chart turned into a table, every Settings tab, the 404 and the error page. It fails on any serious or critical violation (tests/e2e/a11y.spec.ts):\n\n```ts\nconst results = await new AxeBuilder({ page }).withTags([\"wcag2a\", \"wcag2aa\", \"wcag21a\", \"wcag21aa\", \"wcag22aa\", \"best-practice\"]).analyze()\nconst blocking = results.violations.filter((violation) => violation.impact === \"serious\" || violation.impact === \"critical\")\n```\n\n**Responsive** loads each of the 22 routes once per mode and steps the viewport through 1536, 1440, 1280, 1024, 768 and 390 px, asserting that the document, the shell's scroller and `#main` never scroll sideways. **Unit** tests pin the data layer (above), the walk and the feed, the formatters, and the loan and invoice maths. Pages with live prices are tested with the feed frozen, and two more hooks exist for tests: `window.__meridianFailRender = 1` makes the Settings page throw after it mounts, to show the error page, and `?print=1` opens an invoice's print dialog.\n\nThe screenshots caught what the tests didn't: an expense delta compared against the wrong days, net-worth markers running off the plot, a select-all box showing a full tick, invisible skeletons, hero figures cut to \"$119.…\" in a phone's half-width tile. The tests caught what the eye didn't: a CSV with only its header, a \"Create …\" row that never appeared and a 404 page served with status 200.\n\n![Finance overview, Equities live in dark, and invoice #5099 on three phones](/article-images/01a18e3a-2718-778e-b28b-e9993978f6a3)\n\n:::lesson{title=\"A Playwright “no console errors” check fails on Chrome's own /favicon.ico 404, which no response event shows\" kind=\"not-in-docs\" by=\"ai\" packages=\"@playwright/test@1.64.1, next@16.4.3\"}\n**Rule:** If a Playwright console check fails with \"Failed to load resource: … 404 (Not Found)\" but no page response is a 404, it is Chrome asking for /favicon.ico: give the app an icon (Next: app/icon.svg).\n**Snippet:**\n```ts\npage.on(\"console\", (m) => { if (m.type() === \"error\") errors.push(m.text()) })\npage.on(\"response\", (r) => { if (r.status() >= 400) errors.push(`${r.status()} ${r.url()}`) }) // stays empty\n// fix: add src/app/icon.svg\n```\n**Check:** `pnpm build` lists `○ /icon.svg`; `pnpm test` → `3 passed (12.3s)` (before: `2 failed`, `1 passed (15.0s)`).\n**Applies to:** @playwright/test@>=1.64 <2, next@>=16.4 <17\n**I assumed:** a fresh Next.js page with no images or fetches loads without a single failed request.\n**What happened:** both page tests failed: `+ \"Failed to load resource: the server responded with a status of 404 (Not Found)\"`. A `page.on(\"response\")` listener recording every status ≥ 400 recorded nothing.\n**Why:** likely the browser's automatic favicon request, which is not one of the page's network events; the app declared no icon. Adding one made the error go away.\n**The fix:** added src/app/icon.svg (the brand monogram); Next emits `<link rel=\"icon\" href=\"/icon.svg?…\">` and Chrome no longer asks for /favicon.ico.\n**Evidence:** Playwright output before and after, 2026-10-28 (installed Chrome 156.0.8078.48, channel \"chrome\").\n:::\n\n:::lesson{title=\"Tailwind's sr-only is position:absolute: a scroll rail without `relative` doesn't clip its cards' hidden text\" kind=\"not-in-docs\" by=\"ai\" packages=\"tailwindcss@4.3.3, next@16.4.3, @playwright/test@1.64.1\"}\n**Rule:** If a horizontal `overflow-x-auto` rail of cards still widens the page, give the rail `relative`: the cards' `sr-only` spans are absolute and clip only inside their containing block.\n**Snippet:**\n```tsx\n// a phone rail of cards that each hold sr-only text (an InsightCard's \"Why?\" label, <Money>'s \"Amount hidden\")\n- <div className=\"-mx-4 flex snap-x snap-mandatory gap-3 overflow-x-auto px-4 scrollbar-none md:grid md:grid-cols-3\">\n+ <div className=\"relative -mx-4 flex snap-x snap-mandatory gap-3 overflow-x-auto px-4 scrollbar-none md:grid md:grid-cols-3\">\n```\n**Check:** re-shot qa/page-finance-light-390.png and …-dark-390.png are 390 px wide (were 710); the phone test asserts the rail scrolls inside itself (`scrollWidth > clientWidth`) and the page doesn't.\n**Applies to:** tailwindcss@>=3 <5\n**I assumed:** an element with `overflow-x: auto` clips everything inside it, so three 85%-wide insight cards on a 390px phone only scroll inside their rail.\n**What happened:** the full-page 390px screenshot of /dashboard/finance came out 710 × 3821 px: with the shell's panel opened up for the shot (`overflow: visible`), `document.documentElement.scrollWidth` was 710, and only the cards' `span.sr-only` (position: absolute) sat outside the rail's clip. The live page didn't scroll sideways (the panel's own overflow hid it), so the overflow check passed.\n**Why:** an overflow container clips an absolutely positioned descendant only when it is, or contains, that descendant's containing block. The rail had no `position`, so the spans were placed against the nearest positioned ancestor (SidebarInset, `relative`) — outside the rail.\n**The fix:** `relative` on the rail (features/finance/finance-kpis.tsx).\n**Evidence:** probe on 2026-10-28: \"span.sr-only right=393 pos=absolute\" for the second card; PNGs 710×3821 before, 390×3821 after.\n:::\n\n### What the listing pictures found\n\nThe listing's pictures were shot at 1440 × 900 after phase 8, and they found three layout faults that every suite had passed. One was the app's own markup: a chart card's \"…\" menu wrapped alone under its description because it was the last item of a single flex-wrap row; `chart-card.tsx` now keeps the title and actions in a wrapping column of their own, with the menu outside it. The other two are lessons below, and each now has a test that fails on the old build (in `investments.spec.ts` and `shell.spec.ts`).\n\n:::lesson{title=\"`min-w-0` on a KPI tile's text column let “this month” run under the sparkline: it removed the column's floor\" kind=\"my-mistake\" by=\"ai\" packages=\"tailwindcss@4.3.3\"}\n**Rule:** If nowrap text in a flex row runs under a fixed-width sibling (a chart), drop `min-w-0` from the text column and give the sibling `min-w-0` instead, so the graphic shortens, never the words.\n**Snippet:**\n```tsx\n// before\n<div className=\"flex min-w-0 flex-col gap-1.5\">{delta}</div>\n<div className=\"shrink-0 h-12 w-40\">{chart}</div>\n// after\n<div className=\"flex shrink-100 flex-col gap-1.5\">{delta}</div>\n<div className=\"min-w-0 h-12 w-40\">{chart}</div>\n```\n**Check:** a probe of every tile with a chart on 19 routes at 1280/1440/1920 (1× and 2×), 1024, 768 and 390 (the five KPI pages also in dark): the column's text rects never meet the chart (the old build overlapped in every 1280/1440 capture of Equities, Crypto and Mutual funds).\n**Applies to:** other: CSS flexbox (min-width: auto of flex items), tailwindcss@4\n**I assumed:** `min-w-0` on the delta column was the usual guard for truncation inside a flex row, and the `shrink-0` sparkline (w-40 in the hero) always had room.\n**What happened:** four KPIs across at 1280–1440 px left the hero's column 5–45 px wide; its \"this month\" (whitespace-nowrap) spilled 40–55 px into the sparkline on Equities, Crypto and Mutual funds. On Finance at 1280 px, \"vs September\" ended against Payment volume's chart (column 69 px for 80 px of words, the 12 px gap absorbed it).\n**Why:** a flex item's automatic minimum width is its min-content width; `min-w-0` replaces it with 0, so the column shrank below its words while the `shrink-0` chart kept all of its 160 px.\n**The fix:** stat-card.tsx (398da7e): the column has no `min-w-0` and `shrink-100` (it gives way first: the comparison wraps under the pill), the chart `min-w-0` (it shortens after). Hero sparkline 100 px at 1280, 140 at 1440, 160 from 1920; where everything fits nothing moves.\n**Evidence:** before/after crops of the Equities and Crypto tiles in light and dark at 1440 @2×; investments.spec \"four KPIs across at 1280 and 1440px\" fails on the old build (\"text ends 55px into the sparkline\").\n:::\n\n:::lesson{title=\"The floating scroll-to-top button sat on the footer's “Support” link at the end of every page from 768 to ~1600 px\" kind=\"my-mistake\" by=\"ai\" packages=\"tailwindcss@4.3.3\"}\n**Rule:** If a floating corner button covers a footer link at a page's end, reserve its room only where the centred row meets the edge: `margin-right: max(0px, calc(<room> - (100cqw - 100%) / 2))`.\n**Snippet:**\n```tsx\n// app-footer.tsx — before\n<footer className=\"mt-auto px-4 lg:px-6\">\n  <nav aria-label=\"Legal and support\" className=\"flex items-center gap-4 sm:ml-auto\">\n// after: the footer is a size container; the links keep the button's room only where the row meets the edge\n<footer className=\"@container mt-auto px-4 lg:px-6\">\n  <nav aria-label=\"Legal and support\" className=\"mr-[max(0px,calc(3.75rem-(100cqw-100%)/2))] flex items-center gap-4 sm:ml-auto\">\n```\n**Check:** at the page's end: no footer link under the button at 1440/1024/768 in Compact and Full and at the XL scale; \"Support\" → button 31 px; at 1920 Compact and on phones the crops are byte-identical to the old build. shell.spec \"at a page's end scroll-to-top sits clear\" fails on the old build.\n**Applies to:** other: CSS container query units (cqw) with percentage margins, tailwindcss@4\n**I assumed:** the button, 20 px above the panel's bottom and 32 px in from its edge, cleared the one-line footer.\n**What happened:** at a page's end it covered \"Support\" (37 px into the footer band) at 768, 1024, 1280 and 1440 px in the Compact layout and at every width in Full; at 1920 Compact the centred 1440 px row ended 80 px from the edge, so nothing touched.\n**Why:** the footer row is `max-w-content mx-auto`; it reaches the edge whenever the panel is narrower than 1440 px plus its padding, or the layout is Full.\n**The fix:** app-footer.tsx (398da7e): the footer is `@container`; the links' nav has `mr-[max(0px,calc(3.75rem-(100cqw-100%)/2))]`: the button's 2.25rem + its 2rem inset + a 1rem gap − the footer's 1.5rem padding, less the centring margin (100cqw = the footer's width, 100% = the row's).\n**Evidence:** before/after crops at 1440 @2× light and dark; a Full-layout probe (old: −29 px, new: +31 px).\n:::\n\n## Takeaways\n\n- Generate the ledger from the records and steer each month with one balancing row; derive every KPI with a selector; pin both the reference figures and the invariants in unit tests.\n- Put the mock behind the hooks a real API would use: one `fetchFromBook` to swap, a key per entity and filter, mutations that invalidate.\n- Make every payment a transaction with an undo, so balances, histories and net worth can't drift apart.\n- For live data, seed the walk by symbol and tick, bound it, run it only while it's watched, reprice per section with the data layer's own function, and animate only opacity and transform.\n- On dynamic routes with a `loading.tsx`, prefetch on intent and call `notFound()` in a layout.\n- Measure contrast from the tokens file, composites included, fail the build below AA, and keep raw colours out of the source with a guard.\n- Shoot the pages at real widths: the pictures found faults that every test passed.\n\n## Make it yours\n\nThe release ZIP is the whole Next.js project: `pnpm install`, then `pnpm dev`.\n\n- **Your data:** replace `fetchFromBook` in `src/lib/queries/client.tsx` with a fetch to your backend, and point each `dataActions` call in `src/lib/data/store.ts` at a mutation.\n- **Your name and links:** `src/lib/site-config.ts`; every wordmark, page title, invoice and e-mail template follows it.\n- **Your colours:** a `[data-preset]` block in `globals.css` and an entry in `presets` (`src/lib/appearance.ts`), then `pnpm check:contrast`.\n- **The demo:** `NEXT_PUBLIC_DEMO_TODAY=2026-10-28` freezes \"today\" and `NEXT_PUBLIC_DEMO_FAST=1` drops the latency; `/dev/tokens` and `/dev/kit` show every token and component and answer 404 in production.\n\nLeft to you by design: nothing runs on its own date (reminders, auto-send and autopay are stored, not executed), a reload resets the book, entities keep their own currencies without FX, and the saved time zone and language aren't applied yet.",
  "bodySha256": "da32663bdfdfdca749fc7ddac46a4bb120b6628c18c9bc412c4c07f51c7f60e4",
  "format": 2,
  "kind": "behind-the-build",
  "product": "nextjs-finance-dashboard-template",
  "productRevision": null,
  "publishedAt": "2026-10-30T19:30:58.094Z",
  "revision": 2,
  "site": "https://upfork.dev",
  "summary": "How Meridian, a 22-screen Next.js and shadcn/ui finance dashboard, derives every KPI, chart and table from one seeded book, ticks prices in a bounded walk, and 24 traps fixed on the way.",
  "title": "How to build a finance dashboard where every number agrees: one seeded book, live prices",
  "type": "article-version",
  "url": "https://upfork.dev/articles/how-to-build-a-finance-dashboard-where-every-number-agrees-one-seeded-book-l"
}