From 262637113969702af6a89f7c071e0d41aeb1ec03 Mon Sep 17 00:00:00 2001
From: Jono Brandel <developer@jono.fyi>
Date: Wed, 12 Aug 2026 22:23:10 -0700
Subject: [PATCH 1/4] docs: add design for declarative Diffs playground

Ports ~/Documents/diffs into src/playgrounds/diffs, rebuilt on react-two.js
components. Replaces the mutable Registry and frame-driven layout cursors with
one pure buildModel(), and derives highlight state instead of mutating the
scene graph and DOM.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../2026-08-12-diffs-playground-design.md     | 333 ++++++++++++++++++
 1 file changed, 333 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-08-12-diffs-playground-design.md

diff --git a/docs/superpowers/specs/2026-08-12-diffs-playground-design.md b/docs/superpowers/specs/2026-08-12-diffs-playground-design.md
new file mode 100644
index 0000000..ab7c51b
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-12-diffs-playground-design.md
@@ -0,0 +1,333 @@
+# Diffs Playground — Design
+
+Port `~/Documents/diffs` into `react-two.js` as a playground alongside Wiremarks,
+rebuilt on the library's declarative components instead of imperative Two.js
+scene manipulation.
+
+## Source Material
+
+`~/Documents/diffs` is a React 17 + esbuild app (two.js 0.8) that visually
+compares texts by shared vocabulary. Its live code is ~1,900 lines across
+`app.js`, `results/index.js`, `results/stat-line.js`, `results/graph-line.js`,
+`results/arc.js`, `legend.js`, `keyword.js`, `registry.js`, and `utils/`.
+
+`src/visualization/` (matter-js physics) is dead code — nothing imports it. It
+is not ported.
+
+What the app does:
+
+- N text panes, each with a title and a body
+- Words are tokenized, stripped of contractions/punctuation, and stemmed
+  (Porter2, via `wink-porter2-stemmer`)
+- Each text renders a column of "stat lines": a rounded rectangle in the text's
+  color, the word, and a tally count. Repeat occurrences within a text collapse
+  into the first line and bump its tally.
+- Words appearing in two or more texts move to a shared "Shared Words" column
+  and are hidden from their owning columns
+- A "graph line" per column draws a vertical polyline with a point per row
+- A legend maps colors to text names
+- Pan/zoom over the whole scene
+- Highlight mode: clicking a word (in text or on canvas) tints every matching
+  stat line, marks matching points on the graph lines, draws staggered arcs from
+  the visible occurrence to each hidden one, and pans the camera to the match
+- State persists to `localStorage`; the scene exports as SVG
+
+## Goals
+
+1. Feature parity with the original.
+2. The scene is a pure function of state, rendered with `react-two.js`
+   components. No imperative scene-graph construction, no mutable registry, no
+   frame-driven cursors into half-built state.
+3. Follow the structural conventions Wiremarks already established in this repo.
+
+## Non-Goals
+
+- No changes to `lib/`. `useZUI` already provides pointer pan, two-pointer
+  pinch, wheel/trackpad zoom, `pan: 'background'` gating, and the `panTo` /
+  `clientToSurface` / `surfaceToClient` conversions this design needs.
+- No port of `src/visualization/` (matter-js).
+- No new DSL, no new file format. Input is plain text, as before.
+
+## Architecture
+
+```
+src/playgrounds/diffs/
+├── DiffsPlayground.tsx        # DOM chrome; owns texts, mode, selection, toggles
+├── DiffsCanvas.tsx            # <Canvas> child: useZUI, TWEEN tick, camera pan
+├── components/
+│   ├── DiffsScene.tsx         # arcs / graph lines / columns groups
+│   ├── StatLine.tsx           # RoundedRectangle + word Text + tally Text
+│   ├── GraphLine.tsx          # Line + row Points + highlight Points
+│   ├── Arc.tsx                # Path with computed arc vertices
+│   ├── Legend.tsx             # swatch + name per text, plus Shared Words
+│   └── TextColumn.tsx         # DOM pane: textarea, or tokenized highlight view
+├── hooks/
+│   ├── useDiffsModel.ts       # texts -> deferred model + reveal progress
+│   ├── useProgressiveReveal.ts
+│   └── useTweenTick.ts        # one useFrame -> TWEEN.update()
+├── model/
+│   ├── tokenize.ts            # split, strip contractions/non-words
+│   ├── stem.ts                # Porter2 wrapper with a memo cache
+│   ├── analyze.ts             # per-text stems, counts, sorting
+│   ├── merge.ts               # cross-text shared-word resolution
+│   └── layout.ts              # row/column coordinates, graph-line extents
+├── stopwords.ts               # ported from the original utils/string.js
+├── storage.ts                 # versioned localStorage load/save
+├── constants.ts               # leading, size, characterWidth, column pitch
+└── types.ts
+```
+
+Registered in `src/playgrounds/registry.ts`:
+
+```ts
+{
+  id: 'diffs',
+  name: 'Diffs',
+  description: 'Visually compare texts by shared vocabulary',
+  component: DiffsPlayground,
+}
+```
+
+## State
+
+User-owned, persisted:
+
+```ts
+interface TextDoc {
+  id: string;
+  name: string;
+  color: string; // rgb(...) string, assigned on creation
+  body: string;
+}
+```
+
+Plus `mode: SortMode` (`'chronologic' | 'frequency' | 'alphabetic'`),
+`selectedStem: string | null`, and three booleans for the Text / Visuals /
+Highlight toggles.
+
+Everything else is derived.
+
+## The Model
+
+One pure function, `buildModel(texts: TextDoc[], mode: SortMode): DiffsModel`:
+
+1. **Tokenize** each body: split on whitespace, strip trailing contractions
+   (`/['’]\w*$/`) and non-word characters (`/[^\w\-_]+/g`), drop empties.
+2. **Stem** each token with Porter2. A module-level `Map<string, string>` cache
+   keeps repeated words cheap; it is a pure memo, not shared state.
+3. **Fold per text**: group tokens by stem. The first occurrence becomes the
+   visible line; `count` is the number of occurrences. Stopword stems are marked
+   not visible (the original's `regex.restricted`).
+4. **Merge across texts**: any stem present in two or more texts moves into the
+   shared column with a summed count, and is marked hidden in every owning
+   column.
+5. **Sort** each column's lines by mode: `chronologic` by first token index,
+   `frequency` by count descending, `alphabetic` by stem.
+6. **Lay out**: visible lines get `y = row * leading * 1.15`; column `n` sits at
+   `x = (n + 1) * 250`; the shared column sits at `x = 40`. Each column's graph
+   line spans its first to last visible row and carries a point per row. Line
+   width is `(word.length + 1 + String(count).length) * characterWidth`, matching
+   the original — a character-count estimate, so the model stays pure and needs
+   no DOM measurement.
+
+Output:
+
+```ts
+interface StatLineDatum {
+  key: string;      // `${textId}:${stem}`
+  word: string;     // display form (first occurrence)
+  stem: string;
+  count: number;
+  x: number;
+  y: number;
+  width: number;
+}
+
+interface Column {
+  id: string;        // a TextDoc id, or the literal 'shared'
+  color: string;
+  x: number;
+  lines: StatLineDatum[];
+  graph: { top: number; bottom: number; points: { x: number; y: number }[] };
+}
+
+interface DiffsModel {
+  columns: Column[];   // one per text
+  shared: Column;
+  byStem: Map<string, StatLineDatum[]>; // for highlight + arc lookup
+  totalLines: number;
+  totalChars: number;
+}
+```
+
+This replaces the original's mutable `Registry` class, its `needsUpdate` flags,
+and the `layout` / `reconcile` / `merge` frame machinery with its
+`index` / `yid` / `mergeId` cursors. Same output, one function, directly
+testable without a canvas.
+
+## Progressive Reveal
+
+The original builds the scene incrementally — `MAX_ITERATIONS` lines per frame,
+with a spinning indicator while it works. That build-up is preserved, but as
+state rather than as partially-constructed scene graph.
+
+`useDiffsModel(texts, mode)`:
+
+- `const deferred = useDeferredValue(texts)` so typing stays responsive
+- `const model = useMemo(() => buildModel(deferred, mode), [deferred, mode])`
+- `const revealed = useProgressiveReveal(model)` — a `useFrame`-driven counter
+  that grows by `clamp(floor(model.totalChars / 100), 1, 250)` per frame, the
+  original's `MAX_ITERATIONS` formula. It resets to 0 whenever `model` identity
+  changes and stops once it reaches `model.totalLines`.
+- `processing = revealed < model.totalLines || deferred !== texts`
+
+Reveal is allocated across columns in order, so `DiffsScene` renders
+`column.lines.slice(0, revealedForColumn)`.
+
+**Known risk.** Growing a state counter each frame re-renders the scene during
+build-up, and React reconciliation is heavier than the original's direct object
+creation. `StatLine` is wrapped in `memo` and keyed by `StatLineDatum.key`, so
+settled lines neither re-render nor remount and only newly revealed lines mount.
+The chunk size already scales with input length. This is the riskiest part of
+the port; measure it with a large paired text during phase 4 and, if it stalls,
+raise the chunk floor before reaching for a worker.
+
+## Rendering
+
+`DiffsCanvas` mounts inside `<Canvas type={Two.Types.svg}>`, holds the
+`useZUI(sceneGroupRef, { minZoom: 0.06, maxZoom: 8 })` (the original's limits),
+and runs one `useFrame` that calls `TWEEN.update()`.
+
+`DiffsScene` renders, in z-order:
+
+```tsx
+<Group>              {/* arcs */}
+<Group>              {/* graph lines */}
+<Group>              {/* columns of stat lines */}
+```
+
+- **StatLine** — `<Group x y onPointerDown>` containing `<RoundedRectangle>`
+  (fill = column color, stroke = yellow when highlighted), a left-aligned
+  `<Text>` for the word, and a right-aligned `<Text>` for the tally. The
+  pointer handler only reports a selection when highlight mode is on.
+- **GraphLine** — `<Line>` from `graph.top` to `graph.bottom`, a `<Points
+  size={4}>` for row ticks, and a `<Points size={12} fill="yellow">` whose
+  vertices are the rows matching `selectedStem`.
+- **Arc** — `<Path curved beginning={...}>` whose vertices are computed from the
+  source and target points in a `useMemo`. The original's custom `Two.Path`
+  subclass is unnecessary: `Path` already exposes `beginning`, `ending`,
+  `curved`, and `vertices`.
+- **Legend** — rendered by `DiffsCanvas` as a sibling of the ZUI group, not
+  inside `DiffsScene`, so it stays fixed to the viewport while the scene pans.
+  This matches the original, which added the legend to `two` rather than to the
+  panned stage. One row per text plus a Shared Words row, each a `<Circle>`
+  swatch and a `<Text>`.
+
+## Highlight Mode
+
+`selectedStem` is the single source of truth. Both entry points — clicking a
+word span in a text pane, and clicking a stat line on the canvas — call the same
+setter, which toggles off if the stem is already selected.
+
+Derived from it:
+
+- `line.stem === selectedStem` decides a stat line's highlight styling
+- graph-line highlight points are a `useMemo` over the model
+- arcs are a `useMemo` from the visible occurrence (shared column, or the first
+  column containing it) to each hidden occurrence
+
+This removes `stage.getByClassName()`, the
+`className.replace(/(sl|highlight)/ig, '')` string parsing, the
+`document.querySelectorAll('svg g.sl')` listener add/remove toggle, and the
+`requestAnimationFrame` tick loops in `addHighlightsToGraphLines` and the
+`show`/`hide` text highlighters.
+
+## Text Panes
+
+`TextColumn` renders a controlled `<input>` for the title and, depending on
+mode:
+
+- **Editing** — a controlled `<textarea value={body} onChange={...}>`. State
+  updates immediately; only the `localStorage` write is debounced.
+- **Highlight mode** — a read-only `<div style={{ whiteSpace: 'pre-wrap' }}>`
+  rendering memoized tokens, where each word is a `<span data-stem>` that gets a
+  highlight class when its stem matches `selectedStem`. Clicking a span is a
+  plain `onClick` that reads `data-stem`.
+
+This removes the `contentEditable` panes, the `innerHTML` regex rewriting, the
+manual selection-offset word-boundary scanner, and the
+`execCommand('insertHTML')` paste handler — which also resolves the original
+README's open "on paste don't strip carriage returns" item.
+
+## Chrome and Layout
+
+Inside the playground's bounded container: the canvas fills it, and the text
+columns overlay it in a flex row with translucent backgrounds, fading in and out
+via the Text Visible / Visuals Visible toggles exactly as the original does.
+
+Controls become a floating Catalyst button bar, in the idiom Wiremarks
+established:
+
+- Add Text Field / Remove Text Field
+- Sort By: {mode} (cycles)
+- Text Visible / Visuals Visible / Highlight Mode toggles
+- Clear Session (confirms first)
+- Export SVG
+- A processing indicator that spins while `processing` is true
+
+A zoom-percentage readout sits bottom-right and resets zoom on click, matching
+Wiremarks.
+
+## Renderer and Export
+
+The canvas uses `Two.Types.svg`, as the original did. Text stays crisp at any
+zoom and Export SVG works by serializing the live `<svg>` element, the same way
+`WiremarksPlayground.handleDownload` does. The cost is one DOM node group per
+stat line; the progressive reveal already spreads that creation across frames.
+
+## Persistence
+
+`storage.ts` mirrors `wiremarks/storage.ts`: a `DIFFS_STATE_VERSION` constant, a
+`diffs-state-v1` key, and a stored payload of `{ id, name, color, body }[]` plus
+`mode`. A version mismatch discards the stored state rather than migrating it.
+Writes are debounced (1s, as in the original); reads happen once on mount.
+
+## Dependencies
+
+Added to the demo app (not to the library's peer dependencies):
+
+- `wink-porter2-stemmer` — Porter2 stemming, MIT
+- `@tweenjs/tween.js` — arc reveal and camera pan tweens
+
+Not carried over: `matter-js` (dead code), the `less` color-function import
+(replaced by a local HSL→RGB helper), the custom `Arc extends Two.Path` class,
+the `Registry` class, and `utils/easing.js` (TWEEN supplies the easing).
+
+## Testing
+
+Following the repo's existing `tests/` conventions:
+
+- `diffsTokenize.test.ts` — contractions, punctuation, empty tokens, stopwords
+- `diffsModel.test.ts` — within-text tally collapse, cross-text merge into the
+  shared column, all three sort modes, computed row/column coordinates
+- `diffsStorage.test.ts` — round-trip and version invalidation
+- `diffsStatLine.test.tsx` — renders word and tally, emits its stem on click
+  only in highlight mode, applies highlight styling
+- `diffsReveal.test.ts` — the counter reaches `totalLines`, resets on model
+  change, and sizes chunks from `totalChars`
+
+## Phases
+
+1. **Model** — `tokenize`, `stem`, `analyze`, `merge`, `layout`, `stopwords`,
+   with tests. No UI.
+2. **Shell** — `DiffsPlayground`, `TextColumn` editing, add/remove, sort cycle,
+   `storage`, registry entry. Canvas empty.
+3. **Scene** — `DiffsCanvas`, `DiffsScene`, `StatLine`, `GraphLine`, `Legend`,
+   `useZUI`. Full model rendered at once.
+4. **Reveal** — `useProgressiveReveal`, the processing indicator, and a
+   measurement pass on a large paired text.
+5. **Highlight** — `selectedStem`, tokenized text view, canvas selection,
+   stat-line tinting, graph-line highlight points.
+6. **Arcs and camera** — `Arc`, `useTweenTick`, staggered reveal, `panTo` tween.
+7. **Finish** — Export SVG, Clear Session, visual polish against the original,
+   and a `CLAUDE.md` section documenting the playground.

From c3d11bcbababdab238cfef75b9eb637d15a6accb Mon Sep 17 00:00:00 2001
From: Jono Brandel <developer@jono.fyi>
Date: Thu, 20 Aug 2026 21:57:04 -0700
Subject: [PATCH 2/4] Add interactive diffs playground

Introduce a new Diffs playground that compares multiple texts by shared vocabulary. This adds the rendering scene, model/tokenization/stemming pipeline, progressive reveal and tween hooks, localStorage-backed session state, legend/stat line components, and playground registration.

The change also updates test setup and adds focused tests for the diffs model, canvas rendering, reveal behavior, stat-line interactions, storage, and tokenization, plus the new tween/stemmer dependencies needed by the feature.
---
 .claude/launch.json                           |   11 +
 CLAUDE.md                                     |    7 +-
 docs/superpowers/plans/2026-08-09-zui-hook.md | 1825 +++++++++++++++++
 package-lock.json                             |   78 +-
 package.json                                  |    6 +-
 src/playgrounds/diffs/DiffsCanvas.tsx         |  111 +
 src/playgrounds/diffs/DiffsPlayground.tsx     |  309 +++
 src/playgrounds/diffs/components/Arc.tsx      |   87 +
 .../diffs/components/DiffsScene.tsx           |  120 ++
 .../diffs/components/GraphLine.tsx            |   41 +
 src/playgrounds/diffs/components/Legend.tsx   |   60 +
 src/playgrounds/diffs/components/StatLine.tsx |   69 +
 .../diffs/components/TextColumn.tsx           |  117 ++
 src/playgrounds/diffs/constants.ts            |   25 +
 src/playgrounds/diffs/hooks/useDiffsModel.ts  |   25 +
 .../diffs/hooks/useMeasuredHeight.ts          |   24 +
 src/playgrounds/diffs/hooks/usePrefersDark.ts |   22 +
 .../diffs/hooks/useProgressiveReveal.ts       |   28 +
 src/playgrounds/diffs/hooks/useTweenTick.ts   |    8 +
 src/playgrounds/diffs/model/analyze.ts        |   80 +
 src/playgrounds/diffs/model/layout.ts         |  118 ++
 src/playgrounds/diffs/model/merge.ts          |   82 +
 src/playgrounds/diffs/model/stem.ts           |   18 +
 src/playgrounds/diffs/model/tokenize.ts       |   28 +
 src/playgrounds/diffs/stopwords.ts            |   52 +
 src/playgrounds/diffs/storage.ts              |   80 +
 src/playgrounds/diffs/types.ts                |   40 +
 src/playgrounds/registry.ts                   |    7 +
 src/test-setup.ts                             |   20 +-
 src/vite-env.d.ts                             |    5 +
 tests/diffsCanvas.test.tsx                    |  107 +
 tests/diffsModel.test.ts                      |   74 +
 tests/diffsReveal.test.ts                     |   47 +
 tests/diffsStatLine.test.tsx                  |  129 ++
 tests/diffsStorage.test.ts                    |   59 +
 tests/diffsTokenize.test.ts                   |   28 +
 36 files changed, 3942 insertions(+), 5 deletions(-)
 create mode 100644 .claude/launch.json
 create mode 100644 docs/superpowers/plans/2026-08-09-zui-hook.md
 create mode 100644 src/playgrounds/diffs/DiffsCanvas.tsx
 create mode 100644 src/playgrounds/diffs/DiffsPlayground.tsx
 create mode 100644 src/playgrounds/diffs/components/Arc.tsx
 create mode 100644 src/playgrounds/diffs/components/DiffsScene.tsx
 create mode 100644 src/playgrounds/diffs/components/GraphLine.tsx
 create mode 100644 src/playgrounds/diffs/components/Legend.tsx
 create mode 100644 src/playgrounds/diffs/components/StatLine.tsx
 create mode 100644 src/playgrounds/diffs/components/TextColumn.tsx
 create mode 100644 src/playgrounds/diffs/constants.ts
 create mode 100644 src/playgrounds/diffs/hooks/useDiffsModel.ts
 create mode 100644 src/playgrounds/diffs/hooks/useMeasuredHeight.ts
 create mode 100644 src/playgrounds/diffs/hooks/usePrefersDark.ts
 create mode 100644 src/playgrounds/diffs/hooks/useProgressiveReveal.ts
 create mode 100644 src/playgrounds/diffs/hooks/useTweenTick.ts
 create mode 100644 src/playgrounds/diffs/model/analyze.ts
 create mode 100644 src/playgrounds/diffs/model/layout.ts
 create mode 100644 src/playgrounds/diffs/model/merge.ts
 create mode 100644 src/playgrounds/diffs/model/stem.ts
 create mode 100644 src/playgrounds/diffs/model/tokenize.ts
 create mode 100644 src/playgrounds/diffs/stopwords.ts
 create mode 100644 src/playgrounds/diffs/storage.ts
 create mode 100644 src/playgrounds/diffs/types.ts
 create mode 100644 tests/diffsCanvas.test.tsx
 create mode 100644 tests/diffsModel.test.ts
 create mode 100644 tests/diffsReveal.test.ts
 create mode 100644 tests/diffsStatLine.test.tsx
 create mode 100644 tests/diffsStorage.test.ts
 create mode 100644 tests/diffsTokenize.test.ts

diff --git a/.claude/launch.json b/.claude/launch.json
new file mode 100644
index 0000000..04ffa28
--- /dev/null
+++ b/.claude/launch.json
@@ -0,0 +1,11 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "dev",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "dev"],
+      "port": 3000
+    }
+  ]
+}
diff --git a/CLAUDE.md b/CLAUDE.md
index c36b85e..eb51cb3 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -265,4 +265,9 @@ Node ids are scoped as `` `${name}\u0000${occurrence}` `` where occurrence
 counts blocks mentioning that name, in document order. `node.name` stays the
 raw name and is what gets rendered — ids are internal only. Changing this
 scheme requires bumping `POSITIONS_VERSION` in `storage.ts`, since stored
