analdash: split the dashboard into Acquisition, Product, and Link codes pages

The single 1220-line `+page.svelte` had grown too dense to navigate or edit safely. Reorganize it
into a multi-page app under a shared layout, with no behavior change — same charts, blurbs, tooltips,
and range/day selection, just split and componentized.

- Three routes under one `+layout.svelte` shell (sticky header: brand, page nav, range/day picker):
  - `/` Acquisition: daily funnel + channels, awareness, interest, download.
  - `/product` Product: active use, payment, retention, feedback & errors.
  - `/links` Link codes: a stub (heading + "coming soon") so the skeleton and nav entry exist; the
    `?r=` short-link CRUD lands here next. The picker is hidden here (no time window applies).
- Nav marks the active page (`aria-current="page"` + accent), sentence case, reusing existing tokens.
- Shared selection: `+layout.server.ts` resolves the `DashboardSelection` from `?range=`/`?day=` for
  the picker, and each page's `+page.server.ts` re-resolves it for its own fetch, so switching pages
  preserves the selection. The funnel stays a fixed last-30-days view.
- Data loading splits per page: `fetch-all.ts` now exposes per-source loaders plus `fetchAcquisitionData`
  / `fetchProductData` composers, so each page fetches only the sources it renders. The Cloudflare
  source (downloads + heartbeat + update activity) is shared by both pages but cached per selection, so
  it's one fetch, not two. `fetchDashboardData` (all sources) still backs the report endpoint unchanged.
- Componentized the giant page into `lib/components/sections/*` plus shared UI (FunnelTable, CountryTable,
  MetricRow/MetricTable, ErrorState/EmptyState/BetaEmptyState, SectionDescription, Methodology,
  ExternalLinks) and client-safe helpers (`format.ts`, `colors.ts`, `chart-helpers.ts`). Each route file
  is now a few dozen lines.
- Tests: add `fetch-all.subset.test.ts` pinning that each page loads exactly its source subset (and the
  report loads the union). All 88 dashboard tests pass; svelte-check and `pnpm build` are clean.
- Docs: rewrite the page map in `CLAUDE.md` and add `DETAILS.md` (structure, the loading split, the
  shared-Cloudflare-cache rationale, and the client/server import-boundary gotcha that only `pnpm build`
  catches, not svelte-check).

Author: vdavid

apps/analytics-dashboard/CLAUDE.md

@@ -1,7 +1,22 @@
 # Analytics dashboard
 
-Private SvelteKit dashboard consolidating Cmdr business metrics into a single view, organized by acquisition stage.
-Deployed to Cloudflare Pages at `analdash.getcmdr.com`. Auth via Cloudflare Access (zero-trust, no application code).
+Private SvelteKit dashboard consolidating Cmdr business metrics, organized by acquisition stage across a few pages under
+a shared top nav. Deployed to Cloudflare Pages at `analdash.getcmdr.com`. Auth via Cloudflare Access (zero-trust, no
+application code).
+
+## Pages and where each section lives
+
+Three routes share `+layout.svelte` (sticky header: brand, nav, and the range/day picker). The picker is hidden on
+`/links`. Full structure, the data-loading split, and the componentization are in `DETAILS.md` § "Multi-page structure".
+
+- `/` (Acquisition, `routes/+page.svelte`): daily funnel + channels, awareness, interest, download.
+- `/product` (Product, `routes/product/+page.svelte`): active use, payment, retention, feedback & errors.
+- `/links` (Link codes, `routes/links/+page.svelte`): a stub for `?r=` short-link CRUD, filled in later. No data load.
+
+Each section is a component under `src/lib/components/sections/`; shared bits (funnel table, country table, metric
+row/table, state panels, descriptions) are in `src/lib/components/`. Don't import `$lib/server/*` as a runtime value
+into any of these (browser-bundled) — type-only is fine. The build's `vite-plugin-sveltekit-guard` enforces this;
+svelte-check does NOT catch it, so run `pnpm build` before declaring a client/server-boundary change done.
 
 ## Stack
 
@@ -12,21 +27,27 @@ Deployed to Cloudflare Pages at `analdash.getcmdr.com`. Auth via Cloudflare Acce
 
 ## Key files
 
