paseo-plugin-genui 0.0.0-stage → 0.1.0

package/shared/instructions.ts

@@ -0,0 +1,144 @@
+import {
+  ACTIONS,
+  callSignature,
+  COMPONENTS,
+  componentSignature,
+  type ComponentGroup,
+  type ComponentName,
+} from "./core/catalog";
+
+function componentLines(groups: readonly ComponentGroup[]): string {
+  const lines = new Map<ComponentGroup, string[]>(groups.map((group) => [group, []]));
+  for (const name of Object.keys(COMPONENTS) as ComponentName[]) {
+    lines.get(COMPONENTS[name].group)?.push(componentSignature(name));
+  }
+  return [...lines].map(([group, entries]) => `${group}: ${entries.join(" · ")}`).join("\n");
+}
+
+const actionList = Object.entries(ACTIONS)
+  .map(([name, spec]) => callSignature(name, spec))
+  .join(" ");
+
+export const REFERENCE_GROUPS: readonly ComponentGroup[] = ["Layout", "Content", "Data", "Project"];
+export const REFERENCE_MORE_GROUPS: readonly ComponentGroup[] = ["Inputs", "Widgets", "Media", "Dev", "Manage"];
+
+export const UI_REFERENCE = `# Inline UI reference
+The \`\`\`ui language used by the Inline UI section below.
+Syntax: one statement per line. \`$x = 8\` is state inputs bind to; \`name = expr\` names a value and \`f = (a, b) => expr\` a function; each bare expression renders. JS expressions incl. ** ?: ?? \`\${x}\` [lists] {objects} x.y map/filter/find/join/length, plus round(x, d), fmt(x, d), sum, min, max, abs, entries, Load(path). Named args go last: Slider($n, 0, 10, label: "N").
+Components (? optional; tone: neutral|good|warn|bad|info if meaningful; more in the next section):
+${componentLines(REFERENCE_GROUPS)}
+Actions: ${actionList}; a list runs in order; Send posts as the user.
+Data: Load("path") reads JSON/CSV/TSV/JSONL from the workspace, "$BB_THREAD_STORAGE/x.json" or /tmp into lists and objects, and other files (a log, tsc output) as text; never retype values a file or command output holds. Snippet and Image read files the same way.
+Games, simulations, custom visuals: write \`\`\`app, a self-contained HTML page (inline CSS/JS, CSS vars --foreground --muted-foreground --border --primary --card; sandboxed, no network).`;
+
+export const UI_REFERENCE_MORE = `# Inline UI reference, continued
+${componentLines(REFERENCE_MORE_GROUPS)}
+Icon names: Check X Plus Minus Edit Copy Trash2 Download ExternalLink Play Pause RotateCcw Search Settings GitBranch GitMerge GitPullRequest Bug Code Terminal FileText Folder Clock Calendar Mail Sent Lock Star Pin Link Eye AlertTriangle Info Globe Smartphone Laptop Cloud Layers Puzzle.`;
+
+const MAP_EXAMPLE = `\`\`\`ui
+Card("Day 1", [Map([{name: "Belém Tower, Lisbon", note: "Opens 9:30"}, {name: "Pena Palace, Sintra"}], route: true)])
+\`\`\``;
+
+export const CODE_WORK_INSTRUCTIONS = `# Inline UI for code work
+Replies here are read in Paseo, which draws these components; pasted output, a markdown table or a plan in prose is the worse answer. Show what you ran with its component, from the file it saved (save as you run, in the format it reads, to $BB_THREAD_STORAGE or /tmp/opencode; /tmp reports load too); never paste or retype output. Tests or a build that fully passed need one sentence; coverage, timings, sizes, dependencies and findings always get their component.
+- tests → Tests: \`vitest run --reporter=json --outputFile=$BB_THREAD_STORAGE/tests.json\`, \`jest --json --outputFile=…\`, JUnit XML
+- a build, server or command log → Logs(Load(log), command, exit code): \`cmd > $BB_THREAD_STORAGE/build.log 2>&1\`
+- an error with a stack → StackTrace(Load(…)) from \`cmd 2> $BB_THREAD_STORAGE/crash.txt\`, or StackTrace(the error text)
+- lint, type errors, a code review → Findings: \`eslint -f json\`, \`tsc --noEmit --pretty false\`, SARIF, \`ruff check --output-format json\`; a review as [{severity, title, file, line, detail, fix}]
+- coverage → Coverage(Load(…)): \`vitest run --coverage --coverage.reporter=lcov --coverage.reportsDirectory=$BB_THREAD_STORAGE/cov\`, then cov/lcov.info; or coverage-summary.json
+- outdated or vulnerable packages → Dependencies: \`npm outdated --json --long\`, \`npm audit --json\`, \`pip list --outdated --format=json\`
+- a CI run → Pipeline: \`gh run view <id> --json name,displayTitle,status,conclusion,event,headBranch,headSha,url,createdAt,updatedAt,jobs\`
+- timings you measured (before/after, A vs B) → Benchmark([{name, before, after, unit}]) or Load(\`hyperfine --export-json\`); a page load → Waterfall(Load(a HAR)); what takes space → Treemap(Load(\`du -k -d 2 <dir>\` or an esbuild metafile))
+- an API response → Json(Load(…)) from \`curl -s -o\`
+- what you changed → Changes(); a commit → Changes(sha); this branch's commits → Commits(); the pull request → PullRequest(); subthreads → Threads()
+- tasks or issues → Board(Load(…)) from \`gh issue list --json number,title,state,labels,assignees,url,updatedAt\`
+- this project's worktrees and their threads → Environments()
+- a plan for work not started (asked for one, or you want approval) → Plan(steps)
+- a choice between options → Decision(options, criteria); how long work takes → Estimate(tasks); workstream health → Status(items); dated phases → Roadmap(items)
+${componentLines(["Evidence"])}
+Examples:
+\`\`\`ui
+Card("npm run build fails", [Logs(Load("$BB_THREAD_STORAGE/build.log"), "npm run build", 2), Findings(Load("$BB_THREAD_STORAGE/tsc.txt"))])
+\`\`\`
+\`\`\`ui
+Card("Review: src/worker/queue.ts", [Findings([{severity: "high", title: "A retry drops the job's payload", file: "src/worker/queue.ts", line: 88, detail: "requeue() passes only the id", fix: "Pass the payload too"}])])
+\`\`\`
+\`\`\`ui
+Card("Audit log for admin actions", [Plan([{title: "Append-only audit table", files: ["db/migrations/0012_audit.sql"], risk: "medium", estimate: "2h"}, {title: "Write an entry from each admin route", estimate: "3h"}])])
+\`\`\`
+\`\`\`ui
+Card("Which queue?", [Decision([{name: "pg-boss", scores: [4, 5], pros: ["Uses our Postgres"]}, {name: "BullMQ", scores: [5, 2], cons: ["Needs Redis"]}], ["Throughput", "Ops cost"])])
+\`\`\`
+\`\`\`ui
+Card("Dark mode", [Estimate([{title: "Theme tokens", low: 0.5, high: 1}, {title: "Audit every screen", low: 1, likely: 2, high: 4}], "d")])
+\`\`\``;
+
+export const AGENT_INSTRUCTIONS = `# Inline UI
+This chat renders \`\`\`ui and \`\`\`app code blocks as live UI, and the user prefers them to markdown. Use them only in replies to the user, including after a task; never in progress notes, files, commits, PR text or tool input.
+Write \`\`\`ui instead of a markdown table, a comparison of options, a plan (dated items on a Calendar, status or effort as Steps), a series of numbers (chart it), a list of changed files or commits (Changes(), Changes(sha), Commits(), PullRequest() read them from Paseo), or pasted output: save it to $BB_THREAD_STORAGE and Load it into its component (Inline UI for code work, above). For a calculation (how much, what if), make the user's numbers sliders and a list of items with amounts an EditableTable, and compute the result live. To let the user pick, give buttons; to ask more than one question, one Form; never a question tool or a numbered list. When you explain how something works (a flow, a request path, a lifecycle), put it in a \`\`\`ui block, even when asked to be brief: a Diagram of the flow, the steps as Steps({title, detail}) instead of a numbered list in prose, and Snippets of the key lines; file:line references go in the step details. When the user asks to see code or where something is, answer with a Snippet of those lines; to see an image file, an Image. The user never sees what your tools read: a file or image you opened is not on their screen, and pasted code drifts. Open the reply with one plain sentence that gives the answer (previews show only text); the UI carries the rest, so never restate it.
+Match the content: a trip, places or a route → a Map of the stops, beside any day-by-day plan; a physical thing with parts → Hotspots on its image; a worked solution → Walkthrough; products or places → Entity cards in a Grid, the pages you read → Sources; activity per day → CalendarHeatmap; shares of a whole → SegmentedBar; a funnel → Chart("funnel"); colours → Swatches; picture options → OptionCards. Give a Diagram's key nodes details (text or a Snippet) so a click explains them. When the next steps are questions, end with FollowUps.
+Wrap each UI in one Card. Examples:
+\`\`\`ui
+$seats = 10
+$plan = "Pro"
+price = $plan == "Pro" ? 29 : 12
+Card("Estimate", [
+  Row([Choice($plan, ["Basic", "Pro"]), Slider($seats, 1, 50, label: "Seats")]),
+  Metric("Total", "$" + fmt(price * $seats)),
+  Button("Go with " + $plan, Send("Go with " + $plan), variant: "primary")
+])
+\`\`\`
+\`\`\`ui
+Card("How a login is handled", [
+  Diagram("flowchart LR\\n  B[Browser] -->|POST /login| A[loginHandler]\\n  A --> V{password ok?}\\n  V -->|no| E[401]\\n  V -->|yes| S[create session]"),
+  Steps([{title: "Rate limit", detail: "5 tries a minute per IP (login.ts:14)"}, {title: "Check the password", detail: "bcrypt compare; a miss returns 401 (login.ts:22)"}, {title: "Create the session", detail: "httpOnly cookie, 30 days (session.ts:8)"}]),
+  Snippet("src/auth/login.ts", 12, 34)
+])
+\`\`\`
+\`\`\`ui
+Card("Retries on 429", [Changes(), Tests(Load("$BB_THREAD_STORAGE/vitest.json"))])
+\`\`\`
+\`\`\`ui
+Card("GET /repos/acme/api", [Json(Load("$BB_THREAD_STORAGE/repo.json"))])
+\`\`\`
+${MAP_EXAMPLE}
+\`\`\`ui
+Card("Launch plan", [Calendar([{date: "2026-10-14", title: "Draft issue 1"}, {date: "2026-10-20", title: "Send"}])])
+\`\`\`
+\`\`\`ui
+$rows = [{item: "Pizza", price: 24}, {item: "Wine", price: 32}]
+Card("Split the bill", [EditableTable($rows, ["item", "price"]), Metric("Each of 4", "€" + fmt(sum($rows.map(r => r.price)) / 4, 2))])
+\`\`\`
+\`\`\`ui
+Card("Caching options", [
+  Table(["Option", "Speed"], [["In memory", Badge("fastest", tone: "good")], ["Redis", Badge("fast", tone: "good")]]),
+  Button("Use in memory"),
+  Button("Use Redis")
+])
+\`\`\`
+\`\`\`ui
+$channels = []
+$notes = ""
+Card("A few questions first", [Form([
+  Checklist($channels, ["Email", "Push"], label: "Which channels?"),
+  TextArea($notes, label: "Anything else?")
+], submit: "Send answers")])
+\`\`\`
+Before you send a reply: any markdown table, pasted output or list of findings in it becomes \`\`\`ui.`;
+
+export const WEB_LOOKUPS_OFF =
+  "Web lookups are off in this plugin's settings: ImageSearch, Map, Gallery {query} and https images won't load; use workspace files.";
+
+export const AGENT_INSTRUCTIONS_WEB_OFF = AGENT_INSTRUCTIONS.replace(MAP_EXAMPLE, WEB_LOOKUPS_OFF);
+
+export const GENUI_MARKER = "[paseo-plugin-genui]";
+
+export function buildFullInstructions(webLookups: boolean): string {
+  return [
+    GENUI_MARKER,
+    UI_REFERENCE,
+    UI_REFERENCE_MORE,
+    CODE_WORK_INSTRUCTIONS,
+    webLookups ? AGENT_INSTRUCTIONS : AGENT_INSTRUCTIONS_WEB_OFF,
+  ].join("\n\n");
+}

