token-larper 1.0.0

package/src/client/components/KpiCards.tsx

@@ -0,0 +1,122 @@
+import React, { useMemo } from "react";
+import { ArrowDownRight, ArrowUpRight, Minus } from "lucide-react";
+import { useDashboard } from "../context.tsx";
+import { daysInRange, sparkline, summarize, type RangeTotals } from "../lib/aggregate.ts";
+import { daysInRange as spanDays, formatDay, previousRange } from "../lib/range.ts";
+import { formatCompactNumber, formatCurrency, formatExactNumber } from "../utils.ts";
+
+function Sparkline({ values }: { values: number[] }) {
+  if (values.length < 2 || values.every((v) => v === 0)) return <div className="spark spark-empty" aria-hidden="true" />;
+  const max = Math.max(...values);
+  const w = 100;
+  const h = 28;
+  const pts = values.map((v, i) => [(i / (values.length - 1)) * w, h - 2 - (max > 0 ? (v / max) * (h - 4) : 0)] as const);
+  const line = pts.map(([x, y], i) => `${i ? "L" : "M"}${x.toFixed(2)},${y.toFixed(2)}`).join(" ");
+  const [lx, ly] = pts[pts.length - 1]!;
+  return (
+    <svg className="spark" viewBox={`0 0 ${w} ${h}`} preserveAspectRatio="none" aria-hidden="true">
+      <path d={`${line} L${w},${h} L0,${h} Z`} className="spark-area" />
+      <path d={line} className="spark-line" vectorEffect="non-scaling-stroke" />
+      <circle cx={lx} cy={ly} r="2.2" className="spark-dot" />
+    </svg>
+  );
+}
+
+type DeltaUnit = "percent" | "points" | "days";
+
+function Delta({ current, previous, unit, days }: { current: number; previous: number | null; unit: DeltaUnit; days: number }) {
+  if (previous === null) return <span className="kpi-delta">All recorded usage</span>;
+  const vs = `vs previous ${days} ${days === 1 ? "day" : "days"}`;
+  if (unit === "percent" && previous === 0) {
+    return <span className="kpi-delta">{current > 0 ? `No usage in the previous ${days} days` : `None ${vs}`}</span>;
+  }
+  const diff = unit === "percent" ? ((current - previous) / previous) * 100 : current - previous;
+  const flat = Math.abs(diff) < (unit === "days" ? 0.5 : 0.05);
+  const Icon = flat ? Minus : diff > 0 ? ArrowUpRight : ArrowDownRight;
+  const amount =
+    unit === "percent"
+      ? `${Math.abs(diff) >= 100 ? Math.round(Math.abs(diff)).toLocaleString("en-US") : Math.abs(diff).toFixed(1)}%`
+      : unit === "points"
+        ? `${Math.abs(diff).toFixed(1)} pts`
+        : `${Math.round(Math.abs(diff))} ${Math.round(Math.abs(diff)) === 1 ? "day" : "days"}`;
+  return (
+    <span className="kpi-delta">
+      <Icon size={13} aria-hidden="true" />
+      {!flat && <span className="sr-only">{diff > 0 ? "Up" : "Down"}</span>}
+      {flat ? "No change" : amount} {vs}
+    </span>
+  );
+}
+
+export function KpiCards() {
+  const { data, days, range, harness, costOf, estimated } = useDashboard();
+  const prev = previousRange(range);
+  const current = useMemo(() => summarize(days), [days]);
+  const previous: RangeTotals | null = useMemo(
+    () => (prev ? summarize(daysInRange(data.daily, harness, prev.start, prev.end)) : null),
+    [data.daily, harness, prev?.start, prev?.end]
+  );
+  const rangeDays = spanDays(range.start, range.end);
+  const prevDays = prev?.days ?? 0;
+  const spark = (pick: Parameters<typeof sparkline>[3]) => sparkline(days, range.start, range.end, pick);
+
+  const cost = costOf(current);
+  const unpriced = Math.max(0, current.estimatedCost - current.verifiedCost);
+
+  return (
+    <section className="kpi-grid" aria-label="Summary for the selected range">
+      <article className="kpi">
+        <h3 className="kpi-label">Tokens</h3>
+        <div className="kpi-value">{formatCompactNumber(current.totalTokens)}</div>
+        <p className="kpi-sub">{formatExactNumber(current.totalTokens)} tokens</p>
+        <Delta current={current.totalTokens} previous={previous?.totalTokens ?? null} unit="percent" days={prevDays} />
+        <Sparkline values={spark((d) => d.totalTokens)} />
+      </article>
+
+      <article className="kpi">
+        <h3 className="kpi-label">{estimated ? "Estimated API value" : "Verified cost"}</h3>
+        <div className="kpi-value">{formatCurrency(cost)}</div>
+        <p className="kpi-sub">
+          {estimated
+            ? `${formatCurrency(current.verifiedCost)} verified + ${formatCurrency(unpriced)} estimated`
+            : `${formatCurrency(current.estimatedCost)} estimated API value`}
+        </p>
+        <Delta current={cost} previous={previous ? costOf(previous) : null} unit="percent" days={prevDays} />
+        <Sparkline values={spark((d) => costOf(d))} />
+      </article>
+
+      <article className="kpi">
+        <h3 className="kpi-label">Active days</h3>
+        <div className="kpi-value">
+          {current.activeDays}
+          <span className="kpi-of"> / {rangeDays}</span>
+        </div>
+        <p className="kpi-sub">
+          {current.busiestDay
+            ? `Busiest: ${formatDay(current.busiestDay.period)} · ${formatCompactNumber(current.busiestDay.totalTokens)}`
+            : "No recorded usage"}
+        </p>
+        <Delta current={current.activeDays} previous={previous?.activeDays ?? null} unit="days" days={prevDays} />
+        <Sparkline values={spark((d) => (d.totalTokens > 0 ? 1 : 0))} />
+      </article>
+
+      <article className="kpi">
+        <h3 className="kpi-label">Cache read rate</h3>
+        <div className="kpi-value">{current.cacheHitRate.toFixed(1)}%</div>
+        <p className="kpi-sub">
+          {current.activeDays > 0
+            ? `${formatCurrency(cost / current.activeDays)} per active day · ${formatCompactNumber(current.cacheReadTokens)} cached`
+            : `${formatCompactNumber(current.cacheReadTokens)} cached tokens`}
+        </p>
+        {previous && previous.activeDays === 0 ? (
+          <span className="kpi-delta">No usage in the previous {prevDays} days</span>
+        ) : (
+          <Delta current={current.cacheHitRate} previous={previous?.cacheHitRate ?? null} unit="points" days={prevDays} />
+        )}
+        <div className="kpi-meter" role="meter" aria-valuemin={0} aria-valuemax={100} aria-valuenow={Math.round(current.cacheHitRate)} aria-label="Cache read rate">
+          <span style={{ width: `${Math.min(100, current.cacheHitRate)}%` }} />
+        </div>
+      </article>
+    </section>
+  );
+}