-| File                                        | Purpose                                                                                                                                                                        |
-| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `src/app.css`                               | Tailwind v4 theme (dark palette matching getcmdr.com)                                                                                                                          |
-| `src/app.d.ts`                              | Platform env type declarations for CF Pages                                                                                                                                    |
-| `src/routes/+page.svelte`                   | Single-page dashboard: a top "Daily funnel" table, then 6 acquisition stages plus feedback & errors                                                                            |
-| `src/routes/+page.server.ts`                | Server load: reads `?range=` and `?day=` params, delegates to `fetch-all.ts`                                                                                                   |
-| `src/routes/api/report/+server.ts`          | Agent-readable plain-text report (includes the daily funnel) with all breakdowns                                                                                               |
-| `src/lib/server/fetch-all.ts`               | Shared data-fetching logic used by both the page and report API                                                                                                                |
-| `src/lib/components/Chart.svelte`           | Reusable uPlot chart with ResizeObserver and dark theme                                                                                                                        |
-| `src/lib/components/StackedBarChart.svelte` | Discrete per-day stacked bars (plain elements, not uPlot) with an exact-numbers hover/focus tooltip. Used for the by-source new-installs chart and the by-version update chart |
-| `src/lib/server/types.ts`                   | Shared types: `TimeRange`, `DashboardSelection`, `SourceResult`, time window + selection helpers                                                                               |
-| `src/lib/server/cache.ts`                   | CF Cache API wrapper with in-memory Map fallback for local dev                                                                                                                 |
-| `src/lib/server/sources/`                   | Data source modules (one per external API)                                                                                                                                     |
-| `svelte.config.js`                          | Adapter-cloudflare config                                                                                                                                                      |
-| `vitest.config.ts`                          | Vitest config for unit tests                                                                                                                                                   |
+- `src/app.css`: Tailwind v4 theme (dark palette matching getcmdr.com).
+- `src/app.d.ts`: Platform env type declarations for CF Pages.
+- `src/routes/+layout.svelte`: shared shell — sticky header, page nav, and the range/day picker (hidden on `/links`).
+- `src/routes/+layout.server.ts`: resolves the shared `DashboardSelection` from `?range=` / `?day=` once for the layout.
+- `src/routes/+page.{svelte,server.ts}`: Acquisition page; loads the funnel/Umami/Cloudflare/GitHub/PostHog subset.
+- `src/routes/product/+page.{svelte,server.ts}`: Product page; loads the Cloudflare/Paddle/license/feedback subset.
+- `src/routes/links/+page.svelte`: Link codes stub (no data load).
+- `src/routes/api/report/+server.ts`: agent-readable plain-text report (all sections, via `fetchDashboardData`).
+- `src/lib/server/fetch-all.ts`: per-source loaders plus the per-page composers (`fetchAcquisitionData`,
+  `fetchProductData`) and the all-sources `fetchDashboardData` for the report.
+- `src/lib/components/sections/`: one component per dashboard section.
+- `src/lib/components/`: shared UI (FunnelTable, CountryTable, MetricRow/MetricTable, ErrorState/EmptyState/
+  BetaEmptyState, SectionDescription, Methodology, ExternalLinks, Chart, StackedBarChart, MiniTimeline, PieChart).
+- `src/lib/{format,colors,chart-helpers}.ts`: client-safe formatters, color tokens, and chart data-shaping helpers.
+- `StackedBarChart.svelte`: discrete per-day stacked bars (plain elements, not uPlot) with an exact-numbers hover/focus
+  tooltip; used for the by-source new-installs chart and the by-version update chart.
+- `src/lib/server/types.ts`: shared types: `TimeRange`, `DashboardSelection`, `SourceResult`, time window + selection
+  helpers.
+- `src/lib/server/cache.ts`: CF Cache API wrapper with in-memory Map fallback for local dev.
+- `src/lib/server/sources/`: data source modules (one per external API).
+- `svelte.config.js`: adapter-cloudflare config. `vitest.config.ts`: Vitest config.
 
 ## Running locally
 
@@ -157,7 +178,10 @@ so no Listmonk secret reaches the dashboard.
 
 These colors are used in metric dots, chart strokes, and chart fills. Keep them consistent when adding new UI.
 
-**Decision**: Single page, not multi-page. **Why**: A handful of sections. Scroll is simpler than navigation.
+**Decision**: Split across pages (Acquisition, Product, Link codes) under a shared layout, not one long scroll. **Why**:
+the single page grew too dense. Grouping by stage keeps each route readable and lets each page fetch only the sources it
+renders. The range/day selection stays shared (resolved in the layout, carried in the URL), so switching pages preserves
+it. See `DETAILS.md` § "Multi-page structure".
 
 **Decision**: A "Feedback & errors" section reads the app's own stores via two worker admin endpoints (`/admin/feedback`
 from D1, `/admin/error-reports` from the R2 bucket's `list` with `customMetadata`), not Discord. **Why**: the