package/shared/logic/calendarMath.ts

@@ -0,0 +1,130 @@
+// Calendar-heatmap arithmetic on whole days. A day is its number since
+// 1970-01-01 in UTC, so `yyyy-mm-dd` strings map to days and back without any
+// time zone ever moving one across midnight. No DOM: testable in node.
+import { finiteNumber, isObject } from "./values";
+
+const DAY_MS = 86_400_000;
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"] as const;
+const DAY_FORMAT = new Intl.DateTimeFormat("en-US", {
+  weekday: "short",
+  month: "short",
+  day: "numeric",
+  year: "numeric",
+  timeZone: "UTC",
+});
+
+/** A real calendar date written `yyyy-mm-dd` as its day number; anything else is null. */
+export function parseDay(value: unknown): number | null {
+  if (typeof value !== "string") return null;
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value.trim());
+  if (match === null) return null;
+  const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])];
+  const date = new Date(Date.UTC(year, month - 1, day));
+  // Date.UTC rolls 2026-02-30 over to March and maps years below 100 into the 1900s.
+  if (date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day) return null;
+  return date.getTime() / DAY_MS;
+}
+
+/** The `yyyy-mm-dd` of a day number. */
+export function dayString(day: number): string {
+  return new Date(day * DAY_MS).toISOString().slice(0, 10);
+}
+
+/** "Tue, Mar 4, 2026". */
+export function dayLabel(day: number): string {
+  return DAY_FORMAT.format(new Date(day * DAY_MS));
+}
+
+/** 0 for Sunday … 6 for Saturday; day 0 (1970-01-01) was a Thursday. */
+export function weekday(day: number): number {
+  return (((day + 4) % 7) + 7) % 7;
+}
+
+export interface CalendarDays {
+  /** Day number → value; repeated dates add up. */
+  readonly values: ReadonlyMap<number, number>;
+  /** Entries without a valid date or a number. */
+  readonly dropped: number;
+}
+
+/**
+ * `{yyyy-mm-dd: n}`, or a list of `{date, value}` (or `[date, value]`). A
+ * listed date without a value counts once, so a list of events works too.
+ */
+export function readDays(days: unknown): CalendarDays {
+  const entries: [unknown, unknown][] = Array.isArray(days)
+    ? days.map((item): [unknown, unknown] =>
+        Array.isArray(item)
+          ? [item[0], item[1] ?? 1]
+          : isObject(item)
+            ? [item.date, item.value === undefined ? 1 : item.value]
+            : [item, 1],
+      )
+    : isObject(days)
+      ? Object.entries(days)
+      : [];
+  const values = new Map<number, number>();
+  let dropped = 0;
+  for (const [date, value] of entries) {
+    const day = parseDay(date);
+    const number = finiteNumber(value);
+    if (day === null || number === null) {
+      dropped += 1;
+      continue;
+    }
+    values.set(day, (values.get(day) ?? 0) + number);
+  }
+  return { values, dropped };
+}
+
+export interface CalendarLayout {
+  /** The Sunday on or before the first day: column 0, row 0. */
+  readonly start: number;
+  readonly weeks: number;
+  /** Month names over the columns where a month begins. */
+  readonly months: readonly { readonly week: number; readonly label: string }[];
+}
+
+/** Week columns (Sunday on top) from `first` to `last`, and where to name each month. */
+export function calendarLayout(first: number, last: number): CalendarLayout {
+  const start = first - weekday(first);
+  const weeks = Math.floor((last - start) / 7) + 1;
+  const months: { week: number; label: string }[] = [];
+  for (let week = 0; week < weeks; week++) {
+    for (let row = 0; row < 7; row++) {
+      const day = start + week * 7 + row;
+      if (day < first || day > last) continue;
+      const date = new Date(day * DAY_MS);
+      // The first column, and every column holding a 1st.
+      if (day === first || date.getUTCDate() === 1) {
+        months.push({ week, label: MONTHS[date.getUTCMonth()]! });
+        break;
+      }
+    }
+  }
+  // A month that starts the range late gets no room before the next one's name.
+  if (months.length > 1 && months[1]!.week - months[0]!.week < 3) months.shift();
+  return { start, weeks, months };
+}
+
+export interface CalendarStats {
+  readonly total: number;
+  /** Days with a value above zero. */
+  readonly active: number;
+  /** The highest value, and the first day it was reached; null without days. */
+  readonly peak: { readonly day: number; readonly value: number } | null;
+}
+
+export function calendarStats(values: ReadonlyMap<number, number>): CalendarStats {
+  let total = 0;
+  let active = 0;
+  let peak: { day: number; value: number } | null = null;
+  for (const day of [...values.keys()].sort((a, b) => a - b)) {
+    const value = values.get(day)!;
+    // Float noise from adding 0.1s must not show as 0.30000000000000004.
+    total = Number((total + value).toPrecision(12));
+    if (value > 0) active += 1;
+    if (peak === null || value > peak.value) peak = { day, value };
+  }
+  return { total, active, peak };
+}