package/src/client/components/RankChip.tsx

@@ -0,0 +1,22 @@
+import React from "react";
+import { Crown } from "lucide-react";
+import { rankFor } from "../lib/rank.ts";
+import { formatCompactNumber } from "../utils.ts";
+
+/** Compact lifetime rank in the header; opens the Rank tab. */
+export function RankChip({ tokens, onOpen, active }: { tokens: number; onOpen: () => void; active: boolean }) {
+  const rank = rankFor(tokens);
+  const label = rank.next
+    ? `${rank.tier.title}, level ${rank.tier.level}. ${formatCompactNumber(rank.toNext)} tokens to ${rank.next.title}. Open rank.`
+    : `${rank.tier.title}, top level. Open rank.`;
+  return (
+    <button type="button" className={`rank-chip ${active ? "is-active" : ""}`} onClick={onOpen} aria-label={label} title={label}>
+      <Crown size={14} aria-hidden="true" />
+      <span className="rank-chip-level">Lv {rank.tier.level}</span>
+      <span className="rank-chip-title">{rank.tier.title}</span>
+      <span className="rank-chip-bar" aria-hidden="true">
+        <span style={{ width: `${rank.progress}%` }} />
+      </span>
+    </button>
+  );
+}

package/src/client/components/SelectMenu.tsx