apps/analytics-dashboard/DETAILS.md

@@ -0,0 +1,83 @@
+# Analytics dashboard — details
+
+Read this before structural changes. `CLAUDE.md` is the always-loaded summary; this is the depth.
+
+## Multi-page structure
+
+The dashboard is three routes under one shared layout. Each section is its own component; the route files just compose
+sections and pass their loaded data down.
+
+### Routes and sections
+
+- `/` — Acquisition (`routes/+page.svelte`), in render order:
+  - Daily funnel + Channels (`components/FunnelTable.svelte`) — always the last 30 UTC days, independent of the picker.
+  - Awareness (`components/sections/AwarenessSection.svelte`).
+  - Interest (`components/sections/InterestSection.svelte`).
+  - Download (`components/sections/DownloadSection.svelte`), with `CountryTable.svelte` and the per-day pie tooltip.
+- `/product` — Product (`routes/product/+page.svelte`):
+  - Active use (`ActiveUseSection.svelte`), Payment (`PaymentSection.svelte`), Retention (`RetentionSection.svelte`),
+    Feedback & errors (`FeedbackErrorsSection.svelte`).
+- `/links` — Link codes (`routes/links/+page.svelte`): a stub. The `?r=` short-link CRUD lands here later; for now it's
+  a heading + a "coming soon" note, no data load. The layout hides the range/day picker here.
+
+### Shared layout
+
+`routes/+layout.svelte` is the only shell: a sticky header with the brand, the page nav (Acquisition / Product / Link
+codes, active page marked with `aria-current="page"` and the accent background), and the range/day picker. The picker
+writes `?range=` / `?day=` and keeps the current pathname (`${pathname}?range=...`), so switching range on `/product`
+stays on `/product`. It's hidden on `/links`. The "Updated HH:MM" stamp reads `page.data.updatedAt` (set by whichever
+data page is active; absent on `/links`).
+
+`rangeButtons` (the picker's `today/24h/7d/30d` button list) lives as a local const in the layout, NOT in
+`$lib/server/types.ts` — see the boundary gotcha below.
+
+## Data-loading split
+
+`fetch-all.ts` is structured as:
+
+1. **Per-source loaders** (`fetchFunnelSource`, `fetchUmamiSource`, `fetchCloudflareSource`, …): each wraps one source
+   with its env-var guard (`guardedFetch`) and the 20s `withTimeout` cap. One place per source.
+2. **Per-page composers**: `fetchAcquisitionData` runs funnel + Umami + Cloudflare + GitHub + GitHub-stars + PostHog in
+   parallel; `fetchProductData` runs Cloudflare + Paddle + license + feedback-and-errors. Each page's `+page.server.ts`
+   re-resolves the selection from the URL and calls its composer, so a page fetches only what it renders.
+3. **`fetchDashboardData`**: all nine sources, used by the report endpoint (`api/report/+server.ts`) which dumps every
+   section at once. Unchanged contract.
+
+The funnel is always 30 days (`fetchFunnelData` ignores the selection); it's still gated on the worker admin token, with
+Umami and Paddle degrading to dashes inside. Each source returns `SourceResult<T>` (ok+data, or an error string the UI
+shows as "Couldn't load this data").
+
+### The Cloudflare source is shared by both pages
+
+`fetchCloudflareData` returns `downloads` (Download section, on `/`) AND `heartbeatDau` + `updateActivity` (Active use,
+on `/product`) in one fetch. Both pages call `fetchCloudflareSource`. That's intentional, not duplication: the source is
+cached per selection in `cache.ts`, so the two page loads share one cache entry rather than re-fetching. Don't split the
+worker endpoints apart to "load less" — it would fragment the cache key and the 401/timeout degradation, for no gain.
+
+## Selection state
+
+The shared `DashboardSelection` (`{ range, day }`) is resolved from `?range=` / `?day=` in `+layout.server.ts` (for the
+picker UI) and again in each `+page.server.ts` (for that page's fetch); both call the same `resolveSelection`, so they
+agree. A valid `?day=YYYY-MM-DD` forces `range: 'day'`. The funnel row click on `/` navigates to `/?day=<date>`, which
+filters the Acquisition sections to that day and highlights the row. Cache keys include the day (`selectionCacheKey`) so
+two picked days never collide. The whole rationale (why a `DashboardSelection` not a bare `TimeRange`, the coarse-window
+mapping for worker/PostHog sources) is in `CLAUDE.md` § "Key decisions".
+
+## Componentization
+
+- Section components take their `SourceResult<…>` props plus `selection` (so `ErrorState` can build the "Try again"
+  link). They own their own local interaction state — e.g. `DownloadSection` owns the timeline zoom window and the
+  per-day pie tooltip; `CountryTable` owns its hover tooltip and shares the parent's zoom window via props.
+- Shared presentational pieces: `MetricRow`, `MetricTable`, `SectionDescription` (the "what + how reliable" blurb),
+  `Methodology` (the "how this is measured" note), `ErrorState` / `EmptyState` / `BetaEmptyState`, `ExternalLinks`.
+- Pure data shaping lives in `$lib/chart-helpers.ts` (stacking, `aggregateBy`, `buildTimeline`, semver compare, etc.),
+  formatting in `$lib/format.ts`, and color tokens in `$lib/colors.ts`. These are client-safe modules.
+
+## Client/server boundary gotcha
+
+SvelteKit forbids importing `$lib/server/*` as a runtime value into browser-bundled code (components, route `.svelte`
+files). Type-only imports (`import type { DashboardSelection, SourceResult } from '$lib/server/types.js'`) are fine. A
+runtime value import (e.g. a `const`) trips `vite-plugin-sveltekit-guard` at BUILD time — and `svelte-check` does NOT
+catch it. So always run `pnpm build`, not just `pnpm check`, after touching imports across that boundary. Client-shared
+runtime values live outside `$lib/server`: `$lib/funnel.ts`, `$lib/feedback-and-errors.ts`, `$lib/format.ts`,
+`$lib/colors.ts`, `$lib/chart-helpers.ts`.

apps/analytics-dashboard/src/lib/chart-helpers.ts

@@ -0,0 +1,163 @@
+/**
+ * Pure data-shaping helpers for the Download and Active use charts: stacking download/update rows by
+ * day, aggregating by a field, and building per-day timelines. Kept out of the Svelte components so
+ * the section components stay focused on markup. `DownloadRow`/`UpdateActivityRow` are server types
+ * but the shapes are plain data, safe to import into client code.
+ */
+import type { DownloadRow, UpdateActivityRow } from '$lib/server/sources/cloudflare.js'
+
+export interface StackSeries {
+  key: string
+  label: string
+  color: string
+  values: number[]
+}
+
+// Download source colors: website is the product gold, Homebrew an amber, everything else grey.
+export const SOURCE_STACK = [
+  { key: 'website', label: 'Website', color: '#ffc206' },
+  { key: 'homebrew', label: 'Homebrew', color: '#f0883e' },
+  { key: 'other', label: 'Direct / other', color: '#71717a' },
+]
+// Newest release gets the brightest color; the rest cycle, with anything older bucketed as grey.
+export const VERSION_PALETTE = ['#ffc206', '#a78bfa', '#22d3ee', '#8faa3b', '#f0883e', '#f472b6']
+export const COLOR_OLDER = '#71717a'
+
+/** Sorted unique day strings (YYYY-MM-DD, ascending) from a list of rows carrying a `day` field. */
+export function uniqueDays(rows: Array<{ day: string }>): string[] {
+  return [...new Set(rows.map((r) => r.day))].sort()
+}
+
+/** Aligns rows into a per-key map of per-day value arrays (one slot per entry in `days`). */
+function stackByDay<T>(
+  rows: T[],
+  days: string[],
+  getDay: (r: T) => string,
+  getKey: (r: T) => string,
+  getValue: (r: T) => number,
+): Map<string, number[]> {
+  const dayIndex = new Map(days.map((d, i) => [d, i]))
+  const byKey = new Map<string, number[]>()
+  for (const row of rows) {
+    const di = dayIndex.get(getDay(row))
+    if (di === undefined) continue
+    const key = getKey(row)
+    let arr = byKey.get(key)
+    if (!arr) {
+      arr = new Array(days.length).fill(0)
+      byKey.set(key, arr)
+    }
+    arr[di] += getValue(row)
+  }
+  return byKey
+}
+
+/** Downloads stacked by source, using the deduped same-day-distinct count. */
+export function downloadSourceSeries(rows: DownloadRow[], days: string[]): StackSeries[] {
+  const byKey = stackByDay(
+    rows,
+    days,
+    (r) => r.day,
+    (r) => r.source,
+    (r) => r.uniqueDownloads,
+  )
+  return SOURCE_STACK.map((s) => ({ ...s, values: byKey.get(s.key) ?? new Array(days.length).fill(0) })).filter(
+    (s) => s.values.some((v) => v > 0),
+  )
+}
+
+/** Update activity stacked by the version each install was running when it checked. */
+export function updateVersionSeries(rows: UpdateActivityRow[], days: string[]): StackSeries[] {
+  const byKey = stackByDay(
+    rows,
+    days,
+    (r) => r.day,
+    (r) => r.version,
+    (r) => r.updaters,
+  )
+  const versions = [...byKey.keys()].sort(compareSemverDesc)
+  const top = versions.slice(0, VERSION_PALETTE.length)
+  const rest = versions.slice(VERSION_PALETTE.length)
+  const series: StackSeries[] = top.map((v, i) => ({
+    key: v,
+    label: `v${v}`,
+    color: VERSION_PALETTE[i],
+    values: byKey.get(v) ?? new Array(days.length).fill(0),
+  }))
+  if (rest.length > 0) {
+    const olderValues = new Array(days.length).fill(0)
+    for (const v of rest) {
+      const arr = byKey.get(v) ?? []
+      for (let i = 0; i < days.length; i++) olderValues[i] += arr[i] ?? 0
+    }
+    series.push({ key: 'older', label: 'Older', color: COLOR_OLDER, values: olderValues })
+  }
+  return series
+}
+
+/** Aggregates rows by a string field, summing a numeric field. */
+export function aggregateBy(
+  rows: DownloadRow[],
+  groupField: keyof DownloadRow,
+  sumField: keyof DownloadRow,
+): Array<{ x: string; y: number }> {
+  const map = new Map<string, number>()
+  for (const row of rows) {
+    const key = String(row[groupField])
+    map.set(key, (map.get(key) ?? 0) + Number(row[sumField]))
+  }
+  return [...map.entries()].map(([x, y]) => ({ x, y })).sort((a, b) => b.y - a.y)
+}
+
+/** Returns sorted unique day strings and their unix timestamps from download rows. */
+export function getDayAxis(rows: DownloadRow[]): { days: string[]; timestamps: number[] } {
+  const days = [...new Set(rows.map((r) => r.day))].sort()
+  const timestamps = days.map((d) => new Date(d).getTime() / 1000)
+  return { days, timestamps }
+}
+
+/** Builds uPlot [timestamps[], values[]] for a filtered subset, aligned to the full day axis. */
+export function buildTimeline(
+  rows: DownloadRow[],
+  allDays: string[],
+  allTimestamps: number[],
+): [number[], number[]] {
+  const byDay = new Map<string, number>()
+  for (const row of rows) {
+    byDay.set(row.day, (byDay.get(row.day) ?? 0) + row.downloads)
+  }
+  return [allTimestamps, allDays.map((d) => byDay.get(d) ?? 0)]
+}
+
+/** Compares two semver strings, descending (higher version first). */
+export function compareSemverDesc(a: string, b: string): number {
+  const pa = a.split('.').map(Number)
+  const pb = b.split('.').map(Number)
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const diff = (pb[i] ?? 0) - (pa[i] ?? 0)
+    if (diff !== 0) return diff
+  }
+  return 0
+}
+
+/** Finds the max daily download value across a set of groups. */
+export function maxDailyAcrossGroups(
+  rows: DownloadRow[],
+  groupField: keyof DownloadRow,
+  groupKeys: string[],
+  allDays: string[],
+): number {
+  let max = 1
+  for (const key of groupKeys) {
+    const byDay = new Map<string, number>()
+    for (const row of rows) {
+      if (String(row[groupField]) === key) {
+        byDay.set(row.day, (byDay.get(row.day) ?? 0) + row.downloads)
+      }
+    }
+    for (const v of byDay.values()) {
+      if (v > max) max = v
+    }
+  }
+  return max
+}

apps/analytics-dashboard/src/lib/colors.ts

@@ -0,0 +1,13 @@
+/**
+ * The dashboard's shared color tokens. Kept consistent across metric dots, chart strokes, and fills.
+ * See the "Consistent color coding" decision in CLAUDE.md.
+ */
+
+/** getcmdr.com / vdavid/cmdr (the primary product). */
+export const COLOR_GOLD = '#ffc206'
+/** vdavid/mtp-rs (the library repo). */
+export const COLOR_PURPLE = '#a78bfa'
+/** veszelovszki.com (David's personal site). */
+export const COLOR_GREEN = '#8faa3b'
+/** getprvw.com (Prvw product site). */
+export const COLOR_CYAN = '#22d3ee'