-drag positions are keyed by id.
\ No newline at end of file
+drag positions are keyed by id.
+
+### Diffs Playground
+Ported from `~/Documents/diffs`. Compares texts visually by tokenizing, stemming (Porter2 via `wink-porter2-stemmer`), and grouping shared vocabulary into a central Shared Words column. Pure model architecture (`buildModel`) with frame-driven progressive reveal (`useProgressiveReveal`), highlight mode (`selectedStem`), animated arcs, and camera auto-pan tween (`TWEEN`). Storage versioning uses `STORAGE_KEY = 'diffs-state-v1'`.
+
+Text in `StatLine` and `Legend` must set `baseline={TEXT_BASELINE}` (`'baseline'` → `dominant-baseline: alphabetic`). The original asked for `'top'`, which its older two.js emitted verbatim — an invalid CSS value browsers resolve to `auto`, i.e. alphabetic. The `y` offsets (`SIZE * 0.33` for the word, `SIZE * 0.25` for the tally) were tuned against that, so two.js's `middle` default renders the text ~5.6px low.
\ No newline at end of file
diff --git a/docs/superpowers/plans/2026-08-09-zui-hook.md b/docs/superpowers/plans/2026-08-09-zui-hook.md
new file mode 100644
index 0000000..1017075
--- /dev/null
+++ b/docs/superpowers/plans/2026-08-09-zui-hook.md
@@ -0,0 +1,1825 @@
+# ZUI Hook + Wiremarks Integration — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Ship a production-ready `useZUI` React hook that adds zoom/pan to any react-two.js `Group`, and wire it into the Wiremarks playground so background-drag pans, wheel/pinch zooms, and node-dragging stays pixel-accurate at any zoom level.
+
+**Architecture:** `useZUI` wraps Two.js's `ZUI` extra, binds Pointer Events to a target DOM element, and keeps all zoom/pan state in a ref (rAF-coalesced notifications) so high-frequency wheel events never re-render the scene. Panning is gated on a new `hitTestPoint(clientX, clientY)` method exposed through `TwoCoreContext`: if the pointer landed on a registered shape, ZUI stands down and the shape's own drag handler wins.
+
+**Tech Stack:** TypeScript (strict), React 18.3+, Two.js >= v0.8.23 (`two.js/extras/jsm/zui.js`), Vitest + React Testing Library + jsdom.
+
+## Global Constraints
+
+- Branch from `feat-playgrounds`. **Do NOT merge or cherry-pick the `7-zui` branch** — it forks from `e077c5e`, predates the split-context refactor, and is superseded by this plan. Read it for reference only.
+- TypeScript strict mode. No `any` without an `// eslint-disable-next-line @typescript-eslint/no-explicit-any` comment matching existing codebase style.
+- **Never publish an ambient `declare module 'two.js/extras/jsm/zui.js'`.** Types stay local and non-ambient (Task 1).
+- Library code lives in `lib/`. Tests live in `tests/`. Demo code lives in `src/`.
+- Run tests with `npx vitest run <path>` (bare `npm test` starts watch mode).
+- Two.js `contains()` and `getBoundingClientRect(false)` already operate in **world space** and already account for a group's `worldMatrix`. Hit testing therefore works under zoom with **no changes to `lib/Events.ts` hit-test logic.** Do not "fix" it.
+- The ZUI-managed `<Group>` must never receive `x`, `y`, or `scale` props — `lib/Group.tsx:77-92` re-applies props on every render and would fight ZUI.
+
+## Verified Preconditions
+
+These were checked against the installed `two.js@0.8.23-r.2` and this repo's jsdom before the plan was written. Trust them; do not re-litigate.
+
+| Assumption | Status |
+|---|---|
+| `two.js/extras/jsm/zui.js` imports and runs under Vitest | ✅ verified |
+| `addLimits(0.25, 8)` clamps `zui.scale` at both ends | ✅ verified |
+| `zoomBy(Math.LN2)` yields `scale === 2` and writes through to `group.scale` | ✅ verified |
+| `translateSurface(50, 30)` writes to `surfaceMatrix.elements[2]/[5]` and `group.translation` | ✅ verified |
+| At scale 2, a 100px client move is a 50-unit `clientToSurface` delta (the Task 6 invariant) | ✅ verified |
+| `requestAnimationFrame` exists in jsdom | ✅ verified |
+| `PointerEvent` exists in jsdom | ❌ **absent** — polyfill required, Task 4 Step 1 |
+| Two.js `contains()` / `getBoundingClientRect(false)` use `worldMatrix`, so hit testing already works under zoom | ✅ verified by source inspection |
+
+---
+
+## File Structure
+
+**Create:**
+- `lib/zuiTypes.ts` — non-ambient type surface for the untyped Two.js ZUI extra
+- `lib/zuiMath.ts` — pure, framework-free gesture math
+- `lib/ZUI.ts` — `useZUI` + `useZUIState`
+- `tests/zuiMath.test.ts` — pure math tests
+- `tests/zui.test.tsx` — hook + gesture integration tests
+
+**Modify:**
+- `lib/Events.ts` — extract `clientToWorldPoint`
+- `lib/Context.ts` — add `hitTestPoint` to `TwoCoreContextValue`
+- `lib/Provider.tsx` — implement `hitTestPoint`, add to `coreValue`
+- `lib/Group.tsx:110-117`, `lib/SVG.tsx:232-239` — forward `hitTestPoint`
+- `lib/main.ts` — export the hook
+- `vite.config.lib.ts` — externalize deep `two.js/*` imports
+- `src/playgrounds/wiremarks/components/WiremarkEntity.tsx` — emit client coords
+- `src/playgrounds/wiremarks/components/WiremarksScene.tsx` — relay new callback signature
+- `src/playgrounds/wiremarks/WiremarkCanvas.tsx` — mount ZUI, convert drag to surface space
+- `src/playgrounds/wiremarks/WiremarksPlayground.tsx` — zoom UI + cursor
+
+**Explicitly out of scope:** `fitTo`/fit-to-content, minimap, keyboard panning, fixing the pre-existing broken SVG export in `WiremarksPlayground.handleDownload` (it calls `querySelector('svg')` while the Canvas renders with `Two.Types.canvas`).
+
+---
+
+### Task 1: ZUI types + build externalization
+
+**Files:**
+- Create: `lib/zuiTypes.ts`
+- Modify: `vite.config.lib.ts:19`
+
+**Interfaces:**
+- Produces: `ZUIInstance` interface, `ZUIConstructor` type.
+
+`vite.config.lib.ts` currently has `external: ['react', 'react/jsx-runtime', 'two.js']` — an exact-match array. `two.js/extras/jsm/zui.js` would not match and would get **bundled into the published library**. Fix that here.
+
+- [ ] **Step 1: Create the local type surface**
+
+`lib/zuiTypes.ts`:
+
+```ts
+/**
+ * Local, non-ambient types for `two.js/extras/jsm/zui.js`, which ships no
+ * declarations. Declaring this as an ambient module would leak into every
+ * consumer of react-two.js, so we type it structurally and cast at the
+ * single import site in `lib/ZUI.ts`.
+ */
+import type { Group } from 'two.js/src/group';
+import type { Matrix } from 'two.js/src/matrix';
+
+export interface ZUIVector {
+  x: number;
+  y: number;
+  z: number;
+}
+
+export interface ZUIInstance {
+  zoom: number;
+  scale: number;
+  surfaceMatrix: Matrix;
+  viewport: HTMLElement;
+  limits: {
+    scale: { min: number; max: number };
+    x: { min: number; max: number };
+    y: { min: number; max: number };
+  };
+  addLimits(min?: number, max?: number): ZUIInstance;
+  zoomBy(byF: number, clientX: number, clientY: number): ZUIInstance;
+  zoomSet(zoom: number, clientX: number, clientY: number): ZUIInstance;
+  translateSurface(x: number, y: number): ZUIInstance;
+  clientToSurface(x: number, y: number, z?: number): ZUIVector;
+  surfaceToClient(x: number, y: number, z?: number): ZUIVector;
+  updateOffset(): ZUIInstance;
+  updateSurface(): ZUIInstance;
+  reset(): ZUIInstance;
+}
+
+export type ZUIConstructor = new (
+  group: Group,
+  domElement?: HTMLElement
+) => ZUIInstance;
+```
+
+- [ ] **Step 2: Externalize deep two.js imports**
+
+In `vite.config.lib.ts`, replace the `external` line:
+
+```ts
+      external: [/^react$/, /^react\/jsx-runtime$/, /^two\.js(\/.*)?$/],
+```
+
+- [ ] **Step 3: Verify typecheck passes**
+
+Run: `npx tsc --noEmit -p ./tsconfig.build.json`
+Expected: no errors.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add lib/zuiTypes.ts vite.config.lib.ts
+git commit -m "feat(zui): add local ZUI types and externalize deep two.js imports"
+```
+
+---
+
+### Task 2: Gesture math (pure functions)
+
+**Files:**
+- Create: `lib/zuiMath.ts`
+- Test: `tests/zuiMath.test.ts`
+
+**Interfaces:**
+- Produces: `normalizeWheelDelta`, `wheelZoomDelta`, `pinchWheelZoomDelta`, `pinchZoomDelta`, `distance`, `centroid`, `clamp`, and the `PanBounds` type.
+
+Zoom in Two.js's ZUI is **logarithmic**: `scale = Math.exp(zoom)`, and `zoomBy(byF)` adds `byF` to the log-space position. Every function below returns log-space deltas.
+
+- [ ] **Step 1: Write the failing tests**
+
+`tests/zuiMath.test.ts`:
+
+```ts
+import { describe, it, expect } from 'vitest';
+import {
+  normalizeWheelDelta,
+  wheelZoomDelta,
+  pinchWheelZoomDelta,
+  pinchZoomDelta,
+  distance,
+  centroid,
+  clamp,
+} from '../lib/zuiMath';
+
+describe('normalizeWheelDelta', () => {
+  it('passes pixel mode through unchanged', () => {
+    expect(normalizeWheelDelta(100, 0, 800)).toBe(100);
+  });
+
+  it('scales line mode by 16px per line', () => {
+    expect(normalizeWheelDelta(3, 1, 800)).toBe(48);
+  });
+
+  it('scales page mode by the viewport height', () => {
+    expect(normalizeWheelDelta(1, 2, 800)).toBe(800);
+  });
+});
+
+describe('wheelZoomDelta', () => {
+  it('returns a negative log delta when scrolling down (zoom out)', () => {
+    expect(wheelZoomDelta(100, 0, 0.05, 800)).toBeCloseTo(-0.05, 10);
+  });
+
+  it('returns a positive log delta when scrolling up (zoom in)', () => {
+    expect(wheelZoomDelta(-100, 0, 0.05, 800)).toBeCloseTo(0.05, 10);
+  });
+
+  it('is symmetric so a scroll down then up is a round trip', () => {
+    const down = wheelZoomDelta(100, 0, 0.05, 800);
+    const up = wheelZoomDelta(-100, 0, 0.05, 800);
+    expect(down + up).toBeCloseTo(0, 10);
+  });
+});
+
+describe('pinchWheelZoomDelta', () => {
+  it('inverts a ctrl-wheel trackpad pinch', () => {
+    expect(pinchWheelZoomDelta(-10)).toBeCloseTo(0.1, 10);
+  });
+});
+
+describe('pinchZoomDelta', () => {
+  it('returns zero when the distance is unchanged', () => {
+    expect(pinchZoomDelta(100, 100)).toBe(0);
+  });
+
+  it('returns a log ratio so doubling the spread is scale-independent', () => {
+    expect(pinchZoomDelta(100, 200)).toBeCloseTo(Math.LN2, 10);
+    expect(pinchZoomDelta(400, 800)).toBeCloseTo(Math.LN2, 10);
+  });
+
+  it('guards against zero and negative distances', () => {
+    expect(pinchZoomDelta(0, 100)).toBe(0);
+    expect(pinchZoomDelta(100, 0)).toBe(0);
+  });
+});
+
+describe('distance and centroid', () => {
+  it('computes euclidean distance', () => {
+    expect(distance({ x: 0, y: 0 }, { x: 3, y: 4 })).toBe(5);
+  });
+
+  it('computes the midpoint of two points', () => {
+    expect(centroid([{ x: 0, y: 0 }, { x: 10, y: 20 }])).toEqual({ x: 5, y: 10 });
+  });
+
+  it('returns the origin for an empty list', () => {
+    expect(centroid([])).toEqual({ x: 0, y: 0 });
+  });
+});
+
+describe('clamp', () => {
+  it('clamps to both bounds', () => {
+    expect(clamp(5, 0, 10)).toBe(5);
+    expect(clamp(-1, 0, 10)).toBe(0);
+    expect(clamp(11, 0, 10)).toBe(10);
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `npx vitest run tests/zuiMath.test.ts`
+Expected: FAIL — cannot resolve `../lib/zuiMath`.
+
+- [ ] **Step 3: Implement**
+
+`lib/zuiMath.ts`:
+
+```ts
+/**
+ * Pure gesture math for the ZUI hook. No React, no DOM — everything here is
+ * directly unit-testable.
+ *
+ * Two.js's ZUI treats zoom logarithmically (`scale = Math.exp(zoom)`), so all
+ * "delta" helpers below return log-space amounts suitable for `zui.zoomBy()`.
+ */
+
+/** Approximate pixel height of one wheel "line" in DOM_DELTA_LINE mode. */
+export const LINE_HEIGHT_PX = 16;
+
+/** Log-space units applied per unit of ctrl+wheel (trackpad pinch) delta. */
+export const PINCH_WHEEL_FACTOR = 0.01;
+
+/** A single wheel notch in DOM_DELTA_PIXEL mode, used to normalise `speed`. */
+export const WHEEL_NOTCH_PX = 100;
+
+export interface Point {
+  x: number;
+  y: number;
+}
+
+export interface PanBounds {
+  x?: [number, number];
+  y?: [number, number];
+}
+
+export function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+/**
+ * Convert a `WheelEvent.deltaY` into pixels, accounting for `deltaMode`.
+ * Firefox reports lines (mode 1); some environments report pages (mode 2).
+ */
+export function normalizeWheelDelta(
+  deltaY: number,
+  deltaMode: number,
+  viewportHeight: number
+): number {
+  switch (deltaMode) {
+    case 1:
+      return deltaY * LINE_HEIGHT_PX;
+    case 2:
+      return deltaY * viewportHeight;
+    default:
+      return deltaY;
+  }
+}
+
+/**
+ * Log-space zoom delta for a standard scroll wheel. `speed` is expressed in
+ * log units per notch, so the default of 0.05 means one notch changes scale
+ * by a factor of e^0.05 (~5%).
+ */
+export function wheelZoomDelta(
+  deltaY: number,
+  deltaMode: number,
+  speed: number,
+  viewportHeight: number
+): number {
+  const pixels = normalizeWheelDelta(deltaY, deltaMode, viewportHeight);
+  return (-pixels / WHEEL_NOTCH_PX) * speed;
+}
+
+/** Log-space zoom delta for a trackpad pinch, which arrives as ctrl+wheel. */
+export function pinchWheelZoomDelta(deltaY: number): number {
+  return -deltaY * PINCH_WHEEL_FACTOR;
+}
+
+/**
+ * Log-space zoom delta for a two-finger pinch. Using the log of the distance
+ * ratio makes the gesture feel identical at every zoom level — the WIP branch
+ * used a linear pixel difference, which did not.
+ */
+export function pinchZoomDelta(
+  prevDistance: number,
+  nextDistance: number
+): number {
+  if (prevDistance <= 0 || nextDistance <= 0) {
+    return 0;
+  }
+  return Math.log(nextDistance / prevDistance);
+}
+
+export function distance(a: Point, b: Point): number {
+  const dx = a.x - b.x;
+  const dy = a.y - b.y;
+  return Math.sqrt(dx * dx + dy * dy);
+}
+
+export function centroid(points: Point[]): Point {
+  if (points.length === 0) {
+    return { x: 0, y: 0 };
+  }
+  let x = 0;
+  let y = 0;
+  for (const point of points) {
+    x += point.x;
+    y += point.y;
+  }
+  return { x: x / points.length, y: y / points.length };
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `npx vitest run tests/zuiMath.test.ts`
+Expected: PASS, 13 tests.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/zuiMath.ts tests/zuiMath.test.ts
+git commit -m "feat(zui): add pure gesture math helpers"
+```
+
+---
+
+### Task 3: `hitTestPoint` on the core context
+
+**Files:**
+- Modify: `lib/Events.ts:101-112`, `lib/Context.ts:7-30`, `lib/Provider.tsx:186-192` and `:560-567`, `lib/Group.tsx:110-117`, `lib/SVG.tsx:232-239`
+- Test: `tests/events.test.tsx`
+
+**Interfaces:**
+- Consumes: nothing from earlier tasks.
+- Produces: `clientToWorldPoint(clientX: number, clientY: number, canvas: HTMLElement): { x: number; y: number }` from `lib/Events.ts`; `hitTestPoint(clientX: number, clientY: number): boolean` on `TwoCoreContextValue`.
+
+This is the coordination channel that lets `useZUI` know whether a pointerdown was already claimed by a shape. It queries the exact same registry, in the exact same coordinate space, as the Provider's own dispatch — so there is no listener-ordering dependency.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `tests/events.test.tsx`, inside the top-level `describe('react-two.js Event System', ...)` block:
+
+```tsx
+  describe('hitTestPoint', () => {
+    it('reports true over a registered shape and false over empty canvas', () => {
+      const seen: Array<{ label: string; hit: boolean }> = [];
+
+      function Probe() {
+        const { hitTestPoint } = useTwo();
+        useEffect(() => {
+          seen.push({ label: 'inside', hit: hitTestPoint(400, 300) });
+          seen.push({ label: 'outside', hit: hitTestPoint(10, 10) });
+        }, [hitTestPoint]);
+        return null;
+      }
+
+      render(
+        <Canvas type={Two.Types.canvas} width={800} height={600}>
+          <Group>
+            <RoundedRectangle
+              x={400}
+              y={300}
+              width={100}
+              height={60}
+              onPointerDown={() => {}}
+            />
+          </Group>
+          <Probe />
+        </Canvas>,
+      );
+
+      expect(seen.find((s) => s.label === 'inside')?.hit).toBe(true);
+      expect(seen.find((s) => s.label === 'outside')?.hit).toBe(false);
+    });
+  });
+```
+
+Add `useEffect` to the `react` import at the top of the file and `useTwo` to the `react-two.js` import.
+
+> Note on coordinates: jsdom returns an all-zero `getBoundingClientRect()` for the canvas, so client coords and canvas-relative coords coincide in tests. The shape sits at world (400, 300) with a 100x60 box, so client (400, 300) is inside and (10, 10) is outside.
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run tests/events.test.tsx -t hitTestPoint`
+Expected: FAIL — `hitTestPoint is not a function`.
+
+- [ ] **Step 3: Extract the shared coordinate helper**
+
+In `lib/Events.ts`, replace the body of `getWorldCoordinates` (lines 101-112) with a delegating version and add the new export directly above it:
+
+```ts
+/**
+ * Convert raw client coordinates to world-space coordinates for hit testing.
+ * World space uses a top-left origin, relative to the canvas element.
+ */
+export function clientToWorldPoint(
+  clientX: number,
+  clientY: number,
+  canvas: HTMLElement
+): { x: number; y: number } {
+  const rect = canvas.getBoundingClientRect();
+
+  return {
+    x: clientX - rect.left,
+    y: clientY - rect.top,
+  };
+}
+
+/**
+ * Convert DOM event coordinates to world-space coordinates for hit testing
+ * World-space uses top-left origin (same as DOM but relative to canvas)
+ */
+export function getWorldCoordinates(
+  nativeEvent: PointerEvent | MouseEvent,
+  canvas: HTMLElement
+): { x: number; y: number } {
+  return clientToWorldPoint(nativeEvent.clientX, nativeEvent.clientY, canvas);
+}
+```
+
+- [ ] **Step 4: Add `hitTestPoint` to the context type**
+
+In `lib/Context.ts`, add the member to `TwoCoreContextValue` (after `unregisterEventShape`):
+
+```ts
+  hitTestPoint: (clientX: number, clientY: number) => boolean;
+```
+
+and to the `createContext` default:
+
+```ts
+export const TwoCoreContext = createContext<TwoCoreContextValue>({
+  two: null,
+  registerEventShape: () => {},
+  unregisterEventShape: () => {},
+  hitTestPoint: () => false,
+});
+```
+
+- [ ] **Step 5: Implement it in the Provider**
+
+In `lib/Provider.tsx`, add `clientToWorldPoint` to the existing import from `./Events`, then add this callback immediately after the `unregisterEventShape` definition (around line 192):
+
+```tsx
+  /**
+   * Returns true if any registered event shape sits under the given client
+   * coordinates. Used by `useZUI` to leave pointerdowns that landed on a
+   * shape alone, so shape drags and canvas panning never fight.
+   */
+  const hitTestPoint = useCallback(
+    (clientX: number, clientY: number): boolean => {
+      const canvas = twoState?.renderer.domElement;
+      if (!canvas) return false;
+
+      const point = clientToWorldPoint(clientX, clientY, canvas);
+      return (
+        getShapesAtPoint(eventShapes.current, point.x, point.y, twoState)
+          .length > 0
+      );
+    },
+    [twoState],
+  );
+```
+
+Then add it to `coreValue` (around line 560):
+
+```tsx
+  const coreValue = useMemo(
+    () => ({
+      two: twoState,
+      registerEventShape,
+      unregisterEventShape,
+      hitTestPoint,
+    }),
+    [twoState, registerEventShape, unregisterEventShape, hitTestPoint],
+  );
+```
+
+- [ ] **Step 6: Forward it through Group and SVG**
+
+`lib/Group.tsx` — add `hitTestPoint` to the `useTwo()` destructure (line 35-42) and to `coreValue`:
+
+```tsx
+    const coreValue = useMemo(
+      () => ({
+        two,
+        registerEventShape,
+        unregisterEventShape,
+        hitTestPoint,
+      }),
+      [two, registerEventShape, unregisterEventShape, hitTestPoint]
+    );
+```
+
+`lib/SVG.tsx` — make the identical change to its `useTwo()` destructure and its `coreValue` at lines 232-239.
+
+- [ ] **Step 7: Run the full test suite**
+
+Run: `npx vitest run tests/`
+Expected: PASS, including the new `hitTestPoint` test. No regressions in `events.test.tsx`.
+
+- [ ] **Step 8: Lint and commit**
+
+```bash
+npm run lint
+git add lib/Events.ts lib/Context.ts lib/Provider.tsx lib/Group.tsx lib/SVG.tsx tests/events.test.tsx
+git commit -m "feat(events): expose hitTestPoint through the core context"
+```
+
+---
+
+### Task 4: The `useZUI` hook
+
+**Files:**
+- Create: `lib/ZUI.ts`
+- Modify: `lib/main.ts`, `src/test-setup.ts`
+- Test: `tests/zui.test.tsx`
+
+**Interfaces:**
+- Consumes: `ZUIConstructor` / `ZUIInstance` (Task 1); all of `lib/zuiMath.ts` (Task 2); `hitTestPoint` from `useTwo()` (Task 3).
+- Produces: `useZUI(target, options): ZUIControls`, `useZUIState(controls): ZUIState`, and the `UseZUIOptions` / `ZUIControls` / `ZUIState` / `ReadonlyRef` types.
+
+Key correctness requirements, each of which fixes a defect in the `7-zui` WIP:
+1. `instance` is a **ref**, never read during render.
+2. Zoom/pan state lives in a ref; listeners are notified on `requestAnimationFrame`, so a wheel gesture cannot re-render the scene per event.
+3. One Pointer Event code path handles mouse, touch, and pen. There is no separate touch branch.
+4. `lostpointercapture` and `pointercancel` both end a pan, so a drag can never get stuck.
+5. `panBounds` is enforced by us — Two.js's `ZUI` declares `limits.x`/`limits.y` but never reads them.
+
+- [ ] **Step 1: Polyfill `PointerEvent` for jsdom (required — do this first)**
+
+This project's jsdom does **not** implement `PointerEvent` (verified: `typeof PointerEvent === 'undefined'`). Without this, every gesture test throws `PointerEvent is not defined`.
+
+Append to `src/test-setup.ts`:
+
+```ts
+/**
+ * jsdom does not implement PointerEvent. The ZUI hook binds pointer events
+ * exclusively, so tests need a minimal stand-in. MouseEvent already carries
+ * clientX/clientY/button/buttons, so only the pointer-specific fields are added.
+ */
+interface PointerEventInitLike extends MouseEventInit {
+  pointerId?: number;
+  pointerType?: string;
+  isPrimary?: boolean;
+}
+
+if (typeof globalThis.PointerEvent === 'undefined') {
+  class PointerEventPolyfill extends MouseEvent {
+    readonly pointerId: number;
+    readonly pointerType: string;
+    readonly isPrimary: boolean;
+
+    constructor(type: string, params: PointerEventInitLike = {}) {
+      super(type, params);
+      this.pointerId = params.pointerId ?? 0;
+      this.pointerType = params.pointerType ?? 'mouse';
+      this.isPrimary = params.isPrimary ?? true;
+    }
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (globalThis as any).PointerEvent = PointerEventPolyfill;
+}
+```
+
+Verify it loads: `npx vitest run tests/events.test.tsx`
+Expected: PASS, no regressions.
+
+- [ ] **Step 2: Write the failing tests**
+
+`tests/zui.test.tsx`:
+
+```tsx
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, act } from '@testing-library/react';
+import { useEffect, useRef } from 'react';
+import Two from 'two.js';
+import { Canvas, Group, Circle, useZUI, type RefGroup, type ZUIControls } from '../lib/main';
+
+beforeEach(() => {
+  HTMLCanvasElement.prototype.getContext = vi.fn().mockReturnValue({
+    fillRect: vi.fn(), clearRect: vi.fn(), getImageData: vi.fn().mockReturnValue({ data: [] }),
+    putImageData: vi.fn(), createImageData: vi.fn().mockReturnValue([]), setTransform: vi.fn(),
+    drawImage: vi.fn(), save: vi.fn(), fillText: vi.fn(), restore: vi.fn(), beginPath: vi.fn(),
+    moveTo: vi.fn(), lineTo: vi.fn(), closePath: vi.fn(), stroke: vi.fn(), translate: vi.fn(),
+    scale: vi.fn(), rotate: vi.fn(), arc: vi.fn(), fill: vi.fn(),
+    measureText: vi.fn().mockReturnValue({ width: 0 }), transform: vi.fn(), rect: vi.fn(), clip: vi.fn(),
+  });
+});
+
+/** Renders a ZUI-managed group and hands the controls back to the test. */
+function Harness({
+  onReady,
+  withShape = false,
+}: {
+  onReady: (controls: ZUIControls, canvas: HTMLElement) => void;
+  withShape?: boolean;
+}) {
+  const groupRef = useRef<RefGroup | null>(null);
+  const controls = useZUI(groupRef, { minZoom: 0.25, maxZoom: 8 });
+
+  useEffect(() => {
+    const canvas = document.querySelector('canvas');
+    if (canvas) onReady(controls, canvas);
+  }, [controls, onReady]);
+
+  return (
+    <Group ref={groupRef}>
+      {withShape ? (
+        <Circle x={400} y={300} radius={50} onPointerDown={() => {}} />
+      ) : (
+        <Circle x={400} y={300} radius={50} />
+      )}
+    </Group>
+  );
+}
+
+function renderHarness(withShape = false) {
+  const captured: { controls?: ZUIControls; canvas?: HTMLElement } = {};
+  render(
+    <Canvas type={Two.Types.canvas} width={800} height={600}>
+      <Harness
+        withShape={withShape}
+        onReady={(controls, canvas) => {
+          captured.controls = controls;
+          captured.canvas = canvas;
+        }}
+      />
+    </Canvas>,
+  );
+  return captured as { controls: ZUIControls; canvas: HTMLElement };
+}
+
+function pointer(type: string, init: Partial<PointerEventInit>) {
+  return new PointerEvent(type, {
+    bubbles: true,
+    cancelable: true,
+    pointerId: 1,
+    isPrimary: true,
+    button: 0,
+    buttons: type === 'pointerup' ? 0 : 1,
+    ...init,
+  });
+}
+
+describe('useZUI', () => {
+  it('starts at scale 1 with an identity surface', () => {
+    const { controls } = renderHarness();
+    expect(controls.state.current.scale).toBe(1);
+    expect(controls.state.current.zoom).toBe(0);
+    expect(controls.state.current.x).toBe(0);
+    expect(controls.state.current.y).toBe(0);
+  });
+
+  it('exposes the ZUI instance via a ref, not a render-time value', () => {
+    const { controls } = renderHarness();
+    expect(controls.instance.current).not.toBeNull();
+  });
+
+  it('applies the zoom to the target group scale', () => {
+    const { controls } = renderHarness();
+    act(() => {
+      controls.zoomBy(Math.LN2, 400, 300);
+    });
+    expect(controls.state.current.scale).toBeCloseTo(2, 5);
+  });
+
+  it('clamps zoom to maxZoom', () => {
+    const { controls } = renderHarness();
+    act(() => {
+      controls.zoomBy(100, 400, 300);
+    });
+    expect(controls.state.current.scale).toBeCloseTo(8, 5);
+  });
+
+  it('clamps zoom to minZoom', () => {
+    const { controls } = renderHarness();
+    act(() => {
+      controls.zoomBy(-100, 400, 300);
+    });
+    expect(controls.state.current.scale).toBeCloseTo(0.25, 5);
+  });
+
+  it('pans on a background drag', () => {
+    const { controls, canvas } = renderHarness(false);
+    act(() => {
+      canvas.dispatchEvent(pointer('pointerdown', { clientX: 10, clientY: 10 }));
+      window.dispatchEvent(pointer('pointermove', { clientX: 60, clientY: 40 }));
+      window.dispatchEvent(pointer('pointerup', { clientX: 60, clientY: 40 }));
+    });
+    expect(controls.state.current.x).toBeCloseTo(50, 5);
+    expect(controls.state.current.y).toBeCloseTo(30, 5);
+  });
+
+  it('does NOT pan when the pointerdown lands on a registered shape', () => {
+    const { controls, canvas } = renderHarness(true);
+    act(() => {
+      canvas.dispatchEvent(pointer('pointerdown', { clientX: 400, clientY: 300 }));
+      window.dispatchEvent(pointer('pointermove', { clientX: 450, clientY: 330 }));
+      window.dispatchEvent(pointer('pointerup', { clientX: 450, clientY: 330 }));
+    });
+    expect(controls.state.current.x).toBe(0);
+    expect(controls.state.current.y).toBe(0);
+  });
+
+  it('ends a pan on pointercancel', () => {
+    const { controls, canvas } = renderHarness(false);
+    act(() => {
+      canvas.dispatchEvent(pointer('pointerdown', { clientX: 10, clientY: 10 }));
+      window.dispatchEvent(pointer('pointercancel', { clientX: 10, clientY: 10 }));
+      window.dispatchEvent(pointer('pointermove', { clientX: 200, clientY: 200 }));
+    });
+    expect(controls.state.current.x).toBe(0);
+  });
+
+  it('zooms on wheel toward the cursor', () => {
+    const { controls, canvas } = renderHarness();
+    act(() => {
+      canvas.dispatchEvent(
+        new WheelEvent('wheel', { bubbles: true, cancelable: true, deltaY: -100, deltaMode: 0, clientX: 400, clientY: 300 }),
+      );
+    });
+    expect(controls.state.current.scale).toBeGreaterThan(1);
+  });
+
+  it('resets back to the identity surface', () => {
+    const { controls } = renderHarness();
+    act(() => {
+      controls.zoomBy(1, 400, 300);
+      controls.panBy(25, 25);
+      controls.reset();
+    });
+    expect(controls.state.current.scale).toBe(1);
+    expect(controls.state.current.x).toBe(0);
+    expect(controls.state.current.y).toBe(0);
+  });
+
+  it('round-trips client and surface coordinates', () => {
+    const { controls } = renderHarness();
+    act(() => {
+      controls.zoomBy(0.5, 400, 300);
+      controls.panBy(40, -20);
+    });
+    const surface = controls.clientToSurface(250, 175);
+    const client = controls.surfaceToClient(surface.x, surface.y);
+    expect(client.x).toBeCloseTo(250, 4);
+    expect(client.y).toBeCloseTo(175, 4);
+  });
+
+  it('honours panBounds', () => {
+    const captured: { controls?: ZUIControls } = {};
+    function Bounded() {
+      const groupRef = useRef<RefGroup | null>(null);
+      captured.controls = useZUI(groupRef, { panBounds: { x: [-50, 50], y: [-50, 50] } });
+      return <Group ref={groupRef} />;
+    }
+    render(
+      <Canvas type={Two.Types.canvas} width={800} height={600}>
+        <Bounded />
+      </Canvas>,
+    );
+    act(() => {
+      captured.controls!.panBy(500, 500);
+    });
+    expect(captured.controls!.state.current.x).toBe(50);
+    expect(captured.controls!.state.current.y).toBe(50);
+  });
+});
+```
+
+- [ ] **Step 3: Run tests to verify they fail**
+
+Run: `npx vitest run tests/zui.test.tsx`
+Expected: FAIL — `useZUI` is not exported from `../lib/main`.
+
+- [ ] **Step 4: Implement the hook**
+
+`lib/ZUI.ts`:
+
+```ts
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useSyncExternalStore,
+  type RefObject,
+} from 'react';
+import { useTwo } from './Context';
+import type { RefGroup } from './Group';
+import type { ZUIConstructor, ZUIInstance } from './zuiTypes';
+import {
+  centroid,
+  clamp,
+  distance,
+  pinchWheelZoomDelta,
+  pinchZoomDelta,
+  wheelZoomDelta,
+  type PanBounds,
+  type Point,
+} from './zuiMath';
+
+// two.js ships no declarations for its extras; `lib/zuiTypes.ts` types it
+// structurally so we never leak an ambient module into consumers.
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-expect-error - untyped two.js extra
+import { ZUI as ZUIImpl } from 'two.js/extras/jsm/zui.js';
+
+const ZUIClass = ZUIImpl as unknown as ZUIConstructor;
+
+/**
+ * A ref whose `current` is always present. React 18's own `RefObject<T>` types
+ * `current` as `T | null`, which would force a null check on every read of
+ * `zui.state.current`.
+ */
+export interface ReadonlyRef<T> {
+  readonly current: T;
+}
+
+/** Immutable snapshot of the current zoom/pan state. */
+export interface ZUIState {
+  /** Logarithmic zoom position. `scale === Math.exp(zoom)`. */
+  zoom: number;
+  /** Linear scale factor. */
+  scale: number;
+  /** Surface translation on the x axis, in client pixels. */
+  x: number;
+  /** Surface translation on the y axis, in client pixels. */
+  y: number;
+}
+
+export interface UseZUIOptions {
+  /** Minimum scale factor (default: 0.25) */
+  minZoom?: number;
+  /** Maximum scale factor (default: 8) */
+  maxZoom?: number;
+  /** Log-space zoom units per wheel notch (default: 0.05) */
+  wheelZoomSpeed?: number;
+  /** Optional clamp on surface translation, in client pixels */
+  panBounds?: PanBounds;
+  /**
+   * `'background'` (default) pans only when the pointer misses every
+   * registered shape, so shape drag handlers win. `'always'` pans on any
+   * drag. `false` disables pointer panning entirely.
+   */
+  pan?: 'background' | 'always' | false;
+  /** `'wheel'` (default) enables wheel and trackpad-pinch zoom; `false` disables it. */
+  zoom?: 'wheel' | false;
+  /** Override the element that listeners attach to (default: the Two.js renderer element) */
+  domElement?: HTMLElement | null;
+  /** Called at most once per animation frame while zoom or pan changes. */
+  onChange?: (state: ZUIState) => void;
+}
+
+export interface ZUIControls {
+  /** Live, always-current state. Reading this never triggers a re-render. */
+  state: ReadonlyRef<ZUIState>;
+  /** True while a pointer pan is in progress. */
+  isPanning: ReadonlyRef<boolean>;
+  /** The underlying Two.js ZUI instance, for advanced use. */
+  instance: ReadonlyRef<ZUIInstance | null>;
+  /** Zoom by a log-space amount, anchored at the given client point. */
+  zoomBy: (byF: number, clientX: number, clientY: number) => void;
+  /** Zoom to an absolute scale factor, anchored at the given client point. */
+  zoomTo: (scale: number, clientX: number, clientY: number) => void;
+  /** Pan by a delta in client pixels. */
+  panBy: (dx: number, dy: number) => void;
+  /** Pan to an absolute surface translation in client pixels. */
+  panTo: (x: number, y: number) => void;
+  /** Restore scale 1 and zero translation. */
+  reset: () => void;
+  /** Convert client coordinates into the ZUI group's local space. */
+  clientToSurface: (x: number, y: number) => Point;
+  /** Convert the ZUI group's local space back into client coordinates. */
+  surfaceToClient: (x: number, y: number) => Point;
+  /** Subscribe to coalesced state changes. Used by `useZUIState`. */
+  subscribe: (listener: () => void) => () => void;
+  /** Read the current immutable snapshot. Used by `useZUIState`. */
+  getSnapshot: () => ZUIState;
+}
+
+const IDENTITY_STATE: ZUIState = { zoom: 0, scale: 1, x: 0, y: 0 };
+
+/**
+ * Add zoom and pan to a react-two.js `Group`.
+ *
+ * The target group's `x`, `y`, and `scale` are owned by this hook — do not
+ * also pass those props to it, or the two will fight each other.
+ *
+ * @example
+ * ```tsx
+ * function Scene() {
+ *   const groupRef = useRef<RefGroup | null>(null);
+ *   const zui = useZUI(groupRef, { minZoom: 0.25, maxZoom: 8 });
+ *
+ *   return (
+ *     <Group ref={groupRef}>
+ *       <Circle radius={50} />
+ *     </Group>
+ *   );
+ * }
+ * ```
+ */
+export function useZUI(
+  target: RefObject<RefGroup | null>,
+  options: UseZUIOptions = {}
+): ZUIControls {
+  const { two, hitTestPoint } = useTwo();
+
+  const instance = useRef<ZUIInstance | null>(null);
+  const state = useRef<ZUIState>(IDENTITY_STATE);
+  const isPanning = useRef(false);
+  const listeners = useRef(new Set<() => void>());
+  const frame = useRef<number | null>(null);
+
+  // Latest options, read inside event handlers so they never need rebinding.
+  const optionsRef = useRef(options);
+  useEffect(() => {
+    optionsRef.current = options;
+  });
+
+  const {
+    minZoom = 0.25,
+    maxZoom = 8,
+    domElement: domElementOption,
+  } = options;
+
+  const element = domElementOption ?? two?.renderer.domElement ?? null;
+
+  /**
+   * Publish a fresh immutable snapshot. The snapshot updates synchronously so
+   * drag math stays exact, but subscribers are notified on the next animation
+   * frame so a wheel gesture cannot re-render the scene per event.
+   */
+  const flush = useCallback(() => {
+    const zui = instance.current;
+    if (!zui) return;
+
+    const elements = zui.surfaceMatrix.elements;
+    state.current = {
+      zoom: zui.zoom,
+      scale: zui.scale,
+      x: elements[2],
+      y: elements[5],
+    };
+
+    if (frame.current !== null) return;
+
+    frame.current = requestAnimationFrame(() => {
+      frame.current = null;
+      optionsRef.current.onChange?.(state.current);
+      for (const listener of listeners.current) {
+        listener();
+      }
+    });
+  }, []);
+
+  /** Two.js's ZUI declares limits.x / limits.y but never applies them. */
+  const applyPanBounds = useCallback(() => {
+    const zui = instance.current;
+    const bounds = optionsRef.current.panBounds;
+    if (!zui || !bounds) return;
+
+    const elements = zui.surfaceMatrix.elements;
+    const x = clamp(
+      elements[2],
+      bounds.x?.[0] ?? -Infinity,
+      bounds.x?.[1] ?? Infinity
+    );
+    const y = clamp(
+      elements[5],
+      bounds.y?.[0] ?? -Infinity,
+      bounds.y?.[1] ?? Infinity
+    );
+
+    if (x !== elements[2] || y !== elements[5]) {
+      zui.translateSurface(x - elements[2], y - elements[5]);
+    }
+  }, []);
+
+  // Create the ZUI instance once the group and element both exist.
+  useEffect(() => {
+    const group = target.current;
+    if (!group || !element) return;
+
+    const zui = new ZUIClass(group, element);
+    zui.addLimits(minZoom, maxZoom);
+    instance.current = zui;
+    flush();
+
+    return () => {
+      instance.current = null;
+      if (frame.current !== null) {
+        cancelAnimationFrame(frame.current);
+        frame.current = null;
+      }
+    };
+  }, [target, element, minZoom, maxZoom, flush]);
+
+  const zoomBy = useCallback(
+    (byF: number, clientX: number, clientY: number) => {
+      const zui = instance.current;
+      if (!zui) return;
+      zui.zoomBy(byF, clientX, clientY);
+      applyPanBounds();
+      flush();
+    },
+    [applyPanBounds, flush]
+  );
+
+  const zoomTo = useCallback(
+    (scale: number, clientX: number, clientY: number) => {
+      const zui = instance.current;
+      if (!zui) return;
+      zui.zoomSet(scale, clientX, clientY);
+      applyPanBounds();
+      flush();
+    },
+    [applyPanBounds, flush]
+  );
+
+  const panBy = useCallback(
+    (dx: number, dy: number) => {
+      const zui = instance.current;
+      if (!zui) return;
+      zui.translateSurface(dx, dy);
+      applyPanBounds();
+      flush();
+    },
+    [applyPanBounds, flush]
+  );
+
+  const panTo = useCallback(
+    (x: number, y: number) => {
+      const zui = instance.current;
+      if (!zui) return;
+      const elements = zui.surfaceMatrix.elements;
+      zui.translateSurface(x - elements[2], y - elements[5]);
+      applyPanBounds();
+      flush();
+    },
+    [applyPanBounds, flush]
+  );
+
+  const reset = useCallback(() => {
+    const zui = instance.current;
+    if (!zui) return;
+    zui.reset();
+    flush();
+  }, [flush]);
+
+  const clientToSurface = useCallback((x: number, y: number): Point => {
+    const zui = instance.current;
+    if (!zui) return { x, y };
+    const result = zui.clientToSurface(x, y);
+    return { x: result.x, y: result.y };
+  }, []);
+
+  const surfaceToClient = useCallback((x: number, y: number): Point => {
+    const zui = instance.current;
+    if (!zui) return { x, y };
+    const result = zui.surfaceToClient(x, y);
+    return { x: result.x, y: result.y };
+  }, []);
+
+  const subscribe = useCallback((listener: () => void) => {
+    listeners.current.add(listener);
+    return () => {
+      listeners.current.delete(listener);
+    };
+  }, []);
+
+  const getSnapshot = useCallback(() => state.current, []);
+
+  // Pointer panning and pinch zoom. One code path covers mouse, touch and pen.
+  useEffect(() => {
+    if (!element) return;
+
+    const active = new Map<number, Point>();
+    let lastCentroid: Point | null = null;
+    let lastDistance = 0;
+
+    const points = () => Array.from(active.values());
+
+    const handlePointerDown = (event: PointerEvent) => {
+      const mode = optionsRef.current.pan ?? 'background';
+      if (mode === false) return;
+      if (event.pointerType === 'mouse' && event.button !== 0) return;
+      if (mode === 'background' && hitTestPoint(event.clientX, event.clientY)) {
+        return;
+      }
+
+      active.set(event.pointerId, { x: event.clientX, y: event.clientY });
+      isPanning.current = true;
+      lastCentroid = centroid(points());
+      lastDistance = active.size === 2 ? distance(points()[0], points()[1]) : 0;
+    };
+
+    const handlePointerMove = (event: PointerEvent) => {
+      if (!active.has(event.pointerId)) return;
+
+      active.set(event.pointerId, { x: event.clientX, y: event.clientY });
+      const current = points();
+      const nextCentroid = centroid(current);
+
+      if (lastCentroid) {
+        panBy(nextCentroid.x - lastCentroid.x, nextCentroid.y - lastCentroid.y);
+      }
+      lastCentroid = nextCentroid;
+
+      if (current.length === 2) {
+        const nextDistance = distance(current[0], current[1]);
+        if (lastDistance > 0) {
+          zoomBy(
+            pinchZoomDelta(lastDistance, nextDistance),
+            nextCentroid.x,
+            nextCentroid.y
+          );
+        }
+        lastDistance = nextDistance;
+      }
+    };
+
+    const endPointer = (event: PointerEvent) => {
+      if (!active.delete(event.pointerId)) return;
+
+      const remaining = points();
+      lastCentroid = remaining.length > 0 ? centroid(remaining) : null;
+      lastDistance =
+        remaining.length === 2 ? distance(remaining[0], remaining[1]) : 0;
+      isPanning.current = active.size > 0;
+    };
+
+    element.addEventListener('pointerdown', handlePointerDown);
+    window.addEventListener('pointermove', handlePointerMove);
+    window.addEventListener('pointerup', endPointer);
+    window.addEventListener('pointercancel', endPointer);
+    window.addEventListener('lostpointercapture', endPointer);
+
+    return () => {
+      element.removeEventListener('pointerdown', handlePointerDown);
+      window.removeEventListener('pointermove', handlePointerMove);
+      window.removeEventListener('pointerup', endPointer);
+      window.removeEventListener('pointercancel', endPointer);
+      window.removeEventListener('lostpointercapture', endPointer);
+    };
+  }, [element, hitTestPoint, panBy, zoomBy]);
+
+  // Wheel zoom, including ctrl+wheel trackpad pinch.
+  useEffect(() => {
+    if (!element) return;
+
+    const handleWheel = (event: WheelEvent) => {
+      if ((optionsRef.current.zoom ?? 'wheel') === false) return;
+
+      event.preventDefault();
+
+      const delta = event.ctrlKey
+        ? pinchWheelZoomDelta(event.deltaY)
+        : wheelZoomDelta(
+            event.deltaY,
+            event.deltaMode,
+            optionsRef.current.wheelZoomSpeed ?? 0.05,
+            element.clientHeight || window.innerHeight
+          );
+
+      zoomBy(delta, event.clientX, event.clientY);
+    };
+
+    element.addEventListener('wheel', handleWheel, { passive: false });
+    return () => element.removeEventListener('wheel', handleWheel);
+  }, [element, zoomBy]);
+
+  return useMemo(
+    () => ({
+      state,
+      isPanning,
+      instance,
+      zoomBy,
+      zoomTo,
+      panBy,
+      panTo,
+      reset,
+      clientToSurface,
+      surfaceToClient,
+      subscribe,
+      getSnapshot,
+    }),
+    [
+      zoomBy,
+      zoomTo,
+      panBy,
+      panTo,
+      reset,
+      clientToSurface,
+      surfaceToClient,
+      subscribe,
+      getSnapshot,
+    ]
+  );
+}
+
+/**
+ * Opt into re-rendering when zoom or pan changes. Only use this in components
+ * that actually display the value — `useZUI` alone never re-renders.
+ */
+export function useZUIState(controls: ZUIControls): ZUIState {
+  return useSyncExternalStore(
+    controls.subscribe,
+    controls.getSnapshot,
+    controls.getSnapshot
+  );
+}
+```
+
+- [ ] **Step 5: Export from the library entry point**
+
+In `lib/main.ts`, add below the `Group` export:
+
+```ts
+export {
+  useZUI,
+  useZUIState,
+  type UseZUIOptions,
+  type ZUIControls,
+  type ZUIState,
+  type ReadonlyRef,
+} from './ZUI';
+```
+
+- [ ] **Step 6: Run tests to verify they pass**
+
+Run: `npx vitest run tests/zui.test.tsx`
+Expected: PASS, 12 tests.
+
+Debugging notes if they do not:
+- **`state.current` is stale** — the snapshot updates synchronously inside `flush()`. If it lags, something is reading before `flush()` runs; this is not a `requestAnimationFrame` timing problem.
+- **The "does NOT pan on a shape" test pans anyway** — `hitTestPoint` returned false. Two.js `contains()` calls `_update(true)` and works headlessly, but a shape is only registered for hit testing if it has at least one event handler prop. Confirm the harness `Circle` has `onPointerDown`.
+- **The "pans on a background drag" test does not pan** — jsdom's `getBoundingClientRect()` returns all zeros, so client and canvas coordinates coincide. A hit at (10, 10) means a shape is registered near the origin; check the harness is passing `withShape={false}`.
+
+- [ ] **Step 7: Verify no regressions, then lint and commit**
+
+```bash
+npx vitest run tests/
+npm run lint
+npx tsc --noEmit -p ./tsconfig.build.json
+git add lib/ZUI.ts lib/main.ts src/test-setup.ts tests/zui.test.tsx
+git commit -m "feat(zui): add useZUI and useZUIState hooks"
+```
+
+---
+
+### Task 5: Wiremarks — client-space drag callbacks
+
+**Files:**
+- Modify: `src/playgrounds/wiremarks/components/WiremarkEntity.tsx:9-48`
+- Modify: `src/playgrounds/wiremarks/components/WiremarksScene.tsx:13-15`
+
+**Interfaces:**
+- Produces: the new drag callback contract used by Task 6 —
+  `onDragStart?: (nodeId: string, clientX: number, clientY: number) => void`,
+  `onDrag?: (nodeId: string, clientX: number, clientY: number) => void`,
+  `onDragEnd?: (nodeId: string) => void`.
+
+The entity currently computes deltas in **screen pixels** and hands them straight to `updateNodePosition`, which writes **world** coordinates. That is already an implicit assumption that scale is 1, and it breaks the moment ZUI lands. The fix is to stop computing deltas here at all: emit raw client coordinates and let the component that owns the ZUI controls do the conversion. `WiremarksScene` stays presentational and ZUI-unaware.
+
+This task also swaps the `mousemove`/`mouseup` listeners for pointer events, and adds `pointercancel` so a drag interrupted by the OS cannot get stuck.
+
+- [ ] **Step 1: Update the entity's props and handler**
+
+In `src/playgrounds/wiremarks/components/WiremarkEntity.tsx`, replace the props interface and `handlePointerDown`:
+
+```tsx
+interface WiremarkEntityProps {
+  node: WiremarkNode;
+  isDragging?: boolean;
+  onDragStart?: (nodeId: string, clientX: number, clientY: number) => void;
+  onDrag?: (nodeId: string, clientX: number, clientY: number) => void;
+  onDragEnd?: (nodeId: string) => void;
+}
+```
+
+```tsx
+  const handlePointerDown = useCallback(
+    (e: TwoEvent) => {
+      // Keeps useZUI from also treating this as a background pan.
+      e.stopPropagation();
+
+      const native = e.nativeEvent as PointerEvent;
+      onDragStart?.(node.id, native.clientX, native.clientY);
+
+      const handlePointerMove = (moveEvt: PointerEvent) => {
+        onDrag?.(node.id, moveEvt.clientX, moveEvt.clientY);
+      };
+
+      const handlePointerUp = () => {
+        onDragEnd?.(node.id);
+        window.removeEventListener('pointermove', handlePointerMove);
+        window.removeEventListener('pointerup', handlePointerUp);
+        window.removeEventListener('pointercancel', handlePointerUp);
+      };
+
+      window.addEventListener('pointermove', handlePointerMove);
+      window.addEventListener('pointerup', handlePointerUp);
+      window.addEventListener('pointercancel', handlePointerUp);
+    },
+    [node.id, onDragStart, onDrag, onDragEnd],
+  );
+```
+
+Keep the `TwoEvent` import in this file — the handler signature still uses it.
+
+- [ ] **Step 2: Relay the new signature through the scene**
+
+In `src/playgrounds/wiremarks/components/WiremarksScene.tsx`, update the props interface (lines 13-15) to match:
+
+```tsx
+  onDragStart?: (nodeId: string, clientX: number, clientY: number) => void;
+  onDrag?: (nodeId: string, clientX: number, clientY: number) => void;
+  onDragEnd?: (nodeId: string) => void;
+```
+
+The `TwoEvent` import at line 2 is now unused — remove it, leaving `import { Group } from 'react-two.js';`. The JSX below needs no changes; it already forwards the callbacks by reference.
+
+- [ ] **Step 3: Verify the typecheck fails in exactly one expected place**
+
+Run: `npx tsc --noEmit -p ./tsconfig.app.json`
+Expected: errors only in `src/playgrounds/wiremarks/WiremarkCanvas.tsx` — its `handleDragStart`/`handleDrag` still take `(nodeId, dx, dy)`. Task 6 fixes them.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/playgrounds/wiremarks/components/WiremarkEntity.tsx src/playgrounds/wiremarks/components/WiremarksScene.tsx
+git commit -m "refactor(wiremarks): emit client coordinates from entity drags"
+```
+
+---
+
+### Task 6: Wiremarks — mount ZUI and convert drags to surface space
+
+**Files:**
+- Modify: `src/playgrounds/wiremarks/WiremarkCanvas.tsx`
+- Test: `tests/zui.test.tsx`
+
+**Interfaces:**
+- Consumes: `useZUI`, `ZUIControls` (Task 4); the drag callback contract (Task 5).
+- Produces: `WiremarkCanvasProps` gains `controlsRef?: MutableRefObject<ZUIControls | null>` and `onZoomChange?: (scale: number) => void`, both consumed by Task 7.
+
+`sceneGroupRef` already exists here and is currently unused — it is the ZUI mount point.
+
+Drag positions are computed by converting **both** the drag origin and the current pointer into surface space and taking the difference. That is exact, and unlike dividing by `scale` it stays correct if the user zooms or pans mid-drag.
+
+- [ ] **Step 1: Write the failing test**
+
+This tests the exact invariant `WiremarkCanvas` relies on: the difference between two `clientToSurface` results is the true world-space distance the pointer travelled, at any zoom or pan.
+
+Append to `tests/zui.test.tsx`, inside the top-level `describe('useZUI', ...)` block:
+
+```tsx
+  describe('surface-space drag deltas', () => {
+    it('maps screen pixels one-for-one at scale 1', () => {
+      const { controls } = renderHarness();
+      const a = controls.clientToSurface(100, 100);
+      const b = controls.clientToSurface(200, 160);
+      expect(b.x - a.x).toBeCloseTo(100, 5);
+      expect(b.y - a.y).toBeCloseTo(60, 5);
+    });
+
+    it('halves the surface delta at scale 2', () => {
+      const { controls } = renderHarness();
+      act(() => {
+        controls.zoomBy(Math.LN2, 400, 300);
+      });
+      expect(controls.state.current.scale).toBeCloseTo(2, 5);
+
+      const a = controls.clientToSurface(100, 100);
+      const b = controls.clientToSurface(200, 100);
+      expect(b.x - a.x).toBeCloseTo(50, 5);
+    });
+
+    it('doubles the surface delta at scale 0.5', () => {
+      const { controls } = renderHarness();
+      act(() => {
+        controls.zoomBy(-Math.LN2, 400, 300);
+      });
+      expect(controls.state.current.scale).toBeCloseTo(0.5, 5);
+
+      const a = controls.clientToSurface(100, 100);
+      const b = controls.clientToSurface(200, 100);
+      expect(b.x - a.x).toBeCloseTo(200, 5);
+    });
+
+    it('is unaffected by panning', () => {
+      const { controls } = renderHarness();
+      act(() => {
+        controls.zoomBy(Math.LN2, 400, 300);
+        controls.panBy(123, -45);
+      });
+      const a = controls.clientToSurface(100, 100);
+      const b = controls.clientToSurface(200, 100);
+      expect(b.x - a.x).toBeCloseTo(50, 5);
+    });
+  });
+```
+
+- [ ] **Step 2: Run test to verify it passes against Task 4's hook**
+
+Run: `npx vitest run tests/zui.test.tsx -t "surface-space drag deltas"`
+Expected: PASS, 4 tests. These characterise `useZUI` from Task 4 and are the guard rail for Step 3 — if any of them fail, the bug is in `clientToSurface`, not in `WiremarkCanvas`. Fix Task 4 before continuing.
+
+- [ ] **Step 3: Rewrite WiremarkCanvas**
+
+Replace `src/playgrounds/wiremarks/WiremarkCanvas.tsx` entirely:
+
+```tsx
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type MutableRefObject,
+} from 'react';
+import { useFrame, useZUI, Group, RefGroup, type ZUIControls } from 'react-two.js';
+import { useWiremarksGraph } from './hooks/useWiremarksGraph';
+import { WiremarksScene } from './components/WiremarksScene';
+
+interface WiremarkCanvasProps {
+  instructions: string;
+  /** Receives the ZUI controls so DOM chrome outside <Canvas> can drive zoom. */
+  controlsRef?: MutableRefObject<ZUIControls | null>;
+  /** Called at most once per frame while the zoom level changes. */
+  onZoomChange?: (scale: number) => void;
+}
+
+export function WiremarkCanvas({
+  instructions,
+  controlsRef,
+  onZoomChange,
+}: WiremarkCanvasProps) {
+  const sceneGroupRef = useRef<RefGroup | null>(null);
+
+  const [dashOffset, setDashOffset] = useState(0);
+  const [draggingNodeId, setDraggingNodeId] = useState<string | null>(null);
+  const dragOriginRef = useRef<{
+    pointer: { x: number; y: number };
+    node: { x: number; y: number };
+  } | null>(null);
+
+  const { nodes, edges, nodesMap, updateNodePosition } =
+    useWiremarksGraph(instructions);
+
+  const handleZoomChange = useCallback(
+    (state: { scale: number }) => onZoomChange?.(state.scale),
+    [onZoomChange],
+  );
+
+  // `pan: 'background'` leaves pointerdowns that landed on an entity alone, so
+  // dragging a node never also pans the canvas.
+  const zui = useZUI(sceneGroupRef, {
+    minZoom: 0.25,
+    maxZoom: 8,
+    pan: 'background',
+    onChange: handleZoomChange,
+  });
+
+  useEffect(() => {
+    if (controlsRef) {
+      controlsRef.current = zui;
+    }
+  }, [controlsRef, zui]);
+
+  // Smooth 60fps dash offset animation loop
+  useFrame((_, frameDelta) => {
+    setDashOffset((prev) => prev - frameDelta / 10);
+  });
+
+  const handleDragStart = useCallback(
+    (nodeId: string, clientX: number, clientY: number) => {
+      setDraggingNodeId(nodeId);
+      const node = nodesMap.get(nodeId);
+      if (!node) return;
+
+      const pointer = zui.clientToSurface(clientX, clientY);
+      dragOriginRef.current = {
+        pointer,
+        node: { x: node.x, y: node.y },
+      };
+    },
+    [nodesMap, zui],
+  );
+
+  const handleDrag = useCallback(
+    (nodeId: string, clientX: number, clientY: number) => {
+      const origin = dragOriginRef.current;
+      if (!origin) return;
+
+      // Diffing two surface-space points stays exact even if the view zooms
+      // or pans partway through the drag.
+      const pointer = zui.clientToSurface(clientX, clientY);
+      updateNodePosition(
+        nodeId,
+        origin.node.x + (pointer.x - origin.pointer.x),
+        origin.node.y + (pointer.y - origin.pointer.y),
+      );
+    },
+    [updateNodePosition, zui],
+  );
+
+  const handleDragEnd = useCallback(() => {
+    setDraggingNodeId(null);
+    dragOriginRef.current = null;
+  }, []);
+
+  return (
+    // NOTE: this Group's translation and scale are owned by useZUI.
+    // Do not add x, y, or scale props to it.
+    <Group ref={sceneGroupRef}>
+      <WiremarksScene
+        nodes={nodes}
+        edges={edges}
+        nodesMap={nodesMap}
+        dashOffset={dashOffset}
+        draggingNodeId={draggingNodeId}
+        onDragStart={handleDragStart}
+        onDrag={handleDrag}
+        onDragEnd={handleDragEnd}
+      />
+    </Group>
+  );
+}
+```
+
+- [ ] **Step 4: Verify tests and typecheck pass**
+
+```bash
+npx vitest run tests/
+npx tsc --noEmit -p ./tsconfig.app.json
+npm run lint
+```
+Expected: all PASS, no type errors.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/playgrounds/wiremarks/WiremarkCanvas.tsx tests/zui.test.tsx
+git commit -m "feat(wiremarks): add zoom/pan and make node drags zoom-accurate"
+```
+
+---
+
+### Task 7: Wiremarks playground — zoom chrome
+
+**Files:**
+- Modify: `src/playgrounds/wiremarks/WiremarksPlayground.tsx`
+
+**Interfaces:**
+- Consumes: `WiremarkCanvasProps.controlsRef` and `.onZoomChange` (Task 6); `ZUIControls` (Task 4).
+
+The zoom buttons are DOM elements, so they must live outside `<Canvas>` (per the Canvas children restriction in `CLAUDE.md`). That is why this uses the `controlsRef` + `onZoomChange` pair rather than `useZUIState` — `useZUIState` is for components rendered *inside* the Canvas.
+
+- [ ] **Step 1: Wire up the controls ref and zoom readout**
+
+In `src/playgrounds/wiremarks/WiremarksPlayground.tsx`, add to the imports:
+
+```tsx
+import { type ZUIControls } from 'react-two.js';
+import { MagnifyingGlassPlusIcon, MagnifyingGlassMinusIcon } from '@heroicons/react/20/solid';
+```
+
+Add inside the component, next to the existing refs:
+
+```tsx
+  const zuiRef = useRef<ZUIControls | null>(null);
+  const [scale, setScale] = useState(1);
+
+  const zoomAtCenter = useCallback((delta: number) => {
+    const controls = zuiRef.current;
+    const canvas = containerRef.current?.querySelector('canvas');
+    if (!controls || !canvas) return;
+
+    const rect = canvas.getBoundingClientRect();
+    controls.zoomBy(delta, rect.left + rect.width / 2, rect.top + rect.height / 2);
+  }, []);
+
+  const handleResetView = useCallback(() => {
+    zuiRef.current?.reset();
+    setScale(1);
+  }, []);
+```
+
+Add `useCallback` to the `react` import.
+
+- [ ] **Step 2: Pass the props to the canvas**
+
+Replace the `<WiremarkCanvas ... />` call:
+
+```tsx
+          <WiremarkCanvas
+            instructions={text}
+            controlsRef={zuiRef}
+            onZoomChange={setScale}
+          />
+```
+
+- [ ] **Step 3: Add the cursor affordance**
+
+On the `<Canvas>` element, replace the two commented-out lines (currently at lines 99-100) with:
+
+```tsx
+          className="w-full h-full cursor-grab active:cursor-grabbing"
+          style={{ userSelect: 'none', touchAction: 'none' }}
+```
+
+`touchAction: 'none'` is required — without it the browser claims touch drags for scrolling and pinch-zoom before pointer events fire.
+
+- [ ] **Step 4: Add the zoom control cluster**
+
+Insert this block immediately after the closing `</div>` of the "Floating Action Controls" section:
+
+```tsx
+      {/* Zoom Controls */}
+      {!isOpen && (
+        <div className="absolute bottom-4 right-4 z-10 flex items-center gap-1 rounded-lg bg-white/90 dark:bg-zinc-900/90 p-1 shadow-lg backdrop-blur">
+          <Button plain onClick={() => zoomAtCenter(-0.2)} aria-label="Zoom out">
+            <MagnifyingGlassMinusIcon className="w-4 h-4" />
+          </Button>
+          <span className="min-w-[3.5rem] text-center text-xs tabular-nums text-zinc-600 dark:text-zinc-400">
+            {Math.round(scale * 100)}%
+          </span>
+          <Button plain onClick={() => zoomAtCenter(0.2)} aria-label="Zoom in">
+            <MagnifyingGlassPlusIcon className="w-4 h-4" />
+          </Button>
+          <Button plain onClick={handleResetView} aria-label="Reset view">
+            <ArrowPathIcon className="w-4 h-4" />
+          </Button>
+        </div>
+      )}
+```
+
+- [ ] **Step 5: Verify**
+
+```bash
+npx tsc --noEmit -p ./tsconfig.app.json
+npm run lint
+npx vitest run tests/
+```
+Expected: all PASS.
+
+- [ ] **Step 6: Manual smoke test**
+
+Run `npm run dev`, open the Wiremarks playground, close the instructions overlay, then confirm each of:
+1. Scroll wheel zooms toward the cursor; the percentage readout updates.
+2. Dragging empty background pans; the cursor shows grab/grabbing.
+3. Dragging an entity moves **only** that entity — the canvas must not pan at the same time.
+4. Zoom to ~400%, then drag an entity: it tracks the cursor exactly, with no drift or lag.
+5. Zoom to ~30% and repeat step 4.
+6. Zoom clamps at 25% and 800%.
+7. Reset returns to 100% and the original position.
+8. On a trackpad, two-finger pinch zooms rather than scrolling the page.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/playgrounds/wiremarks/WiremarksPlayground.tsx
+git commit -m "feat(wiremarks): add zoom controls and pan cursor affordances"
+```
+
+---
+
+### Task 8: Documentation
+
+**Files:**
+- Modify: `README.md`, `CLAUDE.md`
+
+- [ ] **Step 1: Document the hook in README.md**
+
+Add a `### useZUI()` subsection alongside the existing `useTwo()` / `useFrame()` documentation:
+
+````markdown
+### useZUI()
+
+Adds zoom and pan to a `Group`.
+
+```tsx
+function Scene() {
+  const groupRef = useRef<RefGroup | null>(null);
+  const zui = useZUI(groupRef, { minZoom: 0.25, maxZoom: 8 });
+
+  return (
+    <Group ref={groupRef}>
+      <Circle radius={50} />
+    </Group>
+  );
+}
+```
+
+By default `pan: 'background'` means a drag only pans when it does not land on
+a shape that has event handlers, so shape drag handlers keep working. Use
+`pan: 'always'` to pan unconditionally, or `pan: false` to disable it.
+
+Zoom and pan state lives in `zui.state.current` and updating it does **not**
+re-render. To display the zoom level from a component inside `<Canvas>`, use
+`useZUIState(zui)`. For DOM chrome outside `<Canvas>`, pass an `onChange`
+callback instead.
+
+To convert coordinates between screen and scene space — which you need for any
+drag interaction on a zoomable scene — use `zui.clientToSurface(x, y)`.
+
+> The target `<Group>`'s `x`, `y`, and `scale` are owned by the hook. Do not
+> also pass those props to it.
+````
+
+- [ ] **Step 2: Add the ZUI section to CLAUDE.md**
+
+Under "Context System", after the `useFrame()` block:
+
+````markdown
+### useZUI() Hook
+```typescript
+const zui = useZUI(groupRef, { minZoom: 0.25, maxZoom: 8 });
+```
+Zoom/pan for a `Group`. State lives in `zui.state.current` (a ref) and does not
+re-render; use `useZUIState(zui)` to opt into re-rendering.
+
+**Panning vs. shape drags:** `useZUI` calls `hitTestPoint()` from `TwoCoreContext`
+on pointerdown and skips panning if a registered shape was hit. Any component
+with its own drag behavior gets it for free.
+
+**Coordinate conversion:** drag handlers on a zoomable scene must convert client
+coordinates with `zui.clientToSurface()`. Diff two converted points rather than
+dividing a pixel delta by `scale` — the former stays correct if the view moves
+mid-drag. See `src/playgrounds/wiremarks/WiremarkCanvas.tsx`.
+
+**Constraint:** never pass `x`, `y`, or `scale` to a ZUI-managed `Group` —
+`Group.tsx` re-applies props on every render and would overwrite the transform.
+````
+
+Also add to the "Common Issues & Solutions" section:
+
+````markdown
+### Zoom/Pan Fighting Shape Drags
+- **Problem**: dragging a shape also pans the canvas
+- **Cause**: `pan: 'always'`, or the shape has no registered event handlers so
+  `hitTestPoint()` does not see it
+- **Solution**: keep the default `pan: 'background'` and make sure the shape has
+  at least one event handler prop, which is what registers it for hit testing
+````
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add README.md CLAUDE.md
+git commit -m "docs: document useZUI and the pan/drag interaction model"
+```
+
+---
+
+## Verification Checklist
+
+Before opening a PR, all of these must pass:
+
+```bash
+npx vitest run tests/
+npm run lint
+npx tsc --noEmit -p ./tsconfig.build.json
+npx tsc --noEmit -p ./tsconfig.app.json
+npm run build:lib
+```
+
+Then confirm the library build did not swallow the extra:
+
+```bash
+grep -c "class ZUI" dist/*.js
+```
+Expected: `0` — `two.js/extras/jsm/zui.js` must stay external (Task 1, Step 2).
+
+Finally, re-run the eight manual checks in Task 7 Step 6.
diff --git a/package-lock.json b/package-lock.json
index 901655c..0d9e989 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -16,6 +16,7 @@
         "@testing-library/jest-dom": "^6.6.3",
         "@testing-library/react": "^16.3.0",
         "@testing-library/user-event": "^14.6.1",
+        "@tweenjs/tween.js": "^25.0.0",
         "@types/node": "^22.20.1",
         "@types/react": "^18.3.12",
         "@types/react-dom": "^18.3.1",
@@ -34,7 +35,8 @@
         "typescript-eslint": "^8.11.0",
         "vite": "^7.1.11",
         "vite-plugin-dts": "^4.5.0",
-        "vitest": "^3.2.4"
+        "vitest": "^3.2.4",
+        "wink-porter2-stemmer": "^2.0.1"
       },
       "peerDependencies": {
         "react": ">=19",
@@ -2339,6 +2341,66 @@
         "node": ">=14.0.0"
       }
     },
+    "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/core": {
+      "version": "1.5.0",
+      "dev": true,
+      "inBundle": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@emnapi/wasi-threads": "1.1.0",
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/runtime": {
+      "version": "1.5.0",
+      "dev": true,
+      "inBundle": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/wasi-threads": {
+      "version": "1.1.0",
+      "dev": true,
+      "inBundle": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@napi-rs/wasm-runtime": {
+      "version": "1.0.7",
+      "dev": true,
+      "inBundle": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@emnapi/core": "^1.5.0",
+        "@emnapi/runtime": "^1.5.0",
+        "@tybys/wasm-util": "^0.10.1"
+      }
+    },
+    "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@tybys/wasm-util": {
+      "version": "0.10.1",
+      "dev": true,
+      "inBundle": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/tslib": {
+      "version": "2.8.1",
+      "dev": true,
+      "inBundle": true,
+      "license": "0BSD",
+      "optional": true
+    },
     "node_modules/@tailwindcss/oxide-win32-arm64-msvc": {
       "version": "4.1.15",
       "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-win32-arm64-msvc/-/oxide-win32-arm64-msvc-4.1.15.tgz",
@@ -2507,6 +2569,13 @@
         "@testing-library/dom": ">=7.21.4"
       }
     },
+    "node_modules/@tweenjs/tween.js": {
+      "version": "25.0.0",
+      "resolved": "https://registry.npmjs.org/@tweenjs/tween.js/-/tween.js-25.0.0.tgz",
+      "integrity": "sha512-XKLA6syeBUaPzx4j3qwMqzzq+V4uo72BnlbOjmuljLrRqdsd3qnzvZZoxvMHZ23ndsRS4aufU6JOZYpCbU6T1A==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/argparse": {
       "version": "1.0.38",
       "resolved": "https://registry.npmjs.org/@types/argparse/-/argparse-1.0.38.tgz",
@@ -6508,6 +6577,13 @@
         "node": ">=8"
       }
     },
+    "node_modules/wink-porter2-stemmer": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/wink-porter2-stemmer/-/wink-porter2-stemmer-2.0.1.tgz",
+      "integrity": "sha512-0g+RkkqhRXFmSpJQStVXW5N/WsshWpJXsoDRW7DwVkGI2uDT6IBCoq3xdH5p6IHLaC6ygk7RWUsUx4alKxoagQ==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/word-wrap": {
       "version": "1.2.5",
       "resolved": "https://registry.npmjs.org/word-wrap/-/word-wrap-1.2.5.tgz",
diff --git a/package.json b/package.json
index baef115..2a06412 100644
--- a/package.json
+++ b/package.json
@@ -2,7 +2,7 @@
   "name": "react-two.js",
   "version": "0.8.23-r.2",
   "type": "module",
-  "description": "A React virtual DOM for Two.js — a renderer agnostic two-dimensional drawing API for the web",
+  "description": "A React virtual DOM for Two.js \u2014 a renderer agnostic two-dimensional drawing API for the web",
   "main": "./dist/react-two-main.es.js",
   "module": "./dist/react-two-main.es.js",
   "types": "./dist/main.d.ts",
@@ -58,6 +58,7 @@
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.3.0",
     "@testing-library/user-event": "^14.6.1",
+    "@tweenjs/tween.js": "^25.0.0",
     "@types/node": "^22.20.1",
     "@types/react": "^18.3.12",
     "@types/react-dom": "^18.3.1",
@@ -76,7 +77,8 @@
     "typescript-eslint": "^8.11.0",
     "vite": "^7.1.11",
     "vite-plugin-dts": "^4.5.0",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "wink-porter2-stemmer": "^2.0.1"
   },
   "peerDependencies": {
     "react": ">=19",
diff --git a/src/playgrounds/diffs/DiffsCanvas.tsx b/src/playgrounds/diffs/DiffsCanvas.tsx
new file mode 100644
index 0000000..1002021
--- /dev/null
+++ b/src/playgrounds/diffs/DiffsCanvas.tsx
@@ -0,0 +1,111 @@
+import { useEffect, useRef, type MutableRefObject } from 'react';
+import TWEEN from '@tweenjs/tween.js';
+import { Group, RefGroup, useTwo, useZUI, type ZUIControls } from 'react-two.js';
+import { DiffsScene } from './components/DiffsScene';
+import { Legend } from './components/Legend';
+import { usePrefersDark } from './hooks/usePrefersDark';
+import { useProgressiveReveal } from './hooks/useProgressiveReveal';
+import { useTweenTick } from './hooks/useTweenTick';
+import { DiffsModel } from './types';
+
+export interface DiffsCanvasProps {
+  model: DiffsModel;
+  selectedStem: string | null;
+  highlightMode: boolean;
+  onSelectStem: (stem: string) => void;
+  controlsRef?: MutableRefObject<ZUIControls | null>;
+  onZoomChange?: (scale: number) => void;
+  /** Fires only when the reveal starts or finishes, never per frame. */
+  onProcessingChange?: (isProcessing: boolean) => void;
+}
+
+export function DiffsCanvas({
+  model,
+  selectedStem,
+  highlightMode,
+  onSelectStem,
+  controlsRef,
+  onZoomChange,
+  onProcessingChange,
+}: DiffsCanvasProps) {
+  const { two, height } = useTwo();
+  const sceneGroupRef = useRef<RefGroup | null>(null);
+  const isDark = usePrefersDark();
+
+  // This must live inside <Canvas>: `useFrame` reads the Two instance from
+  // context, and outside the provider it gets null and never binds, which
+  // left `revealed` pinned at 0 and rendered no stat lines at all.
+  const revealed = useProgressiveReveal(model);
+  const isRevealing = revealed < model.totalLines;
+
+  useEffect(() => {
+    onProcessingChange?.(isRevealing);
+  }, [isRevealing, onProcessingChange]);
+
+  const zui = useZUI(sceneGroupRef, {
+    minZoom: 0.06,
+    maxZoom: 8,
+    pan: 'background',
+    onChange: (st) => onZoomChange?.(st.scale),
+  });
+
+  // Enable TWEEN updates each frame
+  useTweenTick();
+
+  useEffect(() => {
+    if (controlsRef) {
+      controlsRef.current = zui;
+    }
+  }, [controlsRef, zui]);
+
+  // Camera pan tween to selected stem's visible occurrence
+  useEffect(() => {
+    if (!selectedStem || !two || !zui.instance.current) return;
+
+    const occurrences = model.byStem.get(selectedStem);
+    const visibleOccurrence = occurrences?.find((o) => o.visible);
+    if (!visibleOccurrence) return;
+
+    const zuiInst = zui.instance.current;
+    const am = zuiInst.surfaceMatrix;
+    const currentScale = am.elements[0];
+
+    const destX = two.width * 0.5 - visibleOccurrence.x * currentScale;
+    const destY = two.height * 0.5 - (visibleOccurrence.y + 100) * currentScale;
+
+    const startPos = { x: am.elements[2], y: am.elements[5] };
+    const tween = new TWEEN.Tween(startPos)
+      .to({ x: destX, y: destY }, 350)
+      .easing(TWEEN.Easing.Sinusoidal.Out)
+      .onUpdate(() => {
+        zui.panTo(startPos.x, startPos.y);
+      })
+      .start();
+
+    return () => {
+      tween.stop();
+    };
+  }, [selectedStem, model.byStem, two, zui]);
+
+  return (
+    <>
+      <Group ref={sceneGroupRef}>
+        <DiffsScene
+          model={model}
+          revealed={revealed}
+          selectedStem={selectedStem}
+          highlightMode={highlightMode}
+          onSelectStem={onSelectStem}
+        />
+      </Group>
+
+      {/* Viewport-fixed Legend */}
+      <Legend
+        columns={model.columns}
+        shared={model.shared}
+        canvasHeight={height}
+        isDark={isDark}
+      />
+    </>
+  );
+}
diff --git a/src/playgrounds/diffs/DiffsPlayground.tsx b/src/playgrounds/diffs/DiffsPlayground.tsx
new file mode 100644
index 0000000..4e8d76d
--- /dev/null
+++ b/src/playgrounds/diffs/DiffsPlayground.tsx
@@ -0,0 +1,309 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import Two from 'two.js';
+import { Button } from '@/components/catalyst/Button';
+import {
+  ArrowDownTrayIcon,
+  ArrowPathIcon,
+  PlusIcon,
+  MinusIcon,
+  AdjustmentsHorizontalIcon,
+} from '@heroicons/react/20/solid';
+import { Canvas, type ZUIControls } from 'react-two.js';
+import { PlaygroundProps } from '../types';
+import { DiffsCanvas } from './DiffsCanvas';
+import { useDiffsModel } from './hooks/useDiffsModel';
+import { useMeasuredHeight } from './hooks/useMeasuredHeight';
+import { CHROME_GAP, CHROME_INSET } from './constants';
+import {
+  clearStoredState,
+  generateColor,
+  loadStoredState,
+  saveStoredState,
+} from './storage';
+import { TextColumn } from './components/TextColumn';
+import { SortMode, TextDoc } from './types';
+
+const defaultTexts: TextDoc[] = [
+  {
+    id: 'text-1',
+    name: 'Text 1',
+    color: 'rgb(220, 80, 80)',
+    body: 'The quick brown fox jumps over the lazy dog.',
+  },
+  {
+    id: 'text-2',
+    name: 'Text 2',
+    color: 'rgb(80, 160, 220)',
+    body: 'The lazy dog sleeps under the warm sun.',
+  },
+];
+
+const MODES: SortMode[] = ['chronologic', 'frequency', 'alphabetic'];
+
+export function DiffsPlayground({ width, height }: PlaygroundProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const zuiRef = useRef<ZUIControls | null>(null);
+
+  // The panes sit under floating chrome, so they reserve room for it rather
+  // than sliding beneath the toolbar and the zoom readout.
+  const [toolbarRef, toolbarHeight] = useMeasuredHeight<HTMLDivElement>();
+  const [zoomRef, zoomHeight] = useMeasuredHeight<HTMLDivElement>();
+
+  const [texts, setTexts] = useState<TextDoc[]>(() => {
+    const loaded = loadStoredState();
+    return loaded?.texts && loaded.texts.length > 0 ? loaded.texts : defaultTexts;
+  });
+
+  const [mode, setMode] = useState<SortMode>(() => {
+    const loaded = loadStoredState();
+    return loaded?.mode || 'chronologic';
+  });
+
+  const [textIsVisible, setTextIsVisible] = useState(true);
+  const [vizIsVisible, setVizIsVisible] = useState(true);
+  const [highlightMode, setHighlightMode] = useState(false);
+  const [selectedStem, setSelectedStem] = useState<string | null>(null);
+  const [scale, setScale] = useState(1);
+
+  // Model hook
+  const { model, isDeferredPending } = useDiffsModel(texts, mode);
+
+  // Reported by DiffsCanvas, which owns the frame-driven reveal.
+  const [isRevealing, setIsRevealing] = useState(false);
+
+  const isProcessing = isRevealing || isDeferredPending;
+
+  // Debounced save to localStorage
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      saveStoredState(texts, mode);
+    }, 1000);
+    return () => clearTimeout(timer);
+  }, [texts, mode]);
+
+  // Stem selection handler
+  const handleSelectStem = useCallback((stem: string) => {
+    setSelectedStem((current) => (current === stem ? null : stem));
+  }, []);
+
+  // Text updates
+  const handleUpdateTitle = useCallback((id: string, name: string) => {
+    setTexts((prev) =>
+      prev.map((t) => (t.id === id ? { ...t, name } : t))
+    );
+  }, []);
+
+  const handleUpdateBody = useCallback((id: string, body: string) => {
+    setTexts((prev) =>
+      prev.map((t) => (t.id === id ? { ...t, body } : t))
+    );
+  }, []);
+
+  // Toolbar actions
+  const handleAddText = useCallback(() => {
+    setTexts((prev) => [
+      ...prev,
+      {
+        id: `text-${Date.now()}`,
+        name: `Text ${prev.length + 1}`,
+        color: generateColor(0, 0.5),
+        body: '',
+      },
+    ]);
+  }, []);
+
+  const handleRemoveText = useCallback(() => {
+    setTexts((prev) => (prev.length > 1 ? prev.slice(0, -1) : prev));
+  }, []);
+
+  const handleCycleMode = useCallback(() => {
+    setMode((current) => {
+      const idx = MODES.indexOf(current);
+      return MODES[(idx + 1) % MODES.length];
+    });
+    setSelectedStem(null);
+  }, []);
+
+  const handleClearSession = useCallback(() => {
+    if (window.confirm('This will delete your current session. Are you sure you want to continue?')) {
+      clearStoredState();
+      setTexts(defaultTexts);
+      setMode('chronologic');
+      setSelectedStem(null);
+      zuiRef.current?.reset();
+      setScale(1);
+    }
+  }, []);
+
+  const handleDownloadSVG = useCallback(() => {
+    const svgElement = containerRef.current?.querySelector('svg');
+    if (!svgElement) return;
+
+    const serializer = new XMLSerializer();
+    const source = serializer.serializeToString(svgElement);
+    const a = document.createElement('a');
+    a.href = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(source)}`;
+    a.download = 'diffs.svg';
+    a.style.display = 'none';
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+  }, []);
+
+  return (
+    <div
+      ref={containerRef}
+      className="relative w-full h-full min-h-[500px] overflow-hidden bg-zinc-50 dark:bg-zinc-950 rounded-xl border border-zinc-200 dark:border-zinc-800"
+    >
+      {/* Two.js Canvas Stage. Kept mounted and faded, so toggling visuals
+          never tears down the scene or resets the zoom. */}
+      <div
+        className={`absolute inset-0 z-0 transition-opacity duration-300 ${
+          vizIsVisible ? 'opacity-100' : 'opacity-0'
+        }`}
+      >
+        <Canvas
+          type={Two.Types.svg}
+          width={width}
+          height={height}
+          autostart={true}
+          className="w-full h-full cursor-grab active:cursor-grabbing"
+          style={{ userSelect: 'none', touchAction: 'none' }}
+          aria-label="Diffs visual vocabulary comparison canvas"
+        >
+          <DiffsCanvas
+            model={model}
+            selectedStem={selectedStem}
+            highlightMode={highlightMode}
+            onSelectStem={handleSelectStem}
+            controlsRef={zuiRef}
+            onZoomChange={setScale}
+            onProcessingChange={setIsRevealing}
+          />
+        </Canvas>
+      </div>
+
+      {/* Text panes overlay. The wrapper stays click-through so the canvas
+          underneath keeps receiving pans; only the editable controls and the
+          individual words claim pointer events. */}
+      <div
+        className={`absolute inset-0 z-10 pointer-events-none flex transition-opacity duration-300 ${
+          textIsVisible ? 'opacity-100' : 'opacity-0'
+        }`}
+        style={{
+          paddingTop: CHROME_INSET + toolbarHeight + CHROME_GAP,
+          paddingBottom: CHROME_INSET + zoomHeight + CHROME_GAP,
+        }}
+        aria-hidden={!textIsVisible}
+      >
+        <div className="flex w-full h-full">
+          {texts.map((doc, idx) => (
+            <TextColumn
+              key={doc.id}
+              doc={doc}
+              index={idx}
+              widthPercent={`${(100 / texts.length).toFixed(3)}%`}
+              interactive={textIsVisible}
+              highlightMode={highlightMode}
+              selectedStem={selectedStem}
+              onUpdateTitle={handleUpdateTitle}
+              onUpdateBody={handleUpdateBody}
+              onSelectStem={handleSelectStem}
+            />
+          ))}
+        </div>
+      </div>
+
+      {/* Floating Action Controls */}
+      <div
+        ref={toolbarRef}
+        className="absolute top-4 left-4 z-20 flex flex-wrap items-center gap-2 pointer-events-auto bg-white/90 dark:bg-zinc-900/90 backdrop-blur-md p-1.5 rounded-xl border border-zinc-200 dark:border-zinc-800 shadow-xl">
+        <Button color="dark/zinc" onClick={handleAddText} title="Add Text Field">
+          <PlusIcon className="w-4 h-4 mr-1" />
+          Add Text
+        </Button>
+        <Button
+          color="dark/zinc"
+          onClick={handleRemoveText}
+          disabled={texts.length <= 1}
+          title="Remove Text Field"
+        >
+          <MinusIcon className="w-4 h-4 mr-1" />
+          Remove
+        </Button>
+
+        <Button color="light" onClick={handleCycleMode} title="Cycle sort mode">
+          <AdjustmentsHorizontalIcon className="w-4 h-4 mr-1" />
+          Sort: <span className="capitalize ml-1 font-semibold">{mode}</span>
+        </Button>
+
+        <div className="h-4 w-px bg-zinc-300 dark:bg-zinc-700 mx-1" />
+
+        <label className="flex items-center gap-1.5 text-xs text-zinc-700 dark:text-zinc-300 cursor-pointer select-none px-2 py-1 hover:bg-zinc-100 dark:hover:bg-zinc-800 rounded">
+          <input
+            type="checkbox"
+            checked={textIsVisible}
+            onChange={(e) => setTextIsVisible(e.target.checked)}
+            className="rounded border-zinc-300 text-blue-600 focus:ring-blue-500"
+          />
+          Text Visible
+        </label>
+
+        <label className="flex items-center gap-1.5 text-xs text-zinc-700 dark:text-zinc-300 cursor-pointer select-none px-2 py-1 hover:bg-zinc-100 dark:hover:bg-zinc-800 rounded">
+          <input
+            type="checkbox"
+            checked={vizIsVisible}
+            onChange={(e) => setVizIsVisible(e.target.checked)}
+            className="rounded border-zinc-300 text-blue-600 focus:ring-blue-500"
+          />
+          Visuals Visible
+        </label>
+
+        <label className="flex items-center gap-1.5 text-xs text-zinc-700 dark:text-zinc-300 cursor-pointer select-none px-2 py-1 hover:bg-zinc-100 dark:hover:bg-zinc-800 rounded">
+          <input
+            type="checkbox"
+            checked={highlightMode}
+            onChange={(e) => {
+              setHighlightMode(e.target.checked);
+              if (!e.target.checked) setSelectedStem(null);
+            }}
+            className="rounded border-zinc-300 text-blue-600 focus:ring-blue-500"
+          />
+          Highlight Mode
+        </label>
+
+        <div className="h-4 w-px bg-zinc-300 dark:bg-zinc-700 mx-1" />
+
+        <Button plain onClick={handleClearSession} title="Clear Session" className="text-zinc-500 hover:text-zinc-900 dark:hover:text-white">
+          Clear
+        </Button>
+
+        <Button color="light" onClick={handleDownloadSVG} title="Export SVG">
+          <ArrowDownTrayIcon className="w-4 h-4 mr-1" />
+          Export SVG
+        </Button>
+
+        {isProcessing && (
+          <div className="flex items-center gap-1 text-xs text-blue-500 font-medium px-2 animate-pulse">
+            <ArrowPathIcon className="w-3.5 h-3.5 animate-spin" />
+            Analyzing...
+          </div>
+        )}
+      </div>
+
+      {/* Floating Zoom Controls Overlay */}
+      <div
+        ref={zoomRef}
+        className="absolute bottom-4 right-4 z-20 flex items-center gap-1 bg-white/90 dark:bg-zinc-900/90 backdrop-blur-sm border border-zinc-200 dark:border-zinc-800 rounded-lg p-1 shadow-lg pointer-events-auto">
+        <button
+          onClick={() => zuiRef.current?.reset()}
+          className="cursor-pointer px-2 py-1 text-xs font-mono text-zinc-600 dark:text-zinc-300 hover:bg-zinc-100 dark:hover:bg-zinc-800 rounded transition-colors"
+          aria-label="Reset zoom"
+          title="Reset Zoom"
+        >
+          {Math.round(scale * 100)}%
+        </button>
+      </div>
+    </div>
+  );
+}
diff --git a/src/playgrounds/diffs/components/Arc.tsx b/src/playgrounds/diffs/components/Arc.tsx
new file mode 100644
index 0000000..6682ac6
--- /dev/null
+++ b/src/playgrounds/diffs/components/Arc.tsx
@@ -0,0 +1,87 @@
+import { useEffect, useMemo, useRef } from 'react';
+import Two from 'two.js';
+import TWEEN from '@tweenjs/tween.js';
+import { Path, type RefPath } from 'react-two.js';
+import { type Anchor } from 'two.js/src/anchor';
+
+export interface ArcProps {
+  source: { x: number; y: number };
+  target: { x: number; y: number };
+  delay?: number;
+}
+
+export function Arc({ source, target, delay = 0 }: ArcProps) {
+  const pathRef = useRef<RefPath | null>(null);
+
+  const vertices = useMemo(() => {
+    const mx = (target.x + source.x) / 2;
+    const my = (target.y + source.y) / 2;
+
+    const dx = target.x - source.x;
+    const dy = target.y - source.y;
+
+    const r = Math.sqrt(dx * dx + dy * dy) / 2;
+    const angle = Math.atan2(dy, dx);
+
+    const resolution = 32;
+    const points: Anchor[] = [];
+
+    const cosA = Math.cos(angle);
+    const sinA = Math.sin(angle);
+
+    for (let i = 0; i < resolution; i++) {
+      const pct = i / (resolution - 1);
+      // Arc angle from 0 to -PI (upper semi-circle in local space)
+      const theta = pct * -Math.PI;
+
+      const lx = r * Math.cos(theta);
+      const ly = r * Math.sin(theta);
+
+      // Rotate by angle and translate to midpoint (mx, my)
+      const wx = mx + (lx * cosA - ly * sinA);
+      const wy = my + (lx * sinA + ly * cosA);
+
+      points.push(new Two.Anchor(wx, wy));
+    }
+
+    return points;
+  }, [source.x, source.y, target.x, target.y]);
+
+  // The reveal writes straight to the Two.js path. Routing it through React
+  // state would re-render the whole scene on every frame of every arc.
+  useEffect(() => {
+    const path = pathRef.current;
+    if (!path) return;
+
+    path.beginning = 1;
+
+    const value = { beginning: 1 };
+    const tween = new TWEEN.Tween(value)
+      .to({ beginning: 0 }, 350)
+      .delay(delay)
+      .easing(TWEEN.Easing.Sinusoidal.Out)
+      .onUpdate(() => {
+        const current = pathRef.current;
+        if (current) {
+          current.beginning = value.beginning;
+        }
+      })
+      .start();
+
+    return () => {
+      tween.stop();
+    };
+  }, [source.x, source.y, target.x, target.y, delay]);
+
+  return (
+    <Path
+      ref={pathRef}
+      vertices={vertices}
+      curved={true}
+      ending={1}
+      fill="none"
+      stroke="#333"
+      linewidth={1.5}
+    />
+  );
+}
diff --git a/src/playgrounds/diffs/components/DiffsScene.tsx b/src/playgrounds/diffs/components/DiffsScene.tsx
new file mode 100644
index 0000000..0d9bd8b
--- /dev/null
+++ b/src/playgrounds/diffs/components/DiffsScene.tsx
@@ -0,0 +1,120 @@
+import { useMemo } from 'react';
+import { Group } from 'react-two.js';
+import { DiffsModel } from '../types';
+import { Arc } from './Arc';
+import { GraphLine } from './GraphLine';
+import { StatLine } from './StatLine';
+
+export interface DiffsSceneProps {
+  model: DiffsModel;
+  revealed: number;
+  selectedStem: string | null;
+  highlightMode: boolean;
+  onSelectStem: (stem: string) => void;
+}
+
+export function DiffsScene({
+  model,
+  revealed,
+  selectedStem,
+  highlightMode,
+  onSelectStem,
+}: DiffsSceneProps) {
+  // Combine all columns: text columns + shared column
+  const allColumns = useMemo(() => {
+    return [...model.columns, model.shared];
+  }, [model.columns, model.shared]);
+
+  // Allocate revealed line counts across columns in order
+  const revealedLinesPerColumn = useMemo(() => {
+    const counts: number[] = [];
+    let acc = 0;
+    for (const col of allColumns) {
+      const remaining = Math.max(0, revealed - acc);
+      const countForCol = Math.min(col.lines.length, remaining);
+      counts.push(countForCol);
+      acc += col.lines.length;
+    }
+    return counts;
+  }, [allColumns, revealed]);
+
+  // Compute arcs when selectedStem is set
+  const arcsData = useMemo(() => {
+    if (!selectedStem) return [];
+    const occurrences = model.byStem.get(selectedStem);
+    if (!occurrences) return [];
+
+    const visibleOccurrence = occurrences.find((o) => o.visible);
+    const hiddenOccurrences = occurrences.filter((o) => !o.visible);
+
+    if (!visibleOccurrence || hiddenOccurrences.length === 0) return [];
+
+    return hiddenOccurrences.map((target, idx) => ({
+      source: { x: visibleOccurrence.x, y: visibleOccurrence.y },
+      target: { x: target.x, y: target.y },
+      delay: idx * 250,
+      key: `${target.key}:${idx}`,
+    }));
+  }, [selectedStem, model.byStem]);
+
+  return (
+    <Group y={100}>
+      {/* 1. Arcs (bottom z-layer) */}
+      <Group>
+        {arcsData.map((arc) => (
+          <Arc
+            key={arc.key}
+            source={arc.source}
+            target={arc.target}
+            delay={arc.delay}
+          />
+        ))}
+      </Group>
+
+      {/* 2. Graph lines (middle z-layer) */}
+      <Group>
+        {allColumns.map((col) => {
+          const highlightYList = selectedStem
+            ? col.lines
+                .filter((l) => l.stem === selectedStem)
+                .map((l) => l.y)
+            : [];
+
+          return (
+            <GraphLine
+              key={col.id}
+              x={col.x}
+              top={col.graph.top}
+              bottom={col.graph.bottom}
+              points={col.graph.points}
+              highlightYList={highlightYList}
+            />
+          );
+        })}
+      </Group>
+
+      {/* 3. Stat lines columns (top z-layer) */}
+      <Group>
+        {allColumns.map((col, colIdx) => {
+          const countToRender = revealedLinesPerColumn[colIdx] || 0;
+          const visibleSlice = col.lines.slice(0, countToRender);
+
+          return (
+            <Group key={col.id}>
+              {visibleSlice.map((datum) => (
+                <StatLine
+                  key={datum.key}
+                  datum={datum}
+                  color={col.color}
+                  isHighlighted={selectedStem === datum.stem}
+                  highlightMode={highlightMode}
+                  onSelect={onSelectStem}
+                />
+              ))}
+            </Group>
+          );
+        })}
+      </Group>
+    </Group>
+  );
+}
diff --git a/src/playgrounds/diffs/components/GraphLine.tsx b/src/playgrounds/diffs/components/GraphLine.tsx
new file mode 100644
index 0000000..bf1e50a
--- /dev/null
+++ b/src/playgrounds/diffs/components/GraphLine.tsx
@@ -0,0 +1,41 @@
+import { memo, useMemo } from 'react';
+import Two from 'two.js';
+import { Group, Line, Points } from 'react-two.js';
+
+export interface GraphLineProps {
+  x: number;
+  top: number;
+  bottom: number;
+  points: { x: number; y: number }[];
+  highlightYList: number[];
+}
+
+export const GraphLine = memo(function GraphLine({
+  x,
+  top,
+  bottom,
+  points,
+  highlightYList,
+}: GraphLineProps) {
+  const tickVertices = useMemo(() => {
+    return points.map((p) => new Two.Vector(p.x, p.y));
+  }, [points]);
+
+  const highlightVertices = useMemo(() => {
+    return highlightYList.map((y) => new Two.Vector(x, y));
+  }, [x, highlightYList]);
+
+  return (
+    <Group>
+      {points.length > 0 && (
+        <Line x1={x} y1={top} x2={x} y2={bottom} stroke="#777" linewidth={1} />
+      )}
+      {tickVertices.length > 0 && (
+        <Points vertices={tickVertices} size={4} fill="#777" stroke="none" />
+      )}
+      {highlightVertices.length > 0 && (
+        <Points vertices={highlightVertices} size={12} fill="yellow" stroke="none" />
+      )}
+    </Group>
+  );
+});
diff --git a/src/playgrounds/diffs/components/Legend.tsx b/src/playgrounds/diffs/components/Legend.tsx
new file mode 100644
index 0000000..bae78dc
--- /dev/null
+++ b/src/playgrounds/diffs/components/Legend.tsx
@@ -0,0 +1,60 @@
+import { Circle, Group, Text } from 'react-two.js';
+import { FONT_FAMILY, LEADING, SIZE, TEXT_BASELINE } from '../constants';
+import { Column } from '../types';
+
+export interface LegendProps {
+  columns: Column[];
+  shared: Column;
+  canvasHeight: number;
+  /** Canvas text needs a literal colour, so the theme has to be passed in. */
+  isDark?: boolean;
+}
+
+export function Legend({
+  columns,
+  shared,
+  canvasHeight,
+  isDark = false,
+}: LegendProps) {
+  const totalItems = columns.length + 1;
+  const labelColor = isDark ? '#ffffff' : '#000000';
+
+  return (
+    <Group x={0} y={canvasHeight}>
+      {columns.map((col, i) => {
+        const j = totalItems - i;
+        const yPos = -j * LEADING;
+        return (
+          <Group key={col.id} y={yPos}>
+            <Circle x={SIZE} y={0} radius={SIZE / 3} fill={col.color} stroke="none" />
+            <Text
+              value={col.name || `Text ${i + 1}`}
+              x={SIZE * 2}
+              y={SIZE * 0.33}
+              alignment="left"
+              baseline={TEXT_BASELINE}
+              family={FONT_FAMILY}
+              size={SIZE}
+              fill={labelColor}
+              stroke="none"
+            />
+          </Group>
+        );
+      })}
+      <Group y={-LEADING}>
+        <Circle x={SIZE} y={0} radius={SIZE / 3} fill={shared.color} stroke="none" />
+        <Text
+          value={shared.name || 'Shared Words'}
+          x={SIZE * 2}
+          y={SIZE * 0.33}
+          alignment="left"
+          baseline={TEXT_BASELINE}
+          family={FONT_FAMILY}
+          size={SIZE}
+          fill={labelColor}
+          stroke="none"
+        />
+      </Group>
+    </Group>
+  );
+}
diff --git a/src/playgrounds/diffs/components/StatLine.tsx b/src/playgrounds/diffs/components/StatLine.tsx
new file mode 100644
index 0000000..207e31f
--- /dev/null
+++ b/src/playgrounds/diffs/components/StatLine.tsx
@@ -0,0 +1,69 @@
+import { memo, useCallback } from 'react';
+import { Group, RoundedRectangle, Text } from 'react-two.js';
+import { FONT_FAMILY, LEADING, SIZE, TEXT_BASELINE } from '../constants';
+import { StatLineDatum } from '../types';
+
+export interface StatLineProps {
+  datum: StatLineDatum;
+  color: string;
+  isHighlighted: boolean;
+  highlightMode: boolean;
+  onSelect: (stem: string) => void;
+}
+
+export const StatLine = memo(function StatLine({
+  datum,
+  color,
+  isHighlighted,
+  highlightMode,
+  onSelect,
+}: StatLineProps) {
+  const handleSelect = useCallback(() => {
+    onSelect(datum.stem);
+  }, [onSelect, datum.stem]);
+
+  // Exactly one handler: `click` and `pointerdown` are dispatched from separate
+  // listeners, so wiring both fired the toggle twice and cancelled itself out.
+  // Leaving it `undefined` outside highlight mode also unregisters the line
+  // from hit testing, so `pan: 'background'` can still pan across the columns.
+  return (
+    <Group
+      x={datum.x}
+      y={datum.y}
+      onPointerDown={highlightMode ? handleSelect : undefined}
+    >
+      <RoundedRectangle
+        x={datum.width / 2}
+        y={0}
+        width={datum.width + LEADING}
+        height={LEADING}
+        radius={LEADING * 0.5}
+        fill={color}
+        stroke={isHighlighted ? 'yellow' : 'none'}
+        linewidth={SIZE * 0.25}
+      />
+      <Text
+        value={datum.word}
+        x={0}
+        y={SIZE * 0.33}
+        alignment="left"
+        baseline={TEXT_BASELINE}
+        family={FONT_FAMILY}
+        size={SIZE}
+        fill="#ffffff"
+        stroke="none"
+      />
+      <Text
+        value={String(datum.count)}
+        x={datum.width}
+        y={SIZE * 0.25}
+        alignment="right"
+        baseline={TEXT_BASELINE}
+        family={FONT_FAMILY}
+        size={SIZE * 0.5}
+        fill="#ffffff"
+        stroke="none"
+      />
+    </Group>
+  );
+});
diff --git a/src/playgrounds/diffs/components/TextColumn.tsx b/src/playgrounds/diffs/components/TextColumn.tsx
new file mode 100644
index 0000000..f824f9c
--- /dev/null
+++ b/src/playgrounds/diffs/components/TextColumn.tsx
@@ -0,0 +1,117 @@
+import { useMemo } from 'react';
+import { stem } from '../model/stem';
+import { TextDoc } from '../types';
+
+export interface TextColumnProps {
+  doc: TextDoc;
+  index: number;
+  widthPercent: string;
+  /** False while the pane is faded out, so it never swallows canvas clicks. */
+  interactive?: boolean;
+  highlightMode: boolean;
+  selectedStem: string | null;
+  onUpdateTitle: (id: string, name: string) => void;
+  onUpdateBody: (id: string, body: string) => void;
+  onSelectStem: (stem: string) => void;
+}
+
+export function TextColumn({
+  doc,
+  index,
+  widthPercent,
+  interactive = true,
+  highlightMode,
+  selectedStem,
+  onUpdateTitle,
+  onUpdateBody,
+  onSelectStem,
+}: TextColumnProps) {
+  // Memoized tokenized view for Highlight Mode
+  const renderedTokens = useMemo(() => {
+    if (!doc.body) return null;
+    // Split text into words and delimiters (whitespace & punctuation)
+    const parts = doc.body.split(/(\s+|[^\w\-_]+)/g);
+
+    return parts.map((part, i) => {
+      if (!part) return null;
+
+      const cleaned = part
+        .replace(/['’]\w*$/i, '')
+        .replace(/[^\w\-_]+/g, '')
+        .trim();
+
+      if (cleaned && /\w/.test(cleaned)) {
+        const wordStem = stem(cleaned);
+        const isHighlighted = selectedStem !== null && wordStem === selectedStem;
+
+        return (
+          <span
+            key={i}
+            data-stem={wordStem}
+            onClick={() => onSelectStem(wordStem)}
+            className={`${
+              interactive ? 'pointer-events-auto' : ''
+            } cursor-pointer transition-colors duration-150 rounded px-0.5 ${
+              isHighlighted
+                ? 'bg-yellow-400 text-zinc-950 font-bold shadow-sm ring-2 ring-yellow-400/50'
+                : 'hover:bg-amber-200 dark:hover:bg-amber-500/30'
+            }`}
+          >
+            {part}
+          </span>
+        );
+      }
+
+      return <span key={i}>{part}</span>;
+    });
+  }, [doc.body, selectedStem, onSelectStem, interactive]);
+
+  return (
+    <div
+      className="flex flex-col h-full border-r border-zinc-200 dark:border-zinc-800 last:border-r-0 p-4 transition-all duration-200"
+      style={{ width: widthPercent }}
+    >
+      <input
+        type="text"
+        value={doc.name}
+        onChange={(e) => onUpdateTitle(doc.id, e.target.value)}
+        placeholder={`Text ${index + 1}`}
+        disabled={!interactive}
+        className={`w-full mb-3 px-3 py-1.5 font-semibold text-sm bg-transparent border-b border-zinc-300 dark:border-zinc-700 focus:border-blue-500 focus:outline-none text-zinc-900 dark:text-zinc-100 placeholder-zinc-400 ${
+          interactive ? 'pointer-events-auto' : 'pointer-events-none'
+        }`}
+      />
+
+      {highlightMode ? (
+        <>
+          <div className="mb-1.5 flex items-center gap-1.5 text-[10px] font-semibold uppercase tracking-wide text-amber-700 dark:text-amber-400">
+            <span className="inline-block h-1.5 w-1.5 rounded-full bg-amber-500" />
+            Highlight mode — click a word
+          </div>
+          {/* Click-through except on the words themselves, so the canvas
+              underneath can still be panned from the gaps. */}
+          <div className="pointer-events-none flex-1 w-full overflow-y-auto p-3 font-mono text-sm leading-relaxed text-zinc-800 dark:text-zinc-200 whitespace-pre-wrap bg-amber-50/80 dark:bg-amber-950/30 rounded-lg border-2 border-dashed border-amber-400/70 dark:border-amber-500/40 select-none">
+            {renderedTokens}
+          </div>
+        </>
+      ) : (
+        <>
+          <div className="mb-1.5 flex items-center gap-1.5 text-[10px] font-semibold uppercase tracking-wide text-zinc-500 dark:text-zinc-400">
+            <span className="inline-block h-1.5 w-1.5 rounded-full bg-blue-500" />
+            Editing
+          </div>
+          <textarea
+            value={doc.body}
+            onChange={(e) => onUpdateBody(doc.id, e.target.value)}
+            placeholder="Paste or type text here..."
+            spellCheck="false"
+            disabled={!interactive}
+            className={`flex-1 w-full p-3 font-mono text-sm leading-relaxed bg-white/75 dark:bg-zinc-900/75 border border-zinc-300 dark:border-zinc-700 rounded-lg focus:outline-none focus:ring-2 focus:ring-blue-500/50 text-zinc-800 dark:text-zinc-200 resize-none shadow-inner ${
+              interactive ? 'pointer-events-auto' : 'pointer-events-none'
+            }`}
+          />
+        </>
+      )}
+    </div>
+  );
+}
diff --git a/src/playgrounds/diffs/constants.ts b/src/playgrounds/diffs/constants.ts
new file mode 100644
index 0000000..835b87f
--- /dev/null
+++ b/src/playgrounds/diffs/constants.ts
@@ -0,0 +1,25 @@
+export const LEADING = 40;
+export const SIZE = 17;
+export const CHARACTER_WIDTH = 10;
+export const COLUMN_PITCH = 250;
+export const SHARED_COLUMN_X = 40;
+export const COLUMN_START_Y = 100;
+export const FONT_FAMILY = '"Inter", Helvetica, Arial, sans-serif';
+
+/** Matches the `top-4` / `bottom-4` insets of the floating chrome. */
+export const CHROME_INSET = 16;
+/** Breathing room between the floating chrome and the text panes. */
+export const CHROME_GAP = 12;
+
+export const STORAGE_KEY = 'diffs-state-v1';
+export const DIFFS_STATE_VERSION = 1;
+
+/**
+ * Two.js writes this through its baseline map as `dominant-baseline:
+ * alphabetic`. The original app asked for `'top'`, but the two.js of the day
+ * emitted that string verbatim — an invalid CSS value that browsers fall back
+ * to `auto`, i.e. the alphabetic baseline. The `y` offsets in StatLine and Legend
+ * were tuned against that fallback, so naming it explicitly keeps the original's optical
+ * centring instead of two.js's `middle` default, which sits ~5.6px low.
+ */
+export const TEXT_BASELINE = 'baseline';
diff --git a/src/playgrounds/diffs/hooks/useDiffsModel.ts b/src/playgrounds/diffs/hooks/useDiffsModel.ts
new file mode 100644
index 0000000..244a988
--- /dev/null
+++ b/src/playgrounds/diffs/hooks/useDiffsModel.ts
@@ -0,0 +1,25 @@
+import { useDeferredValue, useMemo } from 'react';
+import { SortMode, TextDoc, DiffsModel } from '../types';
+import { buildModel } from '../model/layout';
+
+export function useDiffsModel(
+  texts: TextDoc[],
+  mode: SortMode
+): {
+  model: DiffsModel;
+  deferredTexts: TextDoc[];
+  isDeferredPending: boolean;
+} {
+  const deferredTexts = useDeferredValue(texts);
+  const isDeferredPending = deferredTexts !== texts;
+
+  const model = useMemo(() => {
+    return buildModel(deferredTexts, mode);
+  }, [deferredTexts, mode]);
+
+  return {
+    model,
+    deferredTexts,
+    isDeferredPending,
+  };
+}
diff --git a/src/playgrounds/diffs/hooks/useMeasuredHeight.ts b/src/playgrounds/diffs/hooks/useMeasuredHeight.ts
new file mode 100644
index 0000000..f627e9e
--- /dev/null
+++ b/src/playgrounds/diffs/hooks/useMeasuredHeight.ts
@@ -0,0 +1,24 @@
+import { useEffect, useRef, useState } from 'react';
+
+/**
+ * Tracks an element's rendered height so overlays can reserve space for it.
+ * The toolbar wraps at narrow widths, so a fixed offset would be wrong.
+ */
+export function useMeasuredHeight<T extends HTMLElement>() {
+  const ref = useRef<T | null>(null);
+  const [height, setHeight] = useState(0);
+
+  useEffect(() => {
+    const element = ref.current;
+    if (!element) return;
+
+    const measure = () => setHeight(element.getBoundingClientRect().height);
+    measure();
+
+    const observer = new ResizeObserver(measure);
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, []);
+
+  return [ref, height] as const;
+}
diff --git a/src/playgrounds/diffs/hooks/usePrefersDark.ts b/src/playgrounds/diffs/hooks/usePrefersDark.ts
new file mode 100644
index 0000000..6500750
--- /dev/null
+++ b/src/playgrounds/diffs/hooks/usePrefersDark.ts
@@ -0,0 +1,22 @@
+import { useCallback, useSyncExternalStore } from 'react';
+
+const QUERY = '(prefers-color-scheme: dark)';
+
+/**
+ * Canvas text needs an explicit colour, so it cannot ride on Tailwind's `dark:`
+ * variant. This project is on Tailwind v4 with no `dark` class variant
+ * configured, so `dark:` resolves against the same media query used here.
+ */
+export function usePrefersDark(): boolean {
+  const subscribe = useCallback((onChange: () => void) => {
+    const list = window.matchMedia(QUERY);
+    list.addEventListener('change', onChange);
+    return () => list.removeEventListener('change', onChange);
+  }, []);
+
+  return useSyncExternalStore(
+    subscribe,
+    () => window.matchMedia(QUERY).matches,
+    () => false
+  );
+}
diff --git a/src/playgrounds/diffs/hooks/useProgressiveReveal.ts b/src/playgrounds/diffs/hooks/useProgressiveReveal.ts
new file mode 100644
index 0000000..5c3f0f6
--- /dev/null
+++ b/src/playgrounds/diffs/hooks/useProgressiveReveal.ts
@@ -0,0 +1,28 @@
+import { useEffect, useState } from 'react';
+import { useFrame } from 'react-two.js';
+import { DiffsModel } from '../types';
+
+export function useProgressiveReveal(model: DiffsModel): number {
+  const [revealed, setRevealed] = useState(0);
+
+  // Reset to 0 when model identity changes
+  useEffect(() => {
+    setRevealed(0);
+  }, [model]);
+
+  useFrame(() => {
+    setRevealed((current) => {
+      if (current >= model.totalLines) {
+        return model.totalLines;
+      }
+      const chunkSize = Math.min(
+        Math.max(Math.floor(model.totalChars / 100), 1),
+        250
+      );
+      const next = current + chunkSize;
+      return Math.min(next, model.totalLines);
+    });
+  });
+
+  return revealed;
+}
diff --git a/src/playgrounds/diffs/hooks/useTweenTick.ts b/src/playgrounds/diffs/hooks/useTweenTick.ts
new file mode 100644
index 0000000..1f6a7de
--- /dev/null
+++ b/src/playgrounds/diffs/hooks/useTweenTick.ts
@@ -0,0 +1,8 @@
+import TWEEN from '@tweenjs/tween.js';
+import { useFrame } from 'react-two.js';
+
+export function useTweenTick(): void {
+  useFrame(() => {
+    TWEEN.update();
+  });
+}
diff --git a/src/playgrounds/diffs/model/analyze.ts b/src/playgrounds/diffs/model/analyze.ts
new file mode 100644
index 0000000..233fdb4
--- /dev/null
+++ b/src/playgrounds/diffs/model/analyze.ts
@@ -0,0 +1,80 @@
+import { SortMode, TextDoc } from '../types';
+import { isStopword } from '../stopwords';
+import { tokenize } from './tokenize';
+import { stem } from './stem';
+
+export interface UnmergedLine {
+  textId: string;
+  word: string;
+  stem: string;
+  count: number;
+  firstIndex: number;
+  visible: boolean;
+}
+
+export interface AnalyzedText {
+  id: string;
+  name: string;
+  color: string;
+  lines: UnmergedLine[];
+  byStem: Map<string, UnmergedLine>;
+}
+
+export function sortLines<T extends { firstIndex: number; count: number; stem: string }>(
+  lines: T[],
+  mode: SortMode
+): T[] {
+  const result = [...lines];
+  switch (mode) {
+    case 'chronologic':
+      return result.sort((a, b) => a.firstIndex - b.firstIndex);
+    case 'frequency':
+      return result.sort((a, b) => {
+        if (b.count !== a.count) {
+          return b.count - a.count;
+        }
+        return a.firstIndex - b.firstIndex;
+      });
+    case 'alphabetic':
+      return result.sort((a, b) => {
+        const sa = a.stem.toLowerCase();
+        const sb = b.stem.toLowerCase();
+        if (sa < sb) return -1;
+        if (sa > sb) return 1;
+        return a.firstIndex - b.firstIndex;
+      });
+  }
+}
+
+export function analyzeText(textDoc: TextDoc): AnalyzedText {
+  const tokens = tokenize(textDoc.body);
+  const byStem = new Map<string, UnmergedLine>();
+  const lines: UnmergedLine[] = [];
+
+  for (const token of tokens) {
+    const s = stem(token.word);
+    const existing = byStem.get(s);
+    if (existing) {
+      existing.count += 1;
+    } else {
+      const newLine: UnmergedLine = {
+        textId: textDoc.id,
+        word: token.word,
+        stem: s,
+        count: 1,
+        firstIndex: token.index,
+        visible: !isStopword(token.word),
+      };
+      byStem.set(s, newLine);
+      lines.push(newLine);
+    }
+  }
+
+  return {
+    id: textDoc.id,
+    name: textDoc.name,
+    color: textDoc.color,
+    lines,
+    byStem,
+  };
+}
diff --git a/src/playgrounds/diffs/model/layout.ts b/src/playgrounds/diffs/model/layout.ts
new file mode 100644
index 0000000..07b12c2
--- /dev/null
+++ b/src/playgrounds/diffs/model/layout.ts
@@ -0,0 +1,118 @@
+import { Column, DiffsModel, SortMode, StatLineDatum, TextDoc } from '../types';
+import { CHARACTER_WIDTH, COLUMN_PITCH, LEADING, SHARED_COLUMN_X } from '../constants';
+import { analyzeText, sortLines } from './analyze';
+import { mergeTexts, SHARED_COLOR } from './merge';
+
+export function buildModel(texts: TextDoc[], mode: SortMode): DiffsModel {
+  // 1 & 2 & 3. Tokenize, stem, and analyze each text
+  const analyzed = texts.map((t) => analyzeText(t));
+
+  // 4. Merge across texts to resolve shared words
+  const merged = mergeTexts(analyzed);
+
+  const byStem = new Map<string, StatLineDatum[]>();
+
+  function registerDatum(datum: StatLineDatum) {
+    let list = byStem.get(datum.stem);
+    if (!list) {
+      list = [];
+      byStem.set(datum.stem, list);
+    }
+    list.push(datum);
+  }
+
+  // 5 & 6. Sort and lay out text columns
+  const textColumns: Column[] = merged.columns.map((col, colIdx) => {
+    const colX = (colIdx + 1) * COLUMN_PITCH;
+    const sorted = sortLines(col.lines, mode);
+
+    const allData: StatLineDatum[] = sorted.map((line, rowIdx) => {
+      const width = (line.word.length + 1 + String(line.count).length) * CHARACTER_WIDTH;
+      const datum: StatLineDatum = {
+        key: `${col.id}:${line.stem}`,
+        word: line.word,
+        stem: line.stem,
+        count: line.count,
+        x: colX,
+        y: rowIdx * LEADING * 1.15,
+        width,
+        visible: line.visible,
+      };
+      registerDatum(datum);
+      return datum;
+    });
+
+    const visibleLines = allData.filter((d) => d.visible);
+    const points = visibleLines.map((d) => ({ x: colX, y: d.y }));
+    const top = points.length > 0 ? points[0].y : 0;
+    const bottom = points.length > 0 ? points[points.length - 1].y : 0;
+
+    return {
+      id: col.id,
+      name: col.name,
+      color: col.color,
+      x: colX,
+      lines: visibleLines,
+      graph: {
+        top,
+        bottom,
+        points,
+      },
+    };
+  });
+
+  // Sort and lay out shared column
+  const sharedSorted = sortLines(merged.sharedColumn.lines, mode);
+  const sharedAllData: StatLineDatum[] = sharedSorted.map((line, rowIdx) => {
+    const width = (line.word.length + 1 + String(line.count).length) * CHARACTER_WIDTH;
+    const datum: StatLineDatum = {
+      key: `shared:${line.stem}`,
+      word: line.word,
+      stem: line.stem,
+      count: line.count,
+      x: SHARED_COLUMN_X,
+      y: rowIdx * LEADING * 1.15,
+      width,
+      visible: line.visible,
+    };
+    registerDatum(datum);
+    return datum;
+  });
+
+  const sharedVisible = sharedAllData.filter((d) => d.visible);
+  const sharedPoints = sharedVisible.map((d) => ({ x: SHARED_COLUMN_X, y: d.y }));
+  const sharedTop = sharedPoints.length > 0 ? sharedPoints[0].y : 0;
+  const sharedBottom = sharedPoints.length > 0 ? sharedPoints[sharedPoints.length - 1].y : 0;
+
+  const sharedColumn: Column = {
+    id: 'shared',
+    name: merged.sharedColumn.name,
+    color: SHARED_COLOR,
+    x: SHARED_COLUMN_X,
+    lines: sharedVisible,
+    graph: {
+      top: sharedTop,
+      bottom: sharedBottom,
+      points: sharedPoints,
+    },
+  };
+
+  // Compute total visible lines and total input characters
+  let totalLines = sharedVisible.length;
+  for (const c of textColumns) {
+    totalLines += c.lines.length;
+  }
+
+  let totalChars = 0;
+  for (const t of texts) {
+    totalChars += t.body.length;
+  }
+
+  return {
+    columns: textColumns,
+    shared: sharedColumn,
+    byStem,
+    totalLines,
+    totalChars,
+  };
+}
diff --git a/src/playgrounds/diffs/model/merge.ts b/src/playgrounds/diffs/model/merge.ts
new file mode 100644
index 0000000..48e50b7
--- /dev/null
+++ b/src/playgrounds/diffs/model/merge.ts
@@ -0,0 +1,82 @@
+import { AnalyzedText, UnmergedLine } from './analyze';
+
+export interface MergedTextColumn {
+  id: string;
+  name: string;
+  color: string;
+  lines: UnmergedLine[];
+}
+
+export interface MergedResult {
+  columns: MergedTextColumn[];
+  sharedColumn: MergedTextColumn;
+}
+
+export const SHARED_COLOR = 'rgb(120, 120, 120)';
+
+export function mergeTexts(
+  analyzed: AnalyzedText[],
+  sharedColor: string = SHARED_COLOR
+): MergedResult {
+  // Map stem -> array of UnmergedLines across all text columns
+  const stemOccurrences = new Map<string, UnmergedLine[]>();
+
+  for (const text of analyzed) {
+    for (const line of text.lines) {
+      let list = stemOccurrences.get(line.stem);
+      if (!list) {
+        list = [];
+        stemOccurrences.set(line.stem, list);
+      }
+      list.push(line);
+    }
+  }
+
+  const sharedLines: UnmergedLine[] = [];
+
+  for (const [s, occurrences] of stemOccurrences.entries()) {
+    if (occurrences.length >= 2) {
+      // Shared stem! Hide in owning columns and add to shared column
+      let totalCount = 0;
+      let minFirstIndex = Infinity;
+      const displayWord = occurrences[0].word;
+      const isVisible = occurrences[0].visible;
+
+      for (const occ of occurrences) {
+        occ.visible = false;
+        totalCount += occ.count;
+        if (occ.firstIndex < minFirstIndex) {
+          minFirstIndex = occ.firstIndex;
+        }
+      }
+
+      sharedLines.push({
+        textId: 'shared',
+        word: displayWord,
+        stem: s,
+        count: totalCount,
+        firstIndex: minFirstIndex,
+        visible: isVisible,
+      });
+    }
+  }
+
+  const columns: MergedTextColumn[] = analyzed.map((text) => ({
+    id: text.id,
+    name: text.name,
+    color: text.color,
+    lines: text.lines,
+  }));
+
+  const sharedColumn: MergedTextColumn = {
+    id: 'shared',
+    name: 'Shared Words',
+    color: sharedColor,
+    lines: sharedLines,
+  };
+
+  return {
+    columns,
+    sharedColumn,
+  };
+}
diff --git a/src/playgrounds/diffs/model/stem.ts b/src/playgrounds/diffs/model/stem.ts
new file mode 100644
index 0000000..51960ba
--- /dev/null
+++ b/src/playgrounds/diffs/model/stem.ts
@@ -0,0 +1,18 @@
+import porter2 from 'wink-porter2-stemmer';
+
+const stemCache = new Map<string, string>();
+
+export function stem(word: string): string {
+  const lower = word.toLowerCase();
+  const cached = stemCache.get(lower);
+  if (cached !== undefined) {
+    return cached;
+  }
+  const result = porter2(lower);
+  stemCache.set(lower, result);
+  return result;
+}
+
+export function clearStemCache(): void {
+  stemCache.clear();
+}
diff --git a/src/playgrounds/diffs/model/tokenize.ts b/src/playgrounds/diffs/model/tokenize.ts
new file mode 100644
index 0000000..b7ee530
--- /dev/null
+++ b/src/playgrounds/diffs/model/tokenize.ts
@@ -0,0 +1,28 @@
+export interface Token {
+  word: string;
+  index: number;
+}
+
+export function tokenize(text: string): Token[] {
+  if (!text) return [];
+
+  const rawTokens = text.split(/\s+/i);
+  const tokens: Token[] = [];
+
+  for (let i = 0; i < rawTokens.length; i++) {
+    const raw = rawTokens[i];
+    const cleaned = raw
+      .replace(/['’]\w*$/i, '')
+      .replace(/[^\w\-_]+/g, '')
+      .trim();
+
+    if (cleaned.length > 0 && /\w/.test(cleaned)) {
+      tokens.push({
+        word: cleaned,
+        index: i,
+      });
+    }
+  }
+
+  return tokens;
+}
diff --git a/src/playgrounds/diffs/stopwords.ts b/src/playgrounds/diffs/stopwords.ts
new file mode 100644
index 0000000..ef051cd
--- /dev/null
+++ b/src/playgrounds/diffs/stopwords.ts
@@ -0,0 +1,52 @@
+const pronouns = [
+  'all', 'another', 'any', 'anybody', 'anyone', 'anything', 'as', 'aught',
+  'both', 'each', 'each other', 'either', 'enough', 'everybody', 'everyone',
+  'everything', 'few', 'he', 'her', 'hers', 'herself', 'him', 'himself', 'his',
+  'i', 'idem', 'it', 'its', 'itself', 'many', 'me', 'mine', 'most', 'my',
+  'myself', 'naught', 'neither', 'nobody', 'none', 'nothing', 'nought', 'one',
+  'other', 'others', 'ought', 'our', 'ours', 'ourself', 'ourselves', 'several',
+  'she', 'some', 'somebody', 'someone', 'something', 'somewhat', 'such',
+  'suchlike', 'that', 'thee', 'their', 'theirs', 'theirself', 'theirselves',
+  'them', 'themself', 'themselves', 'there', 'these', 'they', 'thine', 'this',
+  'those', 'thou', 'thy', 'thyself', 'us', 'we', 'what', 'whatever', 'whatnot',
+  'whatsoever', 'whence', 'where', 'whereby', 'wherefrom', 'wherein',
+  'whereinto', 'whereof', 'whereon', 'wherever', 'wheresoever', 'whereto',
+  'whereunto', 'wherewith', 'wherewithal', 'whether', 'which', 'whichever',
+  'whichsoever', 'who', 'whoever', 'whom', 'whomever', 'whomso', 'whomsoever',
+  'whose', 'whosever', 'whosesoever', 'whoso', 'whosoever', 'ye', 'yon',
+  'yonder', 'you', 'your', 'yours', 'yourself', 'yourselves',
+];
+
+const articles = ['a', 'an', 'the'];
+
+const prepositions = [
+  'aboard', 'about', 'above', 'across', 'after', 'against', 'along', 'amid',
+  'among', 'anti', 'around', 'as', 'at', 'before', 'behind', 'below', 'beneath',
+  'beside', 'besides', 'between', 'beyond', 'but', 'by', 'concerning',
+  'considering', 'despite', 'down', 'during', 'except', 'excepting', 'excluding',
+  'following', 'for', 'from', 'in', 'inside', 'into', 'like', 'minus', 'near',
+  'of', 'off', 'on', 'onto', 'opposite', 'outside', 'over', 'past', 'per',
+  'plus', 'regarding', 'round', 'save', 'since', 'than', 'through', 'to',
+  'toward', 'towards', 'under', 'underneath', 'unlike', 'until', 'up', 'upon',
+  'versus', 'via', 'with', 'within', 'without',
+];
+
+const conjunctions = ['for', 'and', 'nor', 'but', 'or', 'yet', 'so'];
+
+const verbs = [
+  'is', 'are', 'were', 'be', 'been', 'have', 'has', 'had', 'do', 'does',
+  'done', 'need', 'needed', 'get', 'got', 'gotten', 'let',
+];
+
+export const STOPWORDS = new Set<string>([
+  ...pronouns,
+  ...articles,
+  ...prepositions,
+  ...conjunctions,
+  ...verbs,
+]);
+
+export function isStopword(word: string): boolean {
+  const clean = word.replace(/['’].*/i, '').toLowerCase();
+  return STOPWORDS.has(clean);
+}
diff --git a/src/playgrounds/diffs/storage.ts b/src/playgrounds/diffs/storage.ts
new file mode 100644
index 0000000..29a745b
--- /dev/null
+++ b/src/playgrounds/diffs/storage.ts
@@ -0,0 +1,80 @@
+import { DIFFS_STATE_VERSION, STORAGE_KEY } from './constants';
+import { SortMode, TextDoc } from './types';
+
+export interface StoredDiffsState {
+  version: number;
+  texts: TextDoc[];
+  mode: SortMode;
+}
+
+export function generateColor(min = 0, max = 0.5): string {
+  const h = Math.floor(Math.random() * 360);
+  const s = 100;
+  const l = Math.floor((Math.random() * (max - min) + min) * 100);
+
+  // Convert HSL to RGB
+  const c = (1 - Math.abs((2 * l) / 100 - 1)) * (s / 100);
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+  const m = l / 100 - c / 2;
+
+  let r = 0,
+    g = 0,
+    b = 0;
+  if (0 <= h && h < 60) {
+    r = c; g = x; b = 0;
+  } else if (60 <= h && h < 120) {
+    r = x; g = c; b = 0;
+  } else if (120 <= h && h < 180) {
+    r = 0; g = c; b = x;
+  } else if (180 <= h && h < 240) {
+    r = 0; g = x; b = c;
+  } else if (240 <= h && h < 300) {
+    r = x; g = 0; b = c;
+  } else if (300 <= h && h < 360) {
+    r = c; g = 0; b = x;
+  }
+
+  const red = Math.floor((r + m) * 255);
+  const green = Math.floor((g + m) * 255);
+  const blue = Math.floor((b + m) * 255);
+
+  return `rgb(${red}, ${green}, ${blue})`;
+}
+
+export function loadStoredState(): { texts: TextDoc[]; mode: SortMode } | null {
+  try {
+    const raw = window.localStorage.getItem(STORAGE_KEY);
+    if (!raw) return null;
+    const parsed: StoredDiffsState = JSON.parse(raw);
+    if (parsed.version !== DIFFS_STATE_VERSION || !Array.isArray(parsed.texts)) {
+      return null;
+    }
+    return {
+      texts: parsed.texts,
+      mode: parsed.mode || 'chronologic',
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function saveStoredState(texts: TextDoc[], mode: SortMode): void {
+  try {
+    const payload: StoredDiffsState = {
+      version: DIFFS_STATE_VERSION,
+      texts,
+      mode,
+    };
+    window.localStorage.setItem(STORAGE_KEY, JSON.stringify(payload));
+  } catch (e) {
+    console.error('Failed to save diffs state to localStorage:', e);
+  }
+}
+
+export function clearStoredState(): void {
+  try {
+    window.localStorage.removeItem(STORAGE_KEY);
+  } catch (e) {
+    console.error('Failed to clear diffs state from localStorage:', e);
+  }
+}
diff --git a/src/playgrounds/diffs/types.ts b/src/playgrounds/diffs/types.ts
new file mode 100644
index 0000000..4e6b9be
--- /dev/null
+++ b/src/playgrounds/diffs/types.ts
@@ -0,0 +1,40 @@
+export type SortMode = 'chronologic' | 'frequency' | 'alphabetic';
+
+export interface TextDoc {
+  id: string;
+  name: string;
+  color: string; // rgb(...) string, assigned on creation
+  body: string;
+}
+
+export interface StatLineDatum {
+  key: string; // `${columnId}:${stem}`
+  word: string; // display form (first occurrence)
+  stem: string;
+  count: number;
+  x: number;
+  y: number;
+  width: number;
+  visible: boolean; // false for stopwords or hidden in source text when merged
+}
+
+export interface Column {
+  id: string; // a TextDoc id, or the literal 'shared'
+  name: string; // the TextDoc title, or 'Shared Words'
+  color: string;
+  x: number;
+  lines: StatLineDatum[];
+  graph: {
+    top: number;
+    bottom: number;
+    points: { x: number; y: number }[];
+  };
+}
+
+export interface DiffsModel {
+  columns: Column[]; // one per text
+  shared: Column;
+  byStem: Map<string, StatLineDatum[]>; // for highlight + arc lookup
+  totalLines: number;
+  totalChars: number;
+}
diff --git a/src/playgrounds/registry.ts b/src/playgrounds/registry.ts
index 57317f7..bea327d 100644
--- a/src/playgrounds/registry.ts
+++ b/src/playgrounds/registry.ts
@@ -1,6 +1,7 @@
 import { PlaygroundDefinition } from './types';
 import { WiremarksPlayground } from './wiremarks/WiremarksPlayground';
 import { ComponentsShowcasePlayground } from './components-showcase/ComponentsShowcasePlayground';
+import { DiffsPlayground } from './diffs/DiffsPlayground';
 
 export const PLAYGROUNDS: PlaygroundDefinition[] = [
   {
@@ -9,6 +10,12 @@ export const PLAYGROUNDS: PlaygroundDefinition[] = [
     description: 'Declarative text-to-wireframe interactive diagramming tool',
     component: WiremarksPlayground,
   },
+  {
+    id: 'diffs',
+    name: 'Diffs',
+    description: 'Visually compare texts by shared vocabulary',
+    component: DiffsPlayground,
+  },
   {
     id: 'components-showcase',
     name: 'Components Showcase',
diff --git a/src/test-setup.ts b/src/test-setup.ts
index ff0ab6b..22153b9 100644
--- a/src/test-setup.ts
+++ b/src/test-setup.ts
@@ -65,4 +65,22 @@ if (typeof globalThis.PointerEvent === 'undefined') {
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   (globalThis as any).PointerEvent = PointerEventPolyfill;
-}
\ No newline at end of file
+}
+
+/**
+ * jsdom does not implement `matchMedia`. Components that read the colour
+ * scheme need it to exist; defaulting `matches` to false renders the light
+ * theme, which is what the assertions expect.
+ */
+if (typeof window !== 'undefined' && typeof window.matchMedia !== 'function') {
+  window.matchMedia = ((query: string) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    addListener: () => {},
+    removeListener: () => {},
+    dispatchEvent: () => false,
+  })) as unknown as typeof window.matchMedia;
+}
diff --git a/src/vite-env.d.ts b/src/vite-env.d.ts
index 11f02fe..45d40b2 100644
--- a/src/vite-env.d.ts
+++ b/src/vite-env.d.ts
@@ -1 +1,6 @@
 /// <reference types="vite/client" />
+
+declare module 'wink-porter2-stemmer' {
+  export default function stem(word: string): string;
+}
+
diff --git a/tests/diffsCanvas.test.tsx b/tests/diffsCanvas.test.tsx
new file mode 100644
index 0000000..f88ef55
--- /dev/null
+++ b/tests/diffsCanvas.test.tsx
@@ -0,0 +1,107 @@
+import { describe, expect, it, vi } from 'vitest';
+import { act, render } from '@testing-library/react';
+import Two from 'two.js';
+import { Canvas, useTwo } from 'react-two.js';
+import { DiffsCanvas } from '../src/playgrounds/diffs/DiffsCanvas';
+import { buildModel } from '../src/playgrounds/diffs/model/layout';
+import { TextDoc } from '../src/playgrounds/diffs/types';
+
+const texts: TextDoc[] = [
+  {
+    id: 'text-1',
+    name: 'Alpha',
+    color: 'rgb(220, 80, 80)',
+    body: 'The quick brown fox jumps over the lazy dog.',
+  },
+  {
+    id: 'text-2',
+    name: 'Beta',
+    color: 'rgb(80, 160, 220)',
+    body: 'The lazy dog sleeps under the warm sun.',
+  },
+];
+
+/** Captures the Two instance so tests can drive frames deterministically. */
+function useCapture(sink: { current: Two | null }) {
+  const { two } = useTwo();
+  sink.current = two;
+}
+
+function Probe({ sink }: { sink: { current: Two | null } }) {
+  useCapture(sink);
+  return null;
+}
+
+function renderCanvas(
+  props: Partial<React.ComponentProps<typeof DiffsCanvas>> = {}
+) {
+  const sink: { current: Two | null } = { current: null };
+  const model = buildModel(texts, 'chronologic');
+
+  const utils = render(
+    <Canvas type={Two.Types.svg} width={800} height={600} autostart={false}>
+      <DiffsCanvas
+        model={model}
+        selectedStem={null}
+        highlightMode={false}
+        onSelectStem={() => {}}
+        {...props}
+      />
+      <Probe sink={sink} />
+    </Canvas>
+  );
+
+  const runFrames = (n: number) => {
+    for (let i = 0; i < n; i++) {
+      act(() => {
+        sink.current?.update();
+      });
+    }
+  };
+
+  return { ...utils, model, runFrames };
+}
+
+describe('DiffsCanvas', () => {
+  it('reveals stat lines once frames run', () => {
+    const { container, model, runFrames } = renderCanvas();
+
+    runFrames(10);
+
+    const svg = container.querySelector('svg');
+    const words = Array.from(svg?.querySelectorAll('text') ?? []).map(
+      (node) => node.textContent
+    );
+
+    // Every visible line across both columns plus the shared column.
+    for (const column of [...model.columns, model.shared]) {
+      for (const line of column.lines) {
+        expect(words).toContain(line.word);
+      }
+    }
+  });
+
+  it('reports processing until the reveal completes', () => {
+    const onProcessingChange = vi.fn();
+    const { runFrames } = renderCanvas({ onProcessingChange });
+
+    runFrames(10);
+
+    expect(onProcessingChange).toHaveBeenCalled();
+    expect(onProcessingChange.mock.calls.at(-1)?.[0]).toBe(false);
+  });
+
+  it('labels legend entries with each text name', () => {
+    const { container, runFrames } = renderCanvas();
+
+    runFrames(10);
+
+    const words = Array.from(
+      container.querySelectorAll('svg text') ?? []
+    ).map((node) => node.textContent);
+
+    expect(words).toContain('Alpha');
+    expect(words).toContain('Beta');
+    expect(words).toContain('Shared Words');
+  });
+});
diff --git a/tests/diffsModel.test.ts b/tests/diffsModel.test.ts
new file mode 100644
index 0000000..ffcfda6
--- /dev/null
+++ b/tests/diffsModel.test.ts
@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'vitest';
+import { buildModel } from '../src/playgrounds/diffs/model/layout';
+import { TextDoc } from '../src/playgrounds/diffs/types';
+import { COLUMN_PITCH, LEADING, SHARED_COLUMN_X } from '../src/playgrounds/diffs/constants';
+
+describe('diffs model building & layout', () => {
+  const sampleTexts: TextDoc[] = [
+    {
+      id: 't1',
+      name: 'Text 1',
+      color: 'rgb(255, 0, 0)',
+      body: 'quick brown fox quick',
+    },
+    {
+      id: 't2',
+      name: 'Text 2',
+      color: 'rgb(0, 255, 0)',
+      body: 'lazy brown fox dog',
+    },
+  ];
+
+  it('collapses repeat occurrences within a text into count', () => {
+    const model = buildModel([sampleTexts[0]], 'chronologic');
+    const col = model.columns[0];
+    const quickLine = col.lines.find((l) => l.word === 'quick');
+    expect(quickLine).toBeDefined();
+    expect(quickLine?.count).toBe(2);
+  });
+
+  it('merges cross-text shared words into shared column and hides from source columns', () => {
+    const model = buildModel(sampleTexts, 'chronologic');
+
+    // 'brown' and 'fox' appear in both texts
+    const sharedStems = model.shared.lines.map((l) => l.stem);
+    expect(sharedStems).toContain('brown');
+    expect(sharedStems).toContain('fox');
+
+    // In text columns, 'brown' and 'fox' are not in visible lines
+    const t1Stems = model.columns[0].lines.map((l) => l.stem);
+    const t2Stems = model.columns[1].lines.map((l) => l.stem);
+
+    expect(t1Stems).not.toContain('brown');
+    expect(t1Stems).not.toContain('fox');
+    expect(t2Stems).not.toContain('brown');
+    expect(t2Stems).not.toContain('fox');
+  });
+
+  it('sorts lines by frequency', () => {
+    const model = buildModel([sampleTexts[0]], 'frequency');
+    const col = model.columns[0];
+    // 'quick' has count 2, 'brown' and 'fox' have count 1
+    expect(col.lines[0].word).toBe('quick');
+  });
+
+  it('sorts lines alphabetically', () => {
+    const model = buildModel([sampleTexts[0]], 'alphabetic');
+    const col = model.columns[0];
+    const stems = col.lines.map((l) => l.stem);
+    expect(stems).toEqual([...stems].sort());
+  });
+
+  it('computes expected coordinates for text columns and shared column', () => {
+    const model = buildModel(sampleTexts, 'chronologic');
+
+    expect(model.shared.x).toBe(SHARED_COLUMN_X);
+    expect(model.columns[0].x).toBe(1 * COLUMN_PITCH);
+    expect(model.columns[1].x).toBe(2 * COLUMN_PITCH);
+
+    model.columns[0].lines.forEach((line, idx) => {
+      expect(line.y).toBeCloseTo(idx * LEADING * 1.15);
+      expect(line.x).toBe(1 * COLUMN_PITCH);
+    });
+  });
+});
diff --git a/tests/diffsReveal.test.ts b/tests/diffsReveal.test.ts
new file mode 100644
index 0000000..a7f5c9b
--- /dev/null
+++ b/tests/diffsReveal.test.ts
@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import { buildModel } from '../src/playgrounds/diffs/model/layout';
+import { TextDoc } from '../src/playgrounds/diffs/types';
+
+describe('progressive reveal calculation', () => {
+  it('calculates expected totalLines and chunk formula boundaries', () => {
+    const texts: TextDoc[] = [
+      {
+        id: '1',
+        name: 'T1',
+        color: 'rgb(0,0,0)',
+        body: 'alpha beta gamma delta epsilon',
+      },
+    ];
+
+    const model = buildModel(texts, 'chronologic');
+
+    // Formula: clamp(floor(totalChars / 100), 1, 250)
+    const chunkSize = Math.min(
+      Math.max(Math.floor(model.totalChars / 100), 1),
+      250
+    );
+
+    expect(model.totalLines).toBe(5);
+    expect(chunkSize).toBe(1);
+  });
+
+  it('caps max chunk size at 250 for huge text bodies', () => {
+    const hugeBody = 'a '.repeat(50000);
+    const texts: TextDoc[] = [
+      {
+        id: '1',
+        name: 'T1',
+        color: 'rgb(0,0,0)',
+        body: hugeBody,
+      },
+    ];
+
+    const model = buildModel(texts, 'chronologic');
+    const chunkSize = Math.min(
+      Math.max(Math.floor(model.totalChars / 100), 1),
+      250
+    );
+
+    expect(chunkSize).toBe(250);
+  });
+});
diff --git a/tests/diffsStatLine.test.tsx b/tests/diffsStatLine.test.tsx
new file mode 100644
index 0000000..8497534
--- /dev/null
+++ b/tests/diffsStatLine.test.tsx
@@ -0,0 +1,129 @@
+import { describe, expect, it, vi } from 'vitest';
+import { act, fireEvent, render } from '@testing-library/react';
+import Two from 'two.js';
+import { Canvas, useTwo } from 'react-two.js';
+import { StatLine } from '../src/playgrounds/diffs/components/StatLine';
+import { StatLineDatum } from '../src/playgrounds/diffs/types';
+
+const datum: StatLineDatum = {
+  key: 't1:fox',
+  word: 'fox',
+  stem: 'fox',
+  count: 3,
+  // World space has a top-left origin, so these are also the client
+  // coordinates the line occupies.
+  x: 200,
+  y: 150,
+  width: 50,
+  visible: true,
+};
+
+type HitTest = (clientX: number, clientY: number) => boolean;
+
+interface Sink {
+  current: HitTest | null;
+  two: Two | null;
+}
+
+function Probe({ sink }: { sink: Sink }) {
+  const { hitTestPoint, two } = useTwo();
+  sink.current = hitTestPoint;
+  sink.two = two;
+  return null;
+}
+
+function renderStatLine(highlightMode: boolean) {
+  const onSelect = vi.fn();
+  const sink: Sink = { current: null, two: null };
+
+  const { container } = render(
+    <Canvas type={Two.Types.svg} width={800} height={600} autostart={false}>
+      <StatLine
+        datum={datum}
+        color="rgb(255, 0, 0)"
+        isHighlighted={false}
+        highlightMode={highlightMode}
+        onSelect={onSelect}
+      />
+      <Probe sink={sink} />
+    </Canvas>
+  );
+
+  const svg = container.querySelector('svg') as SVGElement;
+  vi.spyOn(svg, 'getBoundingClientRect').mockReturnValue({
+    left: 0,
+    top: 0,
+    right: 800,
+    bottom: 600,
+    width: 800,
+    height: 600,
+    x: 0,
+    y: 0,
+    toJSON: () => {},
+  } as DOMRect);
+
+  // Draw one frame so the scene graph and its bounds are current.
+  act(() => {
+    sink.two?.update();
+  });
+
+  return { container, svg, onSelect, sink };
+}
+
+/** A real click fires pointerdown, pointerup and click — in that order. */
+function clickAt(target: Element, clientX: number, clientY: number) {
+  act(() => {
+    fireEvent.pointerDown(target, { clientX, clientY });
+    fireEvent.pointerUp(target, { clientX, clientY });
+    fireEvent.click(target, { clientX, clientY });
+  });
+}
+
+describe('StatLine', () => {
+  it('renders the word and its tally', () => {
+    const { container } = renderStatLine(false);
+    const words = Array.from(container.querySelectorAll('svg text')).map(
+      (node) => node.textContent
+    );
+
+    expect(words).toContain('fox');
+    expect(words).toContain('3');
+  });
+
+  it('emits its stem exactly once per click in highlight mode', () => {
+    const { svg, onSelect } = renderStatLine(true);
+
+    clickAt(svg, 200, 150);
+
+    expect(onSelect).toHaveBeenCalledTimes(1);
+    expect(onSelect).toHaveBeenCalledWith('fox');
+  });
+
+  it('does not emit when highlight mode is off', () => {
+    const { svg, onSelect } = renderStatLine(false);
+
+    clickAt(svg, 200, 150);
+
+    expect(onSelect).not.toHaveBeenCalled();
+  });
+
+  it('only claims pointer hits in highlight mode, so panning stays free', () => {
+    const off = renderStatLine(false);
+    expect(off.sink.current?.(200, 150)).toBe(false);
+
+    const on = renderStatLine(true);
+    expect(on.sink.current?.(200, 150)).toBe(true);
+  });
+});
+
+describe('StatLine vertical alignment', () => {
+  it('sits on the alphabetic baseline, as the original does', () => {
+    const { container } = renderStatLine(false);
+    const texts = [...container.querySelectorAll('svg text')];
+
+    expect(texts).toHaveLength(2);
+    for (const node of texts) {
+      expect(node.getAttribute('dominant-baseline')).toBe('alphabetic');
+    }
+  });
+});
diff --git a/tests/diffsStorage.test.ts b/tests/diffsStorage.test.ts
new file mode 100644
index 0000000..bb046b9
--- /dev/null
+++ b/tests/diffsStorage.test.ts
@@ -0,0 +1,59 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { DIFFS_STATE_VERSION, STORAGE_KEY } from '../src/playgrounds/diffs/constants';
+import {
+  clearStoredState,
+  loadStoredState,
+  saveStoredState,
+} from '../src/playgrounds/diffs/storage';
+import { TextDoc } from '../src/playgrounds/diffs/types';
+
+beforeEach(() => {
+  window.localStorage.clear();
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('diffs localStorage persistence', () => {
+  const sampleTexts: TextDoc[] = [
+    {
+      id: 't1',
+      name: 'Sample 1',
+      color: 'rgb(100, 100, 100)',
+      body: 'Hello world',
+    },
+  ];
+
+  it('returns null when nothing stored', () => {
+    expect(loadStoredState()).toBeNull();
+  });
+
+  it('round-trips stored state', () => {
+    saveStoredState(sampleTexts, 'frequency');
+    const loaded = loadStoredState();
+    expect(loaded).toEqual({
+      texts: sampleTexts,
+      mode: 'frequency',
+    });
+  });
+
+  it('discards stored state on version mismatch', () => {
+    window.localStorage.setItem(
+      STORAGE_KEY,
+      JSON.stringify({
+        version: DIFFS_STATE_VERSION + 999,
+        texts: sampleTexts,
+        mode: 'chronologic',
+      })
+    );
+    expect(loadStoredState()).toBeNull();
+  });
+
+  it('clears stored state', () => {
+    saveStoredState(sampleTexts, 'alphabetic');
+    clearStoredState();
+    expect(loadStoredState()).toBeNull();
+    expect(window.localStorage.getItem(STORAGE_KEY)).toBeNull();
+  });
+});
diff --git a/tests/diffsTokenize.test.ts b/tests/diffsTokenize.test.ts
new file mode 100644
index 0000000..5eff8af
--- /dev/null
+++ b/tests/diffsTokenize.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+import { tokenize } from '../src/playgrounds/diffs/model/tokenize';
+import { isStopword } from '../src/playgrounds/diffs/stopwords';
+
+describe('diffs tokenize & stopwords', () => {
+  it('strips trailing contractions and non-word characters', () => {
+    const result = tokenize("they'll don't cat's world!");
+    expect(result.map((t) => t.word)).toEqual(['they', 'don', 'cat', 'world']);
+  });
+
+  it('preserves original token index', () => {
+    const result = tokenize('first   second   third');
+    expect(result.map((t) => t.index)).toEqual([0, 1, 2]);
+  });
+
+  it('filters empty or non-word tokens', () => {
+    const result = tokenize('   !@#$%   \n\t   ');
+    expect(result).toEqual([]);
+  });
+
+  it('identifies stopwords correctly', () => {
+    expect(isStopword('the')).toBe(true);
+    expect(isStopword('is')).toBe(true);
+    expect(isStopword('and')).toBe(true);
+    expect(isStopword('fox')).toBe(false);
+    expect(isStopword('quick')).toBe(false);
+  });
+});

From 907609534dc146863c42650ca2d3af55b689c55e Mon Sep 17 00:00:00 2001
From: Jono Brandel <developer@jono.fyi>
Date: Fri, 21 Aug 2026 12:16:54 -0700
Subject: [PATCH 3/4] Legend theming

---
 tests/diffsCanvas.test.tsx | 40 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/tests/diffsCanvas.test.tsx b/tests/diffsCanvas.test.tsx
index f88ef55..099345b 100644
--- a/tests/diffsCanvas.test.tsx
+++ b/tests/diffsCanvas.test.tsx
@@ -3,6 +3,7 @@ import { act, render } from '@testing-library/react';
 import Two from 'two.js';
 import { Canvas, useTwo } from 'react-two.js';
 import { DiffsCanvas } from '../src/playgrounds/diffs/DiffsCanvas';
+import { Legend } from '../src/playgrounds/diffs/components/Legend';
 import { buildModel } from '../src/playgrounds/diffs/model/layout';
 import { TextDoc } from '../src/playgrounds/diffs/types';
 
@@ -105,3 +106,42 @@ describe('DiffsCanvas', () => {
     expect(words).toContain('Shared Words');
   });
 });
+
+describe('Legend theming', () => {
+  function renderLegend(isDark: boolean) {
+    const sink: { current: Two | null } = { current: null };
+    const model = buildModel(texts, 'chronologic');
+
+    const { container } = render(
+      <Canvas type={Two.Types.svg} width={800} height={600} autostart={false}>
+        <Legend
+          columns={model.columns}
+          shared={model.shared}
+          canvasHeight={600}
+          isDark={isDark}
+        />
+        <Probe sink={sink} />
+      </Canvas>
+    );
+
+    act(() => {
+      sink.current?.update();
+    });
+
+    return [...container.querySelectorAll('svg text')].map((node) =>
+      node.getAttribute('fill')
+    );
+  }
+
+  it('uses black labels on the light theme', () => {
+    const fills = renderLegend(false);
+    expect(fills.length).toBeGreaterThan(0);
+    expect(new Set(fills)).toEqual(new Set(['#000000']));
+  });
+
+  it('uses white labels on the dark theme, so they stay legible', () => {
+    const fills = renderLegend(true);
+    expect(fills.length).toBeGreaterThan(0);
+    expect(new Set(fills)).toEqual(new Set(['#ffffff']));
+  });
+});

From a11069fdad2afc3e794cb25a48abad538256d88a Mon Sep 17 00:00:00 2001
From: Jono Brandel <developer@jono.fyi>
Date: Sun, 23 Aug 2026 11:45:19 -0700
Subject: [PATCH 4/4] Harden diffs sort mode and shared word logic

- Move SORT_MODES array to types.ts; derive SortMode from it; add isSortMode() guard
- Use isSortMode() in loadStoredState() to avoid crashing buildModel on unknown stored modes
- Fix mergeTexts to take the shared line's display word from the earliest-index occurrence, not always occurrences[0]
- Silence console.error on localStorage write/clear failures (Safari private mode, quota limits)
- Add tests covering the display-word fix, the unknown-mode fallback, and the silent-failure paths
---
 src/playgrounds/diffs/DiffsPlayground.tsx |  8 ++---
 src/playgrounds/diffs/model/merge.ts      | 28 +++++++++++------
 src/playgrounds/diffs/storage.ts          | 15 +++++----
 src/playgrounds/diffs/types.ts            |  9 +++++-
 tests/diffsModel.test.ts                  | 30 ++++++++++++++++++
 tests/diffsStorage.test.ts                | 37 +++++++++++++++++++++++
 6 files changed, 105 insertions(+), 22 deletions(-)

diff --git a/src/playgrounds/diffs/DiffsPlayground.tsx b/src/playgrounds/diffs/DiffsPlayground.tsx
index 4e8d76d..e5783be 100644
--- a/src/playgrounds/diffs/DiffsPlayground.tsx
+++ b/src/playgrounds/diffs/DiffsPlayground.tsx
@@ -21,7 +21,7 @@ import {
   saveStoredState,
 } from './storage';
 import { TextColumn } from './components/TextColumn';
-import { SortMode, TextDoc } from './types';
+import { SORT_MODES, SortMode, TextDoc } from './types';
 
 const defaultTexts: TextDoc[] = [
   {
@@ -38,8 +38,6 @@ const defaultTexts: TextDoc[] = [
   },
 ];
 
-const MODES: SortMode[] = ['chronologic', 'frequency', 'alphabetic'];
-
 export function DiffsPlayground({ width, height }: PlaygroundProps) {
   const containerRef = useRef<HTMLDivElement>(null);
   const zuiRef = useRef<ZUIControls | null>(null);
@@ -118,8 +116,8 @@ export function DiffsPlayground({ width, height }: PlaygroundProps) {
 
   const handleCycleMode = useCallback(() => {
     setMode((current) => {
-      const idx = MODES.indexOf(current);
-      return MODES[(idx + 1) % MODES.length];
+      const idx = SORT_MODES.indexOf(current);
+      return SORT_MODES[(idx + 1) % SORT_MODES.length];
     });
     setSelectedStem(null);
   }, []);
diff --git a/src/playgrounds/diffs/model/merge.ts b/src/playgrounds/diffs/model/merge.ts
index 48e50b7..0e6ffe7 100644
--- a/src/playgrounds/diffs/model/merge.ts
+++ b/src/playgrounds/diffs/model/merge.ts
@@ -36,27 +36,35 @@ export function mergeTexts(
 
   for (const [s, occurrences] of stemOccurrences.entries()) {
     if (occurrences.length >= 2) {
-      // Shared stem! Hide in owning columns and add to shared column
+      // Shared stem! Hide in owning columns and add to shared column.
+      // The shared line sorts by the earliest occurrence, so its word and
+      // visibility come from that same occurrence rather than from whichever
+      // text happened to be scanned first.
       let totalCount = 0;
-      let minFirstIndex = Infinity;
-      const displayWord = occurrences[0].word;
-      const isVisible = occurrences[0].visible;
+      let earliest = occurrences[0];
 
       for (const occ of occurrences) {
-        occ.visible = false;
         totalCount += occ.count;
-        if (occ.firstIndex < minFirstIndex) {
-          minFirstIndex = occ.firstIndex;
+        if (occ.firstIndex < earliest.firstIndex) {
+          earliest = occ;
         }
       }
 
+      // Read before hiding: the loop below clears `visible` on every
+      // occurrence, `earliest` included.
+      const { word, firstIndex, visible } = earliest;
+
+      for (const occ of occurrences) {
+        occ.visible = false;
+      }
+
       sharedLines.push({
         textId: 'shared',
-        word: displayWord,
+        word,
         stem: s,
         count: totalCount,
-        firstIndex: minFirstIndex,
-        visible: isVisible,
+        firstIndex,
+        visible,
       });
     }
   }
diff --git a/src/playgrounds/diffs/storage.ts b/src/playgrounds/diffs/storage.ts
index 29a745b..26065b0 100644
--- a/src/playgrounds/diffs/storage.ts
+++ b/src/playgrounds/diffs/storage.ts
@@ -1,5 +1,5 @@
 import { DIFFS_STATE_VERSION, STORAGE_KEY } from './constants';
-import { SortMode, TextDoc } from './types';
+import { isSortMode, SortMode, TextDoc } from './types';
 
 export interface StoredDiffsState {
   version: number;
@@ -51,7 +51,9 @@ export function loadStoredState(): { texts: TextDoc[]; mode: SortMode } | null {
     }
     return {
       texts: parsed.texts,
-      mode: parsed.mode || 'chronologic',
+      // `sortLines` switches on this with no default branch, so an unknown
+      // mode would sort to undefined and crash the model build.
+      mode: isSortMode(parsed.mode) ? parsed.mode : 'chronologic',
     };
   } catch {
     return null;
@@ -66,15 +68,16 @@ export function saveStoredState(texts: TextDoc[], mode: SortMode): void {
       mode,
     };
     window.localStorage.setItem(STORAGE_KEY, JSON.stringify(payload));
-  } catch (e) {
-    console.error('Failed to save diffs state to localStorage:', e);
+  } catch {
+    // Safari private mode and quota limits throw here. Losing a save is not
+    // worth spamming the console on every keystroke.
   }
 }
 
 export function clearStoredState(): void {
   try {
     window.localStorage.removeItem(STORAGE_KEY);
-  } catch (e) {
-    console.error('Failed to clear diffs state from localStorage:', e);
+  } catch {
+    // Storage may be unavailable entirely; nothing to recover from.
   }
 }
diff --git a/src/playgrounds/diffs/types.ts b/src/playgrounds/diffs/types.ts
index 4e6b9be..71fcf0e 100644
--- a/src/playgrounds/diffs/types.ts
+++ b/src/playgrounds/diffs/types.ts
@@ -1,4 +1,11 @@
-export type SortMode = 'chronologic' | 'frequency' | 'alphabetic';
+export const SORT_MODES = ['chronologic', 'frequency', 'alphabetic'] as const;
+
+export type SortMode = (typeof SORT_MODES)[number];
+
+/** Guards untrusted input, such as a hand-edited localStorage payload. */
+export function isSortMode(value: unknown): value is SortMode {
+  return SORT_MODES.includes(value as SortMode);
+}
 
 export interface TextDoc {
   id: string;
diff --git a/tests/diffsModel.test.ts b/tests/diffsModel.test.ts
index ffcfda6..1f911f8 100644
--- a/tests/diffsModel.test.ts
+++ b/tests/diffsModel.test.ts
@@ -72,3 +72,33 @@ describe('diffs model building & layout', () => {
     });
   });
 });
+
+describe('shared column display word', () => {
+  it('takes its word from the same occurrence that supplies its index', () => {
+    // "dog" appears late in t1 ("dogs", index 3) but first in t2 (index 0).
+    // The shared line sorts by the earliest index, so it must display the word
+    // belonging to that earliest occurrence.
+    const model = buildModel(
+      [
+        {
+          id: 't1',
+          name: 'Text 1',
+          color: 'rgb(255, 0, 0)',
+          body: 'alpha beta gamma dogs',
+        },
+        {
+          id: 't2',
+          name: 'Text 2',
+          color: 'rgb(0, 255, 0)',
+          body: 'dog delta',
+        },
+      ],
+      'chronologic'
+    );
+
+    const shared = model.shared.lines.find((line) => line.stem === 'dog');
+    expect(shared).toBeDefined();
+    expect(shared?.word).toBe('dog');
+    expect(shared?.count).toBe(2);
+  });
+});
diff --git a/tests/diffsStorage.test.ts b/tests/diffsStorage.test.ts
index bb046b9..ed125a3 100644
--- a/tests/diffsStorage.test.ts
+++ b/tests/diffsStorage.test.ts
@@ -57,3 +57,40 @@ describe('diffs localStorage persistence', () => {
     expect(window.localStorage.getItem(STORAGE_KEY)).toBeNull();
   });
 });
+
+describe('diffs stored state hardening', () => {
+  it('falls back to a known sort mode when the stored one is unrecognised', () => {
+    window.localStorage.setItem(
+      STORAGE_KEY,
+      JSON.stringify({
+        version: DIFFS_STATE_VERSION,
+        texts: [],
+        mode: 'not-a-real-mode',
+      })
+    );
+
+    // buildModel drives sortLines, which has no default branch — an unknown
+    // mode would sort to undefined and crash on .map().
+    expect(loadStoredState()?.mode).toBe('chronologic');
+  });
+
+  it('does not log when writing is blocked', () => {
+    const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+    vi.spyOn(Storage.prototype, 'setItem').mockImplementation(() => {
+      throw new DOMException('QuotaExceededError');
+    });
+
+    expect(() => saveStoredState([], 'chronologic')).not.toThrow();
+    expect(error).not.toHaveBeenCalled();
+  });
+
+  it('does not log when clearing is blocked', () => {
+    const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+    vi.spyOn(Storage.prototype, 'removeItem').mockImplementation(() => {
+      throw new DOMException('SecurityError');
+    });
+
+    expect(() => clearStoredState()).not.toThrow();
+    expect(error).not.toHaveBeenCalled();
+  });
+});