@humanforest/slidev-theme 0.1.0

package/components/chartTip.ts

@@ -0,0 +1,201 @@
+/*
+  The chart tooltip's markup and placement, for the deck.
+
+  ── WHY THIS IS A DECK-LOCAL COPY ──────────────────────────────────────────────────────────────
+  `packages/charts/src/forestTooltip.ts` is the SOURCE OF TRUTH for this markup, and it is a pure
+  string builder published under its own subpath. Four places in this package already say not to
+  depend on that package — README.md, Bars.vue, boroughGeometry.ts and chartData.ts — because it
+  peer-depends on `@nuxt/ui: ^4`, bun auto-installs peers, and the deck runs UnoCSS.
+
+  ⚠ HALF OF THAT REASONING IS STALE, measured 2026-09-02 rather than assumed: `@nuxt/ui` and
+  `tailwindcss` are in this package's tree ALREADY, pulled by `@humanforest/frames`, which
+  peer-depends on the same thing. Adding `@humanforest/charts` moved the count 339 -> 355 entries,
+  not the 204 -> 326 chartData.ts predicts. The rule still holds — one import of a chart component
+  drags a Nuxt UI pipeline into a deck that cannot compile it — but it holds on the PIPELINE, not
+  on an install size another dependency already pays for.
+
+  So this follows the rule the rest of the deck's chart set already follows — share the VALUES,
+  re-implement the PRESENTATION. What has to match is the SHAPE, and it does: a title bar over a
+  swatch/label/value grid, every size and colour read from a `--vis-tooltip-*` custom property with
+  the same names the product uses, so the two are themed by one vocabulary even though the code is
+  two copies.
+*/
+import { onBeforeUnmount, shallowRef } from 'vue';
+import { Tooltip } from '@unovis/ts';
+
+/*
+  ★ THE HAND-DRAWN CHARTS DRIVE UNOVIS' OWN `Tooltip`, rather than growing a second panel. Neither
+  StatusTrack nor CalendarGrid has a library mark to hang a trigger on — one is a row of `<span>`s,
+  the other a grid of `<rect>`s — but the PANEL is a standalone class, and reusing it is what keeps
+  one implementation of the thing that is actually hard here: `place()`'s arithmetic, the flip near
+  the top edge, the viewport clamp, and the `zoom` correction base.css applies to all of it. It also
+  means these two are themed by the same block as the eleven library charts rather than by a copy.
+
+  Created on first use, so nothing touches `document` until a pointer moves — these components
+  render server-side like any other.
+*/
+export function useDeckTip(): { show: (html: string, e: MouseEvent) => void; hide: () => void } {
+  const held = shallowRef<Tooltip | null>(null);
+  onBeforeUnmount(() => {
+    held.value?.destroy();
+    held.value = null;
+  });
+  return {
+    show(html, e) {
+      if (!held.value) held.value = new Tooltip(deckTooltip());
+      // `show` is render-then-place, and that order is load-bearing: `place()` measures the panel's
+      // own box, which is only laid out once the content is in it.
+      held.value.show(html, { x: e.clientX, y: e.clientY });
+    },
+    hide() {
+      held.value?.hide();
+    },
+  };
+}
+
+/** Every interpolated string passes through here: the output is innerHTML on the tooltip element,
+ *  and titles, series names and formatted values are all arbitrary text. */
+const esc = (value: unknown): string =>
+  String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+
+const TITLE_STYLE = (hasRows: boolean) =>
+  'color:var(--vis-tooltip-title-color,#000);'
+  + 'text-transform:var(--vis-tooltip-title-text-transform,none);'
+  + `border-bottom:${hasRows ? 'var(--vis-tooltip-title-border-bottom,1px solid #e5e7eb)' : 'none'};`
+  + 'padding:var(--vis-tooltip-title-padding,0.75rem 0.75rem 0.5rem 0.75rem);'
+  + `margin:${hasRows ? 'var(--vis-tooltip-title-margin,0 0 0.25rem 0)' : '0'};`
+  + 'font-size:var(--vis-tooltip-title-font-size,0.875rem);'
+  + 'line-height:var(--vis-tooltip-title-line-height,100%);'
+  + 'font-weight:var(--vis-tooltip-title-font-weight,600)';
+
+/* The swatch column is only there when something fills it. A frame whose rows ALL lack a swatch —
+   a timeline's From/To, a treemap's share — would otherwise indent every label past a column of
+   nothing, which reads as a missing dot rather than as a chart with no series to name. Mixed
+   frames keep the column, hidden on the rows without one, so the labels stay in a line. */
+const GRID_STYLE = (hasSwatch: boolean) =>
+  `display:grid;grid-template-columns:${hasSwatch ? 'auto 1fr auto' : '1fr auto'};align-items:center;`
+  + 'gap:var(--vis-tooltip-content-gap,0.25rem 0.5rem);'
+  + 'padding:var(--vis-tooltip-content-padding,0 0.75rem 0.5rem 0.75rem)';
+
+/* The dot is the one thing the product's version hard-codes at 8px. Here it is a variable too, so
+   the deck can size it against 36px type from one place rather than overriding an inline style. */
+const DOT_STYLE =
+  'width:var(--vis-tooltip-dot-size,8px);height:var(--vis-tooltip-dot-size,8px);'
+  + 'aspect-ratio:1;flex-shrink:0;border-radius:999px;';
+
+const LABEL_STYLE =
+  'font-weight:var(--vis-tooltip-label-font-weight,400);'
+  + 'font-size:var(--vis-tooltip-label-font-size,0.875rem);'
+  + 'color:var(--vis-tooltip-label-color,inherit);'
+  + 'margin:var(--vis-tooltip-label-margin,0 1rem 0 0);white-space:nowrap';
+
+const VALUE_STYLE =
+  'font-size:var(--vis-tooltip-value-font-size,0.875rem);'
+  + 'font-weight:var(--vis-tooltip-value-font-weight,600);'
+  + 'color:var(--vis-tooltip-value-color,inherit);'
+  + 'text-align:right;font-variant-numeric:tabular-nums';
+
+/*
+  ★★ A TRIGGER KEY IS A BARE CLASS NAME, ON EVERY MARK. Unovis binds one delegated `mousemove` per
+  component and walks `composedPath()` for `el.classList.contains(key)`, dotting the key itself for
+  its own `selectAll` — so the RAW export is what fires, and a normaliser that prefixed a dot
+  everywhere looked like the tidy fix and silently disabled three charts that had been working.
+
+  The class can sit on any element the mark draws — Sankey's node is a `rect`, not a `g` — so a
+  hand-written selector guessing at the tag finds nothing and looks exactly like a dead trigger.
+
+  The failure is invisible: no error, no warning, just a panel that never appears. It looks
+  identical to a hover that MISSED, which is how four families here were once recorded as broken
+  when all four worked. Verify by dispatching at the mark's own centre, never by hovering at
+  coordinates read off a screenshot.
+*/
+
+export interface TipRow {
+  /** Swatch colour. Omit for a row with no dot: the column holds its width while ANY row in the
+   *  frame carries one, so a mixed set stays aligned, and collapses when none of them do. */
+  swatch?: string;
+  label: string;
+  value: string | number;
+}
+
+/** The house tooltip chrome — a title bar over a swatch/label/value grid. */
+export function tipFrame(title: string | number, rows: TipRow[] = []): string {
+  const hasSwatch = rows.some((r) => r.swatch);
+  const body = rows
+    .map((r) =>
+      (hasSwatch
+        ? `<span style="${DOT_STYLE}${r.swatch ? `background-color:${esc(r.swatch)}` : 'visibility:hidden'}"></span>`
+        : '')
+      + `<span style="${LABEL_STYLE}">${esc(r.label)}</span>`
+      + `<span style="${VALUE_STYLE}">${esc(r.value)}</span>`)
+    .join('');
+  return '<div style="display:flex;flex-direction:column">'
+    + `<div style="${TITLE_STYLE(rows.length > 0)}">${esc(title)}</div>`
+    + (rows.length > 0 ? `<div style="${GRID_STYLE(hasSwatch)}">${body}</div>` : '')
+    + '</div>';
+}
+
+/** A crosshair template: one row per series present on the hovered datum, in legend order. The
+ *  title falls out of the row itself — the deck's rows lead with `label`. */
+export function seriesTip(
+  series: readonly { key: string; name: string; color: string }[],
+  format: (v: number) => string,
+): (d: Record<string, unknown>) => string {
+  return (d) => {
+    const rows = series
+      .filter((s) => s.key in d)
+      .map((s) => ({ swatch: s.color, label: s.name, value: format(Number(d[s.key])) }));
+    return tipFrame(String(Object.values(d)[0]), rows);
+  };
+}
+
+/*
+  ★★ THE PANEL IS MOUNTED ON THE BODY, AND ON A SCALED SLIDE THAT IS NOT OPTIONAL. Slidev draws the
+  1920x1080 canvas by SCALING it, and Unovis positions its panel by writing screen pixels into
+  `left`/`bottom`. Inside the slide those pixels are scaled again — measured on the Grouped bars
+  slide, a pointer at x 700 put the panel at x 264. The body is the only ancestor the transform does
+  not reach. `packages/charts` mounts there too, for its own reason (a short chart clamps the panel
+  back over the pointer), and arrives at the same place.
+
+  ★ `followCursor` IS TRUE HERE AND FALSE IN THE PRODUCT, and on this deck it reaches EVERY chart.
+  A per-mark trigger — a donut arc, a treemap tile, a scatter point — is shown by the tooltip
+  itself, so the flag applies directly. A crosshair shows the panel itself, and rather than ignoring
+  the flag it FORCES it on (`tooltip.config.followCursor = true`, with an inline note that its
+  tooltip must not be hoverable) and passes `[clientX, clientY]` — the raw pointer, not the snapped
+  column. So the panel bobs with the cursor there too. Measured, not assumed: its y tracked the
+  pointer frame by frame across the Line slide.
+
+  The product does not behave that way, and the difference is a dependency rather than a decision.
+  `useTooltipSnap` holds the panel at the top of the plot so it "steps as the crosshair snaps
+  between rows and holds still in between" — a panel that bobs free-floats while the reading it
+  shows only changes datum to datum. That composable lives in @humanforest/charts, which this
+  package cannot import; re-implementing it means owning the placement Unovis overwrites every
+  frame, and the LINE still snaps here, so the reading is never wrong — only restless.
+*/
+export function deckTooltip(): Record<string, unknown> {
+  return {
+    container: typeof document === 'undefined' ? undefined : document.body,
+    followCursor: true,
+    horizontalShift: 12,
+    verticalShift: 12,
+    /*
+      ★★ PINNED SO THE CROSSHAIR CANNOT FLIP IT. Left at the default `auto`, Crosshair._showTooltip
+      re-decides the side on every frame — `xRelative > containerWidth / 2 ? Left : Right` — so
+      crossing the plot's midpoint throws the panel from one side of the pointer to the other.
+      MEASURED on the Line slide: a single frame moved it 262px, and near the midpoint it flips back
+      and forth with the pointer. Unovis guards that override with
+      `if (!config.horizontalPlacement || === Auto)`, so naming a side is what switches it off.
+
+      `center` rather than a side, because it is what the ELEVEN other charts already draw: `auto`
+      resolves to Center inside `place()`, and only the crosshair reinterprets it. One behaviour
+      across the deck, and the clamp keeps a panel near either edge on screen — honestly now that
+      the panel measures its drawn size.
+    */
+    horizontalPlacement: 'center',
+  };
+}