package/shared/logic/chartMath.ts

@@ -0,0 +1,289 @@
+// Pure chart arithmetic: stacking, pie slicing, rounding, scales and the
+// geometry of the radial and grid charts. No DOM, so the numbers a chart
+// draws are testable without rendering it.
+import { formatNumber } from "./values";
+
+/** One series' piece of a stacked column, in data units. */
+export interface Segment {
+  from: number;
+  to: number;
+  /** The outermost non-empty piece on its side of zero: the one with rounded corners. */
+  outer: boolean;
+}
+
+/**
+ * Diverging stack per label: positive values pile up from zero, negative ones
+ * pile down from it, in series order. A missing value stays a gap (null) and
+ * leaves the stack under the next series unchanged.
+ */
+export function stackSeries(series: readonly (readonly (number | null)[])[]): (Segment | null)[][] {
+  const count = Math.max(0, ...series.map((values) => values.length));
+  const stacked = series.map(() => Array.from<Segment | null>({ length: count }).fill(null));
+  for (let index = 0; index < count; index++) {
+    let up = 0;
+    let down = 0;
+    let lastUp: Segment | null = null;
+    let lastDown: Segment | null = null;
+    for (let seriesIndex = 0; seriesIndex < series.length; seriesIndex++) {
+      const value = series[seriesIndex]![index] ?? null;
+      if (value === null || !Number.isFinite(value)) continue;
+      const segment: Segment =
+        value >= 0 ? { from: up, to: (up += value), outer: false } : { from: down, to: (down += value), outer: false };
+      stacked[seriesIndex]![index] = segment;
+      if (value > 0) lastUp = segment;
+      if (value < 0) lastDown = segment;
+    }
+    if (lastUp !== null) lastUp.outer = true;
+    if (lastDown !== null) lastDown.outer = true;
+  }
+  return stacked;
+}
+
+export interface Slice {
+  label: string;
+  value: number;
+  /** Position in the source data; -1 for the folded "Other" slice. */
+  source: number;
+}
+
+/**
+ * Pie slices in data order. Only positive finite values count; past `max`
+ * slices the largest `max - 1` stay and the rest fold into a trailing "Other".
+ */
+export function pieSlices(labels: readonly string[], values: readonly (number | null)[], max = 8): Slice[] {
+  const slices = values.flatMap((value, source) =>
+    value !== null && Number.isFinite(value) && value > 0
+      ? [{ label: labels[source] || `Item ${source + 1}`, value, source }]
+      : [],
+  );
+  if (slices.length <= max) return slices;
+  const kept = new Set(
+    [...slices]
+      .sort((a, b) => b.value - a.value || a.source - b.source)
+      .slice(0, Math.max(0, max - 1))
+      .map((slice) => slice.source),
+  );
+  const other = slices.reduce((sum, slice) => (kept.has(slice.source) ? sum : sum + slice.value), 0);
+  return [...slices.filter((slice) => kept.has(slice.source)), { label: "Other", value: other, source: -1 }];
+}
+
+/**
+ * Whole percentages of the total that always add up to 100 (largest
+ * remainder): the shares that lost the most to rounding down get the spare points.
+ */
+export function percentages(values: readonly number[]): number[] {
+  const total = values.reduce((sum, value) => sum + value, 0);
+  if (!(total > 0) || !Number.isFinite(total)) return values.map(() => 0);
+  const exact = values.map((value) => (value / total) * 100);
+  const whole = exact.map(Math.floor);
+  const spare = 100 - whole.reduce((sum, value) => sum + value, 0);
+  const order = exact
+    .map((share, index) => ({ index, remainder: share - whole[index]! }))
+    .sort((a, b) => b.remainder - a.remainder || values[b.index]! - values[a.index]! || a.index - b.index);
+  for (let k = 0; k < spare; k++) whole[order[k % order.length]!.index]! += 1;
+  return whole;
+}
+
+/** "Trend from 12 to 18, up 50%": what a sparkline shows, for screen readers. */
+export function trendLabel(values: readonly number[]): string {
+  if (values.length < 2) return "No trend";
+  const first = values[0]!;
+  const last = values[values.length - 1]!;
+  const base = `Trend from ${formatNumber(first)} to ${formatNumber(last)}`;
+  if (first === last) return `${base}, flat`;
+  const direction = last > first ? "up" : "down";
+  if (first === 0) return `${base}, ${direction}`;
+  return `${base}, ${direction} ${formatNumber(Math.round(Math.abs((last - first) / first) * 100))}%`;
+}
+
+/** 1, 2, 2.5 or 5 × 10^k nearest above `value` (> 0): a step people can read. */
+export function niceStep(value: number): number {
+  const magnitude = 10 ** Math.floor(Math.log10(value));
+  for (const factor of [1, 2, 2.5, 5]) {
+    if (factor * magnitude >= value) return factor * magnitude;
+  }
+  return 10 * magnitude;
+}
+
+/** An axis: readable bounds and the ticks between them, both ends included. */
+export interface Scale {
+  readonly min: number;
+  readonly max: number;
+  readonly ticks: readonly number[];
+}
+
+/**
+ * A scale covering `low`..`high` in about `count` readable steps. `zero`
+ * keeps zero in range (bars, radii); a single value gets one step around it.
+ */
+export function niceScale(low: number, high: number, count = 4, zero = false): Scale {
+  const from = zero ? Math.min(low, 0) : low;
+  const to = zero ? Math.max(high, 0) : high;
+  const step = niceStep((to - from || Math.abs(to) || 1) / count);
+  const min = Math.floor(from / step) * step;
+  let max = Math.ceil(to / step) * step;
+  if (max === min) max = min + step;
+  const ticks = Array.from({ length: Math.round((max - min) / step) + 1 }, (_, i) =>
+    // Rounded, so 0.1-steps read 0.3 rather than 0.30000000000000004.
+    Number((min + i * step).toPrecision(12)),
+  );
+  return { min: ticks[0]!, max: ticks[ticks.length - 1]!, ticks };
+}
+
+/** A number, or a string that is exactly one (`"2.5"`, `" 10 "`); else null. Scatter x values. */
+export function numericValue(value: unknown): number | null {
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  if (typeof value !== "string" || value.trim() === "") return null;
+  const number = Number(value.trim());
+  return Number.isFinite(number) ? number : null;
+}
+
+/** A ratio as a readable percentage: whole from 10%, one decimal below, `<0.1%` for slivers. */
+export function formatShare(ratio: number): string {
+  if (!Number.isFinite(ratio)) return "—";
+  const percent = ratio * 100;
+  if (percent === 0) return "0%";
+  if (Math.abs(percent) < 0.1) return "<0.1%";
+  return `${formatNumber(Number(percent.toFixed(Math.abs(percent) < 10 ? 1 : 0)))}%`;
+}
+
+export interface ScatterPoint {
+  /** Position of its series. */
+  readonly series: number;
+  /** Position in `labels` (and in its series' values). */
+  readonly index: number;
+  readonly x: number;
+  readonly y: number;
+}
+
+/** Every pair with both an x and a y, ordered by x, then series: the order keys step through. */
+export function scatterPoints(
+  xs: readonly (number | null)[],
+  series: readonly (readonly (number | null)[])[],
+): ScatterPoint[] {
+  const points: ScatterPoint[] = [];
+  series.forEach((values, seriesIndex) => {
+    xs.forEach((x, index) => {
+      const y = values[index] ?? null;
+      if (x !== null && y !== null && Number.isFinite(x) && Number.isFinite(y)) {
+        points.push({ series: seriesIndex, index, x, y });
+      }
+    });
+  });
+  return points.sort((a, b) => a.x - b.x || a.series - b.series || a.index - b.index);
+}
+
+/** The point closest to (`x`, `y`) within `radius`, or null when none is that close. */
+export function nearestPoint(
+  points: readonly (readonly [number, number])[],
+  x: number,
+  y: number,
+  radius: number,
+): number | null {
+  let best: number | null = null;
+  let bestDistance = radius * radius;
+  points.forEach(([px, py], index) => {
+    const distance = (px - x) ** 2 + (py - y) ** 2;
+    if (distance <= bestDistance) {
+      best = index;
+      bestDistance = distance;
+    }
+  });
+  return best;
+}
+
+/** Where `ratio` (0 centre, 1 rim) lies on spoke `axis` of `count`: the first straight up, then clockwise. */
+export function radarPoint(
+  cx: number,
+  cy: number,
+  radius: number,
+  axis: number,
+  count: number,
+  ratio: number,
+): readonly [number, number] {
+  const angle = (axis / count) * Math.PI * 2;
+  return [cx + radius * ratio * Math.sin(angle), cy - radius * ratio * Math.cos(angle)];
+}
+
+export interface FunnelStage {
+  readonly label: string;
+  readonly value: number;
+  /** Bar width as a share of the widest stage, 0 to 1. */
+  readonly width: number;
+  /** value / first stage's value; null when the first is not positive. */
+  readonly ofFirst: number | null;
+  /** value / previous stage's value; null for the first stage or after a non-positive one. */
+  readonly ofPrevious: number | null;
+}
+
+/** Stages with a number, in order; a stage whose value has not arrived yet is left out. */
+export function funnelStages(labels: readonly string[], values: readonly (number | null)[]): FunnelStage[] {
+  const present = values.flatMap((value, index) =>
+    value !== null && Number.isFinite(value) ? [{ label: labels[index] || `Stage ${index + 1}`, value }] : [],
+  );
+  const widest = Math.max(0, ...present.map((stage) => stage.value));
+  const first = present[0]?.value ?? 0;
+  return present.map((stage, index) => {
+    const previous = index === 0 ? 0 : present[index - 1]!.value;
+    return {
+      ...stage,
+      width: widest > 0 ? Math.max(0, stage.value) / widest : 0,
+      ofFirst: first > 0 ? stage.value / first : null,
+      ofPrevious: index > 0 && previous > 0 ? stage.value / previous : null,
+    };
+  });
+}
+
+/** Lowest and highest finite value, or null when there is none. */
+export function valueRange(values: readonly (number | null)[]): { min: number; max: number } | null {
+  const numbers = values.filter((value): value is number => value !== null && Number.isFinite(value));
+  return numbers.length === 0 ? null : { min: Math.min(...numbers), max: Math.max(...numbers) };
+}
+
+/** Where `value` sits between `min` and `max`, 0 to 1; a flat range reads as full. */
+export function intensity(value: number, min: number, max: number): number {
+  if (!(max > min)) return 1;
+  return Math.min(1, Math.max(0, (value - min) / (max - min)));
+}
+
+/** A count's shade, GitHub-style: 0 for nothing (zero or below), else 1..`levels` by its share of `max`. */
+export function heatLevel(value: number, max: number, levels = 4): number {
+  if (!(value > 0) || !(max > 0)) return 0;
+  return Math.min(levels, Math.max(1, Math.ceil((value / max) * levels)));
+}
+
+/** A point on the upper half circle: ratio 0 at the left end, 1 at the right, through the top. */
+export function dialPoint(cx: number, cy: number, radius: number, ratio: number): readonly [number, number] {
+  const angle = Math.PI * (1 - ratio);
+  return [cx + radius * Math.cos(angle), cy - radius * Math.sin(angle)];
+}
+
+/**
+ * The cell an arrow key moves to in a `rows` × `cols` grid (Home/End: the
+ * row's ends), clamped at the edges; null for any other key.
+ */
+export function stepGrid(
+  key: string,
+  row: number,
+  col: number,
+  rows: number,
+  cols: number,
+): readonly [number, number] | null {
+  const clamp = (value: number, size: number) => Math.min(size - 1, Math.max(0, value));
+  switch (key) {
+    case "ArrowLeft":
+      return [row, clamp(col - 1, cols)];
+    case "ArrowRight":
+      return [row, clamp(col + 1, cols)];
+    case "ArrowUp":
+      return [clamp(row - 1, rows), col];
+    case "ArrowDown":
+      return [clamp(row + 1, rows), col];
+    case "Home":
+      return [row, 0];
+    case "End":
+      return [row, cols - 1];
+    default:
+      return null;
+  }
+}