@@ -0,0 +1,116 @@
+import React, { useEffect, useId, useRef, useState } from "react";
+import { Check, ChevronDown } from "lucide-react";
+
+export interface SelectMenuOption<T extends string> {
+  value: T;
+  label: string;
+  description?: string;
+  visual?: React.ReactNode;
+}
+
+interface Props<T extends string> {
+  label: string;
+  value: T;
+  options: SelectMenuOption<T>[];
+  onChange: (value: T) => void;
+  className?: string;
+  showDescriptionInTrigger?: boolean;
+}
+
+export function SelectMenu<T extends string>({ label, value, options, onChange, className = "", showDescriptionInTrigger = false }: Props<T>) {
+  const [open, setOpen] = useState(false);
+  const rootRef = useRef<HTMLDivElement>(null);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const labelId = useId();
+  const selected = options.find((option) => option.value === value) ?? options[0];
+
+  useEffect(() => {
+    if (!open) return;
+    const selectedIndex = Math.max(0, options.findIndex((option) => option.value === value));
+    rootRef.current?.querySelectorAll<HTMLButtonElement>("[role='option']")[selectedIndex]?.focus();
+    const onPointer = (event: PointerEvent) => {
+      if (!rootRef.current?.contains(event.target as Node)) setOpen(false);
+    };
+    document.addEventListener("pointerdown", onPointer);
+    return () => document.removeEventListener("pointerdown", onPointer);
+  }, [open]);
+
+  function moveFocus(direction: number) {
+    const items = rootRef.current?.querySelectorAll<HTMLButtonElement>("[role='option']");
+    if (!items?.length) return;
+    const current = Array.from(items).findIndex((item) => item === document.activeElement);
+    const next = (current + direction + items.length) % items.length;
+    items[next]?.focus();
+  }
+
+  function choose(next: T) {
+    onChange(next);
+    setOpen(false);
+    triggerRef.current?.focus();
+  }
+
+  return (
+    <div
+      ref={rootRef}
+      className={`select-menu ${className}`.trim()}
+      onBlur={(event) => {
+        if (!event.currentTarget.contains(event.relatedTarget as Node | null)) setOpen(false);
+      }}
+      onKeyDown={(event) => {
+        if (event.key === "Escape" && open) {
+          event.preventDefault();
+          event.stopPropagation();
+          setOpen(false);
+          triggerRef.current?.focus();
+        } else if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+          event.preventDefault();
+          if (!open) setOpen(true);
+          else moveFocus(event.key === "ArrowDown" ? 1 : -1);
+        } else if (open && (event.key === "Home" || event.key === "End")) {
+          event.preventDefault();
+          const items = rootRef.current?.querySelectorAll<HTMLButtonElement>("[role='option']");
+          items?.[event.key === "Home" ? 0 : items.length - 1]?.focus();
+        }
+      }}
+    >
+      <span className="field-label" id={labelId}>{label}</span>
+      <button
+        ref={triggerRef}
+        type="button"
+        className="select-menu-trigger"
+        aria-label={`${label}: ${selected?.label ?? ""}`}
+        aria-haspopup="listbox"
+        aria-expanded={open}
+        onClick={() => setOpen((current) => !current)}
+      >
+        {selected?.visual}
+        <span className="select-menu-copy">
+          <strong>{selected?.label}</strong>
+          {showDescriptionInTrigger && selected?.description && <small>{selected.description}</small>}
+        </span>
+        <ChevronDown size={15} className="select-menu-chevron" aria-hidden="true" />
+      </button>
+      {open && (
+        <div className="select-menu-list" role="listbox" aria-labelledby={labelId}>
+          {options.map((option) => (
+            <button
+              key={option.value}
+              type="button"
+              role="option"
+              aria-selected={option.value === value}
+              className="select-menu-option"
+              onClick={() => choose(option.value)}
+            >
+              {option.visual}
+              <span className="select-menu-copy">
+                <strong>{option.label}</strong>
+                {option.description && <small>{option.description}</small>}
+              </span>
+              {option.value === value && <Check size={15} className="select-menu-check" aria-hidden="true" />}
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/client/components/SettingsDialog.tsx

@@ -0,0 +1,207 @@
+import React, { useEffect, useRef } from "react";
+import { ChevronDown, Power, X } from "lucide-react";
+import type { StartupConfig } from "../../types.ts";
+import { ThemeSettings } from "./ThemeSettings.tsx";
+import type { ImportedTheme, ThemeMode, ThemePalette } from "../themes.ts";
+
+interface Props {
+  startup: StartupConfig | null;
+  startupError: string | null;
+  saving: boolean;
+  themeMode: ThemeMode;
+  palette: ThemePalette;
+  importedTheme: ImportedTheme | null;
+  showRanks: boolean;
+  onClose: () => void;
+  onThemeModeChange: (mode: ThemeMode) => void;
+  onPaletteChange: (palette: ThemePalette) => void;
+  onImportTheme: (theme: ImportedTheme) => void;
+  onShowRanksChange: (showRanks: boolean) => void;
+  onToggleStartup: (enabled: boolean, openBrowserOnBoot?: boolean) => void;
+  onRetry: () => void;
+  onQuit: () => void;
+}
+
+export function SettingsDialog({
+  startup,
+  startupError,
+  saving,
+  themeMode,
+  palette,
+  importedTheme,
+  showRanks,
+  onClose,
+  onThemeModeChange,
+  onPaletteChange,
+  onImportTheme,
+  onShowRanksChange,
+  onToggleStartup,
+  onRetry,
+  onQuit,
+}: Props) {
+  const dialogRef = useRef<HTMLDivElement>(null);
+  const closeRef = useRef<HTMLButtonElement>(null);
+
+  useEffect(() => {
+    const previousFocus = document.activeElement as HTMLElement | null;
+    closeRef.current?.focus();
+    const handleKeys = (event: KeyboardEvent) => {
+      if (event.key === "Escape") onClose();
+      if (event.key !== "Tab") return;
+      const focusable = Array.from(
+        dialogRef.current?.querySelectorAll<HTMLElement>(
+          "button:not([disabled]), summary, textarea:not([disabled]), input:not([disabled]), select:not([disabled]), a[href]"
+        ) ?? []
+      );
+      if (!focusable.length) return;
+      const first = focusable[0];
+      const last = focusable[focusable.length - 1];
+      if (event.shiftKey && document.activeElement === first) {
+        event.preventDefault();
+        last?.focus();
+      } else if (!event.shiftKey && document.activeElement === last) {
+        event.preventDefault();
+        first?.focus();
+      }
+    };
+    window.addEventListener("keydown", handleKeys);
+    return () => {
+      window.removeEventListener("keydown", handleKeys);
+      previousFocus?.focus();
+    };
+  }, [onClose]);
+
+  return (
+    <div className="modal-backdrop" onClick={onClose}>
+      <div
+        ref={dialogRef}
+        className="modal settings-dialog"
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="settings-title"
+        onClick={(e) => e.stopPropagation()}
+      >
+        <header className="modal-header">
+          <div>
+            <h3 id="settings-title">Settings</h3>
+            <p>Appearance, dashboard, and startup</p>
+          </div>
+          <button ref={closeRef} className="icon-btn" aria-label="Close settings" onClick={onClose}>
+            <X size={17} />
+          </button>
+        </header>
+
+        <div className="modal-body">
+          {startupError && <div className="inline-error" role="alert">{startupError}</div>}
+          <ThemeSettings
+            mode={themeMode}
+            palette={palette}
+            importedTheme={importedTheme}
+            onModeChange={onThemeModeChange}
+            onPaletteChange={onPaletteChange}
+            onImportTheme={onImportTheme}
+          />
+          <section className="settings-section" aria-labelledby="settings-dashboard-heading">
+            <div className="settings-section-heading">
+              <h4 id="settings-dashboard-heading">Dashboard</h4>
+            </div>
+            <div className="setting-row">
+              <div className="setting-copy">
+                <strong id="setting-ranks-label">Show ranks</strong>
+                <p>Show the Rank tab and level label in the header.</p>
+              </div>
+              <button
+                type="button"
+                className={`toggle ${showRanks ? "on" : ""}`}
+                role="switch"
+                aria-labelledby="setting-ranks-label"
+                aria-checked={showRanks}
+                onClick={() => onShowRanksChange(!showRanks)}
+              >
+                <span className="toggle-knob" />
+              </button>
+            </div>
+          </section>
+          {startup ? (
+            <>
+              <section className="settings-section" aria-labelledby="settings-startup-heading">
+                <div className="settings-section-heading">
+                  <h4 id="settings-startup-heading">Startup</h4>
+                  <span>{startup.enabled ? "Starts with Windows" : "Manual launch"}</span>
+                </div>
+                <div className="setting-row">
+                  <div className="setting-copy">
+                    <strong id="setting-autostart-label">Start with Windows</strong>
+                    <p>Launch Token Larper when you sign in.</p>
+                  </div>
+                  <button
+                    disabled={saving}
+                    className={`toggle ${startup.enabled ? "on" : ""}`}
+                    role="switch"
+                    aria-labelledby="setting-autostart-label"
+                    aria-checked={startup.enabled}
+                    onClick={() => onToggleStartup(!startup.enabled)}
+                  >
+                    <span className="toggle-knob" />
+                  </button>
+                </div>
+                <div className="setting-row">
+                  <div className="setting-copy">
+                    <strong id="setting-browser-label">Open dashboard at sign-in</strong>
+                    <p>
+                      {startup.enabled
+                        ? "Open the dashboard in your browser after launch."
+                        : "Takes effect when Start with Windows is on."}
+                    </p>
+                  </div>
+                  <button
+                    disabled={saving}
+                    className={`toggle ${startup.openBrowserOnBoot ? "on" : ""}`}
+                    role="switch"
+                    aria-labelledby="setting-browser-label"
+                    aria-checked={startup.openBrowserOnBoot}
+                    onClick={() => onToggleStartup(startup.enabled, !startup.openBrowserOnBoot)}
+                  >
+                    <span className="toggle-knob" />
+                  </button>
+                </div>
+              </section>
+
+              <details className="settings-details">
+                <summary>
+                  Technical details <ChevronDown size={14} aria-hidden="true" />
+                </summary>
+                <dl>
+                  <div>
+                    <dt>Dashboard</dt>
+                    <dd><code>http://127.0.0.1:{startup.port}</code></dd>
+                  </div>
+                  <div>
+                    <dt>Windows startup</dt>
+                    <dd><code>{startup.registryValue || "Not registered"}</code></dd>
+                  </div>
+                  <div>
+                    <dt>Launcher</dt>
+                    <dd><code>{startup.launcherPath}</code></dd>
+                  </div>
+                </dl>
+              </details>
+            </>
+          ) : (
+            <div className="settings-empty">
+              <p>Startup settings are unavailable.</p>
+              <button className="btn" onClick={onRetry}>Try again</button>
+            </div>
+          )}
+        </div>
+
+        <footer className="settings-footer">
+          <span>Token Larper runs on this computer.</span>
+          <button className="settings-quit" onClick={onQuit}>
+            <Power size={14} /> Quit app
+          </button>
+        </footer>
+      </div>
+    </div>
+  );
+}

package/src/client/components/ThemeSettings.tsx

@@ -0,0 +1,131 @@
+import React, { useState } from "react";
+import { ChevronDown } from "lucide-react";
+import { importThemeCss, THEME_PRESETS, type ImportedTheme, type ThemeMode, type ThemePalette } from "../themes.ts";
+import { SelectMenu, type SelectMenuOption } from "./SelectMenu.tsx";
+
+interface Props {
+  mode: ThemeMode;
+  palette: ThemePalette;
+  importedTheme: ImportedTheme | null;
+  onModeChange: (mode: ThemeMode) => void;
+  onPaletteChange: (palette: ThemePalette) => void;
+  onImportTheme: (theme: ImportedTheme) => void;
+}
+
+const SAMPLE_THEME = `:root {
+  --bg: #f7f8f6;
+  --surface: #ffffff;
+  --text: #1f2a23;
+  --accent: #2f5a43;
+  --accent-ink: #ffffff;
+}
+
+.dark {
+  --bg: #141916;
+  --surface: #1b221e;
+  --text: #e8eee7;
+  --accent: #9fcaa8;
+  --accent-ink: #11261a;
+}`;
+
+export function ThemeSettings({ mode, palette, importedTheme, onModeChange, onPaletteChange, onImportTheme }: Props) {
+  const [css, setCss] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [message, setMessage] = useState<string | null>(null);
+
+  function applyPastedTheme() {
+    try {
+      const imported = importThemeCss(css);
+      onImportTheme(imported);
+      setError(null);
+      setMessage("Theme applied.");
+    } catch (cause) {
+      setMessage(null);
+      setError(cause instanceof Error ? cause.message : "Could not read this theme CSS.");
+    }
+  }
+
+  const paletteOptions: SelectMenuOption<ThemePalette>[] = THEME_PRESETS.map((preset) => ({
+    value: preset.id,
+    label: preset.name,
+    description: preset.description,
+    visual: <span className="palette-color" aria-hidden="true" style={{ backgroundColor: mode === "dark" ? preset.darkAccent : preset.accent }} />,
+  }));
+  if (importedTheme) {
+    const colors = importedTheme[mode];
+    paletteOptions.push({
+      value: "custom",
+      label: "Imported theme",
+      description: "Your saved CSS colors",
+      visual: <span className="palette-color" aria-hidden="true" style={{ backgroundColor: colors["--accent"] }} />,
+    });
+  }
+
+  return (
+    <section className="settings-section theme-settings" aria-labelledby="settings-appearance-heading">
+      <div className="settings-section-heading">
+        <h4 id="settings-appearance-heading">Appearance</h4>
+        <span>{mode === "dark" ? "Dark mode" : "Light mode"}</span>
+      </div>
+
+      <div className="theme-mode-row">
+        <span>Color mode</span>
+        <div className="segmented" role="group" aria-label="Color mode">
+          {(["light", "dark"] as const).map((option) => (
+            <button key={option} type="button" aria-pressed={mode === option} onClick={() => onModeChange(option)}>
+              {option === "light" ? "Light" : "Dark"}
+            </button>
+          ))}
+        </div>
+      </div>
+
+      <SelectMenu
+        label="Color palette"
+        value={palette}
+        options={paletteOptions}
+        onChange={onPaletteChange}
+        className="palette-picker"
+        showDescriptionInTrigger
+      />
+
+      <details className="theme-import">
+        <summary>
+          <span>Import a CSS theme</span>
+          <ChevronDown size={14} aria-hidden="true" />
+        </summary>
+        <div className="theme-import-body">
+          <p>
+            Paste light and dark CSS variable blocks. Use Token Larper colors or shadcn-style variables; extra CSS is ignored.
+          </p>
+          <details className="theme-format">
+            <summary>Show example CSS <ChevronDown size={14} aria-hidden="true" /></summary>
+            <div className="theme-format-body">
+              <p>This example has the five required Token Larper colors in both modes.</p>
+              <pre>{SAMPLE_THEME}</pre>
+            </div>
+          </details>
+          <label htmlFor="theme-css-input">Theme CSS</label>
+          <textarea
+            id="theme-css-input"
+            rows={7}
+            value={css}
+            onChange={(event) => {
+              setCss(event.target.value);
+              setError(null);
+              setMessage(null);
+            }}
+            placeholder="Paste the light and dark CSS variable blocks here…"
+            spellCheck={false}
+          />
+          {error && <p className="theme-import-feedback is-error" role="alert">{error}</p>}
+          {message && <p className="theme-import-feedback" role="status">{message}</p>}
+          <div className="theme-import-actions">
+            <button className="btn btn-primary" type="button" disabled={!css.trim()} onClick={applyPastedTheme}>
+              Apply theme
+            </button>
+          </div>
+        </div>
+      </details>
+    </section>
+  );
+}

package/src/client/context.tsx

@@ -0,0 +1,60 @@
+import React, { createContext, useContext } from "react";
+import type { DashboardPayload, HarnessId, SessionEntry, TimePeriodRow } from "../types.ts";
+import type { HarnessFilter } from "./lib/aggregate.ts";
+import type { DateRange } from "./lib/range.ts";
+import type { SeriesInfo } from "./charts.tsx";
+
+export interface Dashboard {
+  data: DashboardPayload;
+  range: DateRange;
+  harness: HarnessFilter;
+  setHarness: (h: HarnessFilter) => void;
+  estimated: boolean;
+  costOf: (c: { verifiedCost: number; estimatedCost: number }) => number;
+  /** Days with usage in the selected range, narrowed to the selected tool. */
+  days: TimePeriodRow[];
+  /** Sessions whose last activity falls in the range, narrowed to the selected tool. */
+  sessions: SessionEntry[];
+  series: SeriesInfo[];
+  seriesOf: (id: HarnessId) => SeriesInfo;
+  nameOf: (id: HarnessId) => string;
+  search: string;
+}
+
+const DashboardContext = createContext<Dashboard | null>(null);
+
+export const DashboardProvider = DashboardContext.Provider;
+
+export function useDashboard(): Dashboard {
+  const ctx = useContext(DashboardContext);
+  if (!ctx) throw new Error("useDashboard needs a DashboardProvider");
+  return ctx;
+}
+
+export function ToolTag({ id }: { id: HarnessId }) {
+  const { seriesOf, nameOf } = useDashboard();
+  return (
+    <span className="tool-tag">
+      <i style={{ background: seriesOf(id).color }} aria-hidden="true" />
+      {nameOf(id)}
+    </span>
+  );
+}
+
+/** A thin inline bar for a row's share of the largest row in the table. */
+export function ShareBar({ value, max, color }: { value: number; max: number; color?: string }) {
+  const pct = max > 0 ? Math.max(value > 0 ? 1.5 : 0, (value / max) * 100) : 0;
+  return (
+    <span className="share-bar" aria-hidden="true">
+      <span style={{ width: `${pct}%`, background: color }} />
+    </span>
+  );
+}
+
+export function EmptyState({ children }: { children: React.ReactNode }) {
+  return <div className="empty-state">{children}</div>;
+}
+
+export function pct(part: number, whole: number, digits = 1): string {
+  return whole > 0 ? `${((part / whole) * 100).toFixed(digits)}%` : "0%";
+}