release: v0.0.2-beta — metrics-display redesign wave 1

Replaces hand-rolled bar divs / 30-day grid with a token-driven
chart layer: YearHeatmap on /dashboard and /metrics, TypeBreakdown
donut+barlist on /metrics Overview, plus the foundational MetricCard
shell + lib helpers (feature-flags, telemetry, recharts theme bridge)
so subsequent waves can layer in without rebuilding the chart contract.

Six review passes (3 on strategic plan, 3 on impl plan, 3 on this
PR) caught the load-bearing issues: timeline server cap mismatch
(90 vs 365), telemetry firing for flag-disabled cards, SSR cache
poisoning in the telemetry consent path, and an incorrect column-
math in the year heatmap. All resolved before this commit.

Notable bumps:
  - workspace 0.0.1-beta → 0.0.2-beta
  - tauri.conf.json 0.0.1 → 0.0.2
  - TIMELINE_DAYS_MAX 90 → 366 in validation.rs (so the YearHeatmap
    can request a 365-day window)
  - recharts ^3.8.1 added to apps/web

The cross-cutting checklist (a11y srTable / empty / error / flag /
telemetry) is enforced at the type system level — `MetricCard` makes
those five props required with no defaults, so cards that skip any
fail `tsc` rather than silently degrading.

Migration 0021_share_scopes.sql ships ahead of any consumer to
future-proof the planned cross-user aggregate endpoints; column is
additive with conservative defaults.

Verification: cargo test (271 pass), pnpm typecheck clean, next
build compiled successfully, cargo fmt clean.

Plan docs at docs/DESIGN-METRICS-PLAN.md (strategic) and
docs/DESIGN-METRICS-IMPLEMENTATION-PLAN.md (execution) capture both
rounds of review findings.

Author: Nigel Tatschner

CHANGELOG.md

@@ -32,6 +32,63 @@ Tag-suffix → release-channel mapping (see `release-manifests/`):
 
 - (nothing yet)
 
+## [0.0.2-beta] — 2026-05-12
+
+Metrics-display redesign, first wave. Replaces the hand-rolled 30-day
+heatmap on the dashboard with a GitHub-style 53-week heatmap, and
+rewires the metrics page's Overview tab with a donut+barlist Type
+breakdown alongside the heatmap. Foundational shell + lib helpers
+land so subsequent waves can layer in without rebuilding the chart
+contract.
+
+### Added
+
+- **Web:** `YearHeatmap` component — 53-week GitHub-style activity
+  heatmap, inline SVG, renders against the `--grid-*` token ladder
+  for theme reactivity. Shown on `/dashboard` and `/metrics` Overview.
+- **Web:** `TypeBreakdown` component — recharts donut + ranked-bar
+  combo replacing the manual `<div>` bars previously on the metrics
+  Overview tab.
+- **Web:** `SparklinePill` component — small stat tile with inline
+  sparkline. Foundation for upcoming dashboard pill upgrades.
+- **Web:** `MetricCard` + `ChartCard` shells. Required-props pattern
+  (`flagKey`, `telemetryKey`, `empty`, `error`, `srTable`) enforces
+  the cross-cutting checklist (feature-flag gate, telemetry hook,
+  empty/error states, screen-reader fallback) at the TypeScript
+  level — cards that skip any of these fail `tsc`.
+- **Web:** Typed feature-flag registry (`lib/feature-flags.ts`) for
+  the metrics surfaces. All flags default on for v0.0.2-beta; the
+  `metrics.now_strip` flag stays off (cut per the impl plan).
+- **Web:** Frontend telemetry helper (`lib/metrics-telemetry.ts`).
+  Opt-in (off by default via `localStorage["starstats.telemetry"]`).
+  Server endpoint to receive POSTs is a follow-up.
+- **Web:** Recharts theme bridge (`lib/recharts-theme.ts`) — reads
+  `ss-*` CSS-var hex values from `:root` and re-renders on
+  `data-theme` mutations so chart colours swap with the active theme.
+- **Server:** Migration `0021_share_scopes.sql` — adds a per-user
+  `share_scopes` JSONB column with conservative defaults (own data
+  only for everything except summary, which defaults to friend).
+  Future-proofs the planned cross-user aggregate endpoints; no code
+  consumes the column yet.
+- **Dep:** `recharts ^3.8.1` in `apps/web`.
+
+### Changed
+
+- **Server:** Bumped `TIMELINE_DAYS_MAX` from 90 to 366 in
+  `validation.rs` so `YearHeatmap` callers can request a 365-day
+  window without tripping the validator. Existing
+  `timeline_rejects_days_above_max` test updated accordingly.
+- **Web:** `/dashboard` and `/metrics` now request a 365-day timeline
+  (was 30). DayHeatmap still renders cleanly with the wider window.
+- **Versions:** Workspace `0.0.1-beta → 0.0.2-beta`,
+  `tauri.conf.json` `0.0.1 → 0.0.2`.
+
+### Documentation
+
+- Added `docs/DESIGN-METRICS-PLAN.md` (strategic plan) and
+  `docs/DESIGN-METRICS-IMPLEMENTATION-PLAN.md` (execution plan,
+  reflecting two rounds of independent review findings).
+
 ## [0.0.1-beta] — 2026-05-11
 
 Fresh start on the `beta` channel after the alpha history scrub.