package/components/codeTheme.ts

@@ -0,0 +1,239 @@
+// The Forest code theme — a Shiki theme built out of the deck's own colour roles.
+//
+// WHY THE SHIPPED ONE HAD TO GO, measured rather than asserted. Slidev's default is the vitesse
+// pair, switched by CSS on `html.dark`. This deck runs LIGHT globally and marks individual slides
+// `class: deck-dark`, which is not `html.dark` — so a code block on a dark slide got the LIGHT
+// theme's tokens on a dark ground. Probed on a live render before any of this was written:
+//
+//     ground  #0c332d  (--deck-surface, dark register)
+//     func    #1e754f  2.43:1     <- the most frequent token in the sample
+//     0       #2f798a  2.77:1
+//     *       #ab5959  2.82:1
+//     Fleet   #2e8f82  3.51:1
+//
+// Every scope but punctuation was under the 4.5:1 body floor, and a screenshot did not show it —
+// at slide-thumbnail size the eye fills in what the DOM says is not there. Two fixes, both here:
+// a theme that IS the deck's palette, and a register switch that keys off `.deck-dark` as well as
+// `html.dark` (base.css, "Code" section).
+//
+// ── The palette ────────────────────────────────────────────────────────────────────────────────
+//
+// Ayu's five role colours on the deck's own grounds, lifted where they miss the body floor:
+//
+//     role     ayu scope         light                    dark
+//     ink      (default fg)      #5c6166  5.33 published   #bfbdb6   9.56 published
+//     muted    comment           #696a6d  4.61             #79828c   4.61
+//     accent   keyword           #ab5000  4.62             #ff8f40   7.92 published
+//     text     string            #557400  4.61             #aad94c  10.90 published
+//     value    constant.numeric  #8158a7  4.61             #d2a6ff   9.10 published
+//
+// A lift walks OKLCH lightness with hue and chroma held until the engine's contrast() clears 4.6 —
+// the floor plus headroom, so a rounding difference cannot land a shipped ink under 4.5.
+// codeTheme.static.test.ts re-derives every value from AYU below rather than comparing hexes.
+//
+// `muted` is also clamped under 0.02 chroma, the floor at which the hue-budget gate counts a colour
+// as a hue. Two near-neutral greys a few thousandths apart are a scope distinction an audience
+// cannot resolve at ten metres, so they resolve to one grey and the register stays inside the
+// four-hue ceiling.
+//
+// The mapping is ayu's own, read off its scope rules. Its gold and its blue are left unspent here,
+// which is what lets styles/base.css give the lit line a marker that cannot read as syntax.
+//
+// ⚖ Ayu is MIT-licensed (Copyright (c) 2016 Ike Ku); the entries used are named above.
+import type { ThemeRegistrationRaw } from 'shiki';
+import { palette, ramp, type Register } from './deckPalette';
+
+/**
+ * Ayu's published entries, by its own scope names. The SOURCE, not what ships: `CODE_INKS` below is
+ * what ships, and the two differ only where a colour had to be lifted. Kept separate and exported so
+ * the gate can re-derive the lift rather than compare two copies of a hex.
+ *
+ * `marker` is ayu's blue, used for the lit-line bar. It is darkened on light before it ships — see
+ * --deck-code-marker in styles/tokens.css.
+ */
+export const AYU = {
+  light: { flavour: 'light', marker: '#55b4d4',
+    ink: '#5c6166', muted: '#adaeb1', accent: '#fa8532', text: '#86b300', value: '#a37acc' },
+  dark: { flavour: 'dark', marker: '#39bae6',
+    ink: '#bfbdb6', muted: '#5a6673', accent: '#ff8f40', text: '#aad94c', value: '#d2a6ff' },
+} as const;
+
+/**
+ * The ground a code block is painted on, per register — and it is the DECK's, not ayu's.
+ *
+ * The palette is borrowed; the paper is not. Light is --deck-surface, derived from the page ground,
+ * so the block sits on the deck's own surface ladder.
+ *
+ * Dark is `--neutral-900`, the one deliberate step off that ladder. --deck-surface on dark is the
+ * page lifted 5% toward the ink (#0d332d), which reads 1.13:1 against the slide it sits on — a well
+ * that cannot be seen. neutral-900 is 1.16:1 and gives ayu's roles a worst case of 7.92:1. It is
+ * warm, so it sits with the deck's cream, and it is the same #191617 the light register inks with.
+ */
+export const codeGround = (register: Register) =>
+  register === 'light' ? palette(register).surface : ramp('neutral', 900);
+
+/*
+  ★★ `surface0` AND `blue` ARE THE BLOCK'S CHROME, NOT ITS SYNTAX, and they are here so the gate can
+  pin the stylesheet to published values rather than to two more loose hexes.
+
+  `base` moved the block's GROUND to Catppuccin; its edge and its lit-line marker stayed on the deck's
+  own roles, which is the same half-decision one level out. Measured on the dark register: the border
+  painted --deck-border, i.e. forest-950 mixed 14% toward the ink — #24443e at hue 181, a teal-green
+  line around a #1e1e2e violet-black box, 100 degrees of hue apart. Jose: "is this border green? why?"
+
+  `surface0` is Catppuccin's own one-rung-off-base, so the edge is the palette's answer rather than a
+  second derivation to keep in sync. `blue` is the marker: every other Catppuccin accent this deck
+  uses is already spent by the scope table — mauve on keywords, green on strings, peach on numbers —
+  so a marker in any of them would read as syntax.
+*/
+
+/**
+ * What ships. Four of the five light entries are LIFTED (the derivation is in the header), and
+ * `muted` is additionally pulled under the hue ceiling's chroma floor; on dark, FOUR of five are
+ * ayu's published hex unchanged and only `muted` moves.
+ *
+ * ★ LITERAL HEXES RATHER THAN A LIFT COMPUTED AT IMPORT TIME, and that is a decision rather than a
+ * shortcut. This module runs in NODE at build time — Slidev highlights magic-move steps with it —
+ * so a derivation here would re-run on every build to produce a constant. The gate runs it instead,
+ * where a drift is a failure rather than a silent recompute.
+ */
+const CODE_INKS = {
+  light: { ink: '#5c6166', muted: '#696a6d', accent: '#ab5000', text: '#557400', value: '#8158a7' },
+  dark: { ink: '#bfbdb6', muted: '#79828c', accent: '#ff8f40', text: '#aad94c', value: '#d2a6ff' },
+} as const;
+
+/** The five inks a Forest code block is allowed, per register. */
+export function codeInks(register: Register) {
+  return {
+    /** Everything NAMED — variables, functions, types, properties. Catppuccin `text`. */
+    ink: CODE_INKS[register].ink,
+    /** Comments. Catppuccin `subtext0`. */
+    muted: CODE_INKS[register].muted,
+    /** Keywords, operators, tags — the control flow you point at. Catppuccin `mauve`. */
+    accent: CODE_INKS[register].accent,
+    /** Literal TEXT — strings, characters, regex. Catppuccin `green`. */
+    text: CODE_INKS[register].text,
+    /** Literal VALUES — numbers, booleans, language constants. Catppuccin `peach`. */
+    value: CODE_INKS[register].value,
+    /** The ground a code block is actually painted on — base.css sets `pre` to --deck-surface. */
+    ground: codeGround(register),
+  };
+}
+
+/**
+ * The scope table.
+ *
+ * Written once and instantiated per register, so the two themes cannot disagree about WHICH scopes
+ * are keywords — only about what colour a keyword is. A scope list that differed between light and
+ * dark would be a bug nobody could see without diffing two blobs of JSON.
+ *
+ * `fontStyle` is deliberately sparse. Italic on comments is the one convention worth keeping at
+ * projector scale (it separates prose from code without a hue); bold on names carries the
+ * structural distinction that would otherwise cost a fifth hue. Nothing else is styled.
+ */
+const SCOPES: { key: 'ink' | 'muted' | 'accent' | 'text' | 'value'; fontStyle?: string; scopes: string[] }[] = [
+  {
+    key: 'muted',
+    fontStyle: 'italic',
+    scopes: ['comment', 'punctuation.definition.comment', 'string.comment'],
+  },
+  {
+    key: 'accent',
+    scopes: [
+      'keyword',
+      'keyword.control',
+      'keyword.operator',
+      'keyword.other',
+      'storage',
+      'storage.type',
+      'storage.modifier',
+      'entity.name.tag',
+      'punctuation.definition.tag',
+      'variable.language',
+      'markup.heading',
+    ],
+  },
+  {
+    key: 'text',
+    scopes: [
+      'string',
+      'string.quoted',
+      'string.template',
+      'constant.character',
+      'constant.character.escape',
+      'string.regexp',
+      'meta.attribute-selector',
+    ],
+  },
+  {
+    key: 'value',
+    scopes: [
+      'constant.numeric',
+      'constant.language',
+      'constant.other',
+      'support.constant',
+      'variable.other.constant',
+    ],
+  },
+  {
+    key: 'ink',
+    fontStyle: 'bold',
+    scopes: [
+      'entity.name.function',
+      'support.function',
+      'entity.name.type',
+      'entity.name.class',
+      'support.type',
+      'support.class',
+      'entity.other.attribute-name',
+    ],
+  },
+  {
+    key: 'ink',
+    scopes: [
+      'variable',
+      'variable.other',
+      'variable.parameter',
+      'meta.object-literal.key',
+      'punctuation',
+      'meta.brace',
+      'source',
+    ],
+  },
+];
+
+export const themeName = (register: Register) => `forest-${register}`;
+
+/**
+ * One Shiki theme for one register.
+ *
+ * `type` matters to Shiki's own dual-theme plumbing (it decides which `--shiki-*` variable a token
+ * lands on), so it tracks the register rather than being hard-coded — a theme declared `light` and
+ * handed to the `dark` slot emits its colours into the wrong custom property and the switch in
+ * base.css silently does nothing.
+ */
+export function forestCodeTheme(register: Register): ThemeRegistrationRaw {
+  const inks = codeInks(register);
+  return {
+    name: themeName(register),
+    type: register === 'light' ? 'light' : 'dark',
+    // The block's own fill is base.css's job (--deck-surface, so it re-points with the register and
+    // sits on the same surface ladder as a Card). Declared here anyway because Shiki writes it into
+    // `--shiki-*-bg`, which @shikijs/magic-move and the twoslash popup both read.
+    bg: inks.ground,
+    fg: inks.ink,
+    settings: SCOPES.map(({ key, fontStyle, scopes }) => ({
+      scope: scopes,
+      settings: { foreground: inks[key], ...(fontStyle ? { fontStyle } : {}) },
+    })),
+  };
+}
+
+/** Both registers, in the shape Slidev's `setup/shiki.ts` wants back. */
+export const forestCodeThemes = () => ({
+  light: forestCodeTheme('light'),
+  dark: forestCodeTheme('dark'),
+});
+
+/** Exported for the gate — the scope table is the thing under test, not a copy of it. */
+export const CODE_SCOPES = SCOPES;