Cargo.lock

@@ -7,7 +7,7 @@ members = [
 ]
 
 [workspace.package]
-version = "0.0.1-beta"
+version = "0.0.2-beta"
 edition = "2021"
 license = "MPL-2.0"
 authors = ["StarStats contributors"]

Cargo.toml

@@ -13,19 +13,20 @@
     "test:e2e:install": "playwright install --with-deps chromium"
   },
   "dependencies": {
-    "api-client-ts": "workspace:*",
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/auto-instrumentations-node": "^0.75.0",
     "@opentelemetry/exporter-trace-otlp-grpc": "^0.217.0",
     "@opentelemetry/resources": "^2.7.1",
     "@opentelemetry/sdk-node": "^0.217.0",
     "@opentelemetry/semantic-conventions": "^1.40.0",
     "@sentry/node": "^10.52.0",
+    "api-client-ts": "workspace:*",
     "next": "15.5.18",
     "pino": "^9.6.0",
     "prom-client": "^15.1.3",
     "react": "19.0.0",
     "react-dom": "19.0.0",
+    "recharts": "^3.8.1",
     "server-only": "^0.0.1"
   },
   "devDependencies": {

apps/web/package.json

@@ -28,6 +28,7 @@ import { DayHeatmap } from '@/components/DayHeatmap';
 import { HangarCard } from '@/components/HangarCard';
 import { OrgsCard } from '@/components/OrgsCard';
 import { ProfileCard } from '@/components/ProfileCard';
+import { YearHeatmap } from '@/components/metrics/YearHeatmap';
 
 const PAGE_LIMIT = 50;
 
@@ -75,7 +76,10 @@ export default async function DashboardPage(props: {
           since,
           until,
         }),
-        getTimeline(session.token, { days: 30 }),
+        // Bumped from 30 to 365 days to feed the YearHeatmap card.
+        // DayHeatmap still renders cleanly with the wider window
+        // (it walks `buckets` directly).
+        getTimeline(session.token, { days: 365 }),
         // Location resolver — 204 means "no recent activity", which
         // we treat as null and the pill renders nothing.
         getCurrentLocation(session.token).catch((e) => {
@@ -342,6 +346,10 @@ export default async function DashboardPage(props: {
             </div>
           </section>
 
+          {/* Year view — GitHub-style 53-week grid. Same timeline
+              data, wider window. Card-styled via MetricCard shell. */}
+          <YearHeatmap timeline={timeline} />
+
           <div
             data-rspgrid="2"
             style={{

apps/web/src/app/dashboard/page.tsx

@@ -214,3 +214,119 @@ main h1 {
     opacity: 1;
   }
 }
+
+/* ---- Metrics redesign (v0.0.2-beta) -------------------------------
+ * Cards, pills, and chart shells consumed by `components/metrics/*`.
+ * Token-driven so theme swaps just repaint.
+ * ----------------------------------------------------------------- */
+
+/* Screen-reader-only utility. Used by `MetricCard` for the table
+ * fallback that mirrors each chart's data for keyboard / SR users. */
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+.metric-card {
+  display: flex;
+  flex-direction: column;
+}
+.metric-card__header {
+  padding: 20px 24px 0;
+  display: flex;
+  justify-content: space-between;
+  align-items: flex-start;
+  gap: 12px;
+}
+.metric-card__title {
+  margin: 0;
+  font-size: 17px;
+  font-weight: 600;
+  letter-spacing: -0.01em;
+}
+.metric-card__caption {
+  margin: 6px 0 0;
+  color: var(--fg-muted);
+  font-size: 13px;
+}
+.metric-card__body {
+  padding: 16px 24px 22px;
+}
+.metric-card__empty,
+.metric-card__error {
+  padding: 24px;
+  color: var(--fg-muted);
+  font-size: 14px;
+}
+.metric-card__error {
+  color: var(--danger);
+}
+.metric-card__badge {
+  font-size: 11px;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  padding: 4px 8px;
+  border-radius: var(--r-pill);
+  background: var(--surface-2);
+  border: 1px solid var(--border);
+  color: var(--fg-muted);
+  cursor: help;
+}
+.metric-card__badge--best-effort {
+  color: var(--warn);
+  border-color: var(--warn);
+}
+.chart-card__chart {
+  padding: 0 24px;
+}
+
+.sparkline-pill {
+  flex: 1 1 0;
+  min-width: 0;
+  padding: 12px 14px;
+  border-radius: var(--r-md);
+  background: var(--surface);
+  border: 1px solid var(--border);
+}
+.sparkline-pill__head {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+}
+.sparkline-pill__value {
+  font-size: 22px;
+  font-weight: 600;
+  font-family: var(--font-mono);
+  letter-spacing: -0.01em;
+}
+.sparkline-pill__label {
+  font-size: 12px;
+  color: var(--fg-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+}
+.sparkline-pill__svg {
+  display: block;
+  margin-top: 6px;
+}
+.sparkline-pill__svg--empty {
+  height: 28px;
+  background: var(--surface-2);
+  border-radius: var(--r-xs);
+}
+.sparkline-pill__caption {
+  margin-top: 4px;
+  font-size: 11px;
+  color: var(--fg-dim);
+}
+
+.year-heatmap {
+  scrollbar-width: thin;
+}

apps/web/src/app/globals.css

@@ -34,6 +34,8 @@ import {
 } from '@/lib/api';
 import { formatEventSummary } from '@/lib/event-summary';
 import { getSession } from '@/lib/session';
+import { YearHeatmap } from '@/components/metrics/YearHeatmap';
+import { TypeBreakdown } from '@/components/metrics/TypeBreakdown';
 
 const TAB_IDS = ['overview', 'types', 'sessions', 'raw'] as const;
 type TabId = (typeof TAB_IDS)[number];
@@ -85,7 +87,7 @@ export default async function MetricsPage(props: {
     if (view === 'overview') {
       const [s, t, ts, recent, hdr] = await Promise.all([
         getSummary(session.token),
-        getTimeline(session.token, { days: 30 }),
+        getTimeline(session.token, { days: 365 }),
         getMetricsEventTypes(session.token, '30d'),
         getMetricsSessions(session.token, { limit: 5 }),
         getMetricsSessions(session.token, { limit: HEADER_SESSION_PROBE_LIMIT }),
@@ -436,6 +438,23 @@ function OverviewTab({
         />
       </div>
 
+      {/* Year-view activity heatmap — successor to the 30-day grid.
+          Reads the same `timeline` data (now 365-day window). */}
+      {timeline ? <YearHeatmap timeline={timeline} /> : null}
+
+      {/* Donut + ranked-bar combo replacing the manual bar divs that
+          previously occupied the Types tab. Lives on Overview too so
+          the breakdown is visible without a tab change. */}
+      {typesBreakdown ? (
+        <TypeBreakdown
+          types={typesBreakdown.types.map((t) => ({
+            event_type: t.event_type,
+            count: t.count,
+          }))}
+          caption={`${typesBreakdown.types.length} distinct types`}
+        />
+      ) : null}
+
       <div
         data-rspgrid="2"
         style={{

apps/web/src/app/metrics/page.tsx

@@ -0,0 +1,27 @@
+/**
+ * ChartCard — MetricCard variant tuned for chart layouts.
+ *
+ * Same required props as MetricCard. Adds `height` for the chart area
+ * (recharts needs an explicit pixel height inside a flex parent).
+ */
+
+'use client';
+
+import type { ReactNode } from 'react';
+import { MetricCard, type MetricCardProps } from './MetricCard';
+
+export interface ChartCardProps extends Omit<MetricCardProps, 'children'> {
+  height?: number;
+  children: ReactNode;
+}
+
+export function ChartCard(props: ChartCardProps) {
+  const { height = 220, children, ...rest } = props;
+  return (
+    <MetricCard {...rest}>
+      <div className="chart-card__chart" style={{ height }}>
+        {children}
+      </div>
+    </MetricCard>
+  );
+}