package/components/deckPalette.ts

@@ -0,0 +1,157 @@
+// The deck's colour roles, RESOLVED TO HEX, for the two consumers that cannot read a CSS variable.
+//
+// Everything else on a slide styles itself with `var(--deck-accent)` and re-points for free when the
+// register changes. Two things in this theme cannot:
+//
+//   · SHIKI runs in NODE. A code theme is a JSON object of TextMate scopes to `#rrggbb`, built
+//     before a browser exists, so `var(--deck-fg)` in it is a string that highlights nothing.
+//   · MERMAID renders into a SHADOW ROOT and derives ~100 secondary colours from the ones it is
+//     given, with real colour maths (khroma). A `var(…)` handed to that arithmetic is NaN, and the
+//     shadow boundary means a stylesheet cannot reach in and correct the result afterwards.
+//
+// So both need literal hex, per register — which is exactly the thing a design system must not let
+// anyone type by hand. This module derives it instead, from the same two generated artefacts the CSS
+// is generated from, so a ramp step retuned upstream moves the code theme and the diagrams with it.
+//
+// ★ THE DERIVED SURFACES ARE COMPUTED, NOT PINNED. `--deck-surface` is
+// `color-mix(in oklab, var(--deck-bg), var(--deck-fg) 5%)` — there is no hex for it anywhere in the
+// token output, because the whole point of deriving it is that it re-tunes when the ground moves.
+// `mixOklab` below is that same operation in TypeScript, and codeTheme.static.test.ts checks it
+// against the mix percentages deck.json publishes rather than against a number typed here.
+// Verified against a live Chromium render of the deck before this file was written: computed
+// #f1ede6 / #0c332d, measured #f1ede6 / #0c332d.
+import ramps from '@humanforest/tokens/scales/ramps.json';
+import deckTokens from '@humanforest/tokens/deck/deck.json';
+import { hexToLin, linToOklab, oklabToLin, linToSrgb } from '@humanforest/tokens/colourEngine';
+
+export type Register = 'light' | 'dark';
+
+type Ramps = Record<string, { levels: Record<string, { hex: string }> }>;
+const RAMPS = ramps as unknown as Ramps;
+
+/** One ramp step, by family and level — the only place this theme reaches into the scales. */
+export function ramp(family: string, level: number | string): string {
+  const fam = RAMPS[family];
+  if (!fam) throw new Error(`deckPalette: no ramp "${family}" — [${Object.keys(RAMPS).join(', ')}]`);
+  const step = fam.levels[String(level)];
+  if (!step) throw new Error(`deckPalette: ramp ${family} has no level ${level} — [${Object.keys(fam.levels).join(', ')}]`);
+  return step.hex.toLowerCase();
+}
+
+/**
+ * `color-mix(in oklab, a, b P%)`, in TypeScript.
+ *
+ * Oklab specifically, not sRGB: deck.css mixes in oklab and the two disagree visibly in the middle
+ * of a ramp. Mixing the wrong way here would give a code ground a shade off the one actually painted
+ * and every contrast figure this module's gate reports would be measuring a colour nothing renders.
+ */
+export function mixOklab(a: string, b: string, percentB: number): string {
+  const A = linToOklab(hexToLin(a));
+  const B = linToOklab(hexToLin(b));
+  const t = percentB / 100;
+  const lin = oklabToLin(A.map((v, i) => v * (1 - t) + B[i] * t));
+  const byte = (v: number) => Math.round(Math.max(0, Math.min(1, linToSrgb(v))) * 255).toString(16).padStart(2, '0');
+  return `#${byte(lin[0])}${byte(lin[1])}${byte(lin[2])}`;
+}
+
+type DeckJson = {
+  roles: { light: Record<string, string>; dark: Record<string, string> };
+  derived: Record<string, { mixPercent: number; note: string }>;
+  backgrounds: Record<string, Record<Register, { fill: string; ink: string }>>;
+};
+const DECK = deckTokens as unknown as DeckJson;
+
+/** `var(--forest-700)` → the hex it names. deck.json stores references, not colours. */
+function resolveRef(raw: string, what: string): string {
+  if (raw.startsWith('#')) return raw.toLowerCase();
+  const m = /^var\(--([a-z]+)-(\d+)\)$/.exec(raw.trim());
+  if (!m) throw new Error(`deckPalette: ${what} is "${raw}", which is neither a hex nor a single ramp reference — deck.json's shape changed`);
+  return ramp(m[1], Number(m[2]));
+}
+
+function deref(role: string, register: Register): string {
+  const raw = DECK.roles[register][role];
+  if (!raw) throw new Error(`deckPalette: no --deck-${role} in the ${register} register — [${Object.keys(DECK.roles[register]).join(', ')}]`);
+  return resolveRef(raw, `--deck-${role}`);
+}
+
+/**
+ * A named background and the ink measured against it, resolved for a register.
+ *
+ * Fill and ink come back TOGETHER because deck.json pairs them, and the pairing is the contract: a
+ * caller picks a background by NAME and so cannot put a light ink on a dark ground by picking two values
+ * that were never measured against each other. `BACKGROUND_NAMES` is read off the same table rather than
+ * listed here, so a fifth background reaches every consumer without an edit.
+ */
+export const BACKGROUND_NAMES: string[] = Object.keys(DECK.backgrounds);
+
+export function background(name: string, register: Register): { fill: string; ink: string } {
+  const entry = DECK.backgrounds[name];
+  if (!entry) throw new Error(`deckPalette: deck.json declares no background "${name}" — [${BACKGROUND_NAMES.join(', ')}]`);
+  const pair = entry[register];
+  return {
+    fill: resolveRef(pair.fill, `--deck-bg-${name} (${register})`),
+    ink: resolveRef(pair.ink, `--deck-on-bg-${name} (${register})`),
+  };
+}
+
+/**
+ * Every role these two consumers need, per register.
+ *
+ * The derived levels come out of deck.json's own `derived` table, so the mix percentages live in one
+ * place and this file cannot drift from the stylesheet by a percent nobody notices.
+ */
+/**
+ * A status role's `mark` step, resolved for a register.
+ *
+ * Reads the family off deck.json's own status table rather than naming it here, so a palette
+ * retune that moves danger to a different ramp reaches this without an edit.
+ */
+function statusMark(state: string, register: Register): string {
+  const status = (DECK as { status?: { levels: Record<string, string>; markDark?: string; roles: Record<string, Record<string, string>> } }).status;
+  const ref = status?.roles?.[state]?.mark;
+  if (!ref) throw new Error(`deckPalette: deck.json declares no status role "${state}" with a mark`);
+  const family = /^var\(--([a-z]+)-\d+\)$/.exec(ref)?.[1];
+  if (!family) throw new Error(`deckPalette: status mark "${ref}" is not a single ramp reference — deck.json's shape changed`);
+  const step = register === 'light' ? status.levels.mark : status.markDark;
+  if (!step) throw new Error('deckPalette: deck.json records no markDark step — regenerate with bun run build:deck');
+  return ramp(family, Number(step));
+}
+
+/** One of deck.json's own derived mix percentages, by name — the stylesheet's number, not a copy. */
+export function derivedMix(name: string): number {
+  const d = DECK.derived[name];
+  if (!d) throw new Error(`deckPalette: deck.json declares no derived surface "${name}" — [${Object.keys(DECK.derived).join(', ')}]`);
+  return d.mixPercent;
+}
+
+export function palette(register: Register) {
+  const bg = deref('bg', register);
+  const fg = deref('fg', register);
+  const mixed = (name: string) => {
+    const d = DECK.derived[name];
+    if (!d) throw new Error(`deckPalette: deck.json declares no derived surface "${name}" — [${Object.keys(DECK.derived).join(', ')}]`);
+    return mixOklab(bg, fg, d.mixPercent);
+  };
+  return {
+    bg,
+    fg,
+    fgMuted: deref('fg-muted', register),
+    fgSubtle: deref('fg-subtle', register),
+    accent: deref('accent', register),
+    accentStrong: deref('accent-strong', register),
+    onAccent: deref('on-accent', register),
+    surface: mixed('surface'),
+    surfaceStrong: mixed('surface-strong'),
+    border: mixed('border'),
+    borderStrong: mixed('border-strong'),
+    /* The semantic DANGER mark, per register — family-500 on light and family-400 on dark, exactly
+       as the generator re-points it. Exposed here rather than resolved by each caller because a
+       component that wants "the danger colour" should not have to know which ramp family danger is
+       or which step a mark takes; mermaidTheme's crit bar is the first caller and picked the wrong
+       one by hand before this existed. */
+    dangerMark: statusMark('danger', register),
+  };
+}
+
+export const REGISTERS: Register[] = ['light', 'dark'];

package/components/dottedMapGeometry.js

@@ -0,0 +1,60 @@
+// The pure geometry DottedMap.vue's `highlight` prop resolves through — pulled out of the SFC's
+// <script setup> so it is unit-testable. This package has no @vue/test-utils / component-mounting
+// harness (only vitest, over plain modules) — the same reason backgrounds.js/iconSlugs.js are plain
+// modules rather than living inline in the components that use them.
+//
+// FIX ROUND 3, IMPORTANT 5 — two bugs closed here, both silent:
+//
+//   binOf(point, grid) used to trust its input completely: a caller passing a STRING (a borough
+//   NAME — `manifest/presets.ts`'s own `map` preset text used to tell an author to set `highlight`
+//   to "whichever boroughs the copy is about", with nothing warning that a NAME isn't what the prop
+//   actually accepts) hit `point.lng` on a string, got `undefined`, and every arithmetic step after
+//   that propagated NaN silently: `Math.floor(NaN) === NaN`, and `${NaN},${NaN}` never matches any
+//   real cell key. `binOf('Southwark')` returned `[NaN, NaN]` with no error at all. Fixed: `binOf`
+//   now THROWS on anything that is not a real `[col, row]` pair or a `{ lng, lat }` object with
+//   finite numbers, and validates the result actually lands inside the grid — so a garbled point
+//   (NaN from bad input, or a real lng/lat genuinely outside London's own bbox) is a loud,
+//   actionable error instead of a value that silently matches nothing.
+//
+//   DottedMap.vue's own `onDots` used to be `grid.dots.filter(isOn)` — `grid.dots` is the LAND list
+//   only, disjoint from `grid.river` (the river band is deliberately dilated for legibility, so it
+//   claims real cells of its own). A point that binned correctly and landed in a river cell was
+//   never in `grid.dots` at all, so its highlight never drew — no mark, no warning, no fallback.
+//   Tower Bridge, Canary Wharf and Rotherhithe all bin there. Fixed: `highlightedCells` below
+//   returns every validated highlight directly, independent of whether its cell happens to be
+//   classified land or river in the base grid — DottedMap.vue draws from THIS, not from
+//   `grid.dots.filter(...)`.
+
+/** A single highlight entry ([col, row] or { lng, lat }) resolved to a validated [col, row] pair,
+    or a thrown error naming exactly what was wrong — never a silent NaN. */
+export const binOf = (point, grid) => {
+  let col;
+  let row;
+  if (Array.isArray(point)) {
+    [col, row] = point;
+  } else if (point && typeof point === 'object' && Number.isFinite(point.lng) && Number.isFinite(point.lat)) {
+    const [lng0, lat0, lng1, lat1] = grid.bbox;
+    col = Math.floor(((point.lng - lng0) / (lng1 - lng0)) * grid.width);
+    row = Math.floor(((lat1 - point.lat) / (lat1 - lat0)) * grid.height);
+  } else {
+    throw new Error(
+      `DottedMap: highlight entry ${JSON.stringify(point)} is neither a [col, row] pair nor a { lng, lat } ` +
+        'object with finite numbers — a borough NAME string is not accepted; pass its real coordinates ' +
+        '({ lng, lat }) or a grid index ([col, row]).',
+    );
+  }
+  if (!Number.isFinite(col) || !Number.isFinite(row) || col < 0 || col >= grid.width || row < 0 || row >= grid.height) {
+    throw new Error(
+      `DottedMap: highlight entry ${JSON.stringify(point)} bins to [${col}, ${row}], outside the ` +
+        `${grid.width}×${grid.height} grid — check the coordinate is really inside London's own bbox.`,
+    );
+  }
+  return [col, row];
+};
+
+/** Every highlighted cell, validated and deduplicated by cell — independent of whether that cell
+    is classified land or river in the base grid, so a riverside point still draws its mark. */
+export const highlightedCells = (highlight, grid) => {
+  const keys = new Set(highlight.map((p) => binOf(p, grid).join(',')));
+  return [...keys].map((k) => k.split(',').map(Number));
+};