From 5763504a57d6b7aee0c89362bfd564dbe08cd81d Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Wed, 4 Nov 2026 12:01:55 +0000
Subject: [PATCH 01/38] perf: findings, fix plan and phone-emulated perf probe

Refs CNCKitchen/ScanRuler#91

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../plans/2026-11-04-mobile-perf-fixes.md     | 300 ++++++++++++++++++
 .../specs/2026-11-04-mobile-perf-findings.md  | 140 ++++++++
 scripts/perf-probe.mjs                        | 268 ++++++++++++++++
 3 files changed, 708 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-11-04-mobile-perf-fixes.md
 create mode 100644 docs/superpowers/specs/2026-11-04-mobile-perf-findings.md
 create mode 100644 scripts/perf-probe.mjs

diff --git a/docs/superpowers/plans/2026-11-04-mobile-perf-fixes.md b/docs/superpowers/plans/2026-11-04-mobile-perf-fixes.md
new file mode 100644
index 00000000..7242b0e3
--- /dev/null
+++ b/docs/superpowers/plans/2026-11-04-mobile-perf-fixes.md
@@ -0,0 +1,300 @@
+# Mobile UI Responsiveness Fixes — Implementation Plan (rev 2, after review)
+
+> **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:** Every tab and toggle paints its UI in the first frame after the tap on a phone, and no toggle pays shader compiles, scan-sized uploads or new WebGL contexts it does not need.
+
+**Architecture:** Fix the measurement first (a project with real content, profiler-off timing, medians), then ship the evidence-backed wins (TopBar fold, unchanged-map skips, section-view compile, keep-alive viewports, BVH refit). Work whose payoff the first baseline could not show (overlay rebuilds, deferral, workers, React restructuring) is gated: each such task starts by adding its probe row and proceeds only if the row shows the cost. Battery and startup items come last.
+
+**Tech Stack:** React 19.2, zustand 5, three.js 0.180, three-mesh-bvh 0.8.3, Vite 6, Vitest 3, puppeteer-core e2e.
+
+**Spec:** `docs/superpowers/specs/2026-11-04-mobile-perf-findings.md` (F1–F20, baseline, and the *Review corrections* section — read it; several findings were downgraded).
+
+## Global Constraints
+
+- Every source file keeps `// SPDX-License-Identifier: AGPL-3.0-only`; new files get it too.
+- Match the codebase's comment style: full-sentence comments explaining *why*, in the existing voice.
+- No new runtime dependencies.
+- Colours on screen after the tap must equal colours before the change (byte-identical buffers), except for one transient frame where Task 9 says so.
+- Documented trade-offs that a task reverses are listed under **Owner decisions** and are not implemented until the owner agrees.
+- The commands/agent API awaits `nextFrame()` (`src/commands/core/common.ts:162`) to see the stage follow the stores; anything deferred must be flushed by it.
+- Vitest: `npx vitest run <file> --maxWorkers=8`. Typecheck: `npx tsc --noEmit`. Never two heavy builds/e2e at once.
+- e2e: `npx vite --port 5391 --strictPort` in the background, then `APP_URL=http://localhost:5391/ node scripts/<name>.mjs`. `e2e:<name>` in this plan means `scripts/e2e-<name>.mjs` (or `plugins/*/scripts/e2e-<name>.mjs` for `reverse`, `mesh`), alias or not.
+- Before any PR: `npm run build` must pass; state its output.
+
+## Owner decisions (ask before implementing)
+
+1. **Keep split view and 2D viewer WebGL contexts alive after first use** (reverses `App.tsx:1671-1673`). Recommended: yes — measured 1 context + 6.8 MB + 1 program per split open. Task 6.
+2. **Keep the `deflect` attribute while in the deviation workspace** (+12 B/vertex; reverses `SceneManager.ts:2855-2859`). Recommended: yes. Task 10.
+3. **Cap pixel ratio on touch screens** (sharpness change; `(pointer: coarse)` also matches touch laptops). Recommended: not as a perf fix — offer it as a setting. Not in this plan.
+
+## Review Focus
+
+1. Hidden tab: rAF does not fire; deferred work must complete and `nextFrame()` must flush it *after* its own frame resolves (Task 9 test).
+2. A field buffer recomputed in place (same `Float32Array`) must not be served from a cache — caches key on store versions (Tasks 2, 3 tests).
+3. Rapid repeated taps (map off→on within one frame, tab A→B→A): end state = last tap, painted once (Task 9 test).
+4. Scan replaced / crease changed while a worker job or kept-alive viewport is pending: stale result dropped, never shown on the new geometry (Tasks 6, 10, 11 tests).
+5. Projects with many elements, dimensions and sections, and scans ≥ 1M triangles — every gated task measures on the rich scenario, not only on the bare sample (Task 0).
+
+---
+
+## Phase A — Measure properly
+
+### Task 0: Probe v2
+
+**Files:** Modify `scripts/perf-probe.mjs` (add to git in this task).
+
+**Interfaces (produced):**
+- `PERF_RUNS` (default 5): each measured tap is repeated (toggle taps alternate on/off) and the **median** INP and long-task max reported. Profiler **off** for these runs; one extra profiled run per tap supplies the hot list.
+- Drop the "UI appears" column (its t0 includes CDP overhead).
+- `budget: { links?, uploadMB?, contexts?, inpMs? }` per measure; `PERF_ASSERT=1` exits 1 with a `BUDGET FAIL: <label>: <what>` line per breach. `inpMs` budgets are set at baseline median − 30 % and only checked when `PERF_RUNS ≥ 5`.
+- `PERF_SCENARIO=rich` (dev server only — imports `/src/commands/registry.ts` in `page.evaluate` and calls `runCommand`): after loading the sample, create 6 elements with `fit` (plane, cylinder, sphere ×2 at known vertices found via `runCommand('nearest', …)` / the `fit` input schema in `src/commands/core/element.ts:332`), 4 dimensions (`src/commands/core/dimension.ts`), 1 section (`src/commands/core/section.ts`), 5 deviation probes, then runs the same tap list. GL counters are identical in dev and prod, so GL budgets for this scenario are asserted on dev.
+- `SCAN=<path>` overrides the sample (use a ≥ 1M-triangle scan when available; record its size in the output).
+- Fix the Thickness map toggle row (`toggle-colormap` only exists in deviation — find the thickness view-bar key via `[data-test=part-keys]` and measure it), and add rows: thickness bands change, thickness histogram toggle, deviation range slider step, tolerance change, first show of the reference after switching tabs (load reference in Measure, then tap the Deviation tab).
+- Prod hot lists need names: build the probe's prod target with `npx vite build --sourcemap` and map `callFrame` lines through the source map (`source-map-js` is already in `node_modules` via Vite; import it from there, no new dependency).
+
+- [ ] **Step 1:** Implement; run bare + rich + prod. Save `e2e-out/perf-baseline-v2.txt`.
+- [ ] **Step 2:** Record in the spec's baseline table the medians, and for the rich scenario the rows the gated tasks name (overlay rebuild on tab switch, `evaluateDimensions`, recovery long task after a toggle, element-map recompute, brush stroke upload).
+- [ ] **Step 3: Commit** `perf: probe v2 — medians, rich project scenario, GL budgets`
+
+---
+
+## Phase B — Evidence-backed wins
+
+### Task 1: TopBar fold only when its content changed (F7)
+
+**Files:** Modify `src/ui/TopBar.tsx:111-130` (`useFit`).
+
+**Interfaces:** `useFit(ref)` keeps running after every render but returns early when `signature(el) === last` where `signature(el) = el.textContent + '|' + el.childElementCount + '|' + el.className` (no layout read); the ResizeObserver and `document.fonts.ready` paths clear `last` and fit unconditionally.
+
+- [ ] **Step 1:** `APP_URL=… node scripts/e2e-large-text.mjs` baseline → ALL PASS.
+- [ ] **Step 2:** Implement.
+- [ ] **Step 3:** `e2e-large-text` ALL PASS; probe: `Tab → workspace-reverse` median INP drops ≥ 80 ms vs Task 0 baseline; `fit.current` absent from the profiled hot lists of tab taps.
+- [ ] **Step 4: Commit** `perf(topbar): fold fit only when the bar's content changed`
+
+### Task 2: Skip unchanged map repaints and uploads (F2; review C2)
+
+**Files:** Modify `src/app/useSceneSync.ts:789-827` (paint at `:807`), `src/viewer/SceneManager.ts:2774` (`setFieldColors`), `src/viewer/regionColors.ts` (`setFieldColors`). Test: `tests/regionColors.test.ts`, `tests/paintKey.test.ts` (new).
+
+**Interfaces:**
+- `shownField()` branches each return `version: number` (`mapVersion`, `elementVersion`, `referenceVersion`, `thickVersion`, `plugin.fieldVersion`).
+- `paintKey(version: number, scale: FieldScale, colormapId: string): string` exported from `src/core/field/colormap.ts`.
+- Effect keeps `painted = useRef(new WeakMap<Uint8Array, string>())`; when `painted.get(rgb) === key` it skips `paintField`.
+- `RegionColors.setFieldColors(field)` returns `false` (nothing to upload) when `field === this.fieldColors && fieldPainted === true`, where `fieldPainted` is reset by any element/region/sparse change; `SceneManager.setFieldColors` uploads only on `true`. A repaint *into the same buffer* passes a new `repainted = true` flag: `setFieldColors(colors, repainted)`.
+- **No LUT** (review: band edges would move; payoff small).
+
+- [ ] **Step 1: Failing tests:** `paintKey` differs on version/scale/colormap changes only; `RegionColors.setFieldColors(sameField)` twice → second returns `false`; after `setHiddenRegions([1])` it returns `true`; `setFieldColors(sameField, true)` returns `true`.
+- [ ] **Step 2:** FAIL → **Step 3:** implement → **Step 4:** PASS; `npm test`.
+- [ ] **Step 5:** Probe: `Tab → Deviation (map in hand)`, `Tab → Thickness (map in hand)`, `map on`: `uploadMB: 0` budget green.
+- [ ] **Step 6: Commit** `perf(map): skip repaint and upload when the map is unchanged`
+
+### Task 3: Cached readout figures (F3)
+
+**Files:** Create `src/core/field/readoutCache.ts`; modify `src/app/useSceneSync.ts:834-859` (histogram `:839`, `setReadout` `:841-843`). Test: `tests/readoutCache.test.ts`.
+
+**Interfaces:**
+- `cachedHistogram(values: Float32Array, version: number, low: number, high: number, validMin: number, validMax: number): FieldHistogram`
+- `cachedDeviationStats(values: Float32Array, version: number, maxDistance: number, tolerance: number): DeviationStats`
+- `cachedThicknessStats(values: Float32Array, version: number, limit: number | null): ThicknessStats`
+- Memoised per `values` (WeakMap) on the other args. The effect calls `setReadout` only when either object differs from the store's.
+
+- [ ] **Step 1: Failing tests:** same args → `toBe` same object; same array mutated in place + new version → recomputed, equal to a fresh `fieldHistogram`/`deviationStats`; range change leaves stats `toBe` previous.
+- [ ] **Step 2–4:** FAIL → implement → PASS; `npm test`.
+- [ ] **Step 5:** Probe: `source → reference`, `Tab → … (map in hand)` median INP not worse; range-slider row improves.
+- [ ] **Step 6: Commit** `perf(readout): cache histogram and stats per map version`
+
+### Task 4: Refit, don't rebuild, the BVH on rigid moves (F19, safe half)
+
+**Files:** Modify `src/viewer/SceneManager.ts:2317-2329` (`applyTransform` and `this.other`), plus the same pattern at `:2598`, `:2719` if they are rigid. Test: `tests/bvhRefit.test.ts`.
+
+**Interfaces:** after baking a rigid transform into positions: `geometry.boundsTree ? geometry.boundsTree.refit() : geometry.computeBoundsTree()`.
+
+- [ ] **Step 1: Failing test** (node, three + three-mesh-bvh): build a BVH on a sphere mesh, apply a rotation+translation to positions, `refit()`; 1000 random rays give the same first hit (distance within 1e-6) as a freshly built tree. (Fails until the helper `refitAfterRigid(geometry)` exists in `src/viewer/bvh.ts`, new.)
+- [ ] **Step 2–4:** FAIL → implement `refitAfterRigid(geometry: THREE.BufferGeometry): void` and use it → PASS.
+- [ ] **Step 5:** `e2e:align`, `e2e:auto-align`, `e2e:align-after-deviation` PASS; probe: align-apply row long task max drops.
+- [ ] **Step 6: Commit** `perf(bvh): refit after rigid moves instead of rebuilding`
+
+### Task 5: Section view without compiles in the tap (F5)
+
+**Files:** Modify `src/viewer/SceneManager.ts` (new `warmPrograms()`, `applySlice:1514`, cap creation `:1630-1640`), `src/viewer/sliceCap.ts:61` (`closedPartOf`), `src/core/workerProtocol.ts`/`meshWorker.ts`/`workerClient.ts` (closed shells). Test: `tests/closedShells.test.ts` (exists — extend).
+
+**Interfaces:**
+- `SceneManager.warmPrograms(): void` — scheduled with `requestIdleCallback` (fallback `setTimeout(…, 500)`) after scan load, nominal load and `setReferenceMap(non-null)`; cancelled by a token if the geometry changes. It builds a **throwaway** `THREE.Scene` holding: one 3-vertex mesh per material variant (clones of the scan / nominal / reference-map materials, `onBeforeCompile` copied by reference so the cache key matches) × clipping `[null, this.clipList]` × opacity `[1, SEE_THROUGH_OPACITY]`, plus one `SliceCap` built on the same tiny mesh. It then does a real `renderer.render(scene, camera)` with `setScissorTest(true)`, a 1×1 scissor and viewport, `renderer.localClippingEnabled` as in the live scene, then restores scissor/viewport and disposes **geometries only** (materials kept in `this.warmKeepers` so their programs stay referenced; released on scan dispose). Live materials are never mutated.
+- Closed shells: `MeshWorkerClient.closedShells(which: 'scan' | 'nominal'): Promise<{ closed: Uint8Array; count: number }>`; `closedPartOf` gains `primeClosedPart(geometry, shells)` to fill its WeakMap cache from the worker result, requested right after load. `closedPartOf` keeps its synchronous fallback.
+
+- [ ] **Step 1: Failing test:** worker-side `closedShells` on the shared fixtures equals the main-thread result (extend `tests/closedShells.test.ts`).
+- [ ] **Step 2–4:** FAIL → implement → PASS.
+- [ ] **Step 5:** Probe (prod, ≥ 3 s idle after load): `section view` `links: 0`, median INP ≤ 120 ms; `map on reference` `links: 0`.
+- [ ] **Step 6:** `e2e:section`, `e2e:section-view`, `e2e:crease`, `e2e:section-shadow` PASS.
+- [ ] **Step 7: Commit** `perf(section): warm programs at idle, closed shells in the worker`
+
+### Task 6: Keep split and 2D viewports alive (F4) — *Owner decision 1*
+
+**Files:** `src/App.tsx:1656-1695`, `src/ui/CompareView.tsx`, `src/ui/FlatViewer.tsx`, `src/viewer/orthoViewport.ts` (`resize`), `src/viewer/CompareScene.ts:1-10` (fix the comment: buffers are per context, the geometry is uploaded again).
+
+**Interfaces:**
+- `CompareView` and `FlatViewer` gain `active: boolean`; App renders them once `splitEverOpened` (reset when `nominalGeometry` identity changes) / `flatEverOpened`, hidden via the `hidden` attribute when inactive.
+- `active=false` → `viewport.paused = true`; `OrthoViewport.resize()` ignores 0×0 sizes (keeps the last size) so a hidden container does not reallocate.
+- On `active` false→true: `compare.linkTo(scene.viewLink())` again and the flat sync re-runs what `flatSync.onReady` does (`src/app/useFlatSceneSync.ts` — expose `resync(viewer)` and call it).
+- Context count with everything open: main + split + flat + point-picker halves (2) + reverse plugin layers — count in Step 1 and record; must be ≤ 6.
+
+- [ ] **Step 1:** Probe: second `split on` and second `Tab → 2D Measure` fail `contexts: 0` (confirm); log the context total.
+- [ ] **Step 2:** Implement; dispose kept viewports when the scan or reference geometry is replaced.
+- [ ] **Step 3:** Probe green; `e2e:split`, `e2e:flat`, `e2e:spline`, `e2e:pick-slot`, `e2e:pick-fit` PASS.
+- [ ] **Step 4: Commit** `perf(viewports): keep split and 2D views alive after first use`
+
+---
+
+## Phase C — Gated on the rich-scenario baseline
+
+Each task's Step 1 is: *read its row in `e2e-out/perf-baseline-v2.txt`; if the cost is under 16 ms median and 0 links / < 1 MB, mark the task skipped in this file with the number, commit, and move on.*
+
+### Task 7: Overlay work only where it is shown (review C1, F11)
+
+**Files:** `src/app/useSceneSync.ts:315-436`, `src/viewer/overlays.ts:279`, `src/viewer/sections.ts:162, 440`, `src/viewer/volumeLayer.ts:36`.
+
+**Interfaces:**
+- `evaluateDimensions` and the pairs/angles/tags arrays are computed only when `elementsWorkspace` (they are discarded otherwise).
+- The overlay effect's dependency `elementsWorkspace` stays, but the effect returns early (no `updateOverlays`) when the computed `items`, the visibility flag and the (empty) dimension arrays equal the last ones passed (`lastOverlayInput` ref compared by element identity + style + muted).
+- Material reuse: `Overlays` keeps `shellMaterials` across rebuilds keyed by element id, updating `color`/`opacity` in place; dispose only materials whose element is gone. Same pattern in `sections.ts` (line materials keyed by section id) and `volumeLayer.ts`.
+
+- [ ] **Step 1:** Gate (rich row: tab switch with elements; map toggle with elements → links).
+- [ ] **Step 2:** Implement. **Step 3:** rich probe: tab switch median INP improves; map toggle `links: 0`. `e2e:element-deviation`, `e2e:gdt`, `e2e:section-dimension`, `e2e:edit` PASS.
+- [ ] **Step 4: Commit** `perf(overlays): skip unchanged rebuilds, reuse materials`
+
+### Task 8: Narrow subscriptions; one hints ladder (F16; review C3)
+
+**Files:** `src/ui/ThicknessPanel.tsx:32`, `src/ui/MarkTools.tsx:90`, `src/ui/SplitPicker.tsx:272`, `src/app/useHints.ts:22`.
+
+**Interfaces:** bare `useX()` → `useX(useShallow((s) => ({ …fields read… })))`. `useLadder()` computed once in a `HintsProvider` context mounted in `App`; `usePulse(id)` → `useContext(LadderContext).active === id`.
+
+- [ ] **Step 1:** Gate (rich: Deviation tab mount cost in profiled hot list).
+- [ ] **Step 2:** Implement; `npx tsc --noEmit`, `npm test`, `e2e:thickness`, `e2e:local-fit`, `e2e:support-ask` PASS.
+- [ ] **Step 3: Commit** `perf(ui): narrow subscriptions, compute the hint ladder once`
+
+### Task 9: Post-paint scheduling for remaining scene work (F1)
+
+**Depends on:** Tasks 2, 3, 7 (deferral moves work; those tasks remove it). Do this only if, after them, a tap row still shows a scene effect > 16 ms in its handler.
+
+**Files:** Create `src/app/afterPaint.ts`; modify `src/app/useSceneSync.ts`, `src/commands/core/common.ts:162`. Test: `tests/afterPaint.test.ts`.
+
+**Interfaces:**
+- `afterPaint(key: string, job: () => void): void` — replaces a pending job with the same key; runs via `requestAnimationFrame(() => setTimeout(run, 0))`, or `setTimeout(run, 0)` when hidden / no rAF.
+- `flushAfterPaint(): void`; `pendingAfterPaint(): number`.
+- `nextFrame()` flushes **after** its rAF resolves (visible) or after `nextTask()` and before `pumpFrame()` (hidden) — so jobs scheduled by the effects of the commit that `nextFrame` is waiting on are included.
+- Only effects that still measure > 16 ms are wrapped; each job reads its inputs at run time.
+
+- [ ] **Step 1: Failing tests:** coalescing; hidden-document path; `nextFrame` resolves only after a job scheduled in a microtask after the call has run (simulate: call `nextFrame`, then `queueMicrotask(() => afterPaint('x', spy))`, await → `spy` called).
+- [ ] **Step 2–4:** FAIL → implement → PASS.
+- [ ] **Step 5:** e2e one at a time: `e2e:deviation`, `e2e:element-deviation`, `e2e:thickness`, `e2e:split`, `e2e:agent`, `e2e:history` PASS. (Allowed visual change: the scan shows its previous colours for one frame after a tab tap.)
+- [ ] **Step 6: Commit** `perf(scene): run remaining scene sync after the tap has painted`
+
+### Task 10: Animation without re-upload; motion in the worker (F8) — *Owner decision 2*
+
+**Files:** `src/viewer/SceneManager.ts:2847-2866`, `src/core/workerProtocol.ts`, `meshWorker.ts`, `workerClient.ts`, `src/app/useSceneSync.ts:994-1025`. Test: `tests/deflection.test.ts`.
+
+**Interfaces:**
+- `dropDeflection()` keeps the attribute and sets `uDeflect = 0`; `releaseDeflect` runs on scan replacement and from `setDeflectionHeld(false)`, called when the workspace leaves deviation.
+- `MeshWorkerClient.deflection(values: Float32Array, directions: Int8Array, opts: { limit: number; maxDistance: number; smoothing: number }): Promise<Float32Array>` with a `scanToken`; stale replies reject `StaleScan` and are ignored.
+- **Parity precondition (Step 1):** worker `graph.positions` for vertices `0..scanVertexCount-1` must equal `scene.scanPositions()` after load, crease and a datum transform (`meshWorker.ts:482-499`). If not equal, the request sends `positions` (copy) instead.
+
+- [ ] **Step 1: Failing tests:** parity check on the ball-bar fixture (load → transform → compare); worker `deflectionVectors` equals main-thread call bitwise; stale token rejected.
+- [ ] **Step 2–4:** FAIL → implement → PASS. **Step 5:** probe `animate off` `uploadMB ≤ 1`; `e2e:deviation` PASS.
+- [ ] **Step 6: Commit** `perf(animate): keep the deflect buffer, compute motion in the worker`
+
+### Task 11: Element-mode map in the worker (F12)
+
+**Files:** `src/core/workerProtocol.ts`, `meshWorker.ts`, `workerClient.ts`, `src/app/useElementField.ts:98-137`, `src/state/deviationStore.ts`. Test: `tests/elementFieldWorker.test.ts`.
+
+**Interfaces:**
+- `MeshWorkerClient.elementDeviation(target: ElementTarget, opts: { side: MaterialSide; maxNormalDeviation: number | null; subset: Uint32Array | null }): Promise<{ values: Float32Array; directions: Int8Array; suggestedRange: number }>`.
+- **Normals parity:** render normals are crease-split, graph normals may not be; Step 1 compares. If they differ, send `normals` (copy of `scanArrays().normals`) with the request.
+- The effect captures `restoring` and the input tuple at dispatch; sets `elementStatus = 'running'`; on reply, drops it if `previousInputs.current` changed, else `resolveElementMap(suggestedRange, restoring)`.
+- Facing slider: requests coalesce (latest wins; an in-flight request's reply is dropped when a newer one exists).
+
+- [ ] **Step 1:** Gate (rich row: target select / facing change) + failing parity tests.
+- [ ] **Step 2–4:** implement → PASS. **Step 5:** `e2e:element-deviation`, `e2e:history` PASS.
+- [ ] **Step 6: Commit** `perf(element-map): measure against an element in the worker`
+
+### Task 12: Scene sync in a leaf component (F10, first half only)
+
+**Files:** Create `src/app/SceneSync.tsx`; modify `src/App.tsx` (call site of `useSceneSync` `~1256` and `useElementField`).
+
+**Interfaces:** `export const SceneSync = memo(function SceneSync(props: SceneSyncProps): null)` where `SceneSyncProps` = `Parameters<typeof useSceneSync>[0]` & the `useElementField` inputs; App passes only stable refs; `cancelDraft` and `plugin` via a ref holder (`pluginRef`, `cancelDraftRef`) so props never change identity.
+
+Not in this plan (review: blast radius): memo-wrapping all panels, `PluginHost`, `DeviationLegend` split. Re-measure after this task and open a follow-up only if App renders still dominate.
+
+- [ ] **Step 1:** Gate (dev React Profiler: App commit duration on map toggle; add `<Profiler>` in dev only).
+- [ ] **Step 2:** Implement; `npx tsc --noEmit`, `npm test`, `e2e:deviation`, `e2e:element-deviation`, `e2e:reverse`, `e2e:mesh`, `e2e:agent` PASS.
+- [ ] **Step 3: Commit** `perf(app): scene sync in a leaf component`
+
+### Task 13: Recovery inspection at idle (F13)
+
+**Files:** `src/app/useRecovery.ts:108-137`.
+
+**Interfaces:** `scheduleInspect` → `requestIdleCallback(run, { timeout: 1000 })` (fallback `setTimeout(run, 300)`). View-only keys (`workspace`, `showMap`, `showHistogram`, `split`, `showScan`, `showNominal`) move to a watcher that sets `pending = true` only.
+
+- [ ] **Step 1:** Gate (rich row: long task after map toggle). `e2e:recovery` baseline PASS, note its timing assumptions.
+- [ ] **Step 2:** Implement; `e2e:recovery`, `e2e:project` PASS.
+- [ ] **Step 3: Commit** `perf(recovery): inspect at idle, not after every view toggle`
+
+---
+
+## Phase D — Battery and startup (after B and C)
+
+### Task 14: Idle render loops (F9)
+
+**Files:** `src/viewer/orthoViewport.ts` (loop `~300-352`, `resize`, `worldPerPixel:408`), `src/viewer/SceneManager.ts` onTick `~462-480`, `src/viewer/labelSpread.ts`, `plugins/reverse/viewer/networkLayer.ts:1045`.
+
+**Interfaces:**
+- `OrthoViewport.size: { w; h }` set in `resize()`; `worldPerPixel()`, `frame()` and SceneManager's onTick read it.
+- `OrthoViewport.wake()`; loop sleeps after 30 idle frames when `!needsRender && !flight && !spaceMouseAttached() && !opts.keepAwake?.()`.
+- Wake sources (all must call `wake()`): `invalidate()`; canvas `pointerdown/pointermove/pointerup/wheel/touchstart/touchmove`; window `keydown/keyup`; `ResizeObserver`; `visibilitychange` → visible; `animateLook`; SpaceMouse connect; `CameraLink` (a leader's change wakes followers); prefs/theme changes (`setViewTheme`, `setNavScheme`). `keepAwake`: deflection playing, marking stroke pending, `clipDirty`, a pending region repaint.
+- `spreadLabels` caches `offsetWidth/offsetHeight` per label in a `WeakMap<HTMLElement, { w; h; text }>` and re-reads only when `textContent` changed.
+
+- [ ] **Step 1:** Probe idle row: rAF callbacks into app code per 3 s (count via a wrapped `requestAnimationFrame` in the probe) — target 0 after 1 s idle.
+- [ ] **Step 2:** Implement. **Step 3:** e2e one at a time: `e2e:nav`, `e2e:spacemouse`, `e2e:touch`, `e2e:deviation`, `e2e:split`, `e2e:extend`, `e2e:paint`, `e2e:reverse` PASS.
+- [ ] **Step 4: Commit** `perf(viewport): sleep when idle, no per-frame layout reads`
+
+### Task 15: BVH build off the main thread on load (F19, second half)
+
+**Files:** `src/core/meshWorker.ts`, `workerProtocol.ts`, `workerClient.ts`, `src/viewer/SceneManager.ts:924, 2263`.
+
+**Interfaces:** not `GenerateMeshBVHWorker` (it transfers and neuters the live position/index buffers). The mesh worker builds `new MeshBVH(geometry, { indirect: true })` over the **same index the main geometry uses** (including crease copies — the load reply already carries `indices`), returns `MeshBVH.serialize(bvh, { cloneBuffers: false })` transferred; main does `geometry.boundsTree = MeshBVH.deserialize(data, geometry, { setIndex: false })`. Until it arrives, picks fall back to three's raycast; every direct `boundsTree` consumer (grep `boundsTree` under `src/`) checks presence.
+
+- [ ] **Step 1: Failing test:** serialize in a worker-equivalent context, deserialize on a geometry with identical attributes → same raycast hits as `computeBoundsTree()` (ball-bar fixture).
+- [ ] **Step 2–4:** implement → PASS. **Step 5:** `e2e:smoke`, `e2e:import`, `e2e:align`, `e2e:crease` PASS; probe open-scan long-task max ≤ 150 ms.
+- [ ] **Step 6: Commit** `perf(bvh): build the scan's tree in the worker`
+
+### Task 16: Partial uploads (F18) — gated
+
+**Files:** `src/viewer/marking.ts:398`, `src/viewer/volumeLayer.ts:65-86`.
+
+**Interfaces:** marking keeps a dirty-page bitmap (page = 4096 **elements** of the paint attribute's array); on drain, for each dirty run of pages `attr.addUpdateRange(pageStart * 4096, runLength * 4096)` (units: array elements, per three r180 `BufferAttribute.addUpdateRange(start, count)`), `needsUpdate = true`; three clears ranges after upload.
+
+- [ ] **Step 1:** Gate (rich row: brush stroke upload MB per move).
+- [ ] **Step 2:** Implement; `e2e:local-fit`, `e2e:paint` PASS.
+- [ ] **Step 3: Commit** `perf(marking): upload only the touched pages`
+
+### Task 17: CSS pulse on the compositor (F17) — low priority
+
+**Files:** `src/styles.css:446-470` (`.pulse::after`, `@keyframes pulsering`).
+
+**Interfaces:** the ring is a pseudo-element with a static border/box-shadow; the keyframes animate only `transform: scale()` and `opacity`. `.busybar` unchanged (it is a transition, not a loop).
+
+- [ ] **Step 1:** Screenshots before/after (`e2e:sample` shots), compare by eye. **Step 2: Commit** `perf(css): pulse ring animates transform and opacity`
+
+### Deferred (not in this plan)
+
+- Lazy panels / plugin runtimes (F15): startup only, conflicts with plugin hooks the agent API and hints rely on. Revisit with a plugin-API design.
+- Full App memoisation / `PluginHost` / `DeviationLegend` split: after Task 12's re-measure.
+- Region lazy repaint + owner LUT (F20): ~5 ms.
+- Mobile DPR cap: Owner decision 3.
+
+## Task 18: Final verification
+
+- [ ] `npm run build` → success (record output)
+- [ ] `npm test -- --maxWorkers=8` → all pass
+- [ ] `npm run e2e:ci` → ALL PASS
+- [ ] `PERF_ASSERT=1 PERF_RUNS=5` probe: bare (prod) and rich (dev) → exit 0; before/after medians table in the PR body
+- [ ] Owner real-device check: Chrome remote debugging on Android (or Safari Web Inspector on iPhone), Performance panel, tap Surface Deviation / Map / Split / Section — no task > 100 ms
diff --git a/docs/superpowers/specs/2026-11-04-mobile-perf-findings.md b/docs/superpowers/specs/2026-11-04-mobile-perf-findings.md
new file mode 100644
index 00000000..cacf83da
--- /dev/null
+++ b/docs/superpowers/specs/2026-11-04-mobile-perf-findings.md
@@ -0,0 +1,140 @@
+# Mobile UI responsiveness — findings (spec for the fix plan)
+
+Reported: on a phone, tapping **Surface Deviation** and several other toggles
+takes a while before their UI appears.
+
+## Method
+
+`scripts/perf-probe.mjs` drives the app in Chrome emulating a Pixel-class phone
+(412×915, DPR 2.625, touch), CPU throttled 4×, on the sample scan
+(`public/samples/fridgeBracket_01-reduced.3mf`, 288k tris) with the same file as
+reference. Per tap it records: Event Timing duration (INP), long tasks, Long
+Animation Frame scripts, a CPU profile, and WebGL work (shader links, bytes
+uploaded, contexts created). Runs: `vite` dev and `vite build` + `preview`.
+GPU was a desktop RTX via ANGLE, so GPU cost is under-represented — the WebGL
+counters are the proxy for what a phone GPU pays.
+
+## Baseline (production build, 4× throttle)
+
+| Action | INP ms | GL work in the tap |
+|---|---|---|
+| Section view on | 336 | 6 shader links |
+| Tab → Reverse (plugin) | 232 | – (132 ms TopBar fold loop) |
+| Split on | 128 | 1 new context, 6.8 MB, 1 link |
+| Tab → 2D Measure | 120 | 1 new context |
+| Tab → Deviation (map in hand) | 112 | 0.6 MB |
+| Tab → Thickness (map in hand) | 104 | 0.6 MB |
+| Tab → Deviation (scan only) | 96 | 0.6 MB |
+| Map on reference | 56 (+175 ms task) | 2 links, 18.3 MB |
+| Animate on | 32 (+104 ms task) | 1.7 MB |
+| Animate off | 48 | 7.6 MB re-upload |
+| Map on/off, source switch | 56–88 | 0.6 MB |
+| Idle 3 s | – | 265 ms main-thread busy, rAF never stops |
+
+Dev build is 2–3× worse (React 19 dev owner stacks).
+
+## Findings
+
+F1 Click-path effects run before paint: zustand updates are SyncLane, a tap is a
+discrete event, so every `useEffect` in `src/app/useSceneSync.ts` and
+`src/app/useElementField.ts` runs before the browser paints.
+
+F2 Full CPU recolour per view change: `useSceneSync.ts:789` → `paintField`
+(`src/core/field/colormap.ts:103`) over every vertex on workspace/source/mapOn/
+showMap/range/maxDistance/bands/colormap changes, even when the result is
+identical to what is already in the buffer.
+
+F3 Stats + histogram recomputed per view change: `useSceneSync.ts:834`
+(`fieldHistogram`, `deviationStats`, 3 passes) then `setReadout` → second App
+render.
+
+F4 Split view and 2D viewer create a new WebGLRenderer per open
+(`CompareView` → `CompareScene` → `OrthoViewport`, `orthoViewport.ts:207`;
+`FlatViewer` mounts with its workspace, `App.tsx:1674`).
+
+F5 Section view: first toggle compiles 6 programs (clipping changes program,
+`SceneManager.ts:1514 applySlice`) and runs `closedShells` on the main thread
+(`sliceCap.ts:61 closedPartOf`).
+
+F6 Programs compile in the tap on first show: hidden nominal mesh, reference
+map mesh, see-through variants. `setSurfaceOpacity` (`surfaceModes.ts:34`) sets
+`needsUpdate` unconditionally.
+
+F7 TopBar `useLayoutEffect(() => fit.current())` without deps
+(`src/ui/TopBar.tsx:125`): up to 6 forced full-page layouts per App render.
+Top hot function across taps; 132 ms on the Reverse tab.
+
+F8 Animate off disposes the scan geometry (`SceneManager.ts:2860
+releaseDeflect`) → 7.6 MB re-upload; animate on runs `deflectionVectors` /
+`smoothInSpace` on the main thread.
+
+F9 Render loop never idles (`orthoViewport.ts` `animate`), reading
+`clientWidth/clientHeight` 4–5×/frame (`worldPerPixel`, `SceneManager` onTick)
+→ forced layout after every DOM change; `spreadLabels` reads `offsetWidth` per
+rendered frame.
+
+F10 `App.tsx` is one component with ~60 store subscriptions plus
+`useSceneSync`'s 85; nothing in `src/ui` is memoised; plugin hooks run each
+render (`App.tsx:344`).
+
+F11 Overlay rebuild disposes every material before the new ones render
+(`overlays.ts:279`) → program released and recompiled; the deviation Map
+toggle rebuilds overlays (`bareSurface`). Same in `sections.ts`, `volumeLayer.ts`.
+
+F12 Element-mode deviation computed on the main thread
+(`useElementField.ts:117 computeElementDeviation`, `suggestRange`).
+
+F13 Recovery: view toggles schedule `inspect()` 300 ms later
+(`useRecovery.ts:108`), which serialises the project.
+
+F14 Renderer at DPR up to 2 with MSAA on phones (`orthoViewport.ts:209`).
+
+F15 Main bundle 3.6 MB min / 1.16 MB gzip; plugins eager
+(`src/plugins/registry.ts:14`), all panels eager.
+
+F16 Whole-store subscriptions: `useThickness()` (`ThicknessPanel.tsx:32`),
+`useMark()` (`MarkTools.tsx:90`), `useDeviation()` (`SplitPicker.tsx:272`);
+`usePulse`/`useLadder` duplicated per instance (`src/app/useHints.ts:22`).
+
+F17 CSS: `.pulse::after` animates `box-shadow` forever (`styles.css:446`),
+`.busybar span` animates `width` (`styles.css:1828`).
+
+F18 Whole-buffer uploads for partial changes: marking stroke
+(`marking.ts:398`), volume hover (`volumeLayer.ts:65`).
+
+F19 Main-thread BVH builds on load / nominal load / rigid transform
+(`SceneManager.ts:924, 2263, 2317, 2329`) though the worker already builds one.
+
+F20 Entering deviation does a wasted `repaintFromElements` pass
+(`setHiddenRegions` runs before the field paint).
+
+## Review corrections (independent review, code-checked)
+
+- Measurement: the bare probe does **not** reproduce "takes a while" — prod
+  tab taps are 64–128 ms; only Section view (~340) and the Reverse tab
+  (~240) exceed 200 ms. The sample project had zero elements, dimensions,
+  sections or probes, and only 288k triangles, so anything that scales with
+  project content was not measured. n=1 per tap, profiler on during timing,
+  and the "UI appears" column includes CDP overhead (~120–150 ms) — use
+  INP/LoAF only. The Thickness map toggle was never measured (wrong selector).
+- F1 confirmed (react-dom flushes passive effects for SyncLane commits), but
+  effect work is a minority of the tab-tap handler; F7 is the largest part.
+- F2, F3 overstated: real mechanism, small in the bare probe.
+- F6 overstated: `needsUpdate` with an unchanged program state hits three's
+  program cache; the cost is the *first* use of each variant only.
+  `renderer.compile` never sets clipping state, so it cannot warm clipped
+  variants; and the 6 Section-view links include the `SliceCap` materials
+  created at toggle time.
+- F9 overstated for tap latency (the layout read is layout paint needs anyway);
+  real gain is idle battery. `plugins/reverse/viewer/reScene.ts` rides the
+  viewport loop; `networkLayer.ts:1045` has its own rAF.
+- F11 confirmed in mechanism, unmeasured (needs elements).
+- F13 unsupported by the data (no late long task in any run).
+- F17 overstated: `.busybar` is a width *transition*, not a loop.
+- F19: `GenerateMeshBVHWorker` transfers (neuters) the live position/index
+  buffers — unusable as is. `refit()` after a rigid move is valid and cheap.
+- Missed: the overlay effect rebuilds every element overlay and runs
+  `evaluateDimensions` on every workspace switch, then discards the result
+  outside Measure (scales with project size); every tab/map tap re-uploads the
+  0.6 MB colour buffer even when unchanged; DeviationPanel remounts per tab;
+  first show of the reference after a tab switch was not exercised.
diff --git a/scripts/perf-probe.mjs b/scripts/perf-probe.mjs
new file mode 100644
index 00000000..1de0b392
--- /dev/null
+++ b/scripts/perf-probe.mjs
@@ -0,0 +1,268 @@
+// Perf probe: drives the app in a phone-sized, CPU-throttled Chrome and times
+// every button the scenario taps — input-to-next-paint (Event Timing), time
+// until the UI it should produce appears, long tasks after, and the hottest
+// functions from a CPU profile of each tap.
+//   node scripts/perf-probe.mjs        (APP_URL, THROTTLE, CHROME, HEADLESS)
+import { writeFileSync, mkdirSync } from 'node:fs'
+import puppeteer from 'puppeteer-core'
+import { fileURLToPath } from 'node:url'
+
+const APP_URL = process.env.APP_URL ?? 'http://localhost:5391/'
+const THROTTLE = Number(process.env.THROTTLE ?? 4)
+const CHROME = process.env.CHROME ?? 'C:/Program Files/Google/Chrome/Application/chrome.exe'
+const SAMPLE = fileURLToPath(new URL('../public/samples/fridgeBracket_01-reduced.3mf', import.meta.url))
+const OUT = fileURLToPath(new URL('../e2e-out/perf/', import.meta.url))
+mkdirSync(OUT, { recursive: true })
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+
+const browser = await puppeteer.launch({
+  executablePath: CHROME,
+  headless: process.env.HEADLESS === '0' ? false : 'new',
+  args: ['--no-sandbox', '--enable-gpu', '--ignore-gpu-blocklist', '--window-size=420,930'],
+  protocolTimeout: 900_000,
+})
+const page = await browser.newPage()
+await page.emulate({
+  viewport: { width: 412, height: 915, deviceScaleFactor: 2.625, isMobile: true, hasTouch: true },
+  userAgent: 'Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Mobile Safari/537.36',
+})
+const errors = []
+page.on('pageerror', (e) => errors.push(e.message))
+page.on('console', (m) => m.type() === 'error' && errors.push(m.text()))
+await page.evaluateOnNewDocument(() => {
+  try {
+    localStorage.setItem('scanruler.askstlunits', '0')
+    localStorage.setItem('scanruler.beta', 'all')
+    localStorage.setItem('scanruler.supportask', '0')
+    localStorage.setItem('scanruler.agentdataok', '1')
+  } catch {}
+  const P = (window.__perf = { events: [], longtasks: [], loafs: [] })
+  // GPU-side work each tap sets off, which a desktop GPU hides and a phone's does not.
+  const G = (window.__gl = { link: 0, upload: 0, ctx: 0 })
+  for (const C of [WebGLRenderingContext, WebGL2RenderingContext]) {
+    const p = C.prototype
+    const link = p.linkProgram
+    p.linkProgram = function (...a) { G.link++; return link.apply(this, a) }
+    const bd = p.bufferData
+    p.bufferData = function (t, d, ...r) { G.upload += typeof d === 'number' ? d : d?.byteLength ?? 0; return bd.call(this, t, d, ...r) }
+    const bs = p.bufferSubData
+    p.bufferSubData = function (t, o, d, ...r) { G.upload += r.length >= 2 ? r[1] * (d.BYTES_PER_ELEMENT ?? 1) : d?.byteLength ?? 0; return bs.call(this, t, o, d, ...r) }
+  }
+  const gc = HTMLCanvasElement.prototype.getContext
+  HTMLCanvasElement.prototype.getContext = function (type, ...a) {
+    if (/webgl/.test(type) && !this.__counted) { this.__counted = 1; G.ctx++ }
+    return gc.call(this, type, ...a)
+  }
+  new PerformanceObserver((l) => {
+    for (const e of l.getEntries())
+      P.events.push({ name: e.name, start: e.startTime, ps: e.processingStart, pe: e.processingEnd, dur: e.duration })
+  }).observe({ type: 'event', durationThreshold: 16, buffered: true })
+  new PerformanceObserver((l) => {
+    for (const e of l.getEntries()) P.longtasks.push({ start: e.startTime, dur: e.duration })
+  }).observe({ type: 'longtask', buffered: true })
+  try {
+    new PerformanceObserver((l) => {
+      for (const e of l.getEntries())
+        P.loafs.push({
+          start: e.startTime,
+          dur: e.duration,
+          block: e.blockingDuration,
+          render: e.renderStart ? e.startTime + e.duration - e.renderStart : 0,
+          style: e.styleAndLayoutStart ? e.startTime + e.duration - e.styleAndLayoutStart : 0,
+          scripts: e.scripts.map((s) => ({ fn: s.sourceFunctionName, url: (s.sourceURL || '').replace(/^.*\/\/[^/]+/, ''), dur: s.duration, inv: s.invoker })),
+        })
+    }).observe({ type: 'long-animation-frame', buffered: true })
+  } catch {}
+})
+
+await page.goto(APP_URL, { waitUntil: 'networkidle0' })
+await page.waitForSelector('.panel, .startpane', { timeout: 120_000 })
+const cdp = await page.createCDPSession()
+await cdp.send('Profiler.enable')
+await cdp.send('Profiler.setSamplingInterval', { interval: 250 })
+const gl = await page.evaluate(() => {
+  const g = document.createElement('canvas').getContext('webgl2')
+  const ext = g?.getExtension('WEBGL_debug_renderer_info')
+  return ext ? g.getParameter(ext.UNMASKED_RENDERER_WEBGL) : 'n/a'
+})
+console.log('GPU:', gl, '| CPU throttle', THROTTLE + 'x', '| DPR', await page.evaluate(() => devicePixelRatio))
+await cdp.send('Emulation.setCPUThrottlingRate', { rate: THROTTLE })
+
+/** Self time per function from a CPU profile, the top `n`. */
+function hot(profile, n = 8) {
+  const byId = new Map(profile.nodes.map((nd) => [nd.id, nd]))
+  const self = new Map()
+  const dts = profile.timeDeltas
+  for (let i = 0; i < profile.samples.length; i++) {
+    const nd = byId.get(profile.samples[i])
+    const cf = nd.callFrame
+    if (cf.functionName === '(idle)' || cf.functionName === '(program)') continue
+    const key = `${cf.functionName || '(anon)'} ${cf.url.replace(/^.*\/\/[^/]+/, '').replace(/\?.*$/, '')}:${cf.lineNumber + 1}`
+    self.set(key, (self.get(key) ?? 0) + (dts[i] ?? 0) / 1000)
+  }
+  return [...self.entries()].sort((a, b) => b[1] - a[1]).slice(0, n).map(([k, v]) => `${v.toFixed(0).padStart(5)}ms ${k}`)
+}
+
+const results = []
+/** Tap `sel`, then measure. `appear`: selector (or fn source) whose arrival is
+ *  the UI the tap should produce. */
+async function measure(label, sel, { appear, settle = 2500, timeout = 60_000, optional = false, action } = {}) {
+  if (!action) {
+    const el = await page.$(sel)
+    if (!el) {
+      if (!optional) console.log(`SKIP ${label}: ${sel} not found`)
+      return
+    }
+    // A control off-screen in a scrolling panel is scrolled to first, as a thumb would.
+    await el.evaluate((e) => e.scrollIntoView({ block: 'center' }))
+    await sleep(300)
+  }
+  const t0 = await page.evaluate((appear) => {
+    window.__perf.appear = null
+    if (appear) {
+      const test = () => document.querySelector(appear)
+      const done = () => {
+        const t = performance.now()
+        requestAnimationFrame(() => setTimeout(() => (window.__perf.appear = { dom: t, paint: performance.now() })))
+      }
+      if (test()) window.__perf.appear = { already: true }
+      else {
+        const mo = new MutationObserver(() => {
+          if (test()) { mo.disconnect(); done() }
+        })
+        mo.observe(document.body, { childList: true, subtree: true, attributes: true })
+      }
+    }
+    window.__gl0 = { ...window.__gl }
+    return performance.now()
+  }, appear ?? null)
+  await cdp.send('Profiler.start')
+  if (action) await action()
+  else await page.tap(sel)
+  const wall0 = Date.now()
+  if (appear) {
+    await page.waitForFunction(() => window.__perf.appear, { timeout, polling: 50 }).catch(() => {})
+  }
+  await sleep(settle)
+  const { profile } = await cdp.send('Profiler.stop')
+  const r = await page.evaluate((t0) => {
+    const P = window.__perf
+    const ev = P.events.filter((e) => e.start >= t0 - 5 && ['pointerdown', 'pointerup', 'click', 'touchstart', 'touchend', 'mousedown', 'mouseup'].includes(e.name))
+    const lt = P.longtasks.filter((e) => e.start >= t0)
+    const lo = P.loafs.filter((e) => e.start >= t0)
+    const scripts = {}
+    for (const f of lo) for (const s of f.scripts) {
+      const k = `${s.inv} → ${s.fn || '?'} ${s.url}`
+      scripts[k] = (scripts[k] ?? 0) + s.dur
+    }
+    const G = window.__gl, G0 = window.__gl0
+    return {
+      gl: `GL: ${G.link - G0.link} shader links, ${((G.upload - G0.upload) / 1048576).toFixed(1)} MB uploaded, ${G.ctx - G0.ctx} new contexts`,
+      inp: ev.length ? Math.max(...ev.map((e) => e.dur)) : 0,
+      handler: ev.length ? Math.max(...ev.map((e) => e.pe - e.ps)) : 0,
+      appear: P.appear ? (P.appear.already ? 'already' : Math.round(P.appear.paint - t0)) : null,
+      longTotal: Math.round(lt.reduce((s, e) => s + e.dur, 0)),
+      longMax: Math.round(Math.max(0, ...lt.map((e) => e.dur))),
+      longN: lt.length,
+      loafRender: Math.round(lo.reduce((s, e) => s + e.render, 0)),
+      loafStyle: Math.round(lo.reduce((s, e) => s + e.style, 0)),
+      scripts: Object.entries(scripts).sort((a, b) => b[1] - a[1]).slice(0, 4).map(([k, v]) => `${Math.round(v)}ms ${k}`),
+    }
+  }, t0)
+  r.label = label
+  r.hot = hot(profile)
+  results.push(r)
+  console.log(
+    `\n## ${label}\n  INP ${Math.round(r.inp)}ms (handler ${Math.round(r.handler)}ms) | UI appears ${r.appear ?? '-'}ms | long tasks ${r.longN} total ${r.longTotal}ms max ${r.longMax}ms | LoAF render ${r.loafRender}ms style/layout ${r.loafStyle}ms`,
+  )
+  console.log('  ' + r.gl)
+  for (const s of r.scripts) console.log('   loaf:', s)
+  for (const h of r.hot) console.log('   cpu:', h)
+  void wall0
+  return r
+}
+
+const shot = (n) => page.screenshot({ path: OUT + n + '.png' })
+
+// ---- start: the sample scan ---------------------------------------------------
+await shot('00-start')
+await measure('Close support card', '[data-test=support-card] .sc-x', { settle: 800, optional: true })
+await measure('Open sample scan (288k tris)', null, {
+  action: async () => (await page.$('[data-test=start-scan] input[type=file], input[type=file]')).uploadFile(SAMPLE),
+  appear: '.file-info', settle: 4000, timeout: 300_000,
+})
+await shot('01-loaded')
+
+// ---- workspace tabs with only a scan -------------------------------------------
+const tabs = await page.$$eval('[data-test^=workspace-]', (els) => els.map((e) => e.dataset.test))
+console.log('\ntabs:', tabs.join(', '))
+await measure('Tab → Surface Deviation (scan only)', '[data-test=workspace-deviation]', { appear: '[data-test=workspace-deviation][aria-selected=true]' })
+await shot('02-deviation')
+await measure('Tab → Wall Thickness', '[data-test=workspace-thickness]', { appear: '[data-test=measure-thickness]' })
+await measure('Thickness: Measure', '[data-test=measure-thickness]', { appear: '[data-test=thickness-legend]', settle: 3000, timeout: 300_000 })
+await shot('03-thickness')
+await measure('Thickness: map off', '[data-test=toggle-colormap]', { settle: 1500 })
+await measure('Thickness: map on', '[data-test=toggle-colormap]', { settle: 1500 })
+await measure('Tab → 2D Measure', '[data-test=workspace-flat]', { appear: '[data-test=workspace-flat][aria-selected=true]' })
+for (const t of tabs.filter((t) => !['workspace-elements', 'workspace-deviation', 'workspace-thickness', 'workspace-flat'].includes(t)))
+  await measure(`Tab → ${t} (plugin)`, `[data-test=${t}]`, { appear: `[data-test=${t}][aria-selected=true]`, settle: 3000 })
+await measure('Tab → 3D Measure', '[data-test=workspace-elements]', { appear: '[data-test=workspace-elements][aria-selected=true]' })
+await shot('04-measure')
+
+// ---- deviation against the same part as reference --------------------------------
+await measure('Tab → Surface Deviation (again)', '[data-test=workspace-deviation]', { appear: '[data-test=workspace-deviation][aria-selected=true]' })
+await measure('Deviation: load reference', null, {
+  action: async () => (await page.$('[data-test=slot-reference] input[type=file]')).uploadFile(SAMPLE),
+  appear: '[data-test=align-auto]:not([disabled])', settle: 2000, timeout: 300_000,
+})
+await measure('Deviation: Auto best fit → map', '[data-test=align-auto]', { appear: '[data-test=deviation-legend]', settle: 4000, timeout: 300_000 })
+await shot('05-deviation-map')
+await measure('Deviation: map off', '[data-test=toggle-colormap]', { settle: 1500 })
+await measure('Deviation: map on', '[data-test=toggle-colormap]', { settle: 1500 })
+await measure('Deviation: split on', '[data-test=toggle-split]', { settle: 3000 })
+await shot('06-split')
+await measure('Deviation: split off', '[data-test=toggle-split]', { settle: 2000 })
+await measure('Deviation: map on reference', '[data-test=toggle-map-on-reference]', { settle: 4000, timeout: 300_000 })
+await measure('Deviation: map back on scan', '[data-test=toggle-map-on-reference]', { settle: 2000 })
+await measure('Deviation: histogram', '[data-test=deviation-histogram-toggle], [data-test$=histogram-toggle]', { settle: 1500, optional: true })
+await measure('Deviation: animate on', '[data-test=animate-deformation]', { settle: 2500 })
+await measure('Deviation: animate off', '[data-test=animate-deformation]', { settle: 1500 })
+await measure('Deviation: volume measure', '[data-test=volume-measure]', { appear: '[data-test=volume-show]', settle: 3000, timeout: 300_000 })
+await measure('Deviation: volume show', '[data-test=volume-show]', { settle: 2000 })
+await measure('Deviation: source → element', '[data-test=source-element]', { settle: 2000 })
+await measure('Deviation: source → reference', '[data-test=source-reference]', { settle: 2000 })
+await measure('Deviation: section view', '[data-test=toggle-section-view]', { settle: 2000 })
+await measure('Deviation: section view off', '[data-test=toggle-section-view]', { settle: 1500 })
+
+// ---- switching with maps in hand ---------------------------------------------------
+await measure('Tab → 3D Measure (maps in hand)', '[data-test=workspace-elements]', { appear: '[data-test=workspace-elements][aria-selected=true]' })
+await measure('Tab → Surface Deviation (map in hand)', '[data-test=workspace-deviation]', { appear: '[data-test=deviation-legend]' })
+await measure('Tab → Wall Thickness (map in hand)', '[data-test=workspace-thickness]', { appear: '[data-test=thickness-legend]' })
+await measure('Tab → Surface Deviation (from thickness)', '[data-test=workspace-deviation]', { appear: '[data-test=deviation-legend]' })
+await measure('Settings open', '[data-test=open-settings]', { appear: '[data-test=settings-modal]', settle: 1500 })
+await measure('Settings close', '[data-test=settings-close]', { settle: 1000 })
+await shot('07-end')
+
+// ---- idle cost: what the page burns doing nothing ---------------------------------
+const idle = await page.evaluate(async () => {
+  const t0 = performance.now()
+  let frames = 0
+  await new Promise((res) => {
+    const f = () => (performance.now() - t0 < 3000 ? (frames++, requestAnimationFrame(f)) : res())
+    requestAnimationFrame(f)
+  })
+  return frames
+})
+await cdp.send('Profiler.start')
+await sleep(3000)
+const idleProfile = (await cdp.send('Profiler.stop')).profile
+const idleBusy = idleProfile.timeDeltas.reduce((s, d, i) => {
+  const nd = idleProfile.nodes.find((n) => n.id === idleProfile.samples[i])
+  return nd.callFrame.functionName === '(idle)' ? s : s + d
+}, 0) / 1000
+console.log(`\n## Idle (3 s, nothing touched): ${idle} rAF frames, main thread busy ${idleBusy.toFixed(0)}ms`)
+for (const h of hot(idleProfile, 6)) console.log('   cpu:', h)
+
+writeFileSync(OUT + 'results.json', JSON.stringify(results, null, 2))
+console.log('\nerrors:', errors.length ? errors.slice(0, 5) : 'none')
+await browser.close()

From 3216bb356857dd21b102077ec946c33316072e5e Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Wed, 4 Nov 2026 13:31:02 +0000
Subject: [PATCH 02/38] =?UTF-8?q?perf:=20probe=20v2=20=E2=80=94=20medians,?=
 =?UTF-8?q?=20rich=20project=20scenario,=20GL=20budgets?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PERF_RUNS repeats each tap (toggles alternate, tabs go round) and reports the
median with the profiler off plus one profiled run for the hot list; the UI
appears column is gone. Rows now carry budgets (links, uploadMB, contexts,
longMs, inpMs) checked under PERF_ASSERT=1. PERF_SCENARIO=rich fits elements,
dimensions, a section and probes through the in-page command registry on the
dev server. Production hot lists are named through the build's source maps.
New rows: thickness view-bar key, bands, histograms, range slider, tolerance,
first show of the reference, element target, brush stroke. The spec's baseline
section records the v2 medians.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../specs/2026-11-04-mobile-perf-findings.md  | 115 +++
 scripts/perf-probe.mjs                        | 745 +++++++++++++++---
 2 files changed, 744 insertions(+), 116 deletions(-)

diff --git a/docs/superpowers/specs/2026-11-04-mobile-perf-findings.md b/docs/superpowers/specs/2026-11-04-mobile-perf-findings.md
index cacf83da..548d1764 100644
--- a/docs/superpowers/specs/2026-11-04-mobile-perf-findings.md
+++ b/docs/superpowers/specs/2026-11-04-mobile-perf-findings.md
@@ -16,6 +16,8 @@ counters are the proxy for what a phone GPU pays.
 
 ## Baseline (production build, 4× throttle)
 
+### v1 — one run, the first (cold) tap of each row
+
 | Action | INP ms | GL work in the tap |
 |---|---|---|
 | Section view on | 336 | 6 shader links |
@@ -33,6 +35,119 @@ counters are the proxy for what a phone GPU pays.
 
 Dev build is 2–3× worse (React 19 dev owner stacks).
 
+### v2 — probe v2: median of 5 taps, profiler off
+
+`scripts/perf-probe.mjs`, full output with hot lists and budget results in
+`e2e-out/perf-baseline-v2.txt` (production bare, dev rich, dev bare). Scan: the
+288k-triangle sample — no ≥ 1M-triangle scan was at hand (`SCAN=` overrides).
+The production hot lists are named through `vite build --sourcemap`. "INP first
+tap" is the cold tap of the five (programs compiled, buffers created, caches
+empty); Event Timing is 8 ms-grained and reports nothing under 16 ms, so 0 and
+16 mean "under the floor". The machine is shared: two identical passes differed
+by up to ~1.7× (pass A of the same probe: Tab → Deviation scan only 64, Tab → 3D
+Measure 64, Tab → Deviation map in hand 72, source → reference 72, section view
+on 64), so compare before and after in one sitting.
+
+What the medians say: the warm taps are cheap — a tab is 72–128 ms, most
+toggles 24–80 ms — and what v1 measured was mostly the cold tap: section view
+is 104 ms warm but 416 ms on its first tap (6 links), Tab → Reverse 96 warm but
+232 first, Tab → 2D Measure 88 / 112 and Split on 104 / 144, each making a
+context on every open (the budget `contexts: 0` counts taps after the first). The
+GL work is the same on every tap: 0.6 MB of unchanged colours on every tab or map
+tap, 7.6 MB when the animation stops, 2 links and 18.3 MB on the first map on the
+reference. Idle 3 s: 437 animation-frame callbacks, 536 ms busy.
+
+Production, bare scenario:
+
+| Action | INP median | INP first tap | long task max | GL work (worst tap) |
+|---|---|---|---|---|
+| Open sample scan (single run) | – | – | 324 ms | 1 links, 7.6 MB |
+| Tab → Surface Deviation (scan only) | 72 | 64 | 0 ms | 0.6 MB |
+| Tab → Wall Thickness | 72 | 72 | 0 ms | 0.6 MB |
+| Tab → 2D Measure | 88 | 112 | 55 ms | 0.6 MB, 1 new ctx |
+| Tab → workspace-reverse (plugin) | 96 | 232 | 0 ms | 0.6 MB |
+| Tab → workspace-mesh (plugin) | 72 | 80 | 0 ms | 0.6 MB |
+| Tab → 3D Measure | 80 | 72 | 0 ms | 0.6 MB |
+| Thickness: scan key off (view bar) | 40 | 32 | 0 ms | – |
+| Thickness: scan key on (view bar) | 40 | 32 | 0 ms | – |
+| Thickness: bands on (5 bands) | 64 | 88 | 50 ms | 0.6 MB |
+| Thickness: bands off (continuous) | 64 | 64 | 51 ms | 0.6 MB |
+| Thickness: histogram off | 40 | 48 | 0 ms | – |
+| Thickness: histogram on | 40 | 40 | 0 ms | – |
+| Tab → 3D Measure (reference loaded) | 80 | 80 | 0 ms | 0.6 MB |
+| Tab → Surface Deviation (first show of the reference) | 72 | 72 | 0 ms | 0.6 MB |
+| Deviation: map off | 48 | 56 | 0 ms | 0.6 MB |
+| Deviation: map on | 64 | 80 | 0 ms | 0.6 MB |
+| Deviation: split on | 104 | 144 | 51 ms | 1 links, 6.8 MB, 1 new ctx |
+| Deviation: split off | 48 | 56 | 0 ms | – |
+| Deviation: map on reference | 120 | 56 | 95 ms | 2 links, 18.3 MB |
+| Deviation: map back on scan | 80 | 64 | 56 ms | 0.6 MB |
+| Deviation: histogram off | 40 | 48 | 0 ms | – |
+| Deviation: histogram on | 40 | 40 | 0 ms | – |
+| Deviation: range slider step 1 | 56 | 16 | 0 ms | 0.6 MB |
+| Deviation: range slider step 2 (back) | 64 | 64 | 52 ms | 0.6 MB |
+| Deviation: tolerance change (0.05) | 56 | 64 | 50 ms | – |
+| Deviation: tolerance change (0.08) | 64 | 64 | 0 ms | – |
+| Deviation: animate on | 56 | 56 | 165 ms | 1.7 MB |
+| Deviation: animate off | 72 | 48 | 0 ms | 7.6 MB |
+| Deviation: volume show on | 48 | 48 | 0 ms | – |
+| Deviation: volume show off | 48 | 48 | 0 ms | – |
+| Deviation: source → element | 56 | 72 | 0 ms | 0.6 MB |
+| Deviation: source → reference | 120 | 88 | 80 ms | 0.6 MB |
+| Deviation: section view on | 104 | 416 | 0 ms | 6 links |
+| Deviation: section view off | 56 | 56 | 0 ms | – |
+| Tab → 3D Measure (maps in hand) | 88 | 112 | 56 ms | 0.6 MB |
+| Tab → Surface Deviation (map in hand) | 120 | 120 | 80 ms | 0.6 MB |
+| Tab → Wall Thickness (map in hand) | 128 | 136 | 98 ms | 0.6 MB |
+| Tab → Surface Deviation (from thickness) | 112 | 96 | 77 ms | 0.6 MB |
+| Settings open | 64 | 104 | 0 ms | – |
+| Settings close | 24 | 32 | 0 ms | – |
+
+Rich scenario (dev server; the GL counters are the same as production, INP is
+2–3× production): the sample plus 7 elements (3 planes, 3 cylinders, 1 sphere
+that the sample does not really have — it has no sphere, the fit took the best
+R2–R40 candidate), 4 dimensions, 1 section and, in the deviation workspace, 5
+pinned probes. The rows the gated tasks name:
+
+| Action (dev server, rich project) | INP median | INP first tap | long task max | late long task (> 250 ms after the tap) | GL work (worst tap) |
+|---|---|---|---|---|---|
+| Tab → Surface Deviation (scan only) | 176 | 248 | 141 ms | 81 ms | 0.6 MB |
+| Tab → 3D Measure | 336 | 432 | 228 ms | 130 ms | 5 links, 0.6 MB |
+| Tab → workspace-reverse (plugin) | 312 | 544 | 202 ms | 106 ms | 5 links, 0.6 MB |
+| Tab → 3D Measure (maps in hand) | 368 | 280 | 258 ms | 92 ms | 5 links, 0.6 MB |
+| Tab → Surface Deviation (map in hand) | 376 | 304 | 303 ms | 0 ms | 1 links, 0.6 MB |
+| Tab → Wall Thickness (map in hand) | 336 | 424 | 293 ms | 81 ms | 0.6 MB |
+| Deviation: map off | 176 | 216 | 154 ms | 117 ms | 0.6 MB |
+| Deviation: map on | 184 | 184 | 178 ms | 178 ms | 0.6 MB |
+| Deviation: range slider step 1 | 240 | 32 | 225 ms | 84 ms | 0.6 MB |
+| Deviation: tolerance change (0.05) | 248 | 264 | 233 ms | 93 ms | – |
+| Deviation: source → element | 136 | 136 | 89 ms | 0 ms | 2 links, 0.6 MB |
+| Deviation: change element target (A) | – (page-driven select) | 0 | 331 ms | 72 ms | 2 links, 0.6 MB |
+| Deviation: change element target (B) | – (page-driven select) | 0 | 320 ms | 75 ms | 2 links, 0.6 MB |
+| Deviation: element facing limit on | 312 | 312 | 285 ms | 64 ms | 0.6 MB |
+| Deviation: element facing limit off | 264 | 264 | 237 ms | 74 ms | 0.6 MB |
+| Deviation: section view on | 128 | 368 | 86 ms | 0 ms | 6 links |
+| Brush stroke (20 moves, rich) | 152 | 152 | 130 ms | 0 ms | 3.1 MB |
+
+- **Overlay rebuild on tab switch** (task 7): with the project, every switch
+  into Measure (and the one to the Reverse tab) makes **5 shader links** (bare: 0) and the tap is 336 ms
+  median against 80 in production and 128 on the dev server without the project. `updateOverlays` is 4 ms
+  inclusive in the profiled tap, `evaluateDimensions` under 1 ms (4 dimensions) —
+  the compile, not the evaluation, is what the project adds at this size.
+- **`evaluateDimensions`**: under 1 ms inclusive on every row — nothing to save
+  by skipping it at this project size.
+- **Recovery long task after a toggle** (task 13): a long task starts more than
+  250 ms after the tap on map off / map on — 117 / 178 ms median in the rich
+  scenario (0 in production bare, 0–67 ms in dev bare); the 300 ms `inspect()` timer
+  is the candidate, the profile does not isolate it.
+- **Element-map recompute** (task 11): changing the element target is a
+  331 / 320 ms long task with 2 links, the facing limit a 312 / 264 ms tap;
+  `computeElementDeviation` 19 ms and `suggestRange` 5–10 ms inclusive in the
+  profiled tap. The select is set by the page (a native picker cannot be
+  driven), so the target rows have no INP.
+- **Brush stroke upload** (task 16): 3.1 MB uploaded per 20-move stroke (706
+  points marked), 152 ms median tap.
+
 ## Findings
 
 F1 Click-path effects run before paint: zustand updates are SyncLane, a tap is a
diff --git a/scripts/perf-probe.mjs b/scripts/perf-probe.mjs
index 1de0b392..6af8ee03 100644
--- a/scripts/perf-probe.mjs
+++ b/scripts/perf-probe.mjs
@@ -1,25 +1,71 @@
-// Perf probe: drives the app in a phone-sized, CPU-throttled Chrome and times
-// every button the scenario taps — input-to-next-paint (Event Timing), time
-// until the UI it should produce appears, long tasks after, and the hottest
-// functions from a CPU profile of each tap.
-//   node scripts/perf-probe.mjs        (APP_URL, THROTTLE, CHROME, HEADLESS)
-import { writeFileSync, mkdirSync } from 'node:fs'
-import puppeteer from 'puppeteer-core'
+// SPDX-License-Identifier: AGPL-3.0-only
+// Perf probe v2: drives the app in a phone-sized, CPU-throttled Chrome and times
+// every button the scenario taps — input-to-next-paint (Event Timing), long
+// tasks after, GPU-side work (shader links, bytes uploaded, contexts created)
+// and the hottest functions from a CPU profile of one extra, profiled tap.
+//
+//   node scripts/perf-probe.mjs
+//
+// Env:
+//   APP_URL        the app (default http://localhost:5391/, the dev server)
+//   THROTTLE       CPU slow-down, default 4
+//   PERF_RUNS      repeats per tap, default 5. Toggle rows alternate on/off, tab
+//                  rows go round the tab list; the median is reported. The
+//                  profiler is OFF for these and one extra tap per row is
+//                  profiled for the hot list. Rows that cannot repeat (a file
+//                  load, a measurement) run once, profiled, and say n=1.
+//   PERF_SCENARIO  `bare` (default) or `rich`: after the scan loads, fit 6
+//                  elements, add 4 dimensions and a section, and pin 5
+//                  deviation probes later, so what scales with project content
+//                  is on the stage. Dev server only (it drives the in-page
+//                  command registry through `/src/commands/registry.ts`).
+//   PERF_ASSERT    1: exit 1 with a `BUDGET FAIL: <label>: <what>` line per
+//                  breach. The lines print either way; `inpMs` budgets are only
+//                  checked when PERF_RUNS >= 5.
+//   SCAN           a scan to use instead of the sample (use >= 1M triangles when
+//                  one is at hand); its size is printed.
+//   DIST           where `vite build --sourcemap` wrote the production build
+//                  (default <repo>/dist/): a production hot list is named by
+//                  mapping each call frame through that build's source maps.
+//   CHROME, HEADLESS=0 as before.
+//
+// Production target:  npx vite build --sourcemap && npx vite preview --port 5392 --strictPort
+//                     APP_URL=http://localhost:5392/ node scripts/perf-probe.mjs
+// Rich scenario:      npx vite --port 5391 --strictPort
+//                     PERF_SCENARIO=rich node scripts/perf-probe.mjs
+// GL counters are the same in dev and prod, so the GL budgets of the rich
+// scenario are asserted on dev; INP budgets are the production target's.
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
 import { fileURLToPath } from 'node:url'
+import puppeteer from 'puppeteer-core'
+
+// Vite brings source-map-js along; it is not a dependency of ours, so it is
+// reached through node_modules rather than package.json.
+const { SourceMapConsumer } = createRequire(import.meta.url)('source-map-js')
 
 const APP_URL = process.env.APP_URL ?? 'http://localhost:5391/'
 const THROTTLE = Number(process.env.THROTTLE ?? 4)
+const RUNS = Math.max(1, Number(process.env.PERF_RUNS ?? 5))
+const SCENARIO = process.env.PERF_SCENARIO === 'rich' ? 'rich' : 'bare'
+const ASSERT = process.env.PERF_ASSERT === '1'
 const CHROME = process.env.CHROME ?? 'C:/Program Files/Google/Chrome/Application/chrome.exe'
-const SAMPLE = fileURLToPath(new URL('../public/samples/fridgeBracket_01-reduced.3mf', import.meta.url))
+const SAMPLE = process.env.SCAN ?? fileURLToPath(new URL('../public/samples/fridgeBracket_01-reduced.3mf', import.meta.url))
+const DIST = process.env.DIST ?? fileURLToPath(new URL('../dist/', import.meta.url))
 const OUT = fileURLToPath(new URL('../e2e-out/perf/', import.meta.url))
 mkdirSync(OUT, { recursive: true })
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+const rich = SCENARIO === 'rich'
+
+/** The row's own budget for this scenario: a number is the production bare
+ *  target's, `{ bare, rich }` names both. */
+const inpBudget = (b) => (typeof b === 'number' ? (rich || isDev ? undefined : b) : rich ? b?.rich : isDev ? undefined : b?.bare)
 
 const browser = await puppeteer.launch({
   executablePath: CHROME,
   headless: process.env.HEADLESS === '0' ? false : 'new',
   args: ['--no-sandbox', '--enable-gpu', '--ignore-gpu-blocklist', '--window-size=420,930'],
-  protocolTimeout: 900_000,
+  protocolTimeout: 1_800_000,
 })
 const page = await browser.newPage()
 await page.emulate({
@@ -38,7 +84,7 @@ await page.evaluateOnNewDocument(() => {
   } catch {}
   const P = (window.__perf = { events: [], longtasks: [], loafs: [] })
   // GPU-side work each tap sets off, which a desktop GPU hides and a phone's does not.
-  const G = (window.__gl = { link: 0, upload: 0, ctx: 0 })
+  const G = (window.__gl = { link: 0, upload: 0, ctx: 0, raf: 0 })
   for (const C of [WebGLRenderingContext, WebGL2RenderingContext]) {
     const p = C.prototype
     const link = p.linkProgram
@@ -53,6 +99,9 @@ await page.evaluateOnNewDocument(() => {
     if (/webgl/.test(type) && !this.__counted) { this.__counted = 1; G.ctx++ }
     return gc.call(this, type, ...a)
   }
+  // Frame callbacks that actually ran: what an idle page should not be doing.
+  const raf = window.requestAnimationFrame.bind(window)
+  window.requestAnimationFrame = (cb) => raf((t) => { G.raf++; cb(t) })
   new PerformanceObserver((l) => {
     for (const e of l.getEntries())
       P.events.push({ name: e.name, start: e.startTime, ps: e.processingStart, pe: e.processingEnd, dur: e.duration })
@@ -77,6 +126,12 @@ await page.evaluateOnNewDocument(() => {
 
 await page.goto(APP_URL, { waitUntil: 'networkidle0' })
 await page.waitForSelector('.panel, .startpane', { timeout: 120_000 })
+const isDev = await page.evaluate(() => fetch('/@vite/client').then((r) => r.text()).then((t) => /import.meta.hot|createHotContext/.test(t), () => false))
+if (rich && !isDev) {
+  console.log('PERF_SCENARIO=rich needs the dev server (it imports /src/commands/registry.ts).')
+  await browser.close()
+  process.exit(2)
+}
 const cdp = await page.createCDPSession()
 await cdp.send('Profiler.enable')
 await cdp.send('Profiler.setSamplingInterval', { interval: 250 })
@@ -86,70 +141,157 @@ const gl = await page.evaluate(() => {
   return ext ? g.getParameter(ext.UNMASKED_RENDERER_WEBGL) : 'n/a'
 })
 console.log('GPU:', gl, '| CPU throttle', THROTTLE + 'x', '| DPR', await page.evaluate(() => devicePixelRatio))
+console.log(`target: ${isDev ? 'dev server' : 'production build'} ${APP_URL} | scenario: ${SCENARIO} | PERF_RUNS=${RUNS}${ASSERT ? ' | PERF_ASSERT=1' : ''}`)
+console.log(`scan: ${SAMPLE.replace(/^.*[\\/]/, '')}, ${(statSync(SAMPLE).size / 1048576).toFixed(1)} MB on disk`)
 await cdp.send('Emulation.setCPUThrottlingRate', { rate: THROTTLE })
 
+// ---- naming functions: dev has real names, a production build gets them from its source map ----
+const consumers = new Map()
+/** The source map of a built file, or null (dev, a worker, a file with none). */
+function consumerFor(path) {
+  if (!consumers.has(path)) {
+    const file = DIST + path.replace(/^\//, '') + '.map'
+    consumers.set(path, existsSync(file) ? new SourceMapConsumer(JSON.parse(readFileSync(file, 'utf8'))) : null)
+  }
+  return consumers.get(path)
+}
+const sourceLines = new Map()
+/** The name of the function that starts at an original position, read off the
+ *  source text there: `name(`, `function name(`, or `name = () =>` / `name: () =>`. */
+function nameAt(c, at) {
+  let lines = sourceLines.get(at.source)
+  if (!lines) {
+    lines = (c.sourceContentFor(at.source, true) ?? '').split('\n')
+    sourceLines.set(at.source, lines)
+  }
+  const text = lines[at.line - 1] ?? ''
+  const after = text.slice(at.column)
+  const own = after.match(/^(?:async\s+)?(?:function\s*\*?\s*)?([A-Za-z_$][\w$]*)\s*(?:<[^>(]*>)?\(/)
+  if (own && !/^(?:if|for|while|switch|catch|function|return)$/.test(own[1])) return own[1]
+  const bound = text.slice(0, at.column).match(/([A-Za-z_$][\w$.]*)\s*[:=]\s*(?:async\s*)?$/)
+  return bound ? bound[1] : null
+}
+const named = new Map()
+/** `{ name, src, line }` for a profile call frame. */
+function nameOf(cf) {
+  const path = cf.url.replace(/^.*\/\/[^/]+/, '').replace(/\?.*$/, '')
+  const key = `${path}|${cf.lineNumber}|${cf.columnNumber}|${cf.functionName}`
+  let r = named.get(key)
+  if (r) return r
+  r = { name: cf.functionName || '(anon)', src: path, line: cf.lineNumber + 1 }
+  const c = path.startsWith('/assets/') ? consumerFor(path) : null
+  if (c) {
+    const at = c.originalPositionFor({ line: cf.lineNumber + 1, column: cf.columnNumber })
+    if (at.source) {
+      // The mapping at a function's start names it only when the minifier renamed it; a method or a
+      // property keeps its own name, so that is read off the original source at that spot.
+      const name = at.name ?? nameAt(c, at)
+      r = { name: name ?? `${cf.functionName || '(anon)'}~`, src: at.source.replace(/^(\.\.\/)+/, '').replace(/^.*?(node_modules\/)/, '$1'), line: at.line }
+    }
+  }
+  named.set(key, r)
+  return r
+}
+const where = (n) => `${n.name} ${n.src}:${n.line}`
+
 /** Self time per function from a CPU profile, the top `n`. */
 function hot(profile, n = 8) {
   const byId = new Map(profile.nodes.map((nd) => [nd.id, nd]))
   const self = new Map()
   const dts = profile.timeDeltas
   for (let i = 0; i < profile.samples.length; i++) {
-    const nd = byId.get(profile.samples[i])
-    const cf = nd.callFrame
+    const cf = byId.get(profile.samples[i]).callFrame
     if (cf.functionName === '(idle)' || cf.functionName === '(program)') continue
-    const key = `${cf.functionName || '(anon)'} ${cf.url.replace(/^.*\/\/[^/]+/, '').replace(/\?.*$/, '')}:${cf.lineNumber + 1}`
+    const key = where(nameOf(cf))
     self.set(key, (self.get(key) ?? 0) + (dts[i] ?? 0) / 1000)
   }
   return [...self.entries()].sort((a, b) => b[1] - a[1]).slice(0, n).map(([k, v]) => `${v.toFixed(0).padStart(5)}ms ${k}`)
 }
 
-const results = []
-/** Tap `sel`, then measure. `appear`: selector (or fn source) whose arrival is
- *  the UI the tap should produce. */
-async function measure(label, sel, { appear, settle = 2500, timeout = 60_000, optional = false, action } = {}) {
-  if (!action) {
-    const el = await page.$(sel)
-    if (!el) {
-      if (!optional) console.log(`SKIP ${label}: ${sel} not found`)
-      return
+/** Functions the fix plan's gated tasks name, as inclusive time (the function
+ *  and everything it called) from one profile, outermost call only. */
+const WATCH = [
+  'evaluateDimensions', 'updateOverlays', 'computeElementDeviation', 'suggestRange', 'paintField',
+  'fieldHistogram', 'deviationStats', 'repaintFromElements', 'setFieldColors', 'inspect',
+  'closedPartOf', 'computeBoundsTree', 'deflectionVectors', 'smoothInSpace', 'releaseDeflect',
+]
+function watched(profile) {
+  const byId = new Map(profile.nodes.map((nd) => [nd.id, nd]))
+  const selfMs = new Map()
+  profile.samples.forEach((id, i) => selfMs.set(id, (selfMs.get(id) ?? 0) + (profile.timeDeltas[i] ?? 0) / 1000))
+  const parent = new Map()
+  for (const nd of profile.nodes) for (const c of nd.children ?? []) parent.set(c, nd.id)
+  const total = new Map()
+  const inclusive = (id) => {
+    if (total.has(id)) return total.get(id)
+    let t = selfMs.get(id) ?? 0
+    for (const c of byId.get(id).children ?? []) t += inclusive(c)
+    total.set(id, t)
+    return t
+  }
+  const out = new Map()
+  for (const nd of profile.nodes) {
+    const nm = nameOf(nd.callFrame).name.replace(/~$/, '')
+    if (!WATCH.includes(nm)) continue
+    // Only the outermost call: a function reached again through itself is counted once.
+    let p = parent.get(nd.id)
+    let nested = false
+    while (p !== undefined && !nested) {
+      nested = nameOf(byId.get(p).callFrame).name.replace(/~$/, '') === nm
+      p = parent.get(p)
     }
+    if (!nested) out.set(nm, (out.get(nm) ?? 0) + inclusive(nd.id))
+  }
+  return [...out.entries()].sort((a, b) => b[1] - a[1]).map(([k, v]) => `${v >= 1 ? v.toFixed(0) : '<1'}ms ${k}`)
+}
+
+// ---- taps ---------------------------------------------------------------------
+const median = (xs) => {
+  if (!xs.length) return 0
+  const s = [...xs].sort((a, b) => a - b)
+  const m = s.length >> 1
+  return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2
+}
+const INPUT_EVENTS = ['pointerdown', 'pointerup', 'click', 'touchstart', 'touchend', 'mousedown', 'mouseup', 'keydown', 'keyup', 'input', 'change']
+
+/** The control a label names, for the number fields and selects that carry no
+ *  test id. */
+const labelled = (text, tag) =>
+  page.evaluateHandle(
+    (text, tag) => [...document.querySelectorAll('label.field')].find((l) => l.querySelector('span')?.textContent.trim().startsWith(text))?.querySelector(tag) ?? null,
+    text,
+    tag,
+  )
+
+/** One tap (or action) of a row, then its numbers. `profiled`: with the CPU
+ *  profiler on, for the hot list; the timings of such a tap are not the row's. */
+async function once(row, profiled) {
+  if (!row.action) {
+    const el = await page.$(row.sel)
+    if (!el) return null
     // A control off-screen in a scrolling panel is scrolled to first, as a thumb would.
     await el.evaluate((e) => e.scrollIntoView({ block: 'center' }))
     await sleep(300)
-  }
-  const t0 = await page.evaluate((appear) => {
-    window.__perf.appear = null
-    if (appear) {
-      const test = () => document.querySelector(appear)
-      const done = () => {
-        const t = performance.now()
-        requestAnimationFrame(() => setTimeout(() => (window.__perf.appear = { dom: t, paint: performance.now() })))
-      }
-      if (test()) window.__perf.appear = { already: true }
-      else {
-        const mo = new MutationObserver(() => {
-          if (test()) { mo.disconnect(); done() }
-        })
-        mo.observe(document.body, { childList: true, subtree: true, attributes: true })
-      }
-    }
+  } else if (row.before) await row.before()
+  const t0 = await page.evaluate(() => {
     window.__gl0 = { ...window.__gl }
     return performance.now()
-  }, appear ?? null)
-  await cdp.send('Profiler.start')
-  if (action) await action()
-  else await page.tap(sel)
-  const wall0 = Date.now()
-  if (appear) {
-    await page.waitForFunction(() => window.__perf.appear, { timeout, polling: 50 }).catch(() => {})
-  }
-  await sleep(settle)
-  const { profile } = await cdp.send('Profiler.stop')
-  const r = await page.evaluate((t0) => {
+  })
+  if (profiled) await cdp.send('Profiler.start')
+  if (row.action) await row.action()
+  else await page.tap(row.sel)
+  if (row.appear) await page.waitForFunction((sel) => document.querySelector(sel), { timeout: row.timeout ?? 60_000, polling: 100 }, row.appear).catch(() => {})
+  await sleep(row.settle ?? 2000)
+  const profile = profiled ? (await cdp.send('Profiler.stop')).profile : null
+  const r = await page.evaluate((t0, names) => {
     const P = window.__perf
-    const ev = P.events.filter((e) => e.start >= t0 - 5 && ['pointerdown', 'pointerup', 'click', 'touchstart', 'touchend', 'mousedown', 'mouseup'].includes(e.name))
+    const ev = P.events.filter((e) => e.start >= t0 - 5 && names.includes(e.name))
     const lt = P.longtasks.filter((e) => e.start >= t0)
     const lo = P.loafs.filter((e) => e.start >= t0)
+    // Work that starts a good while after the tap's own handlers have finished:
+    // a timer the tap set, such as the recovery checkpoint.
+    const tapEnd = ev.length ? Math.max(...ev.map((e) => e.start + e.dur)) : t0 + 150
+    const late = lt.filter((e) => e.start > tapEnd + 250)
     const scripts = {}
     for (const f of lo) for (const s of f.scripts) {
       const k = `${s.inv} → ${s.fn || '?'} ${s.url}`
@@ -157,112 +299,483 @@ async function measure(label, sel, { appear, settle = 2500, timeout = 60_000, op
     }
     const G = window.__gl, G0 = window.__gl0
     return {
-      gl: `GL: ${G.link - G0.link} shader links, ${((G.upload - G0.upload) / 1048576).toFixed(1)} MB uploaded, ${G.ctx - G0.ctx} new contexts`,
+      link: G.link - G0.link,
+      upload: (G.upload - G0.upload) / 1048576,
+      ctx: G.ctx - G0.ctx,
       inp: ev.length ? Math.max(...ev.map((e) => e.dur)) : 0,
       handler: ev.length ? Math.max(...ev.map((e) => e.pe - e.ps)) : 0,
-      appear: P.appear ? (P.appear.already ? 'already' : Math.round(P.appear.paint - t0)) : null,
       longTotal: Math.round(lt.reduce((s, e) => s + e.dur, 0)),
       longMax: Math.round(Math.max(0, ...lt.map((e) => e.dur))),
       longN: lt.length,
+      lateMax: Math.round(Math.max(0, ...late.map((e) => e.dur))),
       loafRender: Math.round(lo.reduce((s, e) => s + e.render, 0)),
       loafStyle: Math.round(lo.reduce((s, e) => s + e.style, 0)),
       scripts: Object.entries(scripts).sort((a, b) => b[1] - a[1]).slice(0, 4).map(([k, v]) => `${Math.round(v)}ms ${k}`),
     }
-  }, t0)
-  r.label = label
-  r.hot = hot(profile)
+  }, t0, INPUT_EVENTS)
+  if (profile) {
+    r.hot = hot(profile)
+    r.watch = watched(profile)
+  }
+  return r
+}
+
+const results = []
+const budgetFails = []
+const fmtMB = (x) => x.toFixed(1)
+
+/** Run rows `RUNS` times round (in order, so toggles alternate and tabs go
+ *  round), then once more with the profiler on. `solo`: the rows cannot repeat,
+ *  so they run once, profiled. A row is `{ label, sel | action, settle, appear,
+ *  timeout, optional, budget }`; `budget` is `{ links, uploadMB, contexts,
+ *  longMs, inpMs, steady }` — `steady` leaves the first tap out of the GL
+ *  figures (a context or program made on first use is not the budget's to
+ *  count), `inpMs` is the production target's median (or `{ bare, rich }`).
+ *
+ *  Where the numbers come from: `inpMs` is the baseline median less 30 % — the
+ *  production build for `bare`, the dev server for `rich` — for the rows the
+ *  fix plan's tasks target, from the PERF_RUNS=5 baseline in the spec's
+ *  "Baseline" section; a budget the baseline already breaches is the target the
+ *  fixes are to reach. The GL budgets are the plan's own (links 0, uploadMB 0 or
+ *  1, contexts 0) and are expected to fail until their task lands. */
+async function run(rows, { solo = false } = {}) {
+  const live = rows.map((row) => ({ row, samples: [], prof: null }))
+  const rounds = solo ? 0 : RUNS
+  for (let k = 0; k < rounds; k++) {
+    for (const x of live) {
+      try {
+        const s = await once(x.row, false)
+        if (s) x.samples.push(s)
+      } catch (e) {
+        console.log(`FAILED ${x.row.label} (run ${k + 1}): ${String(e.message).split('\n')[0]}`)
+      }
+    }
+  }
+  for (const x of live) {
+    try {
+      const s = await once(x.row, true)
+      if (!s) continue
+      x.prof = s
+      if (solo) x.samples.push(s)
+    } catch (e) {
+      console.log(`FAILED ${x.row.label} (profiled): ${String(e.message).split('\n')[0]}`)
+    }
+  }
+  for (const x of live) {
+    if (x.samples.length) report(x.row, x.samples, x.prof, solo)
+    else if (!x.row.optional) console.log(`SKIP ${x.row.label}: ${x.row.sel ?? 'no sample taken'} not found`)
+  }
+}
+
+function report(row, samples, prof, solo) {
+  const n = samples.length
+  const m = (f) => median(samples.map(f))
+  const first = samples[0]
+  const r = {
+    label: row.label,
+    n,
+    solo,
+    inp: m((s) => s.inp),
+    inpFirst: first.inp,
+    inpMin: Math.min(...samples.map((s) => s.inp)),
+    inpMax: Math.max(...samples.map((s) => s.inp)),
+    handler: m((s) => s.handler),
+    longMax: m((s) => s.longMax),
+    longMaxAny: Math.max(...samples.map((s) => s.longMax)),
+    longTotal: m((s) => s.longTotal),
+    lateMax: m((s) => s.lateMax),
+    lateMaxAny: Math.max(...samples.map((s) => s.lateMax)),
+    loafRender: m((s) => s.loafRender),
+    loafStyle: m((s) => s.loafStyle),
+    link: Math.max(...samples.map((s) => s.link)),
+    upload: Math.max(...samples.map((s) => s.upload)),
+    ctx: Math.max(...samples.map((s) => s.ctx)),
+    first: { link: first.link, upload: first.upload, ctx: first.ctx },
+    steady: samples.length > 1 ? { link: Math.max(...samples.slice(1).map((s) => s.link)), upload: Math.max(...samples.slice(1).map((s) => s.upload)), ctx: Math.max(...samples.slice(1).map((s) => s.ctx)) } : null,
+    hot: prof?.hot ?? [],
+    watch: prof?.watch ?? [],
+    scripts: (prof ?? first).scripts,
+  }
+  // ---- budgets ----
+  const b = row.budget ?? {}
+  const gl = b.steady ? r.steady : { link: r.link, upload: r.upload, ctx: r.ctx }
+  const breaches = []
+  if (gl) {
+    if (b.links !== undefined && gl.link > b.links) breaches.push(`${gl.link} shader links, budget ${b.links}${b.steady ? ' (after the first tap)' : ''}`)
+    if (b.uploadMB !== undefined && gl.upload > b.uploadMB + 0.05) breaches.push(`${fmtMB(gl.upload)} MB uploaded, budget ${b.uploadMB}${b.steady ? ' (after the first tap)' : ''}`)
+    if (b.contexts !== undefined && gl.ctx > b.contexts) breaches.push(`${gl.ctx} new WebGL contexts, budget ${b.contexts}${b.steady ? ' (after the first tap)' : ''}`)
+  } else if (b.steady && (b.links !== undefined || b.uploadMB !== undefined || b.contexts !== undefined)) {
+    console.log(`  (budget on ${row.label}: after-the-first-tap figures need PERF_RUNS >= 2 — not checked)`)
+    r.unchecked = true
+  }
+  if (b.longMs !== undefined && r.longMaxAny > b.longMs) breaches.push(`long task max ${r.longMaxAny} ms, budget ${b.longMs}`)
+  const inpB = inpBudget(b.inpMs)
+  if (inpB !== undefined && RUNS >= 5 && !solo && r.inp > inpB) breaches.push(`median INP ${Math.round(r.inp)} ms, budget ${inpB}`)
+  if (inpB !== undefined && RUNS < 5 && !solo) r.unchecked = true
+  r.budget = { ...b, inpMs: inpB }
+  r.breaches = breaches
+  for (const x of breaches) budgetFails.push(`BUDGET FAIL: ${row.label}: ${x}`)
   results.push(r)
-  console.log(
-    `\n## ${label}\n  INP ${Math.round(r.inp)}ms (handler ${Math.round(r.handler)}ms) | UI appears ${r.appear ?? '-'}ms | long tasks ${r.longN} total ${r.longTotal}ms max ${r.longMax}ms | LoAF render ${r.loafRender}ms style/layout ${r.loafStyle}ms`,
-  )
-  console.log('  ' + r.gl)
+  // ---- print ----
+  const spread = n > 1 ? ` (min ${Math.round(r.inpMin)}, max ${Math.round(r.inpMax)}, first ${Math.round(r.inpFirst)})` : ''
+  console.log(`\n## ${row.label}  [${solo ? 'n=1, single profiled run' : `n=${n}, median; profiled run separate`}]`)
+  console.log(`  INP ${Math.round(r.inp)}ms${spread} (handler ${Math.round(r.handler)}ms) | long tasks: max ${r.longMax}ms (worst ${r.longMaxAny}ms), total ${r.longTotal}ms | late long task (>250ms after the tap) ${r.lateMax}ms (worst ${r.lateMaxAny}ms) | LoAF render ${r.loafRender}ms style/layout ${r.loafStyle}ms`)
+  console.log(`  GL (worst tap): ${r.link} shader links, ${fmtMB(r.upload)} MB uploaded, ${r.ctx} new contexts | first tap: ${r.first.link} links, ${fmtMB(r.first.upload)} MB, ${r.first.ctx} ctx`)
+  const bs = Object.entries({ ...b, inpMs: inpB }).filter(([, v]) => v !== undefined && v !== false).map(([k, v]) => `${k} ${v === true ? 'yes' : v}`)
+  if (bs.length) console.log(`  budget: ${bs.join(', ')} -> ${breaches.length ? 'FAIL' : 'ok'}`)
   for (const s of r.scripts) console.log('   loaf:', s)
   for (const h of r.hot) console.log('   cpu:', h)
-  void wall0
-  return r
+  if (prof) console.log('   watched (inclusive):', r.watch.length ? r.watch.join(', ') : 'none sampled', ['evaluateDimensions', 'updateOverlays', 'computeElementDeviation'].filter((w) => !r.watch.some((x) => x.endsWith(' ' + w))).map((w) => `| ${w}: not sampled`).join(' '))
 }
 
 const shot = (n) => page.screenshot({ path: OUT + n + '.png' })
+const tab = (id) => `[data-test=${id}]`
+/** A tab row. */
+const tabRow = (label, id, extra = {}) => ({ label, sel: tab(id), settle: 1500, ...extra })
+
+// ---- driving the in-page command registry (dev server, rich scenario) ---------------
+/** Run an in-page snippet with `runCommand` at hand; the registry is the one the
+ *  app's agent bridge uses, its core commands registered on demand. */
+const inApp = (body) =>
+  page.evaluate(
+    `(async () => {
+      const { runCommand } = await import('/src/commands/registry.ts')
+      await (await import('/src/commands/core.ts')).registerCoreCommands()
+      ${body}
+    })()`,
+  )
+
+/** Six elements, four dimensions and a section on the loaded scan — what a
+ *  working session holds and the bare sample lacks. The sample has no sphere
+ *  (a sphere fit on it comes back as a junk R190 or refuses), so the elements
+ *  are the planes and cylinders it does have; the answer says what came to be. */
+async function buildRichProject() {
+  return inApp(`
+    const log = []
+    const tryRun = async (what, name, input) => {
+      try { return await runCommand(name, input) } catch (e) { log.push(what + ' refused: ' + String(e.message).slice(0, 90)); return null }
+    }
+    const seg = await runCommand('scan.segment', { limit: 130 })
+    const ids = { plane: [], cylinder: [], sphere: [] }
+    // Planes from the three largest flat regions that are not curved.
+    for (const r of seg.regions.filter((r) => !r.curved).slice(0, 3)) {
+      const e = await tryRun('plane', 'element.fit', { kind: 'plane', at: { point: r.point } })
+      if (e) ids.plane.push(e.element.id)
+    }
+    // Cylinders from the surfaces the segmentation says are one curved face cut into strips.
+    for (const run of seg.curvedRuns.slice(0, 3)) {
+      await runCommand('scan.segment', { limit: 130, mark: run.regions })
+      const e = await tryRun('cylinder', 'element.fit_marked', { kind: 'cylinder', marked: true })
+      if (e) ids.cylinder.push(e.element.id)
+    }
+    // Spheres, if the scan has any: seeded on the curved regions, a radius a part would have.
+    for (const r of seg.regions.filter((r) => r.curved).slice(0, 4)) {
+      if (ids.sphere.length >= 2) break
+      for (const side of ['outside', 'inside']) {
+        const e = await tryRun('sphere', 'element.fit', { kind: 'sphere', at: { point: r.point }, side, radius: { min: 2, max: 40 } })
+        if (e) { ids.sphere.push(e.element.id); break }
+      }
+    }
+    const dims = []
+    const e = [...ids.plane, ...ids.cylinder, ...ids.sphere]
+    const [p0, p1, p2] = ids.plane, [c0, c1, c2] = ids.cylinder
+    // Pairs the scan's own features make a dimension of: planes at an angle refuse a distance, so
+    // each pair is tried and the first four that take are kept.
+    const pairs = [[p0, p1], [c0, c1], [p0, c0], [p1, p2], [p0, p2], [c0, c2], [p1, c1], [p2, c2], [e[0], e[e.length - 1]]]
+    for (const [a, b] of pairs) {
+      if (dims.length >= 4) break
+      if (a === undefined || b === undefined || a === b) continue
+      const d = await tryRun('dimension', 'dimension.add', { refs: [a, b] })
+      if (d) dims.push(d.dimension.id ?? true)
+    }
+    let section = null
+    const across = [[ids.plane[0], 3], ['XZ', 0], ['XY', 0], ['YZ', 0]]
+    for (const [a, offset] of across) {
+      if (a === undefined) continue
+      const s = await tryRun('section', 'section.cut', { across: a, offset })
+      if (s) { section = s.section; break }
+    }
+    return { elements: ids, dimensions: dims.length, section: section ? 'cut' : 'none', log }
+  `)
+}
+
+/** Pin deviation probes on the part, up to five: a pinned reading is project
+ *  content that is drawn, labelled and re-drawn on every tab and map change. A
+ *  new reference, source or map side clears them, so each group tops them up. */
+async function ensureProbes() {
+  if (!rich) return
+  await page.evaluate(`(async () => {
+    const { useDeviation } = await import('/src/state/deviationStore.ts')
+    const { runCommand } = await import('/src/commands/registry.ts')
+    const have = useDeviation.getState().probes.length
+    if (have >= 5) return
+    await (await import('/src/commands/core.ts')).registerCoreCommands()
+    const q = await runCommand('scan.query', { box: { min: [-1e4, -1e4, -1e4], max: [1e4, 1e4, 1e4] }, limit: 40 })
+    const stride = Math.max(1, Math.floor(q.points.length / 5))
+    for (let i = have; i < 5; i++) useDeviation.getState().addProbe(q.points[Math.min(q.points.length - 1, i * stride)], 0.02 * (i - 2))
+  })()`)
+}
 
-// ---- start: the sample scan ---------------------------------------------------
+// ---- start: the scan ------------------------------------------------------------
 await shot('00-start')
-await measure('Close support card', '[data-test=support-card] .sc-x', { settle: 800, optional: true })
-await measure('Open sample scan (288k tris)', null, {
-  action: async () => (await page.$('[data-test=start-scan] input[type=file], input[type=file]')).uploadFile(SAMPLE),
-  appear: '.file-info', settle: 4000, timeout: 300_000,
-})
+await run([{ label: 'Close support card', sel: '[data-test=support-card] .sc-x', settle: 800, optional: true }], { solo: true })
+await run(
+  [{
+    label: 'Open sample scan',
+    action: async () => (await page.$('[data-test=start-scan] input[type=file], input[type=file]')).uploadFile(SAMPLE),
+    appear: '.file-info', settle: 4000, timeout: 300_000,
+    // Plan task 15: the load's main-thread BVH build goes to the worker.
+    budget: { longMs: 150 },
+  }],
+  { solo: true },
+)
+const fileInfo = await page.$eval('.file-info', (el) => el.textContent.replace(/\s+/g, ' ').trim())
+console.log('\nloaded:', fileInfo)
 await shot('01-loaded')
+if (rich) {
+  const made = await buildRichProject()
+  console.log('rich project:', JSON.stringify(made))
+  await sleep(1500)
+  await shot('01b-rich')
+}
 
-// ---- workspace tabs with only a scan -------------------------------------------
+// ---- workspace tabs: the scan (and, rich, its project) only ---------------------------
 const tabs = await page.$$eval('[data-test^=workspace-]', (els) => els.map((e) => e.dataset.test))
 console.log('\ntabs:', tabs.join(', '))
-await measure('Tab → Surface Deviation (scan only)', '[data-test=workspace-deviation]', { appear: '[data-test=workspace-deviation][aria-selected=true]' })
-await shot('02-deviation')
-await measure('Tab → Wall Thickness', '[data-test=workspace-thickness]', { appear: '[data-test=measure-thickness]' })
-await measure('Thickness: Measure', '[data-test=measure-thickness]', { appear: '[data-test=thickness-legend]', settle: 3000, timeout: 300_000 })
-await shot('03-thickness')
-await measure('Thickness: map off', '[data-test=toggle-colormap]', { settle: 1500 })
-await measure('Thickness: map on', '[data-test=toggle-colormap]', { settle: 1500 })
-await measure('Tab → 2D Measure', '[data-test=workspace-flat]', { appear: '[data-test=workspace-flat][aria-selected=true]' })
-for (const t of tabs.filter((t) => !['workspace-elements', 'workspace-deviation', 'workspace-thickness', 'workspace-flat'].includes(t)))
-  await measure(`Tab → ${t} (plugin)`, `[data-test=${t}]`, { appear: `[data-test=${t}][aria-selected=true]`, settle: 3000 })
-await measure('Tab → 3D Measure', '[data-test=workspace-elements]', { appear: '[data-test=workspace-elements][aria-selected=true]' })
+const PLUGIN_TABS = tabs.filter((t) => !['workspace-elements', 'workspace-deviation', 'workspace-thickness', 'workspace-flat'].includes(t))
+await run([
+  // Budgets (production, bare; the rich ones are the dev baseline's own): the median − 30 %,
+  // for the rows the fix plan's tasks name — set from perf-baseline-v2.txt.
+  tabRow('Tab → Surface Deviation (scan only)', 'workspace-deviation', { budget: { inpMs: { bare: 45, rich: 73 } } }),
+  tabRow('Tab → Wall Thickness', 'workspace-thickness', { budget: { inpMs: { bare: 45, rich: 56 } } }),
+  tabRow('Tab → 2D Measure', 'workspace-flat', {
+    settle: 2000,
+    // Plan task 6: the 2D viewer is kept alive after its first open, so no later tap makes a context.
+    budget: { contexts: 0, steady: true, inpMs: { bare: 50, rich: 106 } },
+  }),
+  ...PLUGIN_TABS.map((t) => tabRow(`Tab → ${t} (plugin)`, t, { settle: 3000, budget: t === 'workspace-reverse' ? { inpMs: { bare: 50, rich: 129 }, links: 0 } : undefined })),
+  tabRow('Tab → 3D Measure', 'workspace-elements', { budget: { inpMs: { bare: 45, rich: 146 }, links: 0 } }),
+])
 await shot('04-measure')
 
+// ---- thickness ----------------------------------------------------------------------
+await page.tap(tab('workspace-thickness'))
+await sleep(1500)
+await run([{ label: 'Thickness: Measure', sel: '[data-test=measure-thickness]', appear: '[data-test=thickness-legend]', settle: 3000, timeout: 300_000 }], { solo: true })
+await shot('03-thickness')
+// The thickness map has no key of its own on the view bar; the Scan key in
+// [data-test=part-keys] is the one the view bar has here, and it hides the
+// scan the map is painted on.
+const bandsSelect = async (dir) => {
+  const el = await labelled('Bands', 'select')
+  await el.asElement().focus()
+  await page.keyboard.press(dir)
+}
+await run([
+  { label: 'Thickness: scan key off (view bar)', sel: '[data-test=part-keys] [data-test=toggle-scan]', settle: 1500 },
+  { label: 'Thickness: scan key on (view bar)', sel: '[data-test=part-keys] [data-test=toggle-scan]', settle: 1500 },
+])
+await run([
+  { label: 'Thickness: bands on (5 bands)', action: () => bandsSelect('ArrowDown'), before: async () => (await labelled('Bands', 'select')).asElement()?.evaluate((e) => e.scrollIntoView({ block: 'center' })), settle: 1500 },
+  { label: 'Thickness: bands off (continuous)', action: () => bandsSelect('ArrowUp'), before: async () => (await labelled('Bands', 'select')).asElement()?.evaluate((e) => e.scrollIntoView({ block: 'center' })), settle: 1500 },
+])
+await run([
+  { label: 'Thickness: histogram off', sel: '[data-test=toggle-thickness-histogram]', settle: 1500 },
+  { label: 'Thickness: histogram on', sel: '[data-test=toggle-thickness-histogram]', settle: 1500 },
+])
+
 // ---- deviation against the same part as reference --------------------------------
-await measure('Tab → Surface Deviation (again)', '[data-test=workspace-deviation]', { appear: '[data-test=workspace-deviation][aria-selected=true]' })
-await measure('Deviation: load reference', null, {
+await page.tap(tab('workspace-deviation'))
+await sleep(1500)
+await run([{
+  label: 'Deviation: load reference',
   action: async () => (await page.$('[data-test=slot-reference] input[type=file]')).uploadFile(SAMPLE),
   appear: '[data-test=align-auto]:not([disabled])', settle: 2000, timeout: 300_000,
-})
-await measure('Deviation: Auto best fit → map', '[data-test=align-auto]', { appear: '[data-test=deviation-legend]', settle: 4000, timeout: 300_000 })
+}], { solo: true })
+// The reference is loaded and has been shown only where it was loaded: the first
+// time it is shown again after a tab switch, which is the first row below.
+await run([
+  tabRow('Tab → 3D Measure (reference loaded)', 'workspace-elements', { budget: { inpMs: { bare: 39, rich: 140 }, links: 0 } }),
+  tabRow('Tab → Surface Deviation (first show of the reference)', 'workspace-deviation', { settle: 3000 }),
+])
+await run([{ label: 'Deviation: Auto best fit → map', sel: '[data-test=align-auto]', appear: '[data-test=deviation-legend]', settle: 4000, timeout: 300_000 }], { solo: true })
 await shot('05-deviation-map')
-await measure('Deviation: map off', '[data-test=toggle-colormap]', { settle: 1500 })
-await measure('Deviation: map on', '[data-test=toggle-colormap]', { settle: 1500 })
-await measure('Deviation: split on', '[data-test=toggle-split]', { settle: 3000 })
+await ensureProbes()
+await run([
+  { label: 'Deviation: map off', sel: '[data-test=toggle-colormap]', settle: 1500, budget: { links: 0 } },
+  // Plan task 2: a colour buffer that did not change is not uploaded again.
+  { label: 'Deviation: map on', sel: '[data-test=toggle-colormap]', settle: 1500, budget: { links: 0, uploadMB: 0 } },
+])
+await ensureProbes()
+await run([
+  // Plan task 6: the split view's second viewport is kept after its first open.
+  { label: 'Deviation: split on', sel: '[data-test=toggle-split]', settle: 3000, budget: { contexts: 0, steady: true, inpMs: { bare: 50, rich: 101 } } },
+  { label: 'Deviation: split off', sel: '[data-test=toggle-split]', settle: 2000 },
+])
 await shot('06-split')
-await measure('Deviation: split off', '[data-test=toggle-split]', { settle: 2000 })
-await measure('Deviation: map on reference', '[data-test=toggle-map-on-reference]', { settle: 4000, timeout: 300_000 })
-await measure('Deviation: map back on scan', '[data-test=toggle-map-on-reference]', { settle: 2000 })
-await measure('Deviation: histogram', '[data-test=deviation-histogram-toggle], [data-test$=histogram-toggle]', { settle: 1500, optional: true })
-await measure('Deviation: animate on', '[data-test=animate-deformation]', { settle: 2500 })
-await measure('Deviation: animate off', '[data-test=animate-deformation]', { settle: 1500 })
-await measure('Deviation: volume measure', '[data-test=volume-measure]', { appear: '[data-test=volume-show]', settle: 3000, timeout: 300_000 })
-await measure('Deviation: volume show', '[data-test=volume-show]', { settle: 2000 })
-await measure('Deviation: source → element', '[data-test=source-element]', { settle: 2000 })
-await measure('Deviation: source → reference', '[data-test=source-reference]', { settle: 2000 })
-await measure('Deviation: section view', '[data-test=toggle-section-view]', { settle: 2000 })
-await measure('Deviation: section view off', '[data-test=toggle-section-view]', { settle: 1500 })
+await ensureProbes()
+await run([
+  // Plan task 5: its programs are warm by the time anyone taps it.
+  { label: 'Deviation: map on reference', sel: '[data-test=toggle-map-on-reference]', settle: 4000, timeout: 300_000, budget: { links: 0 } },
+  { label: 'Deviation: map back on scan', sel: '[data-test=toggle-map-on-reference]', settle: 2000 },
+])
+await ensureProbes()
+await run([
+  { label: 'Deviation: histogram off', sel: '[data-test=toggle-histogram]', settle: 1500 },
+  { label: 'Deviation: histogram on', sel: '[data-test=toggle-histogram]', settle: 1500 },
+])
+const rangeStep = (dir) => async () => {
+  const el = await page.$('[data-test=range-slider]')
+  await el.focus()
+  await page.keyboard.press(dir)
+}
+const toleranceTo = (v) => async () => {
+  const el = (await labelled('Tolerance', 'input')).asElement()
+  await el.tap()
+  await page.keyboard.down('Control')
+  await page.keyboard.press('a')
+  await page.keyboard.up('Control')
+  await page.keyboard.type(String(v))
+  await page.keyboard.press('Enter')
+}
+const scrollTo = (sel) => async () => (await page.$(sel))?.evaluate((e) => e.scrollIntoView({ block: 'center' }))
+// Which way the first step goes: into the track, whichever end the range sits at.
+const towardsMiddle = await page.$eval('[data-test=range-slider]', (e) => (Number(e.value) < (Number(e.min) + Number(e.max)) / 2 ? ['ArrowRight', 'ArrowLeft'] : ['ArrowLeft', 'ArrowRight']))
+await run([
+  // The slider's key steps: one notch of the log scale is one repaint of the map and its figures.
+  { label: 'Deviation: range slider step 1', action: rangeStep(towardsMiddle[0]), before: scrollTo('[data-test=range-slider]'), settle: 1500, budget: { inpMs: { bare: 39, rich: 95 } } },
+  { label: 'Deviation: range slider step 2 (back)', action: rangeStep(towardsMiddle[1]), before: scrollTo('[data-test=range-slider]'), settle: 1500, budget: { inpMs: { bare: 39, rich: 112 } } },
+])
+const tolField = () => labelled('Tolerance', 'input').then((h) => h.asElement()?.evaluate((e) => e.scrollIntoView({ block: 'center' })))
+await run([
+  { label: 'Deviation: tolerance change (0.05)', action: toleranceTo(0.05), before: tolField, settle: 1500 },
+  { label: 'Deviation: tolerance change (0.08)', action: toleranceTo(0.08), before: tolField, settle: 1500 },
+])
+await ensureProbes()
+await run([
+  { label: 'Deviation: animate on', sel: '[data-test=animate-deformation]', settle: 2500 },
+  // Plan task 10: the deflect buffer is kept, so stopping the animation uploads next to nothing.
+  { label: 'Deviation: animate off', sel: '[data-test=animate-deformation]', settle: 1500, budget: { uploadMB: 1 } },
+])
+await run([{ label: 'Deviation: volume measure', sel: '[data-test=volume-measure]', appear: '[data-test=volume-show]', settle: 3000, timeout: 300_000 }], { solo: true })
+await run([
+  { label: 'Deviation: volume show on', sel: '[data-test=volume-show]', settle: 2000 },
+  { label: 'Deviation: volume show off', sel: '[data-test=volume-show]', settle: 1500 },
+])
+await ensureProbes()
+await run([
+  { label: 'Deviation: source → element', sel: '[data-test=source-element]', settle: 2000, budget: { links: 0 } },
+  { label: 'Deviation: source → reference', sel: '[data-test=source-reference]', settle: 2000, budget: { inpMs: { bare: 50, rich: 118 } } },
+])
+if (rich) {
+  // Against one of the project's own elements: the map is computed on the main
+  // thread (plan task 11), which the bare sample, with no elements, cannot show.
+  await page.tap('[data-test=source-element]')
+  await sleep(1500)
+  const options = await page.$$eval('[data-test=target-select] option', (os) => os.map((o) => o.value).filter(Boolean))
+  console.log('element targets:', options.length)
+  if (options.length >= 2) {
+    const pick = (v) => async () => page.select('[data-test=target-select]', v)
+    await run([{ label: 'Deviation: choose element target (first map)', action: pick(options[0]), settle: 4000, timeout: 120_000 }], { solo: true })
+    // The select is set by the page (a native picker cannot be driven), so these two have no INP:
+    // the long task and the hot list carry the cost.
+    await run([
+      { label: 'Deviation: change element target (A)', action: pick(options[1]), settle: 4000, budget: { links: 0 } },
+      { label: 'Deviation: change element target (B)', action: pick(options[0]), settle: 4000, budget: { links: 0 } },
+    ])
+    await run([
+      { label: 'Deviation: element facing limit on', sel: '[data-test=toggle-facing]', settle: 4000, budget: { inpMs: { rich: 162 } } },
+      { label: 'Deviation: element facing limit off', sel: '[data-test=toggle-facing]', settle: 4000, budget: { inpMs: { rich: 162 } } },
+    ])
+  }
+  await page.tap('[data-test=source-reference]')
+  await sleep(1500)
+}
+await run([
+  // Plan task 5: the first tap used to compile six programs. The plan also asks for a median of
+  // 120 ms; the warm median is already 64, so the baseline rule (median − 30 %) stands instead — the
+  // cold first tap (240 ms) is the table's "INP first" column.
+  { label: 'Deviation: section view on', sel: '[data-test=toggle-section-view]', settle: 2000, budget: { links: 0, inpMs: { bare: 45, rich: 78 } } },
+  { label: 'Deviation: section view off', sel: '[data-test=toggle-section-view]', settle: 1500 },
+])
 
 // ---- switching with maps in hand ---------------------------------------------------
-await measure('Tab → 3D Measure (maps in hand)', '[data-test=workspace-elements]', { appear: '[data-test=workspace-elements][aria-selected=true]' })
-await measure('Tab → Surface Deviation (map in hand)', '[data-test=workspace-deviation]', { appear: '[data-test=deviation-legend]' })
-await measure('Tab → Wall Thickness (map in hand)', '[data-test=workspace-thickness]', { appear: '[data-test=thickness-legend]' })
-await measure('Tab → Surface Deviation (from thickness)', '[data-test=workspace-deviation]', { appear: '[data-test=deviation-legend]' })
-await measure('Settings open', '[data-test=open-settings]', { appear: '[data-test=settings-modal]', settle: 1500 })
-await measure('Settings close', '[data-test=settings-close]', { settle: 1000 })
+await ensureProbes()
+await run([
+  tabRow('Tab → 3D Measure (maps in hand)', 'workspace-elements', { budget: { inpMs: { bare: 34, rich: 134 }, links: 0 } }),
+  // Plan task 2: a map already painted is not uploaded again on the way in.
+  tabRow('Tab → Surface Deviation (map in hand)', 'workspace-deviation', { budget: { uploadMB: 0, inpMs: { bare: 50, rich: 129 }, links: 0 } }),
+  tabRow('Tab → Wall Thickness (map in hand)', 'workspace-thickness', { budget: { uploadMB: 0, inpMs: { bare: 50, rich: 123 } } }),
+  tabRow('Tab → Surface Deviation (from thickness)', 'workspace-deviation', { budget: { inpMs: { bare: 50, rich: 118 }, links: 0 } }),
+])
+await run([
+  { label: 'Settings open', sel: '[data-test=open-settings]', settle: 1500 },
+  { label: 'Settings close', sel: '[data-test=settings-close]', settle: 1000 },
+])
+
+// ---- rich: a brush stroke, the marking path's per-move upload --------------------------
+if (rich) {
+  await page.tap(tab('workspace-elements'))
+  await sleep(1500)
+  try {
+    await page.tap('[data-test=fit-sphere]')
+    await page.waitForSelector('[data-test=draft-select-mode]', { timeout: 10_000 })
+    await page.select('[data-test=draft-select-mode]', 'paint')
+    await page.waitForSelector('[data-test=mark-gestures]', { timeout: 10_000 })
+    await page.tap('[data-test=mark-brush]')
+    await sleep(500)
+    const rect = await page.$eval('.viewport canvas', (el) => {
+      const r = el.getBoundingClientRect()
+      return { x: r.x, y: r.y, w: r.width, h: r.height }
+    })
+    // Sweep a slow horizontal stroke through the middle of the viewport, where the part is.
+    const stroke = async () => {
+      const y = rect.y + rect.h * 0.5
+      await page.mouse.move(rect.x + rect.w * 0.3, y)
+      await page.mouse.down()
+      for (let i = 0; i <= 20; i++) {
+        await page.mouse.move(rect.x + rect.w * (0.3 + 0.02 * i), y + Math.sin(i / 3) * 6)
+        await sleep(16)
+      }
+      await page.mouse.up()
+    }
+    await run([{ label: 'Brush stroke (20 moves, rich)', action: stroke, settle: 1500 }])
+    const marked = await page.$eval('[data-test=paint-count]', (e) => e.textContent.trim()).catch(() => 'n/a')
+    console.log('marked after the strokes:', marked)
+    await page.keyboard.press('Escape')
+    await page.keyboard.press('Escape')
+    await sleep(500)
+  } catch (e) {
+    console.log('SKIP brush stroke:', String(e.message).split('\n')[0])
+  }
+}
 await shot('07-end')
 
 // ---- idle cost: what the page burns doing nothing ---------------------------------
-const idle = await page.evaluate(async () => {
-  const t0 = performance.now()
-  let frames = 0
-  await new Promise((res) => {
-    const f = () => (performance.now() - t0 < 3000 ? (frames++, requestAnimationFrame(f)) : res())
-    requestAnimationFrame(f)
-  })
-  return frames
-})
+await page.evaluate(() => (window.__idle0 = window.__gl.raf))
 await cdp.send('Profiler.start')
 await sleep(3000)
 const idleProfile = (await cdp.send('Profiler.stop')).profile
+const idleRaf = await page.evaluate(() => window.__gl.raf - window.__idle0)
 const idleBusy = idleProfile.timeDeltas.reduce((s, d, i) => {
   const nd = idleProfile.nodes.find((n) => n.id === idleProfile.samples[i])
   return nd.callFrame.functionName === '(idle)' ? s : s + d
 }, 0) / 1000
-console.log(`\n## Idle (3 s, nothing touched): ${idle} rAF frames, main thread busy ${idleBusy.toFixed(0)}ms`)
+console.log(`\n## Idle (3 s, nothing touched): ${idleRaf} animation-frame callbacks ran, main thread busy ${idleBusy.toFixed(0)}ms`)
 for (const h of hot(idleProfile, 6)) console.log('   cpu:', h)
 
-writeFileSync(OUT + 'results.json', JSON.stringify(results, null, 2))
+// ---- summary --------------------------------------------------------------------------
+console.log(`\n## Summary — ${isDev ? 'dev' : 'production'}, ${SCENARIO}, PERF_RUNS=${RUNS}, ${THROTTLE}x throttle, ${fileInfo}`)
+console.log('| Row | n | INP median ms | INP first ms | long max ms | late long ms | links | upload MB | new ctx | budget |')
+console.log('|---|---|---|---|---|---|---|---|---|---|')
+for (const r of results) {
+  const b = Object.entries(r.budget).filter(([, v]) => v !== undefined && v !== false).map(([k, v]) => `${k}${v === true ? '' : '=' + v}`).join(' ')
+  console.log(`| ${r.label} | ${r.solo ? '1*' : r.n} | ${Math.round(r.inp)} | ${Math.round(r.inpFirst)} | ${r.longMax} | ${r.lateMax} | ${r.link} | ${fmtMB(r.upload)} | ${r.ctx} | ${b ? (r.breaches.length ? 'FAIL ' : r.unchecked ? 'unchecked ' : 'ok ') + b : ''} |`)
+}
+console.log('(* a row that cannot repeat: one profiled run. INP 0 = under the 16 ms Event Timing floor, or an action driven by the page rather than a tap.)')
+console.log(`idle: ${idleRaf} frame callbacks / 3 s, main thread busy ${idleBusy.toFixed(0)}ms`)
+writeFileSync(OUT + `results-${SCENARIO}-${isDev ? 'dev' : 'prod'}.json`, JSON.stringify(results, null, 2))
 console.log('\nerrors:', errors.length ? errors.slice(0, 5) : 'none')
+console.log(budgetFails.length ? `\n${budgetFails.length} budget breach${budgetFails.length > 1 ? 'es' : ''}:\n${budgetFails.join('\n')}` : '\nno budget breaches')
 await browser.close()
+if (ASSERT && budgetFails.length) process.exit(1)

From 983f939ee20988b670632f662a8c6e40004113e5 Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Wed, 4 Nov 2026 13:45:59 +0000
Subject: [PATCH 03/38] perf: probe v2 review fixes

inpMs budgets are round(0.7 x median) of the saved baseline, stated once next
to them; a budgeted row that took no sample, a rich project that did not come
out whole, and a budgeted tap no input event reached now fail the run; the
profiler is stopped in a finally; the first tap is run 1 even when it failed;
the browser closes in a finally; the first-show row says only INP first is the
first show.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../specs/2026-11-04-mobile-perf-findings.md  |    2 +-
 scripts/perf-probe.mjs                        | 1264 +++++++++--------
 2 files changed, 655 insertions(+), 611 deletions(-)

diff --git a/docs/superpowers/specs/2026-11-04-mobile-perf-findings.md b/docs/superpowers/specs/2026-11-04-mobile-perf-findings.md
index 548d1764..e49c0d19 100644
--- a/docs/superpowers/specs/2026-11-04-mobile-perf-findings.md
+++ b/docs/superpowers/specs/2026-11-04-mobile-perf-findings.md
@@ -75,7 +75,7 @@ Production, bare scenario:
 | Thickness: histogram off | 40 | 48 | 0 ms | – |
 | Thickness: histogram on | 40 | 40 | 0 ms | – |
 | Tab → 3D Measure (reference loaded) | 80 | 80 | 0 ms | 0.6 MB |
-| Tab → Surface Deviation (first show of the reference) | 72 | 72 | 0 ms | 0.6 MB |
+| Tab → Surface Deviation (after reference load; INP first = the first show) | 72 | 72 | 0 ms | 0.6 MB |
 | Deviation: map off | 48 | 56 | 0 ms | 0.6 MB |
 | Deviation: map on | 64 | 80 | 0 ms | 0.6 MB |
 | Deviation: split on | 104 | 144 | 51 ms | 1 links, 6.8 MB, 1 new ctx |
diff --git a/scripts/perf-probe.mjs b/scripts/perf-probe.mjs
index 6af8ee03..c841745e 100644
--- a/scripts/perf-probe.mjs
+++ b/scripts/perf-probe.mjs
@@ -59,6 +59,7 @@ const rich = SCENARIO === 'rich'
 
 /** The row's own budget for this scenario: a number is the production bare
  *  target's, `{ bare, rich }` names both. */
+let isDev = false
 const inpBudget = (b) => (typeof b === 'number' ? (rich || isDev ? undefined : b) : rich ? b?.rich : isDev ? undefined : b?.bare)
 
 const browser = await puppeteer.launch({
@@ -82,7 +83,10 @@ await page.evaluateOnNewDocument(() => {
     localStorage.setItem('scanruler.supportask', '0')
     localStorage.setItem('scanruler.agentdataok', '1')
   } catch {}
-  const P = (window.__perf = { events: [], longtasks: [], loafs: [] })
+  const P = (window.__perf = { events: [], longtasks: [], loafs: [], seen: [] })
+  // Event Timing says nothing about an event under 16 ms; this counts the trusted ones that
+  // reached the page, so a tap that never landed is not mistaken for a very fast one.
+  for (const t of ['click', 'keydown']) window.addEventListener(t, (e) => e.isTrusted && P.seen.push(performance.now()), true)
   // GPU-side work each tap sets off, which a desktop GPU hides and a phone's does not.
   const G = (window.__gl = { link: 0, upload: 0, ctx: 0, raf: 0 })
   for (const C of [WebGLRenderingContext, WebGL2RenderingContext]) {
@@ -124,658 +128,698 @@ await page.evaluateOnNewDocument(() => {
   } catch {}
 })
 
-await page.goto(APP_URL, { waitUntil: 'networkidle0' })
-await page.waitForSelector('.panel, .startpane', { timeout: 120_000 })
-const isDev = await page.evaluate(() => fetch('/@vite/client').then((r) => r.text()).then((t) => /import.meta.hot|createHotContext/.test(t), () => false))
-if (rich && !isDev) {
-  console.log('PERF_SCENARIO=rich needs the dev server (it imports /src/commands/registry.ts).')
-  await browser.close()
-  process.exit(2)
-}
-const cdp = await page.createCDPSession()
-await cdp.send('Profiler.enable')
-await cdp.send('Profiler.setSamplingInterval', { interval: 250 })
-const gl = await page.evaluate(() => {
-  const g = document.createElement('canvas').getContext('webgl2')
-  const ext = g?.getExtension('WEBGL_debug_renderer_info')
-  return ext ? g.getParameter(ext.UNMASKED_RENDERER_WEBGL) : 'n/a'
-})
-console.log('GPU:', gl, '| CPU throttle', THROTTLE + 'x', '| DPR', await page.evaluate(() => devicePixelRatio))
-console.log(`target: ${isDev ? 'dev server' : 'production build'} ${APP_URL} | scenario: ${SCENARIO} | PERF_RUNS=${RUNS}${ASSERT ? ' | PERF_ASSERT=1' : ''}`)
-console.log(`scan: ${SAMPLE.replace(/^.*[\\/]/, '')}, ${(statSync(SAMPLE).size / 1048576).toFixed(1)} MB on disk`)
-await cdp.send('Emulation.setCPUThrottlingRate', { rate: THROTTLE })
+try {
+  await page.goto(APP_URL, { waitUntil: 'networkidle0' })
+  await page.waitForSelector('.panel, .startpane', { timeout: 120_000 })
+  isDev = await page.evaluate(() => fetch('/@vite/client').then((r) => r.text()).then((t) => /import.meta.hot|createHotContext/.test(t), () => false))
+  if (rich && !isDev) {
+    console.log('PERF_SCENARIO=rich needs the dev server (it imports /src/commands/registry.ts).')
+    await browser.close()
+    process.exit(2)
+  }
+  const cdp = await page.createCDPSession()
+  await cdp.send('Profiler.enable')
+  await cdp.send('Profiler.setSamplingInterval', { interval: 250 })
+  const gl = await page.evaluate(() => {
+    const g = document.createElement('canvas').getContext('webgl2')
+    const ext = g?.getExtension('WEBGL_debug_renderer_info')
+    return ext ? g.getParameter(ext.UNMASKED_RENDERER_WEBGL) : 'n/a'
+  })
+  console.log('GPU:', gl, '| CPU throttle', THROTTLE + 'x', '| DPR', await page.evaluate(() => devicePixelRatio))
+  console.log(`target: ${isDev ? 'dev server' : 'production build'} ${APP_URL} | scenario: ${SCENARIO} | PERF_RUNS=${RUNS}${ASSERT ? ' | PERF_ASSERT=1' : ''}`)
+  console.log(`scan: ${SAMPLE.replace(/^.*[\\/]/, '')}, ${(statSync(SAMPLE).size / 1048576).toFixed(1)} MB on disk`)
+  await cdp.send('Emulation.setCPUThrottlingRate', { rate: THROTTLE })
 
-// ---- naming functions: dev has real names, a production build gets them from its source map ----
-const consumers = new Map()
-/** The source map of a built file, or null (dev, a worker, a file with none). */
-function consumerFor(path) {
-  if (!consumers.has(path)) {
-    const file = DIST + path.replace(/^\//, '') + '.map'
-    consumers.set(path, existsSync(file) ? new SourceMapConsumer(JSON.parse(readFileSync(file, 'utf8'))) : null)
+  // ---- naming functions: dev has real names, a production build gets them from its source map ----
+  const consumers = new Map()
+  /** The source map of a built file, or null (dev, a worker, a file with none). */
+  function consumerFor(path) {
+    if (!consumers.has(path)) {
+      const file = DIST + path.replace(/^\//, '') + '.map'
+      consumers.set(path, existsSync(file) ? new SourceMapConsumer(JSON.parse(readFileSync(file, 'utf8'))) : null)
+    }
+    return consumers.get(path)
   }
-  return consumers.get(path)
-}
-const sourceLines = new Map()
-/** The name of the function that starts at an original position, read off the
- *  source text there: `name(`, `function name(`, or `name = () =>` / `name: () =>`. */
-function nameAt(c, at) {
-  let lines = sourceLines.get(at.source)
-  if (!lines) {
-    lines = (c.sourceContentFor(at.source, true) ?? '').split('\n')
-    sourceLines.set(at.source, lines)
+  const sourceLines = new Map()
+  /** The name of the function that starts at an original position, read off the
+   *  source text there: `name(`, `function name(`, or `name = () =>` / `name: () =>`. */
+  function nameAt(c, at) {
+    let lines = sourceLines.get(at.source)
+    if (!lines) {
+      lines = (c.sourceContentFor(at.source, true) ?? '').split('\n')
+      sourceLines.set(at.source, lines)
+    }
+    const text = lines[at.line - 1] ?? ''
+    const after = text.slice(at.column)
+    const own = after.match(/^(?:async\s+)?(?:function\s*\*?\s*)?([A-Za-z_$][\w$]*)\s*(?:<[^>(]*>)?\(/)
+    if (own && !/^(?:if|for|while|switch|catch|function|return)$/.test(own[1])) return own[1]
+    const bound = text.slice(0, at.column).match(/([A-Za-z_$][\w$.]*)\s*[:=]\s*(?:async\s*)?$/)
+    return bound ? bound[1] : null
   }
-  const text = lines[at.line - 1] ?? ''
-  const after = text.slice(at.column)
-  const own = after.match(/^(?:async\s+)?(?:function\s*\*?\s*)?([A-Za-z_$][\w$]*)\s*(?:<[^>(]*>)?\(/)
-  if (own && !/^(?:if|for|while|switch|catch|function|return)$/.test(own[1])) return own[1]
-  const bound = text.slice(0, at.column).match(/([A-Za-z_$][\w$.]*)\s*[:=]\s*(?:async\s*)?$/)
-  return bound ? bound[1] : null
-}
-const named = new Map()
-/** `{ name, src, line }` for a profile call frame. */
-function nameOf(cf) {
-  const path = cf.url.replace(/^.*\/\/[^/]+/, '').replace(/\?.*$/, '')
-  const key = `${path}|${cf.lineNumber}|${cf.columnNumber}|${cf.functionName}`
-  let r = named.get(key)
-  if (r) return r
-  r = { name: cf.functionName || '(anon)', src: path, line: cf.lineNumber + 1 }
-  const c = path.startsWith('/assets/') ? consumerFor(path) : null
-  if (c) {
-    const at = c.originalPositionFor({ line: cf.lineNumber + 1, column: cf.columnNumber })
-    if (at.source) {
-      // The mapping at a function's start names it only when the minifier renamed it; a method or a
-      // property keeps its own name, so that is read off the original source at that spot.
-      const name = at.name ?? nameAt(c, at)
-      r = { name: name ?? `${cf.functionName || '(anon)'}~`, src: at.source.replace(/^(\.\.\/)+/, '').replace(/^.*?(node_modules\/)/, '$1'), line: at.line }
+  const named = new Map()
+  /** `{ name, src, line }` for a profile call frame. */
+  function nameOf(cf) {
+    const path = cf.url.replace(/^.*\/\/[^/]+/, '').replace(/\?.*$/, '')
+    const key = `${path}|${cf.lineNumber}|${cf.columnNumber}|${cf.functionName}`
+    let r = named.get(key)
+    if (r) return r
+    r = { name: cf.functionName || '(anon)', src: path, line: cf.lineNumber + 1 }
+    const c = path.startsWith('/assets/') ? consumerFor(path) : null
+    if (c) {
+      const at = c.originalPositionFor({ line: cf.lineNumber + 1, column: cf.columnNumber })
+      if (at.source) {
+        // The mapping at a function's start names it only when the minifier renamed it; a method or a
+        // property keeps its own name, so that is read off the original source at that spot.
+        const name = at.name ?? nameAt(c, at)
+        r = { name: name ?? `${cf.functionName || '(anon)'}~`, src: at.source.replace(/^(\.\.\/)+/, '').replace(/^.*?(node_modules\/)/, '$1'), line: at.line }
+      }
     }
+    named.set(key, r)
+    return r
   }
-  named.set(key, r)
-  return r
-}
-const where = (n) => `${n.name} ${n.src}:${n.line}`
+  const where = (n) => `${n.name} ${n.src}:${n.line}`
 
-/** Self time per function from a CPU profile, the top `n`. */
-function hot(profile, n = 8) {
-  const byId = new Map(profile.nodes.map((nd) => [nd.id, nd]))
-  const self = new Map()
-  const dts = profile.timeDeltas
-  for (let i = 0; i < profile.samples.length; i++) {
-    const cf = byId.get(profile.samples[i]).callFrame
-    if (cf.functionName === '(idle)' || cf.functionName === '(program)') continue
-    const key = where(nameOf(cf))
-    self.set(key, (self.get(key) ?? 0) + (dts[i] ?? 0) / 1000)
+  /** Self time per function from a CPU profile, the top `n`. */
+  function hot(profile, n = 8) {
+    const byId = new Map(profile.nodes.map((nd) => [nd.id, nd]))
+    const self = new Map()
+    const dts = profile.timeDeltas
+    for (let i = 0; i < profile.samples.length; i++) {
+      const cf = byId.get(profile.samples[i]).callFrame
+      if (cf.functionName === '(idle)' || cf.functionName === '(program)') continue
+      const key = where(nameOf(cf))
+      self.set(key, (self.get(key) ?? 0) + (dts[i] ?? 0) / 1000)
+    }
+    return [...self.entries()].sort((a, b) => b[1] - a[1]).slice(0, n).map(([k, v]) => `${v.toFixed(0).padStart(5)}ms ${k}`)
   }
-  return [...self.entries()].sort((a, b) => b[1] - a[1]).slice(0, n).map(([k, v]) => `${v.toFixed(0).padStart(5)}ms ${k}`)
-}
 
-/** Functions the fix plan's gated tasks name, as inclusive time (the function
- *  and everything it called) from one profile, outermost call only. */
-const WATCH = [
-  'evaluateDimensions', 'updateOverlays', 'computeElementDeviation', 'suggestRange', 'paintField',
-  'fieldHistogram', 'deviationStats', 'repaintFromElements', 'setFieldColors', 'inspect',
-  'closedPartOf', 'computeBoundsTree', 'deflectionVectors', 'smoothInSpace', 'releaseDeflect',
-]
-function watched(profile) {
-  const byId = new Map(profile.nodes.map((nd) => [nd.id, nd]))
-  const selfMs = new Map()
-  profile.samples.forEach((id, i) => selfMs.set(id, (selfMs.get(id) ?? 0) + (profile.timeDeltas[i] ?? 0) / 1000))
-  const parent = new Map()
-  for (const nd of profile.nodes) for (const c of nd.children ?? []) parent.set(c, nd.id)
-  const total = new Map()
-  const inclusive = (id) => {
-    if (total.has(id)) return total.get(id)
-    let t = selfMs.get(id) ?? 0
-    for (const c of byId.get(id).children ?? []) t += inclusive(c)
-    total.set(id, t)
-    return t
-  }
-  const out = new Map()
-  for (const nd of profile.nodes) {
-    const nm = nameOf(nd.callFrame).name.replace(/~$/, '')
-    if (!WATCH.includes(nm)) continue
-    // Only the outermost call: a function reached again through itself is counted once.
-    let p = parent.get(nd.id)
-    let nested = false
-    while (p !== undefined && !nested) {
-      nested = nameOf(byId.get(p).callFrame).name.replace(/~$/, '') === nm
-      p = parent.get(p)
+  /** Functions the fix plan's gated tasks name, as inclusive time (the function
+   *  and everything it called) from one profile, outermost call only. */
+  const WATCH = [
+    'evaluateDimensions', 'updateOverlays', 'computeElementDeviation', 'suggestRange', 'paintField',
+    'fieldHistogram', 'deviationStats', 'repaintFromElements', 'setFieldColors', 'inspect',
+    'closedPartOf', 'computeBoundsTree', 'deflectionVectors', 'smoothInSpace', 'releaseDeflect',
+  ]
+  function watched(profile) {
+    const byId = new Map(profile.nodes.map((nd) => [nd.id, nd]))
+    const selfMs = new Map()
+    profile.samples.forEach((id, i) => selfMs.set(id, (selfMs.get(id) ?? 0) + (profile.timeDeltas[i] ?? 0) / 1000))
+    const parent = new Map()
+    for (const nd of profile.nodes) for (const c of nd.children ?? []) parent.set(c, nd.id)
+    const total = new Map()
+    const inclusive = (id) => {
+      if (total.has(id)) return total.get(id)
+      let t = selfMs.get(id) ?? 0
+      for (const c of byId.get(id).children ?? []) t += inclusive(c)
+      total.set(id, t)
+      return t
+    }
+    const out = new Map()
+    for (const nd of profile.nodes) {
+      const nm = nameOf(nd.callFrame).name.replace(/~$/, '')
+      if (!WATCH.includes(nm)) continue
+      // Only the outermost call: a function reached again through itself is counted once.
+      let p = parent.get(nd.id)
+      let nested = false
+      while (p !== undefined && !nested) {
+        nested = nameOf(byId.get(p).callFrame).name.replace(/~$/, '') === nm
+        p = parent.get(p)
+      }
+      if (!nested) out.set(nm, (out.get(nm) ?? 0) + inclusive(nd.id))
     }
-    if (!nested) out.set(nm, (out.get(nm) ?? 0) + inclusive(nd.id))
+    return [...out.entries()].sort((a, b) => b[1] - a[1]).map(([k, v]) => `${v >= 1 ? v.toFixed(0) : '<1'}ms ${k}`)
   }
-  return [...out.entries()].sort((a, b) => b[1] - a[1]).map(([k, v]) => `${v >= 1 ? v.toFixed(0) : '<1'}ms ${k}`)
-}
 
-// ---- taps ---------------------------------------------------------------------
-const median = (xs) => {
-  if (!xs.length) return 0
-  const s = [...xs].sort((a, b) => a - b)
-  const m = s.length >> 1
-  return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2
-}
-const INPUT_EVENTS = ['pointerdown', 'pointerup', 'click', 'touchstart', 'touchend', 'mousedown', 'mouseup', 'keydown', 'keyup', 'input', 'change']
+  // ---- taps ---------------------------------------------------------------------
+  const median = (xs) => {
+    if (!xs.length) return 0
+    const s = [...xs].sort((a, b) => a - b)
+    const m = s.length >> 1
+    return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2
+  }
+  const INPUT_EVENTS = ['pointerdown', 'pointerup', 'click', 'touchstart', 'touchend', 'mousedown', 'mouseup', 'keydown', 'keyup', 'input', 'change']
 
-/** The control a label names, for the number fields and selects that carry no
- *  test id. */
-const labelled = (text, tag) =>
-  page.evaluateHandle(
-    (text, tag) => [...document.querySelectorAll('label.field')].find((l) => l.querySelector('span')?.textContent.trim().startsWith(text))?.querySelector(tag) ?? null,
-    text,
-    tag,
-  )
+  /** The control a label names, for the number fields and selects that carry no
+   *  test id. */
+  const labelled = (text, tag) =>
+    page.evaluateHandle(
+      (text, tag) => [...document.querySelectorAll('label.field')].find((l) => l.querySelector('span')?.textContent.trim().startsWith(text))?.querySelector(tag) ?? null,
+      text,
+      tag,
+    )
 
-/** One tap (or action) of a row, then its numbers. `profiled`: with the CPU
- *  profiler on, for the hot list; the timings of such a tap are not the row's. */
-async function once(row, profiled) {
-  if (!row.action) {
-    const el = await page.$(row.sel)
-    if (!el) return null
-    // A control off-screen in a scrolling panel is scrolled to first, as a thumb would.
-    await el.evaluate((e) => e.scrollIntoView({ block: 'center' }))
-    await sleep(300)
-  } else if (row.before) await row.before()
-  const t0 = await page.evaluate(() => {
-    window.__gl0 = { ...window.__gl }
-    return performance.now()
-  })
-  if (profiled) await cdp.send('Profiler.start')
-  if (row.action) await row.action()
-  else await page.tap(row.sel)
-  if (row.appear) await page.waitForFunction((sel) => document.querySelector(sel), { timeout: row.timeout ?? 60_000, polling: 100 }, row.appear).catch(() => {})
-  await sleep(row.settle ?? 2000)
-  const profile = profiled ? (await cdp.send('Profiler.stop')).profile : null
-  const r = await page.evaluate((t0, names) => {
-    const P = window.__perf
-    const ev = P.events.filter((e) => e.start >= t0 - 5 && names.includes(e.name))
-    const lt = P.longtasks.filter((e) => e.start >= t0)
-    const lo = P.loafs.filter((e) => e.start >= t0)
-    // Work that starts a good while after the tap's own handlers have finished:
-    // a timer the tap set, such as the recovery checkpoint.
-    const tapEnd = ev.length ? Math.max(...ev.map((e) => e.start + e.dur)) : t0 + 150
-    const late = lt.filter((e) => e.start > tapEnd + 250)
-    const scripts = {}
-    for (const f of lo) for (const s of f.scripts) {
-      const k = `${s.inv} → ${s.fn || '?'} ${s.url}`
-      scripts[k] = (scripts[k] ?? 0) + s.dur
+  /** One tap (or action) of a row, then its numbers. `profiled`: with the CPU
+   *  profiler on, for the hot list; the timings of such a tap are not the row's. */
+  async function once(row, profiled) {
+    if (!row.action) {
+      const el = await page.$(row.sel)
+      if (!el) return null
+      // A control off-screen in a scrolling panel is scrolled to first, as a thumb would.
+      await el.evaluate((e) => e.scrollIntoView({ block: 'center' }))
+      await sleep(300)
+    } else if (row.before) await row.before()
+    const t0 = await page.evaluate(() => {
+      window.__gl0 = { ...window.__gl }
+      return performance.now()
+    })
+    let profile = null
+    if (profiled) await cdp.send('Profiler.start')
+    try {
+      if (row.action) await row.action()
+      else await page.tap(row.sel)
+      if (row.appear) await page.waitForFunction((sel) => document.querySelector(sel), { timeout: row.timeout ?? 60_000, polling: 100 }, row.appear).catch(() => {})
+      await sleep(row.settle ?? 2000)
+    } finally {
+      // Stopped whatever happened above: a profiler left running would slow every timed tap after it.
+      if (profiled) profile = (await cdp.send('Profiler.stop').catch(() => null))?.profile ?? null
     }
-    const G = window.__gl, G0 = window.__gl0
-    return {
-      link: G.link - G0.link,
-      upload: (G.upload - G0.upload) / 1048576,
-      ctx: G.ctx - G0.ctx,
-      inp: ev.length ? Math.max(...ev.map((e) => e.dur)) : 0,
-      handler: ev.length ? Math.max(...ev.map((e) => e.pe - e.ps)) : 0,
-      longTotal: Math.round(lt.reduce((s, e) => s + e.dur, 0)),
-      longMax: Math.round(Math.max(0, ...lt.map((e) => e.dur))),
-      longN: lt.length,
-      lateMax: Math.round(Math.max(0, ...late.map((e) => e.dur))),
-      loafRender: Math.round(lo.reduce((s, e) => s + e.render, 0)),
-      loafStyle: Math.round(lo.reduce((s, e) => s + e.style, 0)),
-      scripts: Object.entries(scripts).sort((a, b) => b[1] - a[1]).slice(0, 4).map(([k, v]) => `${Math.round(v)}ms ${k}`),
+    const r = await page.evaluate((t0, names) => {
+      const P = window.__perf
+      const ev = P.events.filter((e) => e.start >= t0 - 5 && names.includes(e.name))
+      const lt = P.longtasks.filter((e) => e.start >= t0)
+      const lo = P.loafs.filter((e) => e.start >= t0)
+      // Work that starts a good while after the tap's own handlers have finished:
+      // a timer the tap set, such as the recovery checkpoint.
+      const tapEnd = ev.length ? Math.max(...ev.map((e) => e.start + e.dur)) : t0 + 150
+      const late = lt.filter((e) => e.start > tapEnd + 250)
+      const scripts = {}
+      for (const f of lo) for (const s of f.scripts) {
+        const k = `${s.inv} → ${s.fn || '?'} ${s.url}`
+        scripts[k] = (scripts[k] ?? 0) + s.dur
+      }
+      const G = window.__gl, G0 = window.__gl0
+      return {
+        seen: P.seen.filter((t) => t >= t0 - 5).length,
+        link: G.link - G0.link,
+        upload: (G.upload - G0.upload) / 1048576,
+        ctx: G.ctx - G0.ctx,
+        inp: ev.length ? Math.max(...ev.map((e) => e.dur)) : 0,
+        handler: ev.length ? Math.max(...ev.map((e) => e.pe - e.ps)) : 0,
+        longTotal: Math.round(lt.reduce((s, e) => s + e.dur, 0)),
+        longMax: Math.round(Math.max(0, ...lt.map((e) => e.dur))),
+        longN: lt.length,
+        lateMax: Math.round(Math.max(0, ...late.map((e) => e.dur))),
+        loafRender: Math.round(lo.reduce((s, e) => s + e.render, 0)),
+        loafStyle: Math.round(lo.reduce((s, e) => s + e.style, 0)),
+        scripts: Object.entries(scripts).sort((a, b) => b[1] - a[1]).slice(0, 4).map(([k, v]) => `${Math.round(v)}ms ${k}`),
+      }
+    }, t0, INPUT_EVENTS)
+    if (profile) {
+      r.hot = hot(profile)
+      r.watch = watched(profile)
     }
-  }, t0, INPUT_EVENTS)
-  if (profile) {
-    r.hot = hot(profile)
-    r.watch = watched(profile)
+    return r
   }
-  return r
-}
 
-const results = []
-const budgetFails = []
-const fmtMB = (x) => x.toFixed(1)
+  const results = []
+  const budgetFails = []
+  const fmtMB = (x) => x.toFixed(1)
 
-/** Run rows `RUNS` times round (in order, so toggles alternate and tabs go
- *  round), then once more with the profiler on. `solo`: the rows cannot repeat,
- *  so they run once, profiled. A row is `{ label, sel | action, settle, appear,
- *  timeout, optional, budget }`; `budget` is `{ links, uploadMB, contexts,
- *  longMs, inpMs, steady }` — `steady` leaves the first tap out of the GL
- *  figures (a context or program made on first use is not the budget's to
- *  count), `inpMs` is the production target's median (or `{ bare, rich }`).
- *
- *  Where the numbers come from: `inpMs` is the baseline median less 30 % — the
- *  production build for `bare`, the dev server for `rich` — for the rows the
- *  fix plan's tasks target, from the PERF_RUNS=5 baseline in the spec's
- *  "Baseline" section; a budget the baseline already breaches is the target the
- *  fixes are to reach. The GL budgets are the plan's own (links 0, uploadMB 0 or
- *  1, contexts 0) and are expected to fail until their task lands. */
-async function run(rows, { solo = false } = {}) {
-  const live = rows.map((row) => ({ row, samples: [], prof: null }))
-  const rounds = solo ? 0 : RUNS
-  for (let k = 0; k < rounds; k++) {
+  /** Run rows `RUNS` times round (in order, so toggles alternate and tabs go
+   *  round), then once more with the profiler on. `solo`: the rows cannot repeat,
+   *  so they run once, profiled. A row is `{ label, sel | action, settle, appear,
+   *  timeout, optional, budget }`; `budget` is `{ links, uploadMB, contexts,
+   *  longMs, inpMs, steady }` — `steady` leaves the first tap out of the GL
+   *  figures (a context or program made on first use is not the budget's to
+   *  count), `inpMs` is the production target's median (or `{ bare, rich }`).
+   *
+   *  The GL budgets are the plan's own (links 0, uploadMB 0 or 1, contexts 0) and
+   *  are expected to fail until their task lands; where the `inpMs` numbers come
+   *  from is said above the first group of rows that carries them. */
+  async function run(rows, { solo = false } = {}) {
+    const live = rows.map((row) => ({ row, samples: [], prof: null, first: undefined, why: null }))
+    const rounds = solo ? 0 : RUNS
+    for (let k = 0; k < rounds; k++) {
+      for (const x of live) {
+        try {
+          const s = await once(x.row, false)
+          if (s) x.samples.push(s)
+          else x.why = `${x.row.sel} not found`
+          if (k === 0) x.first = s ?? null
+        } catch (e) {
+          x.why = `failed (run ${k + 1}): ${String(e.message).split('\n')[0]}`
+          console.log(`FAILED ${x.row.label} (run ${k + 1}): ${String(e.message).split('\n')[0]}`)
+          if (k === 0) x.first = null
+        }
+      }
+    }
     for (const x of live) {
       try {
-        const s = await once(x.row, false)
-        if (s) x.samples.push(s)
+        const s = await once(x.row, true)
+        if (!s) {
+          x.why ??= `${x.row.sel} not found`
+          continue
+        }
+        x.prof = s
+        if (solo) {
+          x.samples.push(s)
+          x.first = s
+        }
       } catch (e) {
-        console.log(`FAILED ${x.row.label} (run ${k + 1}): ${String(e.message).split('\n')[0]}`)
+        x.why ??= `failed (profiled): ${String(e.message).split('\n')[0]}`
+        console.log(`FAILED ${x.row.label} (profiled): ${String(e.message).split('\n')[0]}`)
       }
     }
-  }
-  for (const x of live) {
-    try {
-      const s = await once(x.row, true)
-      if (!s) continue
-      x.prof = s
-      if (solo) x.samples.push(s)
-    } catch (e) {
-      console.log(`FAILED ${x.row.label} (profiled): ${String(e.message).split('\n')[0]}`)
+    for (const x of live) {
+      if (x.samples.length) report(x.row, x.samples, x.prof, solo, x.first ?? null)
+      else {
+        if (!x.row.optional) console.log(`SKIP ${x.row.label}: ${x.why ?? 'no sample taken'}`)
+        // A row with a budget that took no sample has not met it: a degraded run must not pass.
+        const b = x.row.budget ?? {}
+        if (!x.row.optional && Object.entries(b).some(([k, v]) => k !== 'steady' && v !== undefined)) budgetFails.push(`BUDGET FAIL: ${x.row.label}: row not measured (${x.why ?? 'no sample taken'})`)
+      }
     }
   }
-  for (const x of live) {
-    if (x.samples.length) report(x.row, x.samples, x.prof, solo)
-    else if (!x.row.optional) console.log(`SKIP ${x.row.label}: ${x.row.sel ?? 'no sample taken'} not found`)
-  }
-}
 
-function report(row, samples, prof, solo) {
-  const n = samples.length
-  const m = (f) => median(samples.map(f))
-  const first = samples[0]
-  const r = {
-    label: row.label,
-    n,
-    solo,
-    inp: m((s) => s.inp),
-    inpFirst: first.inp,
-    inpMin: Math.min(...samples.map((s) => s.inp)),
-    inpMax: Math.max(...samples.map((s) => s.inp)),
-    handler: m((s) => s.handler),
-    longMax: m((s) => s.longMax),
-    longMaxAny: Math.max(...samples.map((s) => s.longMax)),
-    longTotal: m((s) => s.longTotal),
-    lateMax: m((s) => s.lateMax),
-    lateMaxAny: Math.max(...samples.map((s) => s.lateMax)),
-    loafRender: m((s) => s.loafRender),
-    loafStyle: m((s) => s.loafStyle),
-    link: Math.max(...samples.map((s) => s.link)),
-    upload: Math.max(...samples.map((s) => s.upload)),
-    ctx: Math.max(...samples.map((s) => s.ctx)),
-    first: { link: first.link, upload: first.upload, ctx: first.ctx },
-    steady: samples.length > 1 ? { link: Math.max(...samples.slice(1).map((s) => s.link)), upload: Math.max(...samples.slice(1).map((s) => s.upload)), ctx: Math.max(...samples.slice(1).map((s) => s.ctx)) } : null,
-    hot: prof?.hot ?? [],
-    watch: prof?.watch ?? [],
-    scripts: (prof ?? first).scripts,
-  }
-  // ---- budgets ----
-  const b = row.budget ?? {}
-  const gl = b.steady ? r.steady : { link: r.link, upload: r.upload, ctx: r.ctx }
-  const breaches = []
-  if (gl) {
-    if (b.links !== undefined && gl.link > b.links) breaches.push(`${gl.link} shader links, budget ${b.links}${b.steady ? ' (after the first tap)' : ''}`)
-    if (b.uploadMB !== undefined && gl.upload > b.uploadMB + 0.05) breaches.push(`${fmtMB(gl.upload)} MB uploaded, budget ${b.uploadMB}${b.steady ? ' (after the first tap)' : ''}`)
-    if (b.contexts !== undefined && gl.ctx > b.contexts) breaches.push(`${gl.ctx} new WebGL contexts, budget ${b.contexts}${b.steady ? ' (after the first tap)' : ''}`)
-  } else if (b.steady && (b.links !== undefined || b.uploadMB !== undefined || b.contexts !== undefined)) {
-    console.log(`  (budget on ${row.label}: after-the-first-tap figures need PERF_RUNS >= 2 — not checked)`)
-    r.unchecked = true
+  function report(row, samples, prof, solo, first) {
+    const n = samples.length
+    const m = (f) => median(samples.map(f))
+    // Every tap after run 1 (all of them when run 1 itself did not take).
+    const later = first ? samples.filter((s) => s !== first) : samples
+    const r = {
+      label: row.label,
+      n,
+      solo,
+      inp: m((s) => s.inp),
+      inpFirst: first ? first.inp : null,
+      seen: median(samples.map((s) => s.seen)),
+      inpMin: Math.min(...samples.map((s) => s.inp)),
+      inpMax: Math.max(...samples.map((s) => s.inp)),
+      handler: m((s) => s.handler),
+      longMax: m((s) => s.longMax),
+      longMaxAny: Math.max(...samples.map((s) => s.longMax)),
+      longTotal: m((s) => s.longTotal),
+      lateMax: m((s) => s.lateMax),
+      lateMaxAny: Math.max(...samples.map((s) => s.lateMax)),
+      loafRender: m((s) => s.loafRender),
+      loafStyle: m((s) => s.loafStyle),
+      link: Math.max(...samples.map((s) => s.link)),
+      upload: Math.max(...samples.map((s) => s.upload)),
+      ctx: Math.max(...samples.map((s) => s.ctx)),
+      first: first ? { link: first.link, upload: first.upload, ctx: first.ctx } : null,
+      steady: later.length ? { link: Math.max(...later.map((s) => s.link)), upload: Math.max(...later.map((s) => s.upload)), ctx: Math.max(...later.map((s) => s.ctx)) } : null,
+      hot: prof?.hot ?? [],
+      watch: prof?.watch ?? [],
+      scripts: (prof ?? first).scripts,
+    }
+    // ---- budgets ----
+    const b = row.budget ?? {}
+    const gl = b.steady ? r.steady : { link: r.link, upload: r.upload, ctx: r.ctx }
+    const breaches = []
+    if (gl) {
+      if (b.links !== undefined && gl.link > b.links) breaches.push(`${gl.link} shader links, budget ${b.links}${b.steady ? ' (after the first tap)' : ''}`)
+      if (b.uploadMB !== undefined && gl.upload > b.uploadMB + 0.05) breaches.push(`${fmtMB(gl.upload)} MB uploaded, budget ${b.uploadMB}${b.steady ? ' (after the first tap)' : ''}`)
+      if (b.contexts !== undefined && gl.ctx > b.contexts) breaches.push(`${gl.ctx} new WebGL contexts, budget ${b.contexts}${b.steady ? ' (after the first tap)' : ''}`)
+    } else if (b.steady && (b.links !== undefined || b.uploadMB !== undefined || b.contexts !== undefined)) {
+      console.log(`  (budget on ${row.label}: after-the-first-tap figures need PERF_RUNS >= 2 — not checked)`)
+      r.unchecked = true
+    }
+    if (b.longMs !== undefined && r.longMaxAny > b.longMs) breaches.push(`long task max ${r.longMaxAny} ms, budget ${b.longMs}`)
+    const inpB = inpBudget(b.inpMs)
+    if (inpB !== undefined && RUNS >= 5 && !solo && r.inp > inpB) breaches.push(`median INP ${Math.round(r.inp)} ms, budget ${inpB}`)
+    if (inpB !== undefined && RUNS >= 5 && !solo && r.inp === 0 && r.seen === 0) breaches.push('no input event reached the page, so no INP was measured')
+    if (inpB !== undefined && RUNS < 5 && !solo) r.unchecked = true
+    r.budget = { ...b, inpMs: inpB }
+    r.breaches = breaches
+    for (const x of breaches) budgetFails.push(`BUDGET FAIL: ${row.label}: ${x}`)
+    results.push(r)
+    // ---- print ----
+    const spread = n > 1 ? ` (min ${Math.round(r.inpMin)}, max ${Math.round(r.inpMax)}, first ${r.inpFirst === null ? 'n/a (run 1 failed)' : Math.round(r.inpFirst)})` : ''
+    console.log(`\n## ${row.label}  [${solo ? 'n=1, single profiled run' : `n=${n}, median; profiled run separate`}]`)
+    console.log(`  INP ${Math.round(r.inp)}ms${spread} (handler ${Math.round(r.handler)}ms) | long tasks: max ${r.longMax}ms (worst ${r.longMaxAny}ms), total ${r.longTotal}ms | late long task (>250ms after the tap) ${r.lateMax}ms (worst ${r.lateMaxAny}ms) | LoAF render ${r.loafRender}ms style/layout ${r.loafStyle}ms`)
+    console.log(`  GL (worst tap): ${r.link} shader links, ${fmtMB(r.upload)} MB uploaded, ${r.ctx} new contexts | first tap: ${r.first ? `${r.first.link} links, ${fmtMB(r.first.upload)} MB, ${r.first.ctx} ctx` : 'n/a (run 1 failed)'}`)
+    const bs = Object.entries({ ...b, inpMs: inpB }).filter(([, v]) => v !== undefined && v !== false).map(([k, v]) => `${k} ${v === true ? 'yes' : v}`)
+    if (bs.length) console.log(`  budget: ${bs.join(', ')} -> ${breaches.length ? 'FAIL' : 'ok'}`)
+    for (const s of r.scripts) console.log('   loaf:', s)
+    for (const h of r.hot) console.log('   cpu:', h)
+    if (prof) console.log('   watched (inclusive):', r.watch.length ? r.watch.join(', ') : 'none sampled', ['evaluateDimensions', 'updateOverlays', 'computeElementDeviation'].filter((w) => !r.watch.some((x) => x.endsWith(' ' + w))).map((w) => `| ${w}: not sampled`).join(' '))
   }
-  if (b.longMs !== undefined && r.longMaxAny > b.longMs) breaches.push(`long task max ${r.longMaxAny} ms, budget ${b.longMs}`)
-  const inpB = inpBudget(b.inpMs)
-  if (inpB !== undefined && RUNS >= 5 && !solo && r.inp > inpB) breaches.push(`median INP ${Math.round(r.inp)} ms, budget ${inpB}`)
-  if (inpB !== undefined && RUNS < 5 && !solo) r.unchecked = true
-  r.budget = { ...b, inpMs: inpB }
-  r.breaches = breaches
-  for (const x of breaches) budgetFails.push(`BUDGET FAIL: ${row.label}: ${x}`)
-  results.push(r)
-  // ---- print ----
-  const spread = n > 1 ? ` (min ${Math.round(r.inpMin)}, max ${Math.round(r.inpMax)}, first ${Math.round(r.inpFirst)})` : ''
-  console.log(`\n## ${row.label}  [${solo ? 'n=1, single profiled run' : `n=${n}, median; profiled run separate`}]`)
-  console.log(`  INP ${Math.round(r.inp)}ms${spread} (handler ${Math.round(r.handler)}ms) | long tasks: max ${r.longMax}ms (worst ${r.longMaxAny}ms), total ${r.longTotal}ms | late long task (>250ms after the tap) ${r.lateMax}ms (worst ${r.lateMaxAny}ms) | LoAF render ${r.loafRender}ms style/layout ${r.loafStyle}ms`)
-  console.log(`  GL (worst tap): ${r.link} shader links, ${fmtMB(r.upload)} MB uploaded, ${r.ctx} new contexts | first tap: ${r.first.link} links, ${fmtMB(r.first.upload)} MB, ${r.first.ctx} ctx`)
-  const bs = Object.entries({ ...b, inpMs: inpB }).filter(([, v]) => v !== undefined && v !== false).map(([k, v]) => `${k} ${v === true ? 'yes' : v}`)
-  if (bs.length) console.log(`  budget: ${bs.join(', ')} -> ${breaches.length ? 'FAIL' : 'ok'}`)
-  for (const s of r.scripts) console.log('   loaf:', s)
-  for (const h of r.hot) console.log('   cpu:', h)
-  if (prof) console.log('   watched (inclusive):', r.watch.length ? r.watch.join(', ') : 'none sampled', ['evaluateDimensions', 'updateOverlays', 'computeElementDeviation'].filter((w) => !r.watch.some((x) => x.endsWith(' ' + w))).map((w) => `| ${w}: not sampled`).join(' '))
-}
 
-const shot = (n) => page.screenshot({ path: OUT + n + '.png' })
-const tab = (id) => `[data-test=${id}]`
-/** A tab row. */
-const tabRow = (label, id, extra = {}) => ({ label, sel: tab(id), settle: 1500, ...extra })
+  const shot = (n) => page.screenshot({ path: OUT + n + '.png' })
+  const tab = (id) => `[data-test=${id}]`
+  /** A tab row. */
+  const tabRow = (label, id, extra = {}) => ({ label, sel: tab(id), settle: 1500, ...extra })
 
-// ---- driving the in-page command registry (dev server, rich scenario) ---------------
-/** Run an in-page snippet with `runCommand` at hand; the registry is the one the
- *  app's agent bridge uses, its core commands registered on demand. */
-const inApp = (body) =>
-  page.evaluate(
-    `(async () => {
-      const { runCommand } = await import('/src/commands/registry.ts')
-      await (await import('/src/commands/core.ts')).registerCoreCommands()
-      ${body}
-    })()`,
-  )
+  // ---- driving the in-page command registry (dev server, rich scenario) ---------------
+  /** Run an in-page snippet with `runCommand` at hand; the registry is the one the
+   *  app's agent bridge uses, its core commands registered on demand. */
+  const inApp = (body) =>
+    page.evaluate(
+      `(async () => {
+        const { runCommand } = await import('/src/commands/registry.ts')
+        await (await import('/src/commands/core.ts')).registerCoreCommands()
+        ${body}
+      })()`,
+    )
 
-/** Six elements, four dimensions and a section on the loaded scan — what a
- *  working session holds and the bare sample lacks. The sample has no sphere
- *  (a sphere fit on it comes back as a junk R190 or refuses), so the elements
- *  are the planes and cylinders it does have; the answer says what came to be. */
-async function buildRichProject() {
-  return inApp(`
-    const log = []
-    const tryRun = async (what, name, input) => {
-      try { return await runCommand(name, input) } catch (e) { log.push(what + ' refused: ' + String(e.message).slice(0, 90)); return null }
-    }
-    const seg = await runCommand('scan.segment', { limit: 130 })
-    const ids = { plane: [], cylinder: [], sphere: [] }
-    // Planes from the three largest flat regions that are not curved.
-    for (const r of seg.regions.filter((r) => !r.curved).slice(0, 3)) {
-      const e = await tryRun('plane', 'element.fit', { kind: 'plane', at: { point: r.point } })
-      if (e) ids.plane.push(e.element.id)
-    }
-    // Cylinders from the surfaces the segmentation says are one curved face cut into strips.
-    for (const run of seg.curvedRuns.slice(0, 3)) {
-      await runCommand('scan.segment', { limit: 130, mark: run.regions })
-      const e = await tryRun('cylinder', 'element.fit_marked', { kind: 'cylinder', marked: true })
-      if (e) ids.cylinder.push(e.element.id)
-    }
-    // Spheres, if the scan has any: seeded on the curved regions, a radius a part would have.
-    for (const r of seg.regions.filter((r) => r.curved).slice(0, 4)) {
-      if (ids.sphere.length >= 2) break
-      for (const side of ['outside', 'inside']) {
-        const e = await tryRun('sphere', 'element.fit', { kind: 'sphere', at: { point: r.point }, side, radius: { min: 2, max: 40 } })
-        if (e) { ids.sphere.push(e.element.id); break }
+  /** Six elements, four dimensions and a section on the loaded scan — what a
+   *  working session holds and the bare sample lacks. The sample has no sphere
+   *  (a sphere fit on it comes back as a junk R190 or refuses), so the elements
+   *  are the planes and cylinders it does have; the answer says what came to be. */
+  async function buildRichProject() {
+    return inApp(`
+      const log = []
+      const tryRun = async (what, name, input) => {
+        try { return await runCommand(name, input) } catch (e) { log.push(what + ' refused: ' + String(e.message).slice(0, 90)); return null }
       }
-    }
-    const dims = []
-    const e = [...ids.plane, ...ids.cylinder, ...ids.sphere]
-    const [p0, p1, p2] = ids.plane, [c0, c1, c2] = ids.cylinder
-    // Pairs the scan's own features make a dimension of: planes at an angle refuse a distance, so
-    // each pair is tried and the first four that take are kept.
-    const pairs = [[p0, p1], [c0, c1], [p0, c0], [p1, p2], [p0, p2], [c0, c2], [p1, c1], [p2, c2], [e[0], e[e.length - 1]]]
-    for (const [a, b] of pairs) {
-      if (dims.length >= 4) break
-      if (a === undefined || b === undefined || a === b) continue
-      const d = await tryRun('dimension', 'dimension.add', { refs: [a, b] })
-      if (d) dims.push(d.dimension.id ?? true)
-    }
-    let section = null
-    const across = [[ids.plane[0], 3], ['XZ', 0], ['XY', 0], ['YZ', 0]]
-    for (const [a, offset] of across) {
-      if (a === undefined) continue
-      const s = await tryRun('section', 'section.cut', { across: a, offset })
-      if (s) { section = s.section; break }
-    }
-    return { elements: ids, dimensions: dims.length, section: section ? 'cut' : 'none', log }
-  `)
-}
-
-/** Pin deviation probes on the part, up to five: a pinned reading is project
- *  content that is drawn, labelled and re-drawn on every tab and map change. A
- *  new reference, source or map side clears them, so each group tops them up. */
-async function ensureProbes() {
-  if (!rich) return
-  await page.evaluate(`(async () => {
-    const { useDeviation } = await import('/src/state/deviationStore.ts')
-    const { runCommand } = await import('/src/commands/registry.ts')
-    const have = useDeviation.getState().probes.length
-    if (have >= 5) return
-    await (await import('/src/commands/core.ts')).registerCoreCommands()
-    const q = await runCommand('scan.query', { box: { min: [-1e4, -1e4, -1e4], max: [1e4, 1e4, 1e4] }, limit: 40 })
-    const stride = Math.max(1, Math.floor(q.points.length / 5))
-    for (let i = have; i < 5; i++) useDeviation.getState().addProbe(q.points[Math.min(q.points.length - 1, i * stride)], 0.02 * (i - 2))
-  })()`)
-}
+      const seg = await runCommand('scan.segment', { limit: 130 })
+      const ids = { plane: [], cylinder: [], sphere: [] }
+      // Planes from the three largest flat regions that are not curved.
+      for (const r of seg.regions.filter((r) => !r.curved).slice(0, 3)) {
+        const e = await tryRun('plane', 'element.fit', { kind: 'plane', at: { point: r.point } })
+        if (e) ids.plane.push(e.element.id)
+      }
+      // Cylinders from the surfaces the segmentation says are one curved face cut into strips.
+      for (const run of seg.curvedRuns.slice(0, 3)) {
+        await runCommand('scan.segment', { limit: 130, mark: run.regions })
+        const e = await tryRun('cylinder', 'element.fit_marked', { kind: 'cylinder', marked: true })
+        if (e) ids.cylinder.push(e.element.id)
+      }
+      // Spheres, if the scan has any: seeded on the curved regions, a radius a part would have.
+      for (const r of seg.regions.filter((r) => r.curved).slice(0, 4)) {
+        if (ids.sphere.length >= 2) break
+        for (const side of ['outside', 'inside']) {
+          const e = await tryRun('sphere', 'element.fit', { kind: 'sphere', at: { point: r.point }, side, radius: { min: 2, max: 40 } })
+          if (e) { ids.sphere.push(e.element.id); break }
+        }
+      }
+      const dims = []
+      const e = [...ids.plane, ...ids.cylinder, ...ids.sphere]
+      const [p0, p1, p2] = ids.plane, [c0, c1, c2] = ids.cylinder
+      // Pairs the scan's own features make a dimension of: planes at an angle refuse a distance, so
+      // each pair is tried and the first four that take are kept.
+      const pairs = [[p0, p1], [c0, c1], [p0, c0], [p1, p2], [p0, p2], [c0, c2], [p1, c1], [p2, c2], [e[0], e[e.length - 1]]]
+      for (const [a, b] of pairs) {
+        if (dims.length >= 4) break
+        if (a === undefined || b === undefined || a === b) continue
+        const d = await tryRun('dimension', 'dimension.add', { refs: [a, b] })
+        if (d) dims.push(d.dimension.id ?? true)
+      }
+      let section = null
+      const across = [[ids.plane[0], 3], ['XZ', 0], ['XY', 0], ['YZ', 0]]
+      for (const [a, offset] of across) {
+        if (a === undefined) continue
+        const s = await tryRun('section', 'section.cut', { across: a, offset })
+        if (s) { section = s.section; break }
+      }
+      return { elements: ids, dimensions: dims.length, section: section ? 'cut' : 'none', log }
+    `)
+  }
 
-// ---- start: the scan ------------------------------------------------------------
-await shot('00-start')
-await run([{ label: 'Close support card', sel: '[data-test=support-card] .sc-x', settle: 800, optional: true }], { solo: true })
-await run(
-  [{
-    label: 'Open sample scan',
-    action: async () => (await page.$('[data-test=start-scan] input[type=file], input[type=file]')).uploadFile(SAMPLE),
-    appear: '.file-info', settle: 4000, timeout: 300_000,
-    // Plan task 15: the load's main-thread BVH build goes to the worker.
-    budget: { longMs: 150 },
-  }],
-  { solo: true },
-)
-const fileInfo = await page.$eval('.file-info', (el) => el.textContent.replace(/\s+/g, ' ').trim())
-console.log('\nloaded:', fileInfo)
-await shot('01-loaded')
-if (rich) {
-  const made = await buildRichProject()
-  console.log('rich project:', JSON.stringify(made))
-  await sleep(1500)
-  await shot('01b-rich')
-}
+  /** Pin deviation probes on the part, up to five: a pinned reading is project
+   *  content that is drawn, labelled and re-drawn on every tab and map change. A
+   *  new reference, source or map side clears them, so each group tops them up. */
+  async function ensureProbes() {
+    if (!rich) return
+    const pinned = await page.evaluate(`(async () => {
+      const { useDeviation } = await import('/src/state/deviationStore.ts')
+      const { runCommand } = await import('/src/commands/registry.ts')
+      const have = useDeviation.getState().probes.length
+      if (have >= 5) return have
+      await (await import('/src/commands/core.ts')).registerCoreCommands()
+      const q = await runCommand('scan.query', { box: { min: [-1e4, -1e4, -1e4], max: [1e4, 1e4, 1e4] }, limit: 40 })
+      const stride = Math.max(1, Math.floor(q.points.length / 5))
+      for (let i = have; i < 5; i++) useDeviation.getState().addProbe(q.points[Math.min(q.points.length - 1, i * stride)], 0.02 * (i - 2))
+      return useDeviation.getState().probes.length
+    })()`)
+    probesPinned = Math.min(probesPinned, pinned)
+  }
+  /** The fewest probes any group had on the stage (rich scenario). */
+  let probesPinned = Infinity
 
-// ---- workspace tabs: the scan (and, rich, its project) only ---------------------------
-const tabs = await page.$$eval('[data-test^=workspace-]', (els) => els.map((e) => e.dataset.test))
-console.log('\ntabs:', tabs.join(', '))
-const PLUGIN_TABS = tabs.filter((t) => !['workspace-elements', 'workspace-deviation', 'workspace-thickness', 'workspace-flat'].includes(t))
-await run([
-  // Budgets (production, bare; the rich ones are the dev baseline's own): the median − 30 %,
-  // for the rows the fix plan's tasks name — set from perf-baseline-v2.txt.
-  tabRow('Tab → Surface Deviation (scan only)', 'workspace-deviation', { budget: { inpMs: { bare: 45, rich: 73 } } }),
-  tabRow('Tab → Wall Thickness', 'workspace-thickness', { budget: { inpMs: { bare: 45, rich: 56 } } }),
-  tabRow('Tab → 2D Measure', 'workspace-flat', {
-    settle: 2000,
-    // Plan task 6: the 2D viewer is kept alive after its first open, so no later tap makes a context.
-    budget: { contexts: 0, steady: true, inpMs: { bare: 50, rich: 106 } },
-  }),
-  ...PLUGIN_TABS.map((t) => tabRow(`Tab → ${t} (plugin)`, t, { settle: 3000, budget: t === 'workspace-reverse' ? { inpMs: { bare: 50, rich: 129 }, links: 0 } : undefined })),
-  tabRow('Tab → 3D Measure', 'workspace-elements', { budget: { inpMs: { bare: 45, rich: 146 }, links: 0 } }),
-])
-await shot('04-measure')
+  // ---- start: the scan ------------------------------------------------------------
+  await shot('00-start')
+  await run([{ label: 'Close support card', sel: '[data-test=support-card] .sc-x', settle: 800, optional: true }], { solo: true })
+  await run(
+    [{
+      label: 'Open sample scan',
+      action: async () => (await page.$('[data-test=start-scan] input[type=file], input[type=file]')).uploadFile(SAMPLE),
+      appear: '.file-info', settle: 4000, timeout: 300_000,
+      // Plan task 15: the load's main-thread BVH build goes to the worker.
+      budget: { longMs: 150 },
+    }],
+    { solo: true },
+  )
+  const fileInfo = await page.$eval('.file-info', (el) => el.textContent.replace(/\s+/g, ' ').trim())
+  console.log('\nloaded:', fileInfo)
+  await shot('01-loaded')
+  if (rich) {
+    const made = await buildRichProject()
+    console.log('rich project:', JSON.stringify(made))
+    const elementCount = Object.values(made.elements).reduce((n, ids) => n + ids.length, 0)
+    if (elementCount < 6) budgetFails.push(`BUDGET FAIL: rich scenario: ${elementCount} elements made, 6 wanted`)
+    if (made.dimensions < 4) budgetFails.push(`BUDGET FAIL: rich scenario: ${made.dimensions} dimensions made, 4 wanted`)
+    if (made.section !== 'cut') budgetFails.push('BUDGET FAIL: rich scenario: no section was cut')
+    await sleep(1500)
+    await shot('01b-rich')
+  }
 
-// ---- thickness ----------------------------------------------------------------------
-await page.tap(tab('workspace-thickness'))
-await sleep(1500)
-await run([{ label: 'Thickness: Measure', sel: '[data-test=measure-thickness]', appear: '[data-test=thickness-legend]', settle: 3000, timeout: 300_000 }], { solo: true })
-await shot('03-thickness')
-// The thickness map has no key of its own on the view bar; the Scan key in
-// [data-test=part-keys] is the one the view bar has here, and it hides the
-// scan the map is painted on.
-const bandsSelect = async (dir) => {
-  const el = await labelled('Bands', 'select')
-  await el.asElement().focus()
-  await page.keyboard.press(dir)
-}
-await run([
-  { label: 'Thickness: scan key off (view bar)', sel: '[data-test=part-keys] [data-test=toggle-scan]', settle: 1500 },
-  { label: 'Thickness: scan key on (view bar)', sel: '[data-test=part-keys] [data-test=toggle-scan]', settle: 1500 },
-])
-await run([
-  { label: 'Thickness: bands on (5 bands)', action: () => bandsSelect('ArrowDown'), before: async () => (await labelled('Bands', 'select')).asElement()?.evaluate((e) => e.scrollIntoView({ block: 'center' })), settle: 1500 },
-  { label: 'Thickness: bands off (continuous)', action: () => bandsSelect('ArrowUp'), before: async () => (await labelled('Bands', 'select')).asElement()?.evaluate((e) => e.scrollIntoView({ block: 'center' })), settle: 1500 },
-])
-await run([
-  { label: 'Thickness: histogram off', sel: '[data-test=toggle-thickness-histogram]', settle: 1500 },
-  { label: 'Thickness: histogram on', sel: '[data-test=toggle-thickness-histogram]', settle: 1500 },
-])
+  // ---- workspace tabs: the scan (and, rich, its project) only ---------------------------
+  const tabs = await page.$$eval('[data-test^=workspace-]', (els) => els.map((e) => e.dataset.test))
+  console.log('\ntabs:', tabs.join(', '))
+  const PLUGIN_TABS = tabs.filter((t) => !['workspace-elements', 'workspace-deviation', 'workspace-thickness', 'workspace-flat'].includes(t))
+  await run([
+    // The `inpMs` budgets, here and below: round(0.7 × median) of the SAVED baseline in
+    // e2e-out/perf-baseline-v2.txt (and the spec's v2 table) — `bare` from its production section,
+    // `rich` from its dev rich section — for the rows the fix plan's tasks target. A budget set this
+    // way is breached by the baseline itself: it is the target, and on this shared machine an
+    // advisory one (compare BASE and HEAD in one sitting). The GL budgets are the hard gate.
+    tabRow('Tab → Surface Deviation (scan only)', 'workspace-deviation', { budget: { inpMs: { bare: 50, rich: 123 } } }),
+    tabRow('Tab → Wall Thickness', 'workspace-thickness', { budget: { inpMs: { bare: 50, rich: 106 } } }),
+    tabRow('Tab → 2D Measure', 'workspace-flat', {
+      settle: 2000,
+      // Plan task 6: the 2D viewer is kept alive after its first open, so no later tap makes a context.
+      budget: { contexts: 0, steady: true, inpMs: { bare: 62, rich: 185 } },
+    }),
+    ...PLUGIN_TABS.map((t) => tabRow(`Tab → ${t} (plugin)`, t, { settle: 3000, budget: t === 'workspace-reverse' ? { inpMs: { bare: 67, rich: 218 }, links: 0 } : undefined })),
+    tabRow('Tab → 3D Measure', 'workspace-elements', { budget: { inpMs: { bare: 56, rich: 235 }, links: 0 } }),
+  ])
+  await shot('04-measure')
 
-// ---- deviation against the same part as reference --------------------------------
-await page.tap(tab('workspace-deviation'))
-await sleep(1500)
-await run([{
-  label: 'Deviation: load reference',
-  action: async () => (await page.$('[data-test=slot-reference] input[type=file]')).uploadFile(SAMPLE),
-  appear: '[data-test=align-auto]:not([disabled])', settle: 2000, timeout: 300_000,
-}], { solo: true })
-// The reference is loaded and has been shown only where it was loaded: the first
-// time it is shown again after a tab switch, which is the first row below.
-await run([
-  tabRow('Tab → 3D Measure (reference loaded)', 'workspace-elements', { budget: { inpMs: { bare: 39, rich: 140 }, links: 0 } }),
-  tabRow('Tab → Surface Deviation (first show of the reference)', 'workspace-deviation', { settle: 3000 }),
-])
-await run([{ label: 'Deviation: Auto best fit → map', sel: '[data-test=align-auto]', appear: '[data-test=deviation-legend]', settle: 4000, timeout: 300_000 }], { solo: true })
-await shot('05-deviation-map')
-await ensureProbes()
-await run([
-  { label: 'Deviation: map off', sel: '[data-test=toggle-colormap]', settle: 1500, budget: { links: 0 } },
-  // Plan task 2: a colour buffer that did not change is not uploaded again.
-  { label: 'Deviation: map on', sel: '[data-test=toggle-colormap]', settle: 1500, budget: { links: 0, uploadMB: 0 } },
-])
-await ensureProbes()
-await run([
-  // Plan task 6: the split view's second viewport is kept after its first open.
-  { label: 'Deviation: split on', sel: '[data-test=toggle-split]', settle: 3000, budget: { contexts: 0, steady: true, inpMs: { bare: 50, rich: 101 } } },
-  { label: 'Deviation: split off', sel: '[data-test=toggle-split]', settle: 2000 },
-])
-await shot('06-split')
-await ensureProbes()
-await run([
-  // Plan task 5: its programs are warm by the time anyone taps it.
-  { label: 'Deviation: map on reference', sel: '[data-test=toggle-map-on-reference]', settle: 4000, timeout: 300_000, budget: { links: 0 } },
-  { label: 'Deviation: map back on scan', sel: '[data-test=toggle-map-on-reference]', settle: 2000 },
-])
-await ensureProbes()
-await run([
-  { label: 'Deviation: histogram off', sel: '[data-test=toggle-histogram]', settle: 1500 },
-  { label: 'Deviation: histogram on', sel: '[data-test=toggle-histogram]', settle: 1500 },
-])
-const rangeStep = (dir) => async () => {
-  const el = await page.$('[data-test=range-slider]')
-  await el.focus()
-  await page.keyboard.press(dir)
-}
-const toleranceTo = (v) => async () => {
-  const el = (await labelled('Tolerance', 'input')).asElement()
-  await el.tap()
-  await page.keyboard.down('Control')
-  await page.keyboard.press('a')
-  await page.keyboard.up('Control')
-  await page.keyboard.type(String(v))
-  await page.keyboard.press('Enter')
-}
-const scrollTo = (sel) => async () => (await page.$(sel))?.evaluate((e) => e.scrollIntoView({ block: 'center' }))
-// Which way the first step goes: into the track, whichever end the range sits at.
-const towardsMiddle = await page.$eval('[data-test=range-slider]', (e) => (Number(e.value) < (Number(e.min) + Number(e.max)) / 2 ? ['ArrowRight', 'ArrowLeft'] : ['ArrowLeft', 'ArrowRight']))
-await run([
-  // The slider's key steps: one notch of the log scale is one repaint of the map and its figures.
-  { label: 'Deviation: range slider step 1', action: rangeStep(towardsMiddle[0]), before: scrollTo('[data-test=range-slider]'), settle: 1500, budget: { inpMs: { bare: 39, rich: 95 } } },
-  { label: 'Deviation: range slider step 2 (back)', action: rangeStep(towardsMiddle[1]), before: scrollTo('[data-test=range-slider]'), settle: 1500, budget: { inpMs: { bare: 39, rich: 112 } } },
-])
-const tolField = () => labelled('Tolerance', 'input').then((h) => h.asElement()?.evaluate((e) => e.scrollIntoView({ block: 'center' })))
-await run([
-  { label: 'Deviation: tolerance change (0.05)', action: toleranceTo(0.05), before: tolField, settle: 1500 },
-  { label: 'Deviation: tolerance change (0.08)', action: toleranceTo(0.08), before: tolField, settle: 1500 },
-])
-await ensureProbes()
-await run([
-  { label: 'Deviation: animate on', sel: '[data-test=animate-deformation]', settle: 2500 },
-  // Plan task 10: the deflect buffer is kept, so stopping the animation uploads next to nothing.
-  { label: 'Deviation: animate off', sel: '[data-test=animate-deformation]', settle: 1500, budget: { uploadMB: 1 } },
-])
-await run([{ label: 'Deviation: volume measure', sel: '[data-test=volume-measure]', appear: '[data-test=volume-show]', settle: 3000, timeout: 300_000 }], { solo: true })
-await run([
-  { label: 'Deviation: volume show on', sel: '[data-test=volume-show]', settle: 2000 },
-  { label: 'Deviation: volume show off', sel: '[data-test=volume-show]', settle: 1500 },
-])
-await ensureProbes()
-await run([
-  { label: 'Deviation: source → element', sel: '[data-test=source-element]', settle: 2000, budget: { links: 0 } },
-  { label: 'Deviation: source → reference', sel: '[data-test=source-reference]', settle: 2000, budget: { inpMs: { bare: 50, rich: 118 } } },
-])
-if (rich) {
-  // Against one of the project's own elements: the map is computed on the main
-  // thread (plan task 11), which the bare sample, with no elements, cannot show.
-  await page.tap('[data-test=source-element]')
+  // ---- thickness ----------------------------------------------------------------------
+  await page.tap(tab('workspace-thickness'))
   await sleep(1500)
-  const options = await page.$$eval('[data-test=target-select] option', (os) => os.map((o) => o.value).filter(Boolean))
-  console.log('element targets:', options.length)
-  if (options.length >= 2) {
-    const pick = (v) => async () => page.select('[data-test=target-select]', v)
-    await run([{ label: 'Deviation: choose element target (first map)', action: pick(options[0]), settle: 4000, timeout: 120_000 }], { solo: true })
-    // The select is set by the page (a native picker cannot be driven), so these two have no INP:
-    // the long task and the hot list carry the cost.
-    await run([
-      { label: 'Deviation: change element target (A)', action: pick(options[1]), settle: 4000, budget: { links: 0 } },
-      { label: 'Deviation: change element target (B)', action: pick(options[0]), settle: 4000, budget: { links: 0 } },
-    ])
-    await run([
-      { label: 'Deviation: element facing limit on', sel: '[data-test=toggle-facing]', settle: 4000, budget: { inpMs: { rich: 162 } } },
-      { label: 'Deviation: element facing limit off', sel: '[data-test=toggle-facing]', settle: 4000, budget: { inpMs: { rich: 162 } } },
-    ])
+  await run([{ label: 'Thickness: Measure', sel: '[data-test=measure-thickness]', appear: '[data-test=thickness-legend]', settle: 3000, timeout: 300_000 }], { solo: true })
+  await shot('03-thickness')
+  // The thickness map has no key of its own on the view bar; the Scan key in
+  // [data-test=part-keys] is the one the view bar has here, and it hides the
+  // scan the map is painted on.
+  const bandsSelect = async (dir) => {
+    const el = await labelled('Bands', 'select')
+    await el.asElement().focus()
+    await page.keyboard.press(dir)
   }
-  await page.tap('[data-test=source-reference]')
+  await run([
+    { label: 'Thickness: scan key off (view bar)', sel: '[data-test=part-keys] [data-test=toggle-scan]', settle: 1500 },
+    { label: 'Thickness: scan key on (view bar)', sel: '[data-test=part-keys] [data-test=toggle-scan]', settle: 1500 },
+  ])
+  await run([
+    { label: 'Thickness: bands on (5 bands)', action: () => bandsSelect('ArrowDown'), before: async () => (await labelled('Bands', 'select')).asElement()?.evaluate((e) => e.scrollIntoView({ block: 'center' })), settle: 1500 },
+    { label: 'Thickness: bands off (continuous)', action: () => bandsSelect('ArrowUp'), before: async () => (await labelled('Bands', 'select')).asElement()?.evaluate((e) => e.scrollIntoView({ block: 'center' })), settle: 1500 },
+  ])
+  await run([
+    { label: 'Thickness: histogram off', sel: '[data-test=toggle-thickness-histogram]', settle: 1500 },
+    { label: 'Thickness: histogram on', sel: '[data-test=toggle-thickness-histogram]', settle: 1500 },
+  ])
+
+  // ---- deviation against the same part as reference --------------------------------
+  await page.tap(tab('workspace-deviation'))
   await sleep(1500)
-}
-await run([
-  // Plan task 5: the first tap used to compile six programs. The plan also asks for a median of
-  // 120 ms; the warm median is already 64, so the baseline rule (median − 30 %) stands instead — the
-  // cold first tap (240 ms) is the table's "INP first" column.
-  { label: 'Deviation: section view on', sel: '[data-test=toggle-section-view]', settle: 2000, budget: { links: 0, inpMs: { bare: 45, rich: 78 } } },
-  { label: 'Deviation: section view off', sel: '[data-test=toggle-section-view]', settle: 1500 },
-])
+  await run([{
+    label: 'Deviation: load reference',
+    action: async () => (await page.$('[data-test=slot-reference] input[type=file]')).uploadFile(SAMPLE),
+    appear: '[data-test=align-auto]:not([disabled])', settle: 2000, timeout: 300_000,
+  }], { solo: true })
+  // The reference is loaded and has been shown only where it was loaded: the first
+  // time it is shown again after a tab switch is the second row's FIRST tap — its
+  // median is the warm switch, only "INP first" is the first show.
+  await run([
+    tabRow('Tab → 3D Measure (reference loaded)', 'workspace-elements', { budget: { inpMs: { bare: 56, rich: 213 }, links: 0 } }),
+    tabRow('Tab → Surface Deviation (after reference load; INP first = the first show)', 'workspace-deviation', { settle: 3000 }),
+  ])
+  await run([{ label: 'Deviation: Auto best fit → map', sel: '[data-test=align-auto]', appear: '[data-test=deviation-legend]', settle: 4000, timeout: 300_000 }], { solo: true })
+  await shot('05-deviation-map')
+  await ensureProbes()
+  await run([
+    { label: 'Deviation: map off', sel: '[data-test=toggle-colormap]', settle: 1500, budget: { links: 0 } },
+    // Plan task 2: a colour buffer that did not change is not uploaded again.
+    { label: 'Deviation: map on', sel: '[data-test=toggle-colormap]', settle: 1500, budget: { links: 0, uploadMB: 0 } },
+  ])
+  await ensureProbes()
+  await run([
+    // Plan task 6: the split view's second viewport is kept after its first open.
+    { label: 'Deviation: split on', sel: '[data-test=toggle-split]', settle: 3000, budget: { contexts: 0, steady: true, inpMs: { bare: 73, rich: 190 } } },
+    { label: 'Deviation: split off', sel: '[data-test=toggle-split]', settle: 2000 },
+  ])
+  await shot('06-split')
+  await ensureProbes()
+  await run([
+    // Plan task 5: its programs are warm by the time anyone taps it.
+    { label: 'Deviation: map on reference', sel: '[data-test=toggle-map-on-reference]', settle: 4000, timeout: 300_000, budget: { links: 0 } },
+    { label: 'Deviation: map back on scan', sel: '[data-test=toggle-map-on-reference]', settle: 2000 },
+  ])
+  await ensureProbes()
+  await run([
+    { label: 'Deviation: histogram off', sel: '[data-test=toggle-histogram]', settle: 1500 },
+    { label: 'Deviation: histogram on', sel: '[data-test=toggle-histogram]', settle: 1500 },
+  ])
+  const rangeStep = (dir) => async () => {
+    const el = await page.$('[data-test=range-slider]')
+    await el.focus()
+    await page.keyboard.press(dir)
+  }
+  const toleranceTo = (v) => async () => {
+    const el = (await labelled('Tolerance', 'input')).asElement()
+    await el.tap()
+    await page.keyboard.down('Control')
+    await page.keyboard.press('a')
+    await page.keyboard.up('Control')
+    await page.keyboard.type(String(v))
+    await page.keyboard.press('Enter')
+  }
+  const scrollTo = (sel) => async () => (await page.$(sel))?.evaluate((e) => e.scrollIntoView({ block: 'center' }))
+  // Which way the first step goes: into the track, whichever end the range sits at.
+  const towardsMiddle = await page.$eval('[data-test=range-slider]', (e) => (Number(e.value) < (Number(e.min) + Number(e.max)) / 2 ? ['ArrowRight', 'ArrowLeft'] : ['ArrowLeft', 'ArrowRight']))
+  await run([
+    // The slider's key steps: one notch of the log scale is one repaint of the map and its figures.
+    { label: 'Deviation: range slider step 1', action: rangeStep(towardsMiddle[0]), before: scrollTo('[data-test=range-slider]'), settle: 1500, budget: { inpMs: { bare: 39, rich: 168 } } },
+    { label: 'Deviation: range slider step 2 (back)', action: rangeStep(towardsMiddle[1]), before: scrollTo('[data-test=range-slider]'), settle: 1500, budget: { inpMs: { bare: 45, rich: 179 } } },
+  ])
+  const tolField = () => labelled('Tolerance', 'input').then((h) => h.asElement()?.evaluate((e) => e.scrollIntoView({ block: 'center' })))
+  await run([
+    { label: 'Deviation: tolerance change (0.05)', action: toleranceTo(0.05), before: tolField, settle: 1500 },
+    { label: 'Deviation: tolerance change (0.08)', action: toleranceTo(0.08), before: tolField, settle: 1500 },
+  ])
+  await ensureProbes()
+  await run([
+    { label: 'Deviation: animate on', sel: '[data-test=animate-deformation]', settle: 2500 },
+    // Plan task 10: the deflect buffer is kept, so stopping the animation uploads next to nothing.
+    { label: 'Deviation: animate off', sel: '[data-test=animate-deformation]', settle: 1500, budget: { uploadMB: 1 } },
+  ])
+  await run([{ label: 'Deviation: volume measure', sel: '[data-test=volume-measure]', appear: '[data-test=volume-show]', settle: 3000, timeout: 300_000 }], { solo: true })
+  await run([
+    { label: 'Deviation: volume show on', sel: '[data-test=volume-show]', settle: 2000 },
+    { label: 'Deviation: volume show off', sel: '[data-test=volume-show]', settle: 1500 },
+  ])
+  await ensureProbes()
+  await run([
+    { label: 'Deviation: source → element', sel: '[data-test=source-element]', settle: 2000, budget: { links: 0 } },
+    { label: 'Deviation: source → reference', sel: '[data-test=source-reference]', settle: 2000, budget: { inpMs: { bare: 84, rich: 157 } } },
+  ])
+  if (rich) {
+    // Against one of the project's own elements: the map is computed on the main
+    // thread (plan task 11), which the bare sample, with no elements, cannot show.
+    await page.tap('[data-test=source-element]')
+    await sleep(1500)
+    const options = await page.$$eval('[data-test=target-select] option', (os) => os.map((o) => o.value).filter(Boolean))
+    console.log('element targets:', options.length)
+    if (options.length < 2) budgetFails.push(`BUDGET FAIL: rich scenario: ${options.length} element-target options, 2 wanted (the element-map rows were not run)`)
+    if (options.length >= 2) {
+      const pick = (v) => async () => page.select('[data-test=target-select]', v)
+      await run([{ label: 'Deviation: choose element target (first map)', action: pick(options[0]), settle: 4000, timeout: 120_000 }], { solo: true })
+      // The select is set by the page (a native picker cannot be driven), so these two have no INP:
+      // the long task and the hot list carry the cost.
+      await run([
+        { label: 'Deviation: change element target (A)', action: pick(options[1]), settle: 4000, budget: { links: 0 } },
+        { label: 'Deviation: change element target (B)', action: pick(options[0]), settle: 4000, budget: { links: 0 } },
+      ])
+      await run([
+        { label: 'Deviation: element facing limit on', sel: '[data-test=toggle-facing]', settle: 4000, budget: { inpMs: { rich: 218 } } },
+        { label: 'Deviation: element facing limit off', sel: '[data-test=toggle-facing]', settle: 4000, budget: { inpMs: { rich: 185 } } },
+      ])
+    }
+    await page.tap('[data-test=source-reference]')
+    await sleep(1500)
+  }
+  await run([
+    // Plan task 5: the first tap used to compile six programs. The plan also asks for a median of
+    // 120 ms, which the warm median (104) nearly meets already, so the baseline rule stands instead —
+    // the cold first tap (416 ms) is the table's "INP first" column.
+    { label: 'Deviation: section view on', sel: '[data-test=toggle-section-view]', settle: 2000, budget: { links: 0, inpMs: { bare: 73, rich: 90 } } },
+    { label: 'Deviation: section view off', sel: '[data-test=toggle-section-view]', settle: 1500 },
+  ])
 
-// ---- switching with maps in hand ---------------------------------------------------
-await ensureProbes()
-await run([
-  tabRow('Tab → 3D Measure (maps in hand)', 'workspace-elements', { budget: { inpMs: { bare: 34, rich: 134 }, links: 0 } }),
-  // Plan task 2: a map already painted is not uploaded again on the way in.
-  tabRow('Tab → Surface Deviation (map in hand)', 'workspace-deviation', { budget: { uploadMB: 0, inpMs: { bare: 50, rich: 129 }, links: 0 } }),
-  tabRow('Tab → Wall Thickness (map in hand)', 'workspace-thickness', { budget: { uploadMB: 0, inpMs: { bare: 50, rich: 123 } } }),
-  tabRow('Tab → Surface Deviation (from thickness)', 'workspace-deviation', { budget: { inpMs: { bare: 50, rich: 118 }, links: 0 } }),
-])
-await run([
-  { label: 'Settings open', sel: '[data-test=open-settings]', settle: 1500 },
-  { label: 'Settings close', sel: '[data-test=settings-close]', settle: 1000 },
-])
+  // ---- switching with maps in hand ---------------------------------------------------
+  await ensureProbes()
+  await run([
+    tabRow('Tab → 3D Measure (maps in hand)', 'workspace-elements', { budget: { inpMs: { bare: 62, rich: 258 }, links: 0 } }),
+    // Plan task 2: a map already painted is not uploaded again on the way in.
+    tabRow('Tab → Surface Deviation (map in hand)', 'workspace-deviation', { budget: { uploadMB: 0, inpMs: { bare: 84, rich: 263 }, links: 0 } }),
+    tabRow('Tab → Wall Thickness (map in hand)', 'workspace-thickness', { budget: { uploadMB: 0, inpMs: { bare: 90, rich: 235 } } }),
+    tabRow('Tab → Surface Deviation (from thickness)', 'workspace-deviation', { budget: { inpMs: { bare: 78, rich: 252 }, links: 0 } }),
+  ])
+  await run([
+    { label: 'Settings open', sel: '[data-test=open-settings]', settle: 1500 },
+    { label: 'Settings close', sel: '[data-test=settings-close]', settle: 1000 },
+  ])
 
-// ---- rich: a brush stroke, the marking path's per-move upload --------------------------
-if (rich) {
-  await page.tap(tab('workspace-elements'))
-  await sleep(1500)
-  try {
-    await page.tap('[data-test=fit-sphere]')
-    await page.waitForSelector('[data-test=draft-select-mode]', { timeout: 10_000 })
-    await page.select('[data-test=draft-select-mode]', 'paint')
-    await page.waitForSelector('[data-test=mark-gestures]', { timeout: 10_000 })
-    await page.tap('[data-test=mark-brush]')
-    await sleep(500)
-    const rect = await page.$eval('.viewport canvas', (el) => {
-      const r = el.getBoundingClientRect()
-      return { x: r.x, y: r.y, w: r.width, h: r.height }
-    })
-    // Sweep a slow horizontal stroke through the middle of the viewport, where the part is.
-    const stroke = async () => {
-      const y = rect.y + rect.h * 0.5
-      await page.mouse.move(rect.x + rect.w * 0.3, y)
-      await page.mouse.down()
-      for (let i = 0; i <= 20; i++) {
-        await page.mouse.move(rect.x + rect.w * (0.3 + 0.02 * i), y + Math.sin(i / 3) * 6)
-        await sleep(16)
+  // ---- rich: a brush stroke, the marking path's per-move upload --------------------------
+  if (rich) {
+    await page.tap(tab('workspace-elements'))
+    await sleep(1500)
+    try {
+      await page.tap('[data-test=fit-sphere]')
+      await page.waitForSelector('[data-test=draft-select-mode]', { timeout: 10_000 })
+      await page.select('[data-test=draft-select-mode]', 'paint')
+      await page.waitForSelector('[data-test=mark-gestures]', { timeout: 10_000 })
+      await page.tap('[data-test=mark-brush]')
+      await sleep(500)
+      const rect = await page.$eval('.viewport canvas', (el) => {
+        const r = el.getBoundingClientRect()
+        return { x: r.x, y: r.y, w: r.width, h: r.height }
+      })
+      // Sweep a slow horizontal stroke through the middle of the viewport, where the part is.
+      const stroke = async () => {
+        const y = rect.y + rect.h * 0.5
+        await page.mouse.move(rect.x + rect.w * 0.3, y)
+        await page.mouse.down()
+        for (let i = 0; i <= 20; i++) {
+          await page.mouse.move(rect.x + rect.w * (0.3 + 0.02 * i), y + Math.sin(i / 3) * 6)
+          await sleep(16)
+        }
+        await page.mouse.up()
       }
-      await page.mouse.up()
+      await run([{ label: 'Brush stroke (20 moves, rich)', action: stroke, settle: 1500 }])
+      const marked = await page.$eval('[data-test=paint-count]', (e) => e.textContent.trim()).catch(() => 'n/a')
+      console.log('marked after the strokes:', marked)
+      await page.keyboard.press('Escape')
+      await page.keyboard.press('Escape')
+      await sleep(500)
+    } catch (e) {
+      console.log('SKIP brush stroke:', String(e.message).split('\n')[0])
     }
-    await run([{ label: 'Brush stroke (20 moves, rich)', action: stroke, settle: 1500 }])
-    const marked = await page.$eval('[data-test=paint-count]', (e) => e.textContent.trim()).catch(() => 'n/a')
-    console.log('marked after the strokes:', marked)
-    await page.keyboard.press('Escape')
-    await page.keyboard.press('Escape')
-    await sleep(500)
-  } catch (e) {
-    console.log('SKIP brush stroke:', String(e.message).split('\n')[0])
   }
-}
-await shot('07-end')
+  await shot('07-end')
+
+  if (rich && probesPinned < 5) budgetFails.push(`BUDGET FAIL: rich scenario: ${probesPinned === Infinity ? 'no' : probesPinned} deviation probes pinned, 5 wanted`)
 
-// ---- idle cost: what the page burns doing nothing ---------------------------------
-await page.evaluate(() => (window.__idle0 = window.__gl.raf))
-await cdp.send('Profiler.start')
-await sleep(3000)
-const idleProfile = (await cdp.send('Profiler.stop')).profile
-const idleRaf = await page.evaluate(() => window.__gl.raf - window.__idle0)
-const idleBusy = idleProfile.timeDeltas.reduce((s, d, i) => {
-  const nd = idleProfile.nodes.find((n) => n.id === idleProfile.samples[i])
-  return nd.callFrame.functionName === '(idle)' ? s : s + d
-}, 0) / 1000
-console.log(`\n## Idle (3 s, nothing touched): ${idleRaf} animation-frame callbacks ran, main thread busy ${idleBusy.toFixed(0)}ms`)
-for (const h of hot(idleProfile, 6)) console.log('   cpu:', h)
+  // ---- idle cost: what the page burns doing nothing ---------------------------------
+  await page.evaluate(() => (window.__idle0 = window.__gl.raf))
+  await cdp.send('Profiler.start')
+  await sleep(3000)
+  const idleProfile = (await cdp.send('Profiler.stop')).profile
+  const idleRaf = await page.evaluate(() => window.__gl.raf - window.__idle0)
+  const idleBusy = idleProfile.timeDeltas.reduce((s, d, i) => {
+    const nd = idleProfile.nodes.find((n) => n.id === idleProfile.samples[i])
+    return nd.callFrame.functionName === '(idle)' ? s : s + d
+  }, 0) / 1000
+  console.log(`\n## Idle (3 s, nothing touched): ${idleRaf} animation-frame callbacks ran, main thread busy ${idleBusy.toFixed(0)}ms`)
+  for (const h of hot(idleProfile, 6)) console.log('   cpu:', h)
 
-// ---- summary --------------------------------------------------------------------------
-console.log(`\n## Summary — ${isDev ? 'dev' : 'production'}, ${SCENARIO}, PERF_RUNS=${RUNS}, ${THROTTLE}x throttle, ${fileInfo}`)
-console.log('| Row | n | INP median ms | INP first ms | long max ms | late long ms | links | upload MB | new ctx | budget |')
-console.log('|---|---|---|---|---|---|---|---|---|---|')
-for (const r of results) {
-  const b = Object.entries(r.budget).filter(([, v]) => v !== undefined && v !== false).map(([k, v]) => `${k}${v === true ? '' : '=' + v}`).join(' ')
-  console.log(`| ${r.label} | ${r.solo ? '1*' : r.n} | ${Math.round(r.inp)} | ${Math.round(r.inpFirst)} | ${r.longMax} | ${r.lateMax} | ${r.link} | ${fmtMB(r.upload)} | ${r.ctx} | ${b ? (r.breaches.length ? 'FAIL ' : r.unchecked ? 'unchecked ' : 'ok ') + b : ''} |`)
+  // ---- summary --------------------------------------------------------------------------
+  console.log(`\n## Summary — ${isDev ? 'dev' : 'production'}, ${SCENARIO}, PERF_RUNS=${RUNS}, ${THROTTLE}x throttle, ${fileInfo}`)
+  console.log('| Row | n | INP median ms | INP first ms | long max ms | late long ms | links | upload MB | new ctx | budget |')
+  console.log('|---|---|---|---|---|---|---|---|---|---|')
+  for (const r of results) {
+    const b = Object.entries(r.budget).filter(([, v]) => v !== undefined && v !== false).map(([k, v]) => `${k}${v === true ? '' : '=' + v}`).join(' ')
+    console.log(`| ${r.label} | ${r.solo ? '1*' : r.n} | ${Math.round(r.inp)} | ${r.inpFirst === null ? 'n/a' : Math.round(r.inpFirst)} | ${r.longMax} | ${r.lateMax} | ${r.link} | ${fmtMB(r.upload)} | ${r.ctx} | ${b ? (r.breaches.length ? 'FAIL ' : r.unchecked ? 'unchecked ' : 'ok ') + b : ''} |`)
+  }
+  console.log('(* a row that cannot repeat: one profiled run. INP 0 = under the 16 ms Event Timing floor, or an action driven by the page rather than a tap.)')
+  console.log(`idle: ${idleRaf} frame callbacks / 3 s, main thread busy ${idleBusy.toFixed(0)}ms`)
+  writeFileSync(OUT + `results-${SCENARIO}-${isDev ? 'dev' : 'prod'}.json`, JSON.stringify(results, null, 2))
+  console.log('\nerrors:', errors.length ? errors.slice(0, 5) : 'none')
+  console.log(budgetFails.length ? `\n${budgetFails.length} budget breach${budgetFails.length > 1 ? 'es' : ''}:\n${budgetFails.join('\n')}` : '\nno budget breaches')
+  if (ASSERT && budgetFails.length) process.exitCode = 1
+} finally {
+  await browser.close()
 }
-console.log('(* a row that cannot repeat: one profiled run. INP 0 = under the 16 ms Event Timing floor, or an action driven by the page rather than a tap.)')
-console.log(`idle: ${idleRaf} frame callbacks / 3 s, main thread busy ${idleBusy.toFixed(0)}ms`)
-writeFileSync(OUT + `results-${SCENARIO}-${isDev ? 'dev' : 'prod'}.json`, JSON.stringify(results, null, 2))
-console.log('\nerrors:', errors.length ? errors.slice(0, 5) : 'none')
-console.log(budgetFails.length ? `\n${budgetFails.length} budget breach${budgetFails.length > 1 ? 'es' : ''}:\n${budgetFails.join('\n')}` : '\nno budget breaches')
-await browser.close()
-if (ASSERT && budgetFails.length) process.exit(1)

From 0310b2eed73adf75689678876c160dde2b86098e Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Wed, 4 Nov 2026 13:48:02 +0000
Subject: [PATCH 04/38] perf: probe guard when run 1 and the profiled run both
 fail

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 scripts/perf-probe.mjs | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/scripts/perf-probe.mjs b/scripts/perf-probe.mjs
index c841745e..811c0949 100644
--- a/scripts/perf-probe.mjs
+++ b/scripts/perf-probe.mjs
@@ -420,7 +420,7 @@ try {
       steady: later.length ? { link: Math.max(...later.map((s) => s.link)), upload: Math.max(...later.map((s) => s.upload)), ctx: Math.max(...later.map((s) => s.ctx)) } : null,
       hot: prof?.hot ?? [],
       watch: prof?.watch ?? [],
-      scripts: (prof ?? first).scripts,
+      scripts: (prof ?? first ?? samples[0]).scripts,
     }
     // ---- budgets ----
     const b = row.budget ?? {}
@@ -583,7 +583,8 @@ try {
     // e2e-out/perf-baseline-v2.txt (and the spec's v2 table) — `bare` from its production section,
     // `rich` from its dev rich section — for the rows the fix plan's tasks target. A budget set this
     // way is breached by the baseline itself: it is the target, and on this shared machine an
-    // advisory one (compare BASE and HEAD in one sitting). The GL budgets are the hard gate.
+    // advisory one (compare BASE and HEAD in one sitting), though under PERF_ASSERT=1 its
+    // breach still sets exit 1 like any other. The GL budgets are the hard gate.
     tabRow('Tab → Surface Deviation (scan only)', 'workspace-deviation', { budget: { inpMs: { bare: 50, rich: 123 } } }),
     tabRow('Tab → Wall Thickness', 'workspace-thickness', { budget: { inpMs: { bare: 50, rich: 106 } } }),
     tabRow('Tab → 2D Measure', 'workspace-flat', {

From c962ce52a86c11966262ae91c338f5c7ce36f119 Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Wed, 4 Nov 2026 14:19:37 +0000
Subject: [PATCH 05/38] perf(topbar): fold fit only when the bar's content
 changed

A tab tap re-renders the bar for the highlight alone, and each render ran the
fold loop, which forces the page's layout once per fold. useFit now skips a
render-driven fit when the bar's text, child count and class are as the last
fit left them; the resize and font-ready paths always fit.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 src/ui/TopBar.tsx | 25 ++++++++++++++++++++-----
 1 file changed, 20 insertions(+), 5 deletions(-)

diff --git a/src/ui/TopBar.tsx b/src/ui/TopBar.tsx
index 646d76f9..20d864f7 100644
--- a/src/ui/TopBar.tsx
+++ b/src/ui/TopBar.tsx
@@ -100,6 +100,12 @@ function ProjectName() {
  *  when everything spelled out does not fit its row. */
 const FOLDS = 5
 
+/** What the fold depends on, read without asking the page for a layout: the
+ *  words, how many things hold them, and the class that sets the bar's mode. */
+function signature(el: HTMLElement) {
+  return el.textContent + '|' + el.childElementCount + '|' + el.className
+}
+
 /** Folds the bar just as far as its row needs, and marks the ends with keys
  *  scrolled out of sight ('start', 'end' or both) for the fade that says
  *  there is more that way. Measured rather than set by window width, since
@@ -108,12 +114,18 @@ const FOLDS = 5
  *  before the part's name is cut to an ellipsis. Written to
  *  the bar directly, so a fit costs no render; it runs after every render of
  *  the bar — a chip coming or going changes the row and not the bar — and
- *  whenever the bar's own width changes. */
+ *  whenever the bar's own width changes. A render that left the bar's content
+ *  as it was (a tab tap re-renders the bar for the highlight alone) is told
+ *  apart without a layout read and skipped: each fit forces the page's layout
+ *  several times over, which is most of what such a tap costs. The resize and
+ *  font paths always fit, as then it is the width, not the content, that moved. */
 function useFit(ref: RefObject<HTMLElement | null>) {
-  const fit = useRef(() => {})
-  fit.current = () => {
+  const fit = useRef((_force?: boolean) => {})
+  const last = useRef('')
+  fit.current = (force) => {
     const el = ref.current
     if (!el) return
+    if (!force && signature(el) === last.current) return
     el.classList.add('measuring')
     for (let fold = 0; ; fold++) {
       el.dataset.fold = Array.from({ length: fold }, (_, i) => i + 1).join(' ')
@@ -121,6 +133,9 @@ function useFit(ref: RefObject<HTMLElement | null>) {
     }
     el.classList.remove('measuring')
     markEnds(el)
+    // Taken after the fold and the measuring class are settled, so what is
+    // remembered is what the next render will be compared with.
+    last.current = signature(el)
   }
   useLayoutEffect(() => fit.current())
   useEffect(() => {
@@ -129,9 +144,9 @@ function useFit(ref: RefObject<HTMLElement | null>) {
     const onScroll = () => markEnds(el)
     el.addEventListener('scroll', onScroll, { passive: true })
     // The web fonts arriving widen every word.
-    document.fonts?.ready.then(() => fit.current())
+    document.fonts?.ready.then(() => fit.current(true))
     if (typeof ResizeObserver === 'undefined') return () => el.removeEventListener('scroll', onScroll)
-    const observer = new ResizeObserver(() => fit.current())
+    const observer = new ResizeObserver(() => fit.current(true))
     observer.observe(el)
     return () => {
       observer.disconnect()

From 70c9598c9dcd259dcf6e304a0e2fe465141edd14 Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Wed, 4 Nov 2026 14:29:35 +0000
Subject: [PATCH 06/38] perf(topbar): fold signature includes the active tab

From the fourth fold on only the open tab shows its word, so a tab tap
changes the row's width with no change of text, child count or class. The
signature now names the open tab, so such a render fits again.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 src/ui/TopBar.tsx | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/src/ui/TopBar.tsx b/src/ui/TopBar.tsx
index 20d864f7..16ee6a32 100644
--- a/src/ui/TopBar.tsx
+++ b/src/ui/TopBar.tsx
@@ -101,9 +101,12 @@ function ProjectName() {
 const FOLDS = 5
 
 /** What the fold depends on, read without asking the page for a layout: the
- *  words, how many things hold them, and the class that sets the bar's mode. */
+ *  words, how many things hold them, the class that sets the bar's mode, and
+ *  which tab is open, since from the fourth fold on only that tab shows its
+ *  word, so the row's width follows the tab with no change of text. */
 function signature(el: HTMLElement) {
-  return el.textContent + '|' + el.childElementCount + '|' + el.className
+  const open = el.querySelector('.modeswitch .on')?.getAttribute('data-test')
+  return el.textContent + '|' + el.childElementCount + '|' + el.className + '|' + open
 }
 
 /** Folds the bar just as far as its row needs, and marks the ends with keys

From d914e42145c8b1554cc0b3d9965ccd221de4b900 Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Wed, 4 Nov 2026 14:32:13 +0000
Subject: [PATCH 07/38] perf(topbar): fold signature includes the project
 name's width

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/ui/TopBar.tsx | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/src/ui/TopBar.tsx b/src/ui/TopBar.tsx
index 16ee6a32..4dd62dc2 100644
--- a/src/ui/TopBar.tsx
+++ b/src/ui/TopBar.tsx
@@ -103,10 +103,13 @@ const FOLDS = 5
 /** What the fold depends on, read without asking the page for a layout: the
  *  words, how many things hold them, the class that sets the bar's mode, and
  *  which tab is open, since from the fourth fold on only that tab shows its
- *  word, so the row's width follows the tab with no change of text. */
+ *  word, so the row's width follows the tab with no change of text. The
+ *  project's name sits in an input, whose words are not the bar's text: its
+ *  size, which follows the name, stands in for them. */
 function signature(el: HTMLElement) {
   const open = el.querySelector('.modeswitch .on')?.getAttribute('data-test')
-  return el.textContent + '|' + el.childElementCount + '|' + el.className + '|' + open
+  const name = el.querySelector<HTMLInputElement>('.projectname')?.size
+  return el.textContent + '|' + el.childElementCount + '|' + el.className + '|' + open + '|' + name
 }
 
 /** Folds the bar just as far as its row needs, and marks the ends with keys

From 3c9fc50ed9d20e39515ee75e5d58036244236dcf Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Wed, 4 Nov 2026 14:57:17 +0000
Subject: [PATCH 08/38] perf(map): skip repaint and upload when the map is
 unchanged

A tab or map tap re-ran paintField over every vertex and re-uploaded the
colour buffer even when nothing the map is read from had changed. The paint
effect now remembers, per colour buffer, the version, scale and ramp it last
painted under (paintKey) and skips the pass when they match; RegionColors
skips laying the same field on again, and the scene its upload, until a
layer changes or the array is repainted.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 src/app/useSceneSync.ts    |  42 +++++++++--
 src/core/field/colormap.ts |  14 ++++
 src/viewer/SceneManager.ts |   8 +-
 src/viewer/regionColors.ts |  31 +++++++-
 tests/paintKey.test.ts     |  83 ++++++++++++++++++++
 tests/regionColors.test.ts | 151 +++++++++++++++++++++++++++++++++++++
 6 files changed, 317 insertions(+), 12 deletions(-)
 create mode 100644 tests/paintKey.test.ts

diff --git a/src/app/useSceneSync.ts b/src/app/useSceneSync.ts
index bb7b4cf4..ab217366 100644
--- a/src/app/useSceneSync.ts
+++ b/src/app/useSceneSync.ts
@@ -44,7 +44,7 @@ import { sectionElementsOf, useFlat } from '../state/flatStore'
 import { useShell } from '../state/shellStore'
 import { useMark } from '../state/markStore'
 import { useThickness } from '../state/thicknessStore'
-import { colormapById, paintField, type FieldScale } from '../core/field/colormap'
+import { colormapById, paintField, paintKey, type FieldScale } from '../core/field/colormap'
 import { fieldHistogram } from '../core/field/stats'
 import { deviationScale, deviationStats } from '../core/deviation/deviation'
 import {
@@ -753,6 +753,16 @@ export function useSceneSync({
   }, [volumeHover, volume])
   const pluginRef = useRef(plugin)
   pluginRef.current = plugin
+  /** A plugin's `fieldVersion` is anything that changes when its map does —
+   *  a string, the reading itself — so it is counted here into the number
+   *  the paint key wants. A plugin that gives none can never be told to be
+   *  unchanged, and is painted every time. */
+  const pluginSerial = useRef<{ last: unknown; n: number }>({ last: undefined, n: 0 })
+  /** The key each colour buffer was last painted under, so a repaint of what
+   *  is already in it — a tab taken, the map put away and back — is skipped.
+   *  Keyed by the buffer: a new scan, or a map re-measured, brings a new one,
+   *  and the old key goes with the old buffer. */
+  const painted = useRef(new WeakMap<Uint8Array, string>())
   /** Whichever map this workspace is showing: its values, and the scale they
    *  are read through. The maps differ only in that scale and in the figures
    *  that go under it — the two deviation maps not even in that, since a
@@ -762,7 +772,7 @@ export function useSceneSync({
     if (workspace === 'deviation' && source === 'reference' && mapOn === 'reference') {
       const values = referenceMap.current?.values
       if (!values) return null
-      return { values, rgb: referenceRgb, scale: referenceScale(range, maxDistance, bands), onReference: true }
+      return { values, rgb: referenceRgb, scale: referenceScale(range, maxDistance, bands), version: referenceVersion, onReference: true }
     }
     if (workspace === 'deviation') {
       const values = source === 'element' ? elementField.current : deviation.current
@@ -771,12 +781,21 @@ export function useSceneSync({
         values,
         rgb: source === 'element' ? elementRgb : deviationRgb,
         scale: deviationScale(range, maxDistance, bands),
+        version: source === 'element' ? elementVersion : mapVersion,
       }
     }
     if (workspace === 'thickness' && thickness.current) {
-      return { values: thickness.current, rgb: thicknessRgb, scale: thickScale }
+      return { values: thickness.current, rgb: thicknessRgb, scale: thickScale, version: thickVersion }
     }
-    return pluginRef.current?.field ?? null
+    const field = pluginRef.current?.field
+    if (!field) return null
+    const serial = pluginSerial.current
+    const version = pluginRef.current?.fieldVersion
+    if (version === undefined || version !== serial.last) {
+      serial.last = version
+      serial.n++
+    }
+    return { ...field, version: serial.n }
   }
   // The colour plot can be switched off to look at the bare scan surface — its
   // shape, its holes, the marks a finish leaves — with the map still measured
@@ -798,17 +817,26 @@ export function useSceneSync({
       return
     }
 
-    const { values, rgb: rgbRef, scale } = showing
+    const { values, rgb: rgbRef, scale, version } = showing
     let rgb = rgbRef.current
     if (!rgb || rgb.length !== values.length * 3) {
       rgb = new Uint8Array(values.length * 3)
       rgbRef.current = rgb
     }
-    paintField(values, scale, colormapById(colormap), rgb)
+    // Nothing a paint reads has changed since this buffer was last painted
+    // (a tab taken, the map put away and back): its colours stand, and the
+    // scene is told so it does not lay them on or upload them again.
+    const map = colormapById(colormap)
+    const key = paintKey(version, scale, map.id)
+    const repainted = painted.current.get(rgb) !== key
+    if (repainted) {
+      paintField(values, scale, map, rgb)
+      painted.current.set(rgb, key)
+    }
     if ('onReference' in showing) {
       scene.setFieldColors(null)
       scene.setReferenceMapColors(rgb)
-    } else scene.setFieldColors(rgb)
+    } else scene.setFieldColors(rgb, repainted)
   }, [
     workspace,
     source,
diff --git a/src/core/field/colormap.ts b/src/core/field/colormap.ts
index 79ee4480..dc842da4 100644
--- a/src/core/field/colormap.ts
+++ b/src/core/field/colormap.ts
@@ -225,6 +225,20 @@ export function paintField(values: Float32Array, scale: FieldScale, map: Colorma
   }
 }
 
+/**
+ * What a painted buffer was painted from, short of the values themselves: the
+ * map's version (which moves whenever its values do — see the stores), the
+ * scale it was read through and the ramp it was coloured in. Two paints with
+ * the same key into the same buffer are byte for byte the same, so a caller
+ * holding the key of the last paint can skip the pass over every vertex when
+ * nothing has changed. Every input `paintField` reads besides the values and
+ * the buffer is in it; a new one belongs here too.
+ */
+export function paintKey(version: number, scale: FieldScale, colormapId: string): string {
+  const { low, high, bands, validMin, validMax, reversed } = scale
+  return `${version}|${colormapId}|${low}|${high}|${bands ?? ''}|${validMin}|${validMax}|${reversed ? 1 : 0}`
+}
+
 export function cssRgb(rgb: Rgb): string {
   return `rgb(${rgb[0]},${rgb[1]},${rgb[2]})`
 }
diff --git a/src/viewer/SceneManager.ts b/src/viewer/SceneManager.ts
index 8b7e0fb7..af98f7e7 100644
--- a/src/viewer/SceneManager.ts
+++ b/src/viewer/SceneManager.ts
@@ -2770,9 +2770,11 @@ export class SceneManager {
   }
 
   /** Paint the scan from a measured map — deviation, wall thickness — or pass
-   *  null to hand the surface back to the element colours. */
-  setFieldColors(colors: Uint8Array | null): void {
-    const painted = this.regions.setFieldColors(colors)
+   *  null to hand the surface back to the element colours. The map already on
+   *  the surface is not laid on or uploaded again; `repainted` says that the
+   *  array was painted afresh since it was last handed over. */
+  setFieldColors(colors: Uint8Array | null, repainted = false): void {
+    const painted = this.regions.setFieldColors(colors, repainted)
     this.invalidate()
     if (!painted) return
     this.surfaceRepainted()
diff --git a/src/viewer/regionColors.ts b/src/viewer/regionColors.ts
index 77d0357d..3cbfeba8 100644
--- a/src/viewer/regionColors.ts
+++ b/src/viewer/regionColors.ts
@@ -42,6 +42,7 @@ const REGION_STATE = [
   'previewRegion',
   'previewRgb',
   'sparse',
+  'fieldPainted',
   'paintMask',
   'count',
   'tintMask',
@@ -71,6 +72,11 @@ export class RegionColors {
    *  layer above the element tints and below the preview region, put back
    *  on top by every repaint underneath it. */
   private sparse: { subset: Uint32Array; rgb: Uint8Array } | null = null
+  /** Whether the colour buffer holds what `setFieldColors` last made of
+   *  `fieldColors` and nothing has touched the layers since — so asking for
+   *  the same field again would write the same bytes over themselves. Every
+   *  call that records or paints a change to the layers puts it down. */
+  private fieldPainted = false
   /** Hand-painted surface selection: one byte per vertex, vertex indices like
    *  everything else the fitter speaks. The mesh's paint attribute — written in
    *  place, thresholded per triangle by the scan's shader. */
@@ -93,6 +99,7 @@ export class RegionColors {
   setBaseColor(rgb: Rgb): boolean {
     if (rgb.every((c, i) => c === this.baseColor[i])) return false
     this.baseColor = rgb
+    this.fieldPainted = false
     if (!this.colors || this.fieldColors) return false
     this.repaintFromElements()
     return true
@@ -126,6 +133,7 @@ export class RegionColors {
     this.elementColors.clear()
     this.hiddenRegions.clear()
     this.fieldColors = null
+    this.fieldPainted = false
     this.previewRegion = null
     this.sparse = null
     this.paintMask = paint
@@ -145,6 +153,8 @@ export class RegionColors {
     this.scanVertices = scanVertices
     this.paintMask = paint
     this.tintMask = tint
+    // The arrays are new: whatever they hold was copied, not painted.
+    this.fieldPainted = false
   }
 
   /** Trade everything with another compositor: its buffers, its ownership,
@@ -168,6 +178,7 @@ export class RegionColors {
     this.elementColors.clear()
     this.hiddenRegions.clear()
     this.fieldColors = null
+    this.fieldPainted = false
     this.previewRegion = null
     this.sparse = null
     this.paintMask = null
@@ -191,6 +202,7 @@ export class RegionColors {
    *  element owned before. Returns whether the colour buffer changed. */
   applyRegion(elementId: number, rgb: Rgb, region: Uint32Array): boolean {
     if (!this.colors || !this.owner) return false
+    this.fieldPainted = false
     const cleared = this.clearElement(elementId)
     this.elementColors.set(elementId, rgb)
     for (let i = 0; i < region.length; i++) this.owner[region[i]] = elementId
@@ -214,6 +226,7 @@ export class RegionColors {
   /** Take an element's region away and hand the surface back to bare scan. */
   clearElement(elementId: number): boolean {
     if (!this.colors || !this.owner) return false
+    this.fieldPainted = false
     this.elementColors.delete(elementId)
     this.hiddenRegions.delete(elementId)
     const arr = this.colors
@@ -235,6 +248,7 @@ export class RegionColors {
 
   clearAllRegions(): boolean {
     if (!this.colors || !this.owner) return false
+    this.fieldPainted = false
     this.owner.fill(0)
     this.elementColors.clear()
     this.hiddenRegions.clear()
@@ -255,6 +269,7 @@ export class RegionColors {
    *  lifting the preview restores whatever was underneath. */
   setPreviewRegion(region: Uint32Array | null, rgb?: Rgb): boolean {
     if (!this.colors || !this.owner || this.fieldColors) return false
+    this.fieldPainted = false
     if (rgb) this.previewRgb = rgb
     const arr = this.colors
     const tint = this.tintMask!
@@ -277,9 +292,17 @@ export class RegionColors {
    *  null to hand the surface back to the element colours. Returns whether the
    *  colour buffer was there to paint. A map is a reading at every vertex, so
    *  it tints every vertex: no triangle falls under the shader's threshold and
-   *  the map stays the smooth interpolation it is meant to be. */
-  setFieldColors(field: Uint8Array | null): boolean {
+   *  the map stays the smooth interpolation it is meant to be.
+   *
+   *  The same field asked for again, with the layers untouched since, is
+   *  already what the buffer holds: nothing is written and false comes back,
+   *  so the caller uploads nothing. A field whose colours were repainted into
+   *  the same array since — `repainted` — is a different field that happens to
+   *  share it, and is laid on again. */
+  setFieldColors(field: Uint8Array | null, repainted = false): boolean {
+    if (!repainted && this.fieldPainted && field === this.fieldColors) return false
     this.fieldColors = field
+    this.fieldPainted = false
     if (!this.colors) return false
     // A map is a reading per vertex of the scan, and the buffer may run on
     // past those with the copies sharp edges were split into for shading
@@ -291,6 +314,7 @@ export class RegionColors {
       this.tintMask!.fill(1)
       this.paintOverlays()
     } else this.repaintFromElements()
+    this.fieldPainted = true
     return true
   }
 
@@ -304,6 +328,7 @@ export class RegionColors {
     const next = subset && rgb && rgb.length === subset.length * 3 ? { subset, rgb } : null
     if (!next && !this.sparse) return false
     this.sparse = next
+    this.fieldPainted = false
     if (!this.colors || this.fieldColors) return false
     this.repaintFromElements()
     return true
@@ -318,6 +343,7 @@ export class RegionColors {
     if (next.size === this.hiddenRegions.size && ids.every((id) => this.hiddenRegions.has(id)))
       return false
     this.hiddenRegions = next
+    this.fieldPainted = false
     if (!this.colors || this.fieldColors) return false
     this.repaintFromElements()
     return true
@@ -327,6 +353,7 @@ export class RegionColors {
    *  ownership records, then put the overlays back on top. */
   repaintFromElements(): void {
     if (!this.colors || !this.owner) return
+    this.fieldPainted = false
     const arr = this.colors
     const tint = this.tintMask!
     for (let v = 0; v < this.owner.length; v++) {
diff --git a/tests/paintKey.test.ts b/tests/paintKey.test.ts
new file mode 100644
index 00000000..aba14205
--- /dev/null
+++ b/tests/paintKey.test.ts
@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// The key a painted colour buffer is remembered by: the same key must mean the
+// same bytes out of `paintField`, and any input a paint reads must move it.
+import { describe, expect, it } from 'vitest'
+import { COLORMAPS, colormapById, paintField, paintKey, type FieldScale } from '../src/core/field/colormap'
+import { deviationScale } from '../src/core/deviation/deviation'
+import { thicknessScale } from '../src/core/thickness/thickness'
+
+const SCALE: FieldScale = { low: -0.5, high: 0.5, bands: null, validMin: -2, validMax: 2 }
+
+describe('paintKey', () => {
+  it('is the same for the same inputs, whichever object the scale is', () => {
+    expect(paintKey(3, { ...SCALE }, 'jet')).toBe(paintKey(3, SCALE, 'jet'))
+    expect(paintKey(3, deviationScale(0.5, 2, null), 'jet')).toBe(paintKey(3, deviationScale(0.5, 2, null), 'jet'))
+  })
+
+  it('moves with the version', () => {
+    expect(paintKey(4, SCALE, 'jet')).not.toBe(paintKey(3, SCALE, 'jet'))
+  })
+
+  it('moves with the colour map', () => {
+    const keys = new Set(COLORMAPS.map((m) => paintKey(1, SCALE, m.id)))
+    expect(keys.size).toBe(COLORMAPS.length)
+  })
+
+  it('moves with every part of the scale a paint reads', () => {
+    const base = paintKey(1, SCALE, 'jet')
+    const variants: FieldScale[] = [
+      { ...SCALE, low: -0.6 },
+      { ...SCALE, high: 0.6 },
+      { ...SCALE, bands: 5 },
+      { ...SCALE, validMin: -3 },
+      { ...SCALE, validMax: 3 },
+      { ...SCALE, reversed: true },
+    ]
+    for (const v of variants) expect(paintKey(1, v, 'jet')).not.toBe(base)
+    expect(new Set(variants.map((v) => paintKey(1, v, 'jet'))).size).toBe(variants.length)
+  })
+
+  it('tells band counts apart, and unbanded from banded', () => {
+    expect(paintKey(1, { ...SCALE, bands: 5 }, 'jet')).not.toBe(paintKey(1, { ...SCALE, bands: 7 }, 'jet'))
+    expect(paintKey(1, { ...SCALE, bands: null }, 'jet')).not.toBe(paintKey(1, { ...SCALE, bands: 2 }, 'jet'))
+  })
+
+  it('is the same for an absent reversed flag and a false one', () => {
+    expect(paintKey(1, { ...SCALE, reversed: false }, 'jet')).toBe(paintKey(1, SCALE, 'jet'))
+  })
+
+  it('holds the infinite ends of the reference and thickness windows', () => {
+    const a = paintKey(1, thicknessScale(1, 5, null), 'jet')
+    expect(a).toContain('Infinity')
+    expect(paintKey(1, { ...thicknessScale(1, 5, null), validMax: 50 }, 'jet')).not.toBe(a)
+  })
+
+  it('stands for the bytes: equal keys paint equal buffers', () => {
+    const values = Float32Array.from([-1, -0.4, -0.1, 0, 0.1, 0.4, 1, 5, NaN])
+    const paint = (scale: FieldScale, id: string): Uint8Array => {
+      const out = new Uint8Array(values.length * 3)
+      paintField(values, scale, colormapById(id), out)
+      return out
+    }
+    const scales: FieldScale[] = [
+      SCALE,
+      { ...SCALE },
+      { ...SCALE, bands: 5 },
+      { ...SCALE, reversed: true },
+      { ...SCALE, validMax: 0.2 },
+      { ...SCALE, high: 0.2 },
+    ]
+    const seen = new Map<string, Uint8Array>()
+    for (const scale of scales) {
+      for (const id of ['jet', 'viridis']) {
+        const key = paintKey(1, scale, id)
+        const bytes = paint(scale, id)
+        const prior = seen.get(key)
+        if (prior) expect(bytes).toEqual(prior)
+        seen.set(key, bytes)
+      }
+    }
+    // The copy of SCALE shares its keys; every other scale and map is its own.
+    expect(seen.size).toBe((scales.length - 1) * 2)
+  })
+})
diff --git a/tests/regionColors.test.ts b/tests/regionColors.test.ts
index 227893d5..5f616ec8 100644
--- a/tests/regionColors.test.ts
+++ b/tests/regionColors.test.ts
@@ -121,6 +121,157 @@ describe('field maps', () => {
   })
 })
 
+describe('asking for the map already on the surface', () => {
+  it('writes and uploads nothing the second time', () => {
+    const { rc, colors } = setup()
+    const field = new Uint8Array(N * 3).fill(77)
+    expect(rc.setFieldColors(field)).toBe(true)
+    const before = colors.slice()
+    expect(rc.setFieldColors(field)).toBe(false)
+    expect(colors).toEqual(before)
+    expect(rc.fieldState).toBe('painted')
+  })
+
+  it('lays on a different map, and the first one again after it', () => {
+    const { rc, colors } = setup()
+    const a = new Uint8Array(N * 3).fill(77)
+    const b = new Uint8Array(N * 3).fill(55)
+    rc.setFieldColors(a)
+    expect(rc.setFieldColors(b)).toBe(true)
+    expect(colorAt(colors, 0)).toEqual([55, 55, 55])
+    expect(rc.setFieldColors(a)).toBe(true)
+    expect(colorAt(colors, 0)).toEqual([77, 77, 77])
+  })
+
+  it('is told when the same array has been painted afresh', () => {
+    const { rc, colors } = setup()
+    const field = new Uint8Array(N * 3).fill(77)
+    rc.setFieldColors(field)
+    field.fill(33)
+    expect(rc.setFieldColors(field)).toBe(false)
+    expect(colorAt(colors, 0)).toEqual([77, 77, 77])
+    expect(rc.setFieldColors(field, true)).toBe(true)
+    expect(colorAt(colors, 0)).toEqual([33, 33, 33])
+    // And it is the map in hand again afterwards.
+    expect(rc.setFieldColors(field)).toBe(false)
+  })
+
+  it('does it again after a region is hidden, shown, added or taken away', () => {
+    const { rc } = setup()
+    rc.applyRegion(1, RED, Uint32Array.of(1))
+    const field = new Uint8Array(N * 3).fill(77)
+    rc.setFieldColors(field)
+    expect(rc.setHiddenRegions([1])).toBe(false)
+    expect(rc.setFieldColors(field)).toBe(true)
+    expect(rc.setFieldColors(field)).toBe(false)
+    rc.setHiddenRegions([])
+    expect(rc.setFieldColors(field)).toBe(true)
+    expect(rc.setFieldColors(field)).toBe(false)
+    rc.applyRegion(2, GREEN, Uint32Array.of(3))
+    expect(rc.setFieldColors(field)).toBe(true)
+    expect(rc.setFieldColors(field)).toBe(false)
+    rc.clearElement(2)
+    expect(rc.setFieldColors(field)).toBe(true)
+    expect(rc.setFieldColors(field)).toBe(false)
+    rc.clearAllRegions()
+    expect(rc.setFieldColors(field)).toBe(true)
+  })
+
+  it('does it again after a sparse map is laid or lifted', () => {
+    const { rc } = setup()
+    const field = new Uint8Array(N * 3).fill(77)
+    rc.setFieldColors(field)
+    rc.setSparseField(Uint32Array.of(2), Uint8Array.of(1, 2, 3))
+    expect(rc.setFieldColors(field)).toBe(true)
+    expect(rc.setFieldColors(field)).toBe(false)
+    rc.setSparseField(null, null)
+    expect(rc.setFieldColors(field)).toBe(true)
+  })
+
+  it('does it again after the preview region moves or the bare colour changes', () => {
+    const { rc } = setup()
+    rc.setFieldColors(null)
+    expect(rc.setFieldColors(null)).toBe(false)
+    rc.setPreviewRegion(Uint32Array.of(1), BLUE)
+    expect(rc.setFieldColors(null)).toBe(true)
+    expect(rc.setFieldColors(null)).toBe(false)
+    rc.setBaseColor([1, 2, 3])
+    expect(rc.setFieldColors(null)).toBe(true)
+  })
+
+  it('hands the surface back to the elements once, however often it is asked', () => {
+    const { rc, colors } = setup()
+    rc.applyRegion(1, RED, Uint32Array.of(1))
+    rc.setFieldColors(new Uint8Array(N * 3).fill(77))
+    expect(rc.setFieldColors(null)).toBe(true)
+    expect(colorAt(colors, 1)).toEqual(RED)
+    expect(rc.setFieldColors(null)).toBe(false)
+    expect(colorAt(colors, 1)).toEqual(RED)
+    expect(colorAt(colors, 0)).toEqual(BASE)
+  })
+
+  it('holds a map of the wrong layout to the same bargain', () => {
+    const { rc, colors } = setup()
+    const odd = new Uint8Array((N + 3) * 3).fill(55)
+    expect(rc.setFieldColors(odd)).toBe(true)
+    expect(rc.fieldState).toBe('unfit')
+    expect(rc.setFieldColors(odd)).toBe(false)
+    expect(colorAt(colors, 0)).toEqual(BASE)
+  })
+
+  it('starts over with a new scan', () => {
+    const { rc } = setup()
+    const field = new Uint8Array(N * 3).fill(77)
+    rc.setFieldColors(field)
+    const colors = new Uint8Array(N * 3)
+    rc.attach(colors, new Uint8Array(N), new Uint8Array(N))
+    expect(rc.setFieldColors(field)).toBe(true)
+    expect(colorAt(colors, 0)).toEqual([77, 77, 77])
+  })
+
+  it('goes with the state when compositors trade', () => {
+    const scan = setup()
+    const field = new Uint8Array(N * 3).fill(77)
+    scan.rc.setFieldColors(field)
+    const copy = new RegionColors(BASE)
+    copy.attach(new Uint8Array(4 * 3), new Uint8Array(4), new Uint8Array(4))
+    scan.rc.exchange(copy)
+    expect(scan.rc.setFieldColors(field)).toBe(true)
+    scan.rc.exchange(copy)
+    expect(scan.rc.setFieldColors(field)).toBe(false)
+  })
+
+  it('leaves the colours and tints as a forced repaint does, over a run of changes', () => {
+    const asked = setup()
+    const forced = setup()
+    let current: Uint8Array | null = null
+    const field = new Uint8Array(N * 3)
+    for (let i = 0; i < field.length; i++) field[i] = (i * 37) & 255
+    const steps: Array<(c: RegionColors) => void> = [
+      (c) => c.applyRegion(1, RED, Uint32Array.of(1, 2)),
+      (c) => c.setHiddenRegions([1]),
+      (c) => c.setSparseField(Uint32Array.of(4), Uint8Array.of(9, 9, 9)),
+      (c) => c.applyRegion(2, GREEN, Uint32Array.of(5)),
+      (c) => c.setHiddenRegions([]),
+      (c) => c.setSparseField(null, null),
+      (c) => c.clearElement(1),
+      (c) => c.clearAllRegions(),
+    ]
+    // The map comes and goes between the changes, as a tab or the map key
+    // would have it, and is asked for after each — as the paint effect does.
+    for (const [i, step] of steps.entries()) {
+      current = i % 3 === 2 ? null : field
+      step(asked.rc)
+      step(forced.rc)
+      asked.rc.setFieldColors(current)
+      asked.rc.setFieldColors(current)
+      forced.rc.setFieldColors(current, true)
+      expect(asked.colors).toEqual(forced.colors)
+      expect(asked.tint).toEqual(forced.tint)
+    }
+  })
+})
+
 describe('a field map on a scan with shading copies', () => {
   it('is a reading per vertex of the scan, the copies past them left to the scene', () => {
     // Eight vertices of the scan and three copies split off at sharp edges.

From e3263617067d10091f2e104d92cf8d9039e809e6 Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Wed, 4 Nov 2026 15:24:47 +0000
Subject: [PATCH 09/38] perf(map): document the paint-skip invariants; probe
 budgets per R9

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 scripts/perf-probe.mjs  | 6 ++++--
 src/app/useSceneSync.ts | 8 ++++++--
 2 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/scripts/perf-probe.mjs b/scripts/perf-probe.mjs
index 811c0949..2485353b 100644
--- a/scripts/perf-probe.mjs
+++ b/scripts/perf-probe.mjs
@@ -644,7 +644,8 @@ try {
   await run([
     { label: 'Deviation: map off', sel: '[data-test=toggle-colormap]', settle: 1500, budget: { links: 0 } },
     // Plan task 2: a colour buffer that did not change is not uploaded again.
-    { label: 'Deviation: map on', sel: '[data-test=toggle-colormap]', settle: 1500, budget: { links: 0, uploadMB: 0 } },
+    // The picture changes here (bare to map), so one colour upload is the floor (ruling R9).
+    { label: 'Deviation: map on', sel: '[data-test=toggle-colormap]', settle: 1500, budget: { links: 0, uploadMB: 0.7 } },
   ])
   await ensureProbes()
   await run([
@@ -746,7 +747,8 @@ try {
     tabRow('Tab → 3D Measure (maps in hand)', 'workspace-elements', { budget: { inpMs: { bare: 62, rich: 258 }, links: 0 } }),
     // Plan task 2: a map already painted is not uploaded again on the way in.
     tabRow('Tab → Surface Deviation (map in hand)', 'workspace-deviation', { budget: { uploadMB: 0, inpMs: { bare: 84, rich: 263 }, links: 0 } }),
-    tabRow('Tab → Wall Thickness (map in hand)', 'workspace-thickness', { budget: { uploadMB: 0, inpMs: { bare: 90, rich: 235 } } }),
+    // Bare to the thickness map: one colour upload is the floor (ruling R9).
+    tabRow('Tab → Wall Thickness (map in hand)', 'workspace-thickness', { budget: { uploadMB: 0.7, inpMs: { bare: 90, rich: 235 } } }),
     tabRow('Tab → Surface Deviation (from thickness)', 'workspace-deviation', { budget: { inpMs: { bare: 78, rich: 252 }, links: 0 } }),
   ])
   await run([
diff --git a/src/app/useSceneSync.ts b/src/app/useSceneSync.ts
index ab217366..30c3459b 100644
--- a/src/app/useSceneSync.ts
+++ b/src/app/useSceneSync.ts
@@ -756,7 +756,9 @@ export function useSceneSync({
   /** A plugin's `fieldVersion` is anything that changes when its map does —
    *  a string, the reading itself — so it is counted here into the number
    *  the paint key wants. A plugin that gives none can never be told to be
-   *  unchanged, and is painted every time. */
+   *  unchanged, and is painted every time. One count serves every plugin:
+   *  it only ever rises, and a buffer's key holds the count it was painted
+   *  under, so one plugin's version cannot pass for another's. */
   const pluginSerial = useRef<{ last: unknown; n: number }>({ last: undefined, n: 0 })
   /** The key each colour buffer was last painted under, so a repaint of what
    *  is already in it — a tab taken, the map put away and back — is skipped.
@@ -825,7 +827,9 @@ export function useSceneSync({
     }
     // Nothing a paint reads has changed since this buffer was last painted
     // (a tab taken, the map put away and back): its colours stand, and the
-    // scene is told so it does not lay them on or upload them again.
+    // scene is told so it does not lay them on or upload them again. This
+    // leans on a buffer only ever being handed to the scan state that is
+    // showing: the mesh tools' edited-copy swap runs before this effect.
     const map = colormapById(colormap)
     const key = paintKey(version, scale, map.id)
     const repainted = painted.current.get(rgb) !== key

From d5438d46d6b366bd5f6dd544b1c355269d978854 Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Wed, 4 Nov 2026 15:36:39 +0000
Subject: [PATCH 10/38] perf(readout): cache histogram and stats per map
 version

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 src/app/useSceneSync.ts        | 22 +++++++----
 src/core/field/readoutCache.ts | 72 ++++++++++++++++++++++++++++++++++
 tests/readoutCache.test.ts     | 68 ++++++++++++++++++++++++++++++++
 3 files changed, 155 insertions(+), 7 deletions(-)
 create mode 100644 src/core/field/readoutCache.ts
 create mode 100644 tests/readoutCache.test.ts

diff --git a/src/app/useSceneSync.ts b/src/app/useSceneSync.ts
index 30c3459b..1dbf275e 100644
--- a/src/app/useSceneSync.ts
+++ b/src/app/useSceneSync.ts
@@ -45,14 +45,13 @@ import { useShell } from '../state/shellStore'
 import { useMark } from '../state/markStore'
 import { useThickness } from '../state/thicknessStore'
 import { colormapById, paintField, paintKey, type FieldScale } from '../core/field/colormap'
-import { fieldHistogram } from '../core/field/stats'
-import { deviationScale, deviationStats } from '../core/deviation/deviation'
+import { cachedDeviationStats, cachedHistogram, cachedThicknessStats } from '../core/field/readoutCache'
+import { deviationScale } from '../core/deviation/deviation'
 import {
   DEFLECTION_SMOOTHING,
   deflectionVectors,
   suggestDeflectionScale,
 } from '../core/deviation/deflection'
-import { thicknessStats } from '../core/thickness/thickness'
 import { identityRigid, rigidCompose, rigidInvert, rigidToColumnMajor } from '../core/deviation/rigid'
 import { sectionViewFrames, useSectionView } from '../state/sectionViewStore'
 import type { RefObject } from 'react'
@@ -867,12 +866,21 @@ export function useSceneSync({
     // A plugin's map brings its own figures; nothing here adds to them.
     const showing = workspace === 'deviation' || workspace === 'thickness' ? shownField() : null
     if (!showing) return
-    const { values, scale } = showing
-    const histogram = fieldHistogram(values, scale.low, scale.high, scale.validMin, scale.validMax)
+    const { values, scale, version } = showing
+    const histogram = cachedHistogram(values, version, scale.low, scale.high, scale.validMin, scale.validMax)
+    // The figures come back as the very objects the store already holds when
+    // nothing they read has moved (a tab, a source or a range tap on the same
+    // map), and setting them again would only wake every subscriber to the same
+    // numbers. The store is read here rather than subscribed to: this effect
+    // must not re-run on its own write.
     if (workspace === 'deviation') {
-      useDeviation.getState().setReadout(deviationStats(values, maxDistance, tolerance), histogram)
+      const stats = cachedDeviationStats(values, version, maxDistance, tolerance)
+      const held = useDeviation.getState()
+      if (held.stats !== stats || held.histogram !== histogram) held.setReadout(stats, histogram)
     } else {
-      useThickness.getState().setReadout(thicknessStats(values, thickLimit), histogram)
+      const stats = cachedThicknessStats(values, version, thickLimit)
+      const held = useThickness.getState()
+      if (held.stats !== stats || held.histogram !== histogram) held.setReadout(stats, histogram)
     }
   }, [
     workspace,
diff --git a/src/core/field/readoutCache.ts b/src/core/field/readoutCache.ts
new file mode 100644
index 00000000..225bf919
--- /dev/null
+++ b/src/core/field/readoutCache.ts
@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// The figures under the legend — the histogram and the deviation or thickness
+// tally — each take a pass over every vertex of the map. A tab, a map or a
+// range tap re-runs the effect that reads them though most of those taps change
+// only one of the inputs (or none the figures read), so the last result is kept
+// per values array and handed back as the very same object while the numbers
+// that produced it are unchanged. The caller can then tell "nothing moved" by
+// identity alone and leave the store, and everything subscribed to it, be.
+import { deviationStats, type DeviationStats } from '../deviation/deviation'
+import { thicknessStats, type ThicknessStats } from '../thickness/thickness'
+import { fieldHistogram, type FieldHistogram } from './stats'
+
+interface Entry<T> {
+  args: readonly number[]
+  result: T
+}
+
+/** One slot per values array: a map is read at one scale at a time, so the last
+ *  result is the one worth keeping. The WeakMap lets a replaced map's slot go
+ *  with the array. */
+type Slots<T> = WeakMap<Float32Array, Entry<T>>
+
+function memo<T>(
+  slots: Slots<T>,
+  values: Float32Array,
+  args: readonly number[],
+  compute: () => T,
+): T {
+  const held = slots.get(values)
+  // The version is among the args: a new version is a new map even when the
+  // array object is the same one, so it recomputes rather than trust the old tally.
+  if (held && held.args.every((a, i) => Object.is(a, args[i]))) return held.result
+  const result = compute()
+  slots.set(values, { args, result })
+  return result
+}
+
+const histograms: Slots<FieldHistogram> = new WeakMap()
+const deviations: Slots<DeviationStats> = new WeakMap()
+const thicknesses: Slots<ThicknessStats> = new WeakMap()
+
+export function cachedHistogram(
+  values: Float32Array,
+  version: number,
+  low: number,
+  high: number,
+  validMin: number,
+  validMax: number,
+): FieldHistogram {
+  return memo(histograms, values, [version, low, high, validMin, validMax], () =>
+    fieldHistogram(values, low, high, validMin, validMax),
+  )
+}
+
+export function cachedDeviationStats(
+  values: Float32Array,
+  version: number,
+  maxDistance: number,
+  tolerance: number,
+): DeviationStats {
+  return memo(deviations, values, [version, maxDistance, tolerance], () =>
+    deviationStats(values, maxDistance, tolerance),
+  )
+}
+
+export function cachedThicknessStats(
+  values: Float32Array,
+  version: number,
+  limit: number,
+): ThicknessStats {
+  return memo(thicknesses, values, [version, limit], () => thicknessStats(values, limit))
+}
diff --git a/tests/readoutCache.test.ts b/tests/readoutCache.test.ts
new file mode 100644
index 00000000..57b10e8b
--- /dev/null
+++ b/tests/readoutCache.test.ts
@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+import { describe, expect, it } from 'vitest'
+import { deviationStats } from '../src/core/deviation/deviation'
+import { thicknessStats } from '../src/core/thickness/thickness'
+import { fieldHistogram } from '../src/core/field/stats'
+import {
+  cachedDeviationStats,
+  cachedHistogram,
+  cachedThicknessStats,
+} from '../src/core/field/readoutCache'
+
+function map(n = 500): Float32Array {
+  const v = new Float32Array(n)
+  for (let i = 0; i < n; i++) v[i] = Math.sin(i * 0.37) * 0.8
+  v[3] = NaN
+  return v
+}
+
+describe('readout cache', () => {
+  it('hands back the same object for the same arguments', () => {
+    const v = map()
+    expect(cachedHistogram(v, 1, -0.5, 0.5, -1, 1)).toBe(cachedHistogram(v, 1, -0.5, 0.5, -1, 1))
+    expect(cachedDeviationStats(v, 1, 1, 0.1)).toBe(cachedDeviationStats(v, 1, 1, 0.1))
+    expect(cachedThicknessStats(v, 1, 0.2)).toBe(cachedThicknessStats(v, 1, 0.2))
+  })
+
+  it('recomputes when the same array arrives under a new version', () => {
+    const v = map()
+    const hist = cachedHistogram(v, 1, -0.5, 0.5, -1, 1)
+    const dev = cachedDeviationStats(v, 1, 1, 0.1)
+    const thick = cachedThicknessStats(v, 1, 0.2)
+    for (let i = 0; i < v.length; i += 2) v[i] += 0.3
+    const hist2 = cachedHistogram(v, 2, -0.5, 0.5, -1, 1)
+    const dev2 = cachedDeviationStats(v, 2, 1, 0.1)
+    const thick2 = cachedThicknessStats(v, 2, 0.2)
+    expect(hist2).not.toBe(hist)
+    expect(dev2).not.toBe(dev)
+    expect(thick2).not.toBe(thick)
+    expect(hist2).toEqual(fieldHistogram(v, -0.5, 0.5, -1, 1))
+    expect(dev2).toEqual(deviationStats(v, 1, 0.1))
+    expect(thick2).toEqual(thicknessStats(v, 0.2))
+  })
+
+  it('recomputes the figure whose argument moved and keeps the other', () => {
+    const v = map()
+    const hist = cachedHistogram(v, 1, -0.5, 0.5, -1, 1)
+    const dev = cachedDeviationStats(v, 1, 1, 0.1)
+    // A range change moves the histogram only: the tally does not read the range.
+    const hist2 = cachedHistogram(v, 1, -0.25, 0.25, -1, 1)
+    expect(hist2).not.toBe(hist)
+    expect(hist2).toEqual(fieldHistogram(v, -0.25, 0.25, -1, 1))
+    expect(cachedDeviationStats(v, 1, 1, 0.1)).toBe(dev)
+    // A tolerance change moves the tally only.
+    const dev2 = cachedDeviationStats(v, 1, 1, 0.2)
+    expect(dev2).not.toBe(dev)
+    expect(dev2).toEqual(deviationStats(v, 1, 0.2))
+    expect(cachedHistogram(v, 1, -0.25, 0.25, -1, 1)).toBe(hist2)
+  })
+
+  it('keeps separate results for separate arrays', () => {
+    const a = map()
+    const b = map(300)
+    const ha = cachedHistogram(a, 1, -0.5, 0.5, -1, 1)
+    const hb = cachedHistogram(b, 1, -0.5, 0.5, -1, 1)
+    expect(hb).not.toBe(ha)
+    expect(cachedHistogram(a, 1, -0.5, 0.5, -1, 1)).toBe(ha)
+  })
+})

From 02cea4057c9b1fa646b4e27c2d3e0f5f3127cea3 Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Wed, 4 Nov 2026 16:04:14 +0000
Subject: [PATCH 11/38] perf(bvh): refit after rigid moves instead of
 rebuilding

applyTransform baked the alignment into the scan's positions and then built
the bounds tree over them from scratch on the main thread. The triangles
are the same after a rigid move, so refitAfterRigid rewrites the boxes in
place instead; it renews the bounding box and sphere with it, and builds a
tree only where the geometry has none.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 src/viewer/SceneManager.ts |  15 ++---
 src/viewer/bvh.ts          |  33 +++++++++
 tests/bvhRefit.test.ts     | 134 +++++++++++++++++++++++++++++++++++++
 3 files changed, 173 insertions(+), 9 deletions(-)
 create mode 100644 src/viewer/bvh.ts
 create mode 100644 tests/bvhRefit.test.ts

diff --git a/src/viewer/SceneManager.ts b/src/viewer/SceneManager.ts
index af98f7e7..9b0b8ae9 100644
--- a/src/viewer/SceneManager.ts
+++ b/src/viewer/SceneManager.ts
@@ -33,6 +33,7 @@ import type { SectionCut } from '../core/section/slice'
 import type { ControlScheme } from './navSchemes'
 import type { PickMarker } from './PickScene'
 import { computeBoundsTree, disposeBoundsTree } from 'three-mesh-bvh'
+import { refitAfterRigid } from './bvh'
 import type { FitData, Vec3 } from '../core/types'
 import { rigidApplyToPoints, rigidRotate, rigidRotateVectors, type Rigid } from '../core/deviation/rigid'
 import { deflectionFactor, deflectionStartPhase } from '../core/deviation/deflection'
@@ -2301,7 +2302,8 @@ export class SceneManager {
   /** Bake a datum alignment into the scan's vertices. Vertex order is
    *  untouched, so painted regions, element ownership and the deviation field
    *  all stay valid; only the coordinates (and the BVH built over them)
-   *  change. Heavy — the BVH is rebuilt synchronously. */
+   *  change. The BVH is refitted, not rebuilt: the triangles are the same, so
+   *  only the boxes round them move. */
   applyTransform(m: Rigid): void {
     if (!this.mesh) return
     const geometry = this.mesh.geometry as THREE.BufferGeometry
@@ -2311,10 +2313,8 @@ export class SceneManager {
     rigidRotateVectors(m, normals.array as Float32Array)
     positions.needsUpdate = true
     normals.needsUpdate = true
-    geometry.computeBoundingBox()
-    geometry.computeBoundingSphere()
-    geometry.disposeBoundsTree?.()
-    geometry.computeBoundsTree()
+    // Also renews the bounding box and sphere.
+    refitAfterRigid(geometry)
     // The edited copy — or the scan, while the copy is shown — is in the same
     // frame, and moves with it.
     if (this.other) {
@@ -2323,10 +2323,7 @@ export class SceneManager {
       rigidRotateVectors(m, g.getAttribute('normal').array as Float32Array)
       g.getAttribute('position').needsUpdate = true
       g.getAttribute('normal').needsUpdate = true
-      g.computeBoundingBox()
-      g.computeBoundingSphere()
-      g.disposeBoundsTree?.()
-      g.computeBoundsTree()
+      refitAfterRigid(g)
       this.other.axis = rotatedDirection(m, this.other.axis)
     }
     // So does whatever the layers keep in the scan's frame.
diff --git a/src/viewer/bvh.ts b/src/viewer/bvh.ts
new file mode 100644
index 00000000..2ca7196c
--- /dev/null
+++ b/src/viewer/bvh.ts
@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Keeping a geometry's bounds tree in step with positions that moved.
+
+import type * as THREE from 'three'
+import { computeBoundsTree } from 'three-mesh-bvh'
+
+/**
+ * Bring a geometry's culling bounds and bounds tree up to date after a rigid
+ * move was baked into its positions.
+ *
+ * A rigid move leaves the triangles and the index as they were, so the tree's
+ * shape — which triangles share a leaf — is still a good one; only the boxes
+ * around them have moved. Refitting rewrites those boxes in place, walking the
+ * tree once, where a rebuild partitions every triangle again on the main
+ * thread; on a 287k-triangle part that is about eight times less work.
+ * A mirroring counts as rigid here: the tree holds boxes and indices, never a
+ * winding, so it does not mind which way the triangles now face.
+ *
+ * Only for a move that kept the index and the vertex count. Anything that lays
+ * the geometry out again must build a tree afresh, as the tree is indexed by
+ * the triangles it was built over. The tree object stays the same one, mutated
+ * in place; nothing in the app holds on to it beyond a single call.
+ *
+ * The bounding box and sphere are renewed here too, before anything reads
+ * them: a new tree only ever sets the box on a geometry that has none, so the
+ * stale ones would otherwise outlive a fallback build as well.
+ */
+export function refitAfterRigid(geometry: THREE.BufferGeometry): void {
+  geometry.computeBoundingBox()
+  geometry.computeBoundingSphere()
+  if (geometry.boundsTree) geometry.boundsTree.refit()
+  else computeBoundsTree.call(geometry)
+}
diff --git a/tests/bvhRefit.test.ts b/tests/bvhRefit.test.ts
new file mode 100644
index 00000000..2f40b7c3
--- /dev/null
+++ b/tests/bvhRefit.test.ts
@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// A bounds tree refitted after a rigid move must answer a ray as a tree built
+// afresh over the moved positions does. The scan's alignment is baked into its
+// vertices and the tree refitted rather than rebuilt (SceneManager.applyTransform),
+// so a refit that missed a box would make a part unpickable where it now is.
+import * as THREE from 'three'
+import { MeshBVH } from 'three-mesh-bvh'
+import { describe, expect, it } from 'vitest'
+import { refitAfterRigid } from '../src/viewer/bvh'
+
+/** A seeded generator, so a failure is the same failure on every run. */
+function mulberry32(seed: number): () => number {
+  let a = seed >>> 0
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0
+    let t = a
+    t = Math.imul(t ^ (t >>> 15), t | 1)
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+  }
+}
+
+/** A lumpy sphere: indexed, a few thousand triangles, no two leaves alike. */
+function lumpySphere(rand: () => number): THREE.BufferGeometry {
+  const geometry = new THREE.SphereGeometry(10, 64, 48)
+  const p = geometry.getAttribute('position') as THREE.BufferAttribute
+  for (let i = 0; i < p.count; i++) {
+    const k = 1 + (rand() - 0.5) * 0.2
+    p.setXYZ(i, p.getX(i) * k, p.getY(i) * k, p.getZ(i) * k)
+  }
+  geometry.computeVertexNormals()
+  return geometry
+}
+
+/** Bake a transform into the positions the way the scan's alignment does:
+ *  in place, in the same array, the index untouched. */
+function bake(geometry: THREE.BufferGeometry, m: THREE.Matrix4): void {
+  const p = geometry.getAttribute('position') as THREE.BufferAttribute
+  const v = new THREE.Vector3()
+  for (let i = 0; i < p.count; i++) p.setXYZ(i, ...v.fromBufferAttribute(p, i).applyMatrix4(m).toArray())
+  p.needsUpdate = true
+}
+
+/** The first hit of 1000 rays aimed at the part from a shell around where it
+ *  now is, through the geometry's tree. A miss is null. */
+function firstHits(geometry: THREE.BufferGeometry, centre: THREE.Vector3, seed: number): (number | null)[] {
+  const rand = mulberry32(seed)
+  const bvh = geometry.boundsTree as MeshBVH
+  const ray = new THREE.Ray()
+  const hits: (number | null)[] = []
+  for (let i = 0; i < 1000; i++) {
+    // A direction uniform on the sphere, an origin well outside, an aim a
+    // little off centre so grazing hits and clean misses both turn up.
+    const z = rand() * 2 - 1
+    const phi = rand() * Math.PI * 2
+    const r = Math.sqrt(1 - z * z)
+    const dir = new THREE.Vector3(r * Math.cos(phi), r * Math.sin(phi), z)
+    const aim = new THREE.Vector3((rand() - 0.5) * 24, (rand() - 0.5) * 24, (rand() - 0.5) * 24).add(centre)
+    ray.origin.copy(aim).addScaledVector(dir, -60)
+    ray.direction.copy(dir)
+    const hit = bvh.raycastFirst(ray, THREE.DoubleSide)
+    hits.push(hit ? hit.distance : null)
+  }
+  return hits
+}
+
+function expectSameAnswers(moved: THREE.BufferGeometry, centre: THREE.Vector3): void {
+  const fresh = moved.clone()
+  fresh.boundsTree = new MeshBVH(fresh)
+  const got = firstHits(moved, centre, 99)
+  const want = firstHits(fresh, centre, 99)
+  expect(got).toHaveLength(1000)
+  // The ground truth must not be vacuous: most rays hit the part.
+  expect(want.filter((d) => d !== null).length).toBeGreaterThan(300)
+  for (let i = 0; i < 1000; i++) {
+    if (want[i] === null) expect(got[i], `ray ${i}`).toBeNull()
+    else expect(Math.abs((got[i] as number) - want[i]!), `ray ${i}`).toBeLessThan(1e-6)
+  }
+}
+
+describe('refitAfterRigid', () => {
+  const rigid = new THREE.Matrix4()
+    .makeTranslation(37, -21, 14)
+    .multiply(new THREE.Matrix4().makeRotationFromEuler(new THREE.Euler(0.7, -1.1, 2.3)))
+  const centre = new THREE.Vector3().applyMatrix4(rigid)
+
+  it('answers rays as a fresh tree does after a rotation and a translation', () => {
+    const geometry = lumpySphere(mulberry32(5))
+    geometry.boundsTree = new MeshBVH(geometry)
+    const tree = geometry.boundsTree
+    bake(geometry, rigid)
+    refitAfterRigid(geometry)
+    expect(geometry.boundsTree).toBe(tree)
+    expectSameAnswers(geometry, centre)
+  })
+
+  it('answers rays as a fresh tree does after a mirroring', () => {
+    const geometry = lumpySphere(mulberry32(6))
+    geometry.boundsTree = new MeshBVH(geometry)
+    const mirror = new THREE.Matrix4().makeScale(-1, 1, 1).premultiply(rigid)
+    bake(geometry, mirror)
+    refitAfterRigid(geometry)
+    expectSameAnswers(geometry, new THREE.Vector3().applyMatrix4(mirror))
+  })
+
+  it('renews the bounding box and sphere the culling reads', () => {
+    const geometry = lumpySphere(mulberry32(7))
+    geometry.boundsTree = new MeshBVH(geometry)
+    geometry.computeBoundingBox()
+    geometry.computeBoundingSphere()
+    bake(geometry, rigid)
+    refitAfterRigid(geometry)
+    const fresh = geometry.clone()
+    fresh.computeBoundingBox()
+    fresh.computeBoundingSphere()
+    expect(geometry.boundingBox!.min.distanceTo(fresh.boundingBox!.min)).toBeLessThan(1e-9)
+    expect(geometry.boundingBox!.max.distanceTo(fresh.boundingBox!.max)).toBeLessThan(1e-9)
+    expect(geometry.boundingSphere!.center.distanceTo(fresh.boundingSphere!.center)).toBeLessThan(1e-9)
+    expect(geometry.boundingSphere!.radius).toBeCloseTo(fresh.boundingSphere!.radius, 9)
+    // The root of the tree encloses the moved part, not the old one.
+    const root = geometry.boundsTree!.getBoundingBox(new THREE.Box3())
+    expect(root.containsBox(geometry.boundingBox!.clone().expandByScalar(-1e-4))).toBe(true)
+    expect(root.min.distanceTo(geometry.boundingBox!.min)).toBeLessThan(1e-4)
+  })
+
+  it('builds a tree when the geometry has none', () => {
+    const geometry = lumpySphere(mulberry32(8))
+    bake(geometry, rigid)
+    expect(geometry.boundsTree).toBeUndefined()
+    refitAfterRigid(geometry)
+    expect(geometry.boundsTree).toBeInstanceOf(MeshBVH)
+    expectSameAnswers(geometry, centre)
+  })
+})

From 7fc5930185c0083824c51157f91424e4008a5234 Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Wed, 4 Nov 2026 16:19:49 +0000
Subject: [PATCH 12/38] perf(bvh): refit the mesh tools' moved parts too; align
 status no longer says rebuild

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 plugins/mesh-tools/viewer/meshScene.ts | 6 ++----
 src/app/partAlignment.ts               | 4 ++--
 2 files changed, 4 insertions(+), 6 deletions(-)

diff --git a/plugins/mesh-tools/viewer/meshScene.ts b/plugins/mesh-tools/viewer/meshScene.ts
index a81e021f..63578781 100644
--- a/plugins/mesh-tools/viewer/meshScene.ts
+++ b/plugins/mesh-tools/viewer/meshScene.ts
@@ -15,6 +15,7 @@ import { applyFinish, setSurfaceColor, type ViewTheme } from '../../../src/viewe
 import { patchWireframe, setSurfaceOpacity } from '../../../src/viewer/surfaceModes'
 import { CAP_SLOT, CapSet, cutColor, type CapPart } from '../../../src/viewer/sliceCap'
 import { clipTree } from '../../../src/viewer/clipTree'
+import { refitAfterRigid } from '../../../src/viewer/bvh'
 import { paintField, type Colormap, type FieldScale } from '../../../src/core/field/colormap'
 
 /** The islands a removal would take: a warning orange, unlit, so it stands
@@ -176,10 +177,7 @@ export class MeshScene {
           const at = geometry.getAttribute('position') as THREE.BufferAttribute
           rigidApplyToPoints(m, at.array as Float32Array)
           at.needsUpdate = true
-          geometry.computeBoundingBox()
-          geometry.computeBoundingSphere()
-          geometry.disposeBoundsTree?.()
-          geometry.computeBoundsTree()
+          refitAfterRigid(geometry)
         }
         const solids = new Set(this.booleanSolids.flatMap((d) => [d.fill.geometry, d.edges.geometry]))
         for (const geometry of [...this.islandGeometries(), ...solids]) {
diff --git a/src/app/partAlignment.ts b/src/app/partAlignment.ts
index 737be6dc..220d38da 100644
--- a/src/app/partAlignment.ts
+++ b/src/app/partAlignment.ts
@@ -57,8 +57,8 @@ export function partAlignment({ clientRef, sceneRef, imports, maps, clearPreview
     useStore.setState({ busy: true })
     try {
       clearPreview()
-      useStore.getState().setStatus('Aligning part — rebuilding spatial index…')
-      // Let the status paint before the synchronous BVH rebuild.
+      useStore.getState().setStatus('Aligning part…')
+      // Let the status paint before the part moves.
       await new Promise((r) => setTimeout(r, 30))
       await clientRef.current!.transform(m)
       // The real transform goes on and the preview of it comes off together.

From 53dfcc9a5560de416385b9a157fe6936ec26b16e Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Wed, 4 Nov 2026 16:45:42 +0000
Subject: [PATCH 13/38] perf(section): warm programs at idle, closed shells in
 the worker

The section view's first tap compiled six programs and searched the
part's closed shells on the main thread. The programs are now drawn once
in idle time into a one-pixel scissor, in a throwaway scene lit like the
stage, and their materials kept so the live ones hit the program cache;
the closed shells are found by the mesh worker as a part loads and primed
into the cap's cache, keyed by the geometry asked about.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/App.tsx                |   3 +
 src/core/meshWorker.ts     |  15 ++
 src/core/workerClient.ts   |  13 ++
 src/core/workerProtocol.ts |   9 ++
 src/viewer/SceneManager.ts | 288 ++++++++++++++++++++++++++++++++++++-
 src/viewer/sliceCap.ts     |  37 ++++-
 tests/closedShells.test.ts |  78 +++++++++-
 7 files changed, 431 insertions(+), 12 deletions(-)

diff --git a/src/App.tsx b/src/App.tsx
index 0128fbee..1298f2c5 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -1642,6 +1642,9 @@ export default function App() {
               onReady={(s) => {
                 sceneRef.current = s
                 attachSurfaceScene(() => sceneRef.current)
+                // A part's closed shells are searched in the worker as it
+                // loads, not on the main thread at the first cut.
+                s.closedShellsFrom = (which) => clientRef.current!.closedShells(which)
                 s.setNavScheme(schemeById(useStore.getState().navScheme))
                 s.setViewTheme(sceneTheme(useStore.getState().viewTheme, usePrefs.getState().dark))
                 s.setSectionLineWidth(usePrefs.getState().sectionLines)
diff --git a/src/core/meshWorker.ts b/src/core/meshWorker.ts
index 320732ec..b8013b5b 100644
--- a/src/core/meshWorker.ts
+++ b/src/core/meshWorker.ts
@@ -42,6 +42,7 @@ import { planeRegionReport, segmentPlanes } from './fit/segment'
 import { meanCurvature } from './geometry/curvature'
 import { scanSpot } from './geometry/nearest'
 import { boundsOf } from './geometry/bounds'
+import { closedShells } from './geometry/closedShells'
 import { gatherVertices, queryVertices } from './geometry/query'
 import { findSymmetryPlane } from './symmetry'
 import { autoAlign } from './autoAlign'
@@ -545,6 +546,20 @@ function handle(msg: Exclude<WorkerRequest, { type: 'align-abort' }>): void {
     return
   }
 
+  if (msg.type === 'closed-shells') {
+    // On the welded copy held here: the render thread's is split for
+    // shading, but its triangles are these, in this order, and its corners
+    // are copies of these bit for bit — which is what closedShells welds on.
+    const mesh = msg.which === 'scan' ? (graph ? { positions: graph.positions, indices: graph.indices } : null) : nominal ? { positions: nominal.positions, indices: nominal.index } : null
+    if (!mesh) {
+      post({ type: 'error', requestId: msg.requestId, message: 'No model loaded.' })
+      return
+    }
+    const { closed, count } = closedShells(mesh.positions, mesh.indices)
+    post({ type: 'closed-shells-ok', requestId: msg.requestId, closed, count }, [closed.buffer])
+    return
+  }
+
   if (msg.type === 'bounds') {
     if (!graph) {
       post({ type: 'error', requestId: msg.requestId, message: 'No model loaded.' })
diff --git a/src/core/workerClient.ts b/src/core/workerClient.ts
index d07584bd..82552e86 100644
--- a/src/core/workerClient.ts
+++ b/src/core/workerClient.ts
@@ -487,6 +487,19 @@ export class MeshWorkerClient {
     return res.result
   }
 
+  /** Which of the scan's or the reference's triangles lie in closed shells,
+   *  found in the worker — see viewer/sliceCap primeClosedPart. An answer
+   *  that lands after another scan or reference was put in place is about
+   *  the one before, and is turned away rather than handed on. */
+  async closedShells(which: 'scan' | 'nominal'): Promise<{ closed: Uint8Array; count: number }> {
+    const version = () => (which === 'scan' ? this.scanVersion : this.nominalVersion)
+    const asked = version()
+    const requestId = this.nextId++
+    const res = await this.request<Extract<WorkerResponse, { type: 'closed-shells-ok' }>>({ type: 'closed-shells', requestId, which })
+    if (version() !== asked) throw new Error(`The ${which === 'scan' ? 'scan' : 'reference'} was replaced before its closed shells came back.`)
+    return { closed: res.closed, count: res.count }
+  }
+
   /** The box around the scan as it now stands, mm. */
   async bounds(): Promise<{ min: Vec3; max: Vec3 }> {
     const requestId = this.nextId++
diff --git a/src/core/workerProtocol.ts b/src/core/workerProtocol.ts
index 34d85847..f7e9e112 100644
--- a/src/core/workerProtocol.ts
+++ b/src/core/workerProtocol.ts
@@ -199,6 +199,13 @@ export type WorkerRequest =
    *  the side it stood on, a zero point. See core/autoAlign. Nothing moves:
    *  the answer is a proposal for the alignment editor. */
   | { type: 'auto-align'; requestId: number }
+  /** Which of the scan's or the reference's triangles lie in closed shells
+   *  — see geometry/closedShells — found here, off the main thread, for the
+   *  section view's caps (viewer/sliceCap primeClosedPart). The worker's
+   *  copy is welded and the render thread's split for shading, but the
+   *  triangles are the same ones in the same order, and a closed shell is
+   *  closed in either. */
+  | { type: 'closed-shells'; requestId: number; which: 'scan' | 'nominal' }
   /** A request for a plugin's part of the worker — see workerPluginApi.ts.
    *  `op` names the plugin's operation, `payload` is its own. */
   | { type: 'plugin'; requestId: number; plugin: string; op: string; payload: unknown }
@@ -323,6 +330,8 @@ export type WorkerResponse =
   | { type: 'scan-qa-ok'; requestId: number; rims: { count: number; total: number; largest: ScanRim[]; circles: ScanRim[]; moreCircles: number }; noise: { median: number; p90: number; sampled: number } }
   /** The rim's loop in order, null past the last rim. */
   | { type: 'scan-rim-ok'; requestId: number; rim: { vertices: Uint32Array; positions: Float32Array; corners: Uint32Array; closed: boolean; length: number; circle?: RimCircle } | null }
+  /** 1 for each triangle of a closed shell, and how many there are. */
+  | { type: 'closed-shells-ok'; requestId: number; closed: Uint8Array; count: number }
   /** A plugin's answer. */
   | { type: 'plugin-ok'; requestId: number; result: unknown }
   | { type: 'error'; requestId: number; message: string }
diff --git a/src/viewer/SceneManager.ts b/src/viewer/SceneManager.ts
index 9b0b8ae9..0457f7db 100644
--- a/src/viewer/SceneManager.ts
+++ b/src/viewer/SceneManager.ts
@@ -64,7 +64,8 @@ import {
 } from './surfaceModes'
 import { principalAxis } from './scanLayout'
 import { patchScanShader } from './scanShader'
-import { CAP_SLOT, closedPartOf, cutColor, SliceCap, type ClosedPart } from './sliceCap'
+import { CAP_SLOT, closedPartOf, cutColor, primeClosedPart, SliceCap, type ClosedPart } from './sliceCap'
+import type { ClosedShells } from '../core/geometry/closedShells'
 import { clippedRaycast } from './clipRaycast'
 import { clipTree } from './clipTree'
 import { CSS2DObject } from 'three/addons/renderers/CSS2DRenderer.js'
@@ -102,6 +103,51 @@ interface HeldCap {
   theme: ViewTheme
 }
 
+/** A program to warm before it is wanted — see SceneManager.warmPrograms:
+ *  the name its material is kept under, what that material was made from
+ *  (a live material, or a name for one made the same way every time), and
+ *  how to dress a throwaway scene with it, giving back what is to be kept. */
+interface WarmJob {
+  key: string
+  from: object | string
+  make: (scene: THREE.Scene) => { dispose(): void }
+}
+
+/** How much of an idle period has to be left for another program to be
+ *  warmed in it, ms: one usually takes the whole period and more. */
+const WARM_SLACK_MS = 10
+
+/** A turn of idle time for `run` — or half a second on, where the browser
+ *  has no idle callbacks; the returned function takes it back. */
+function inIdle(run: (deadline: IdleDeadline | null) => void): () => void {
+  if (typeof requestIdleCallback === 'function') {
+    const handle = requestIdleCallback((deadline) => run(deadline))
+    return () => cancelIdleCallback(handle)
+  }
+  const handle = setTimeout(() => run(null), 500)
+  return () => clearTimeout(handle)
+}
+
+/** Three corners at the origin, with every attribute `geometry` has — the
+ *  program drawn with is chosen by them as well as by the material — and
+ *  nothing to draw: what a program is warmed on (see warmPrograms). */
+function warmGeometry(geometry: THREE.BufferGeometry): THREE.BufferGeometry {
+  const tiny = new THREE.BufferGeometry()
+  for (const [name, attribute] of Object.entries(geometry.attributes)) {
+    if (!(attribute instanceof THREE.BufferAttribute)) continue
+    const array = new (attribute.array.constructor as THREE.TypedArrayConstructor)(3 * attribute.itemSize)
+    tiny.setAttribute(name, new THREE.BufferAttribute(array, attribute.itemSize, attribute.normalized))
+  }
+  return tiny
+}
+
+/** The map on the reference's material — see setReferenceMap. Matte,
+ *  whatever the scheme's finish: a CAD face square to the view takes the
+ *  whole highlight, and a map is read by its colours. */
+function referenceMapMaterial(): THREE.MeshStandardMaterial {
+  return new THREE.MeshStandardMaterial({ color: 0xffffff, vertexColors: true, side: THREE.DoubleSide, roughness: 1, metalness: 0 })
+}
+
 /** The overlay data and the marking brush are defined beside the modules that
  *  draw them; consumers keep importing everything from here. */
 export type { OverlayElement, OverlayPair, OverlayAngle, OverlayTag, ProbeMarker } from './overlays'
@@ -314,6 +360,18 @@ export class SceneManager {
   private scanCap: HeldCap | null = null
   private referenceCap: HeldCap | null = null
   private capGeometry = new THREE.PlaneGeometry(1, 1)
+  /** The materials the programs were warmed with — see warmPrograms — by
+   *  the kind of program, with what each was made from. Kept until this
+   *  viewport goes, or a part of another make warms its kind again: a
+   *  program goes with the last material that used it. */
+  private warmKeepers = new Map<string, { from: object | string; keep: { dispose(): void } }>()
+  /** The warming run in hand, and the way to take its next turn back. */
+  private warmToken = 0
+  private warmCancel: (() => void) | null = null
+  /** Where the closed shells of a part loaded are found off the main thread
+   *  — the mesh worker, wired by the app — for the section view's caps (see
+   *  sliceCap primeClosedPart). Without it, a cut finds them itself. */
+  closedShellsFrom: ((which: 'scan' | 'nominal') => Promise<ClosedShells>) | null = null
   /** Elements lit because something being built refers to them, and
    *  elements lit because a picker's option is hovered — two reasons, one
    *  look; the overlays hear the union. */
@@ -959,6 +1017,8 @@ export class SceneManager {
       )
       this.scanAxis = axis
       this.frameCamera(geometry.boundingBox!, this.scanAxis)
+      this.primeClosedShells('scan', geometry)
+      this.warmPrograms()
     })
   }
 
@@ -1645,6 +1705,215 @@ export class SceneManager {
     return { cap, wish, geometry, index: geometry.getIndex(), theme: this.theme }
   }
 
+  /**
+   * Compile, in idle time, the programs a tap would otherwise compile in its
+   * own frame: the scan and the reference cut by the section view and seen
+   * through, the cap that closes a cut, the gizmo on the plane, and the map
+   * on the reference. A program is linked the first time something is drawn
+   * with it — hundreds of milliseconds on a phone for the six the section
+   * view's first tap used to ask for — and three.js keeps it for as long as
+   * a material that used it lives, so each is drawn once here with a
+   * material of the same make, which is then kept (warmKeepers) for the
+   * live ones to find the program in the cache when their turn comes.
+   *
+   * three.js's own compile() does not do: it never sets the clipping state,
+   * so a cut material's program is not among what it compiles. Here each is
+   * really drawn, a corner-less triangle in a one-pixel scissor, into a
+   * throwaway scene. A program is chosen by the scene as well as by the
+   * material — the lights, by kind and number, the fog, the environment —
+   * so the throwaway scene is given copies of the stage's lights and the
+   * same fog and environment: drawing the stage itself instead would draw
+   * the whole scan again for each program. The renderer is the stage's, so
+   * its clipping, tone mapping and output colour space are the same too.
+   *
+   * One kind of program at a time, as idle time comes, and not under a hand
+   * moving the view; each call starts over, the run before it dropped —
+   * which is what a scan or a reference loaded, replaced or taken away does.
+   * The live materials are never touched.
+   */
+  private warmPrograms(): void {
+    this.cancelWarm()
+    const token = this.warmToken
+    let jobs: WarmJob[] | null = null
+    const step = (deadline: IdleDeadline | null): void => {
+      this.warmCancel = null
+      if (token !== this.warmToken) return
+      if (!this.viewport.navigating()) {
+        jobs ??= this.warmJobs()
+        if (jobs.length === 0) return
+        do this.warmOne(jobs.shift()!)
+        while (jobs.length > 0 && deadline !== null && deadline.timeRemaining() > WARM_SLACK_MS)
+        // The pixel drawn into is the canvas's, whose other pixels are not
+        // kept from the last frame once it was shown: the whole frame is
+        // drawn again before this task ends, so none of that is ever seen.
+        this.viewport.invalidate()
+        this.viewport.pump()
+        if (jobs.length === 0) return
+      }
+      this.warmCancel = inIdle(step)
+    }
+    this.warmCancel = inIdle(step)
+  }
+
+  /** Drop a warming run that has not finished — see warmPrograms. */
+  private cancelWarm(): void {
+    this.warmToken++
+    this.warmCancel?.()
+    this.warmCancel = null
+  }
+
+  /** What there is to warm on the stage as it now stands, the section
+   *  view's first, less one already warm from the same material. */
+  private warmJobs(): WarmJob[] {
+    const jobs: WarmJob[] = []
+    const scan = this.mesh
+    const nominal = this.nominalMesh
+    /** A part's own material, cut or whole, solid or see-through. */
+    const part = (name: string, mesh: THREE.Mesh | null, cut: boolean, seeThrough: boolean) => {
+      if (!mesh) return
+      const live = mesh.material as THREE.MeshStandardMaterial
+      const geometry = mesh.geometry as THREE.BufferGeometry
+      jobs.push({
+        key: `${name}:${cut ? 'cut' : 'whole'}:${seeThrough ? 'see-through' : 'solid'}`,
+        from: live,
+        make: (scene) => {
+          const m = live.clone()
+          // The amendments, by reference: a copy does not carry them, and
+          // the program is known by their text.
+          m.onBeforeCompile = live.onBeforeCompile
+          m.customProgramCacheKey = live.customProgramCacheKey
+          setSurfaceOpacity(m, seeThrough ? SEE_THROUGH_OPACITY : 1)
+          m.clippingPlanes = cut ? this.clipList : null
+          scene.add(new THREE.Mesh(warmGeometry(geometry), m))
+          return m
+        },
+      })
+    }
+    part('scan', scan, true, false)
+    if (scan || nominal) {
+      // The section view's cap, as updateCaps makes it: flat, in a cut
+      // colour, its counting passes cut by the plane.
+      const source = (scan ?? nominal)!.geometry as THREE.BufferGeometry
+      jobs.push({
+        key: 'cap',
+        from: 'cap',
+        make: (scene) => {
+          const target = new THREE.Mesh(warmGeometry(source), new THREE.MeshBasicMaterial({ visible: false }))
+          const cap = new SliceCap(target, this.clipList, this.capGeometry, { slot: CAP_SLOT.scan, color: cutColor(CAP_SLOT.scan), flat: true, theme: this.theme })
+          scene.add(target)
+          return {
+            dispose: () => {
+              cap.dispose()
+              ;(target.material as THREE.Material).dispose()
+            },
+          }
+        },
+      })
+      // The plane's gizmo, as ExtendGrips draws its grips: unlit and
+      // see-through, and the arrow both sides — which three.js draws in two
+      // passes, a program each; a ring is the front pass's.
+      jobs.push({
+        key: 'grips',
+        from: 'grips',
+        make: (scene) => {
+          const m = new THREE.MeshBasicMaterial({ transparent: true, opacity: 0.95, depthTest: false, depthWrite: false, side: THREE.DoubleSide })
+          scene.add(new THREE.Mesh(warmGeometry(this.capGeometry), m))
+          return m
+        },
+      })
+    }
+    part('reference', nominal, false, false)
+    if (nominal) {
+      // The map on the reference — never cut and never see-through, so the
+      // one program; made before the map is, from the material it will have.
+      jobs.push({
+        key: 'referenceMap',
+        from: 'referenceMap',
+        make: (scene) => {
+          const geometry = new THREE.BufferGeometry()
+          geometry.setAttribute('position', new THREE.BufferAttribute(new Float32Array(9), 3))
+          geometry.setAttribute('normal', new THREE.BufferAttribute(new Float32Array(9), 3))
+          geometry.setAttribute('color', new THREE.BufferAttribute(new Uint8Array(9), 3, true))
+          const m = referenceMapMaterial()
+          scene.add(new THREE.Mesh(geometry, m))
+          return m
+        },
+      })
+    }
+    part('reference', nominal, true, false)
+    for (const cut of [false, true]) {
+      part('scan', scan, cut, true)
+      part('reference', nominal, cut, true)
+    }
+    part('scan', scan, false, false)
+    return jobs.filter((job) => this.warmKeepers.get(job.key)?.from !== job.from)
+  }
+
+  /** Draw one job's throwaway scene into a pixel, keep its material, and
+   *  let go of the rest. */
+  private warmOne(job: WarmJob): void {
+    const renderer = this.viewport.renderer
+    const scene = new THREE.Scene()
+    const lights: THREE.Light[] = []
+    this.scene.traverseVisible((o) => {
+      if (!(o as THREE.Light).isLight) return
+      const light = (o as THREE.Light).clone(false)
+      lights.push(light)
+      scene.add(light)
+    })
+    scene.environment = this.scene.environment
+    scene.fog = this.scene.fog
+    const keep = job.make(scene)
+    // The triangles have no size: kept from the frustum test, which would
+    // otherwise be all that decides whether they are drawn.
+    scene.traverse((o) => {
+      o.frustumCulled = false
+    })
+    const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0.1, 10)
+    camera.position.set(0, 0, 5)
+    const viewport = renderer.getViewport(new THREE.Vector4())
+    const scissor = renderer.getScissor(new THREE.Vector4())
+    const scissorTest = renderer.getScissorTest()
+    renderer.setScissorTest(true)
+    renderer.setScissor(0, 0, 1, 1)
+    renderer.setViewport(0, 0, 1, 1)
+    try {
+      renderer.render(scene, camera)
+    } finally {
+      renderer.setViewport(viewport)
+      renderer.setScissor(scissor)
+      renderer.setScissorTest(scissorTest)
+    }
+    // The geometries are this job's own but for the cap's sheet, which is
+    // the stage's.
+    scene.traverse((o) => {
+      const geometry = (o as THREE.Mesh).geometry as THREE.BufferGeometry | undefined
+      if (geometry && geometry !== this.capGeometry) geometry.dispose()
+    })
+    for (const light of lights) light.dispose()
+    // The program stays referenced throughout: the new keeper holds it
+    // before the old one lets go.
+    const held = this.warmKeepers.get(job.key)
+    this.warmKeepers.set(job.key, { from: job.from, keep })
+    held?.keep.dispose()
+  }
+
+  /** Have the closed shells of a part just put in place found off the main
+   *  thread (see closedShellsFrom), for its first cut to find ready. An
+   *  answer is kept only for the geometry it was asked about, still the
+   *  part's; one that comes back for a part since replaced is dropped, and
+   *  that part's cut finds its own. */
+  private primeClosedShells(which: 'scan' | 'nominal', geometry: THREE.BufferGeometry): void {
+    this.closedShellsFrom?.(which).then(
+      (shells) => {
+        const mesh = which === 'scan' ? this.mesh : this.nominalMesh
+        if (mesh?.geometry === geometry) primeClosedPart(geometry, shells)
+      },
+      // Not found off the thread: found on it, if a cut comes to need them.
+      () => {},
+    )
+  }
+
   /**
    * Cut what is drawn on the part with the section view: the elements, the
    * dimensions, the sections and the pins — their meshes and lines clipped
@@ -2282,6 +2551,8 @@ export class SceneManager {
       this.scene.add(this.nominalMesh)
       // Cut with the rest, if the section view is cutting.
       this.applySlice()
+      this.primeClosedShells('nominal', geometry)
+      this.warmPrograms()
       this.invalidate()
     })
   }
@@ -2290,12 +2561,16 @@ export class SceneManager {
     this.disposeMesh()
     this.setPreview(null)
     this.setAlignment(null)
+    // A run under way may hold the scan's material: started again on what
+    // is left.
+    this.warmPrograms()
     this.invalidate()
   }
 
   clearNominal(): void {
     this.disposeNominal()
     this.setReferenceMap(null)
+    this.warmPrograms()
     this.invalidate()
   }
 
@@ -2428,13 +2703,13 @@ export class SceneManager {
       geometry.setIndex(new THREE.BufferAttribute(mesh.indices, 1))
       geometry.computeBoundingBox()
       geometry.computeBoundingSphere()
-      // Matte, whatever the scheme's finish: a CAD face square to the view
-      // takes the whole highlight, and a map is read by its colours.
-      const material = new THREE.MeshStandardMaterial({ color: 0xffffff, vertexColors: true, side: THREE.DoubleSide, roughness: 1, metalness: 0 })
-      this.referenceMapMesh = new THREE.Mesh(geometry, material)
+      this.referenceMapMesh = new THREE.Mesh(geometry, referenceMapMaterial())
       this.referenceMapMesh.visible = false
       this.referenceMapMesh.renderOrder = 1
       this.scene.add(this.referenceMapMesh)
+      // Its program was warmed with the reference's; a run is cheap when
+      // every kind is warm already.
+      this.warmPrograms()
     }
     this.invalidate()
   }
@@ -2977,6 +3252,9 @@ export class SceneManager {
     this.gizmo.dispose()
     this.disposeNominal()
     this.disposeMesh()
+    this.cancelWarm()
+    for (const { keep } of this.warmKeepers.values()) keep.dispose()
+    this.warmKeepers.clear()
     this.viewport.dispose()
   }
 
diff --git a/src/viewer/sliceCap.ts b/src/viewer/sliceCap.ts
index f0081608..edef0d3c 100644
--- a/src/viewer/sliceCap.ts
+++ b/src/viewer/sliceCap.ts
@@ -3,7 +3,7 @@
 // SceneManager.setSlicePlane and setSectionView.
 
 import * as THREE from 'three'
-import { closedShells } from '../core/geometry/closedShells'
+import { closedShells, type ClosedShells } from '../core/geometry/closedShells'
 import { CAPPED_TRIANGLES } from './clipRaycast'
 import { hatch } from './hatch'
 import { applyFinish, setSurfaceColor, type ViewTheme } from './viewThemes'
@@ -57,14 +57,41 @@ export interface ClosedPart {
  *  nothing. */
 const closedCache = new WeakMap<object, ClosedPart>()
 
-/** The closed shells of a part's geometry — see core/geometry/closedShells. */
+/** The closed shells of a part's geometry — see core/geometry/closedShells.
+ *  Found here, on the main thread, only when nothing primed them (see
+ *  primeClosedPart). */
 export function closedPartOf(geometry: THREE.BufferGeometry): ClosedPart {
   const index = geometry.getIndex()
   const position = geometry.getAttribute('position')
   const key = index ?? position
   const known = closedCache.get(key)
   if (known) return known
-  const shells = closedShells(position.array as Float32Array, index ? index.array : null)
+  const part = partOf(closedShells(position.array as Float32Array, index ? index.array : null), index)
+  closedCache.set(key, part)
+  return part
+}
+
+/**
+ * Keep closed shells found elsewhere as this geometry's — the mesh worker's,
+ * found on its own welded copy of the same triangles in the same order (a
+ * split for shading only repeats corners, bit for bit) — so the first cut
+ * of a part loaded does not search it on the main thread. False, and
+ * nothing kept, when the answer cannot be about these triangles: a part
+ * replaced while it was on its way has another count of them.
+ */
+export function primeClosedPart(geometry: THREE.BufferGeometry, shells: ClosedShells): boolean {
+  const index = geometry.getIndex()
+  const position = geometry.getAttribute('position')
+  const total = Math.floor((index ? index.count : position.count) / 3)
+  if (shells.closed.length !== total) return false
+  const key = index ?? position
+  if (!closedCache.has(key)) closedCache.set(key, partOf(shells, index))
+  return true
+}
+
+/** The closed shells of a part with the index of their corners, when they
+ *  are not all of it. */
+function partOf(shells: ClosedShells, index: THREE.BufferAttribute | null): ClosedPart {
   const total = shells.closed.length
   let subset: Uint32Array | null = null
   if (shells.count > 0 && shells.count < total) {
@@ -75,9 +102,7 @@ export function closedPartOf(geometry: THREE.BufferGeometry): ClosedPart {
       for (let c = 0; c < 3; c++) subset[k++] = index ? index.getX(3 * t + c) : 3 * t + c
     }
   }
-  const part = { closed: shells.closed, count: shells.count, total, index: subset }
-  closedCache.set(key, part)
-  return part
+  return { closed: shells.closed, count: shells.count, total, index: subset }
 }
 
 export interface SliceCapOptions {
diff --git a/tests/closedShells.test.ts b/tests/closedShells.test.ts
index 692320f5..1af64670 100644
--- a/tests/closedShells.test.ts
+++ b/tests/closedShells.test.ts
@@ -1,8 +1,13 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 // Which shells of a mesh are closed — what decides where the section view
 // closes a cut with a cap and where it leaves it open.
+import * as THREE from 'three'
 import { describe, expect, it } from 'vitest'
-import { closedShells } from '../src/core/geometry/closedShells'
+import { buildMeshGraph } from '../src/core/geometry/buildGraph'
+import { closedShells, type ClosedShells } from '../src/core/geometry/closedShells'
+import { scanRender, splitCreases } from '../src/core/geometry/crease'
+import { wireSlots } from '../src/core/geometry/wireSlots'
+import { closedPartOf, primeClosedPart } from '../src/viewer/sliceCap'
 
 /** A unit cube at `at`, eight corners and twelve triangles wound outward. */
 function cube(at: [number, number, number] = [0, 0, 0]): { positions: number[]; indices: number[] } {
@@ -84,3 +89,74 @@ describe('closedShells', () => {
     expect(closedShells(withCopy, indices).count).toBe(12)
   })
 })
+
+/** The meshes above, each as it reaches the worker. */
+const fixtures = (): [string, { positions: number[]; indices: number[] }][] => {
+  const holed = cube([5, 0, 0])
+  holed.indices.splice(0, 6)
+  const fin = cube()
+  fin.positions.push(0.5, 1, 2)
+  fin.indices.push(6, 7, 8)
+  return [
+    ['a closed cube', cube()],
+    ['a cube with a hole', holed],
+    ['a closed cube beside an open one', join(cube(), holed)],
+    ['a cube with a fin', fin],
+  ]
+}
+
+/** A geometry laid out as the viewport lays out a part: the render arrays
+ *  the worker posts, indexed. */
+function geometryOf(positions: Float32Array, indices: Uint32Array): THREE.BufferGeometry {
+  const g = new THREE.BufferGeometry()
+  g.setAttribute('position', new THREE.BufferAttribute(positions, 3))
+  g.setIndex(new THREE.BufferAttribute(indices, 1))
+  return g
+}
+
+const plain = (s: ClosedShells) => ({ closed: [...s.closed], count: s.count })
+
+describe('closed shells from the worker', () => {
+  // The worker finds them on its own welded copy — the scan's graph, the
+  // reference's surface — while the viewport's copy of the same triangles
+  // is split at the sharp edges for shading. The answer has to be the one
+  // the viewport would have found on its own, triangle for triangle.
+  for (const [name, mesh] of fixtures()) {
+    it(`agrees with the viewport's own on ${name}`, () => {
+      const graph = buildMeshGraph({ kind: 'indexed', positions: new Float32Array(mesh.positions), indices: new Uint32Array(mesh.indices) })
+      const worker = closedShells(graph.positions, graph.indices)
+      // The scan, split as the setting says, every way it can be.
+      for (const mode of ['on', 'off', 'auto'] as const) {
+        const render = scanRender(graph, { mode, angleDeg: 30 })
+        expect(plain(worker), mode).toEqual(plain(closedShells(render.positions, render.indices)))
+      }
+      // The reference, always split.
+      const slots = wireSlots(graph.adjOffsets, graph.adjList, graph.vertexCount)
+      const split = splitCreases(graph.positions, graph.indices, slots)
+      if (split) expect(plain(worker)).toEqual(plain(closedShells(split.positions, split.indices)))
+    })
+
+    it(`primes the viewport's cache with what it would have found on ${name}`, () => {
+      const graph = buildMeshGraph({ kind: 'indexed', positions: new Float32Array(mesh.positions), indices: new Uint32Array(mesh.indices) })
+      const render = scanRender(graph, { mode: 'on', angleDeg: 30 })
+      const primed = geometryOf(render.positions, render.indices)
+      expect(primeClosedPart(primed, closedShells(graph.positions, graph.indices))).toBe(true)
+      const found = closedPartOf(geometryOf(render.positions.slice(), render.indices.slice()))
+      const kept = closedPartOf(primed)
+      expect([...kept.closed]).toEqual([...found.closed])
+      expect(kept.count).toBe(found.count)
+      expect(kept.total).toBe(found.total)
+      expect(kept.index ? [...kept.index] : null).toEqual(found.index ? [...found.index] : null)
+    })
+  }
+
+  it('turns away an answer about other triangles', () => {
+    const m = cube()
+    const g = geometryOf(new Float32Array(m.positions), new Uint32Array(m.indices))
+    // One triangle short: a reply about some other mesh.
+    const other = run({ positions: m.positions, indices: m.indices.slice(3) })
+    expect(primeClosedPart(g, other)).toBe(false)
+    // Found on the geometry itself instead.
+    expect(closedPartOf(g).count).toBe(12)
+  })
+})

From a255d9a4a0080474322a131452675aa6bae0e9b3 Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Wed, 4 Nov 2026 17:34:36 +0000
Subject: [PATCH 14/38] perf(section): closed shells by render vertex; one
 program per warm slot

The worker's closed mask was per triangle in its own order, while a
bounds tree reorders the render index before the part is shown and the
reference's surface keeps an index of its own: a part with closed and
open shells got another part's mask. The worker now answers a vertex at
a time over the render layout (its vertices, then its shading copies),
which no tree reorders, and the main thread reads each triangle through
its index as it stands. A warm job now compiles one program at most,
and the repaint and disposal hold if a job throws.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/core/geometry/closedShells.ts |  47 +++++--
 src/core/meshWorker.ts            |  28 +++-
 src/core/workerClient.ts          |  14 +-
 src/core/workerProtocol.ts        |  18 +--
 src/viewer/SceneManager.ts        | 219 +++++++++++++++++-------------
 src/viewer/sliceCap.ts            |  27 ++--
 tests/closedShells.test.ts        | 110 ++++++++++-----
 7 files changed, 294 insertions(+), 169 deletions(-)

diff --git a/src/core/geometry/closedShells.ts b/src/core/geometry/closedShells.ts
index 6376f6ad..b4eb10d0 100644
--- a/src/core/geometry/closedShells.ts
+++ b/src/core/geometry/closedShells.ts
@@ -26,6 +26,40 @@ export interface ClosedShells {
 /** The closed shells of a triangle mesh — `indices` null for a soup, its
  *  triangles three vertices after another. */
 export function closedShells(positions: Float32Array, indices: ArrayLike<number> | null): ClosedShells {
+  const { triangles, corner, id, closedAt } = shellsOf(positions, indices)
+  const closed = new Uint8Array(triangles)
+  let count = 0
+  for (let t = 0; t < triangles; t++) {
+    if (closedAt(id[corner(3 * t)])) {
+      closed[t] = 1
+      count++
+    }
+  }
+  return { closed, count }
+}
+
+/**
+ * The same answer a vertex at a time: 1 for each vertex of a closed shell.
+ * A triangle's shell is each of its corners' shell, so a triangle is closed
+ * when its first corner is — whatever order the triangles are later put in:
+ * a bounds tree built over the mesh reorders its index and never its
+ * vertices. `copyOf` lays the answer over a copy of the mesh split for
+ * shading (see crease.ts) — its vertices, then one for each copy, the
+ * copy's vertex's — which, its corners repeated bit for bit, has the same
+ * shells. A vertex no triangle uses says nothing.
+ */
+export function closedVertices(positions: Float32Array, indices: ArrayLike<number> | null, copyOf: ArrayLike<number> = []): Uint8Array {
+  const { id, closedAt } = shellsOf(positions, indices)
+  const vertexCount = id.length
+  const flags = new Uint8Array(vertexCount + copyOf.length)
+  for (let v = 0; v < vertexCount; v++) flags[v] = closedAt(id[v]) ? 1 : 0
+  for (let k = 0; k < copyOf.length; k++) flags[vertexCount + k] = flags[copyOf[k]]
+  return flags
+}
+
+/** The shells of a mesh, tallied: each vertex's welded id and whether the
+ *  shell a welded vertex lies in is closed. */
+function shellsOf(positions: Float32Array, indices: ArrayLike<number> | null) {
   const vertexCount = Math.floor(positions.length / 3)
   const triangles = Math.floor((indices ? indices.length : vertexCount) / 3)
   const corner = indices ? (i: number) => indices[i] : (i: number) => i
@@ -58,16 +92,11 @@ export function closedShells(positions: Float32Array, indices: ArrayLike<number>
     tally(r, c2, c0)
   }
 
-  const closed = new Uint8Array(triangles)
-  let count = 0
-  for (let t = 0; t < triangles; t++) {
-    const r = sets.find(id[corner(3 * t)])
-    if (lo[r] === 0 && hi[r] === 0) {
-      closed[t] = 1
-      count++
-    }
+  const closedAt = (w: number): boolean => {
+    const r = sets.find(w)
+    return lo[r] === 0 && hi[r] === 0
   }
-  return { closed, count }
+  return { triangles, corner, id, closedAt }
 }
 
 /** Each vertex's welded id: the first vertex with its exact bits — −0 read
diff --git a/src/core/meshWorker.ts b/src/core/meshWorker.ts
index b8013b5b..088384e6 100644
--- a/src/core/meshWorker.ts
+++ b/src/core/meshWorker.ts
@@ -42,7 +42,7 @@ import { planeRegionReport, segmentPlanes } from './fit/segment'
 import { meanCurvature } from './geometry/curvature'
 import { scanSpot } from './geometry/nearest'
 import { boundsOf } from './geometry/bounds'
-import { closedShells } from './geometry/closedShells'
+import { closedVertices } from './geometry/closedShells'
 import { gatherVertices, queryVertices } from './geometry/query'
 import { findSymmetryPlane } from './symmetry'
 import { autoAlign } from './autoAlign'
@@ -89,6 +89,11 @@ function scanLoops(g: MeshGraph): RimLoop[] {
   }
   return loops
 }
+/** The copies the render thread's layout of each model last posted was
+ *  split into for shading (see geometry/crease.ts) — the scan's by its
+ *  graph, the reference's by its surface — what lays a vertex-by-vertex
+ *  answer over that layout (see 'closed-shells'). */
+const renderCopies = new WeakMap<object, Uint32Array>()
 const stagedScans = new Map<number, MeshGraph>()
 const stagedNominals = new Map<number, NominalSurface>()
 
@@ -112,6 +117,8 @@ function postScan(
 ): void {
   if (crease.mode !== 'off') progress('Finding sharp edges…')
   const { positions, indices, normals, wireSlots: slots, copyOf, crease: report } = scanRender(g, crease)
+  // Kept: the posted one goes over with the rest.
+  renderCopies.set(g, copyOf.slice())
   // The file's own colours are the render thread's alone: nothing measured
   // here reads them, and a worker restart reads the geometry back without.
   const colors = file?.colors && file.colors.length === g.vertexCount * 3 ? file.colors : undefined
@@ -404,6 +411,7 @@ function handle(msg: Exclude<WorkerRequest, { type: 'align-abort' }>): void {
       const indices = split ? split.indices : g.indices.slice()
       const normals = split ? split.normals : g.normals.slice()
       const slots = split ? split.wireSlots : slotsOwn
+      renderCopies.set(candidate, split ? split.copyOf : new Uint32Array(0))
       post(
         {
           type: 'nominal-loaded',
@@ -547,16 +555,22 @@ function handle(msg: Exclude<WorkerRequest, { type: 'align-abort' }>): void {
   }
 
   if (msg.type === 'closed-shells') {
-    // On the welded copy held here: the render thread's is split for
-    // shading, but its triangles are these, in this order, and its corners
-    // are copies of these bit for bit — which is what closedShells welds on.
-    const mesh = msg.which === 'scan' ? (graph ? { positions: graph.positions, indices: graph.indices } : null) : nominal ? { positions: nominal.positions, indices: nominal.index } : null
+    // On the welded copy held here, laid over the render thread's split
+    // copy by the copies it was split into: the same vertices, then copies
+    // of some of them bit for bit — the same shells. A vertex at a time, as
+    // nothing here or there keeps the triangles in one order: a bounds tree
+    // (the reference's, a thickness ray's, the render thread's) reorders an
+    // index in place, and never a vertex.
+    const mesh =
+      msg.which === 'scan'
+        ? graph && { held: graph, positions: graph.positions, indices: graph.indices }
+        : nominal && { held: nominal, positions: nominal.positions, indices: nominal.index }
     if (!mesh) {
       post({ type: 'error', requestId: msg.requestId, message: 'No model loaded.' })
       return
     }
-    const { closed, count } = closedShells(mesh.positions, mesh.indices)
-    post({ type: 'closed-shells-ok', requestId: msg.requestId, closed, count }, [closed.buffer])
+    const closed = closedVertices(mesh.positions, mesh.indices, renderCopies.get(mesh.held) ?? [])
+    post({ type: 'closed-shells-ok', requestId: msg.requestId, closed }, [closed.buffer])
     return
   }
 
diff --git a/src/core/workerClient.ts b/src/core/workerClient.ts
index 82552e86..b42a9436 100644
--- a/src/core/workerClient.ts
+++ b/src/core/workerClient.ts
@@ -487,17 +487,19 @@ export class MeshWorkerClient {
     return res.result
   }
 
-  /** Which of the scan's or the reference's triangles lie in closed shells,
-   *  found in the worker — see viewer/sliceCap primeClosedPart. An answer
-   *  that lands after another scan or reference was put in place is about
-   *  the one before, and is turned away rather than handed on. */
-  async closedShells(which: 'scan' | 'nominal'): Promise<{ closed: Uint8Array; count: number }> {
+  /** Which of the scan's or the reference's vertices lie in closed shells —
+   *  1 for each, over the render layout last loaded (its vertices, then its
+   *  shading copies) — found in the worker; see viewer/sliceCap
+   *  primeClosedPart. An answer that lands after another scan or reference
+   *  was put in place is about the one before, and is turned away rather
+   *  than handed on. */
+  async closedShells(which: 'scan' | 'nominal'): Promise<Uint8Array> {
     const version = () => (which === 'scan' ? this.scanVersion : this.nominalVersion)
     const asked = version()
     const requestId = this.nextId++
     const res = await this.request<Extract<WorkerResponse, { type: 'closed-shells-ok' }>>({ type: 'closed-shells', requestId, which })
     if (version() !== asked) throw new Error(`The ${which === 'scan' ? 'scan' : 'reference'} was replaced before its closed shells came back.`)
-    return { closed: res.closed, count: res.count }
+    return res.closed
   }
 
   /** The box around the scan as it now stands, mm. */
diff --git a/src/core/workerProtocol.ts b/src/core/workerProtocol.ts
index f7e9e112..92b6b293 100644
--- a/src/core/workerProtocol.ts
+++ b/src/core/workerProtocol.ts
@@ -199,12 +199,14 @@ export type WorkerRequest =
    *  the side it stood on, a zero point. See core/autoAlign. Nothing moves:
    *  the answer is a proposal for the alignment editor. */
   | { type: 'auto-align'; requestId: number }
-  /** Which of the scan's or the reference's triangles lie in closed shells
-   *  — see geometry/closedShells — found here, off the main thread, for the
-   *  section view's caps (viewer/sliceCap primeClosedPart). The worker's
-   *  copy is welded and the render thread's split for shading, but the
-   *  triangles are the same ones in the same order, and a closed shell is
-   *  closed in either. */
+  /** Which of the scan's or the reference's vertices lie in closed shells
+   *  — see geometry/closedShells closedVertices — found here, off the main
+   *  thread, for the section view's caps (viewer/sliceCap primeClosedPart).
+   *  Answered a vertex at a time, over the render thread's layout of the
+   *  part — its vertices, then the copies its sharp edges were split into —
+   *  and not a triangle at a time: the render thread's bounds tree puts its
+   *  triangles in an order of its own, and so does the reference's here,
+   *  but neither moves a vertex. */
   | { type: 'closed-shells'; requestId: number; which: 'scan' | 'nominal' }
   /** A request for a plugin's part of the worker — see workerPluginApi.ts.
    *  `op` names the plugin's operation, `payload` is its own. */
@@ -330,8 +332,8 @@ export type WorkerResponse =
   | { type: 'scan-qa-ok'; requestId: number; rims: { count: number; total: number; largest: ScanRim[]; circles: ScanRim[]; moreCircles: number }; noise: { median: number; p90: number; sampled: number } }
   /** The rim's loop in order, null past the last rim. */
   | { type: 'scan-rim-ok'; requestId: number; rim: { vertices: Uint32Array; positions: Float32Array; corners: Uint32Array; closed: boolean; length: number; circle?: RimCircle } | null }
-  /** 1 for each triangle of a closed shell, and how many there are. */
-  | { type: 'closed-shells-ok'; requestId: number; closed: Uint8Array; count: number }
+  /** 1 for each render vertex of a closed shell. */
+  | { type: 'closed-shells-ok'; requestId: number; closed: Uint8Array }
   /** A plugin's answer. */
   | { type: 'plugin-ok'; requestId: number; result: unknown }
   | { type: 'error'; requestId: number; message: string }
diff --git a/src/viewer/SceneManager.ts b/src/viewer/SceneManager.ts
index 0457f7db..053e4673 100644
--- a/src/viewer/SceneManager.ts
+++ b/src/viewer/SceneManager.ts
@@ -65,7 +65,6 @@ import {
 import { principalAxis } from './scanLayout'
 import { patchScanShader } from './scanShader'
 import { CAP_SLOT, closedPartOf, cutColor, primeClosedPart, SliceCap, type ClosedPart } from './sliceCap'
-import type { ClosedShells } from '../core/geometry/closedShells'
 import { clippedRaycast } from './clipRaycast'
 import { clipTree } from './clipTree'
 import { CSS2DObject } from 'three/addons/renderers/CSS2DRenderer.js'
@@ -371,7 +370,7 @@ export class SceneManager {
   /** Where the closed shells of a part loaded are found off the main thread
    *  — the mesh worker, wired by the app — for the section view's caps (see
    *  sliceCap primeClosedPart). Without it, a cut finds them itself. */
-  closedShellsFrom: ((which: 'scan' | 'nominal') => Promise<ClosedShells>) | null = null
+  closedShellsFrom: ((which: 'scan' | 'nominal') => Promise<Uint8Array>) | null = null
   /** Elements lit because something being built refers to them, and
    *  elements lit because a picker's option is hovered — two reasons, one
    *  look; the overlays hear the union. */
@@ -1741,13 +1740,17 @@ export class SceneManager {
       if (!this.viewport.navigating()) {
         jobs ??= this.warmJobs()
         if (jobs.length === 0) return
-        do this.warmOne(jobs.shift()!)
-        while (jobs.length > 0 && deadline !== null && deadline.timeRemaining() > WARM_SLACK_MS)
-        // The pixel drawn into is the canvas's, whose other pixels are not
-        // kept from the last frame once it was shown: the whole frame is
-        // drawn again before this task ends, so none of that is ever seen.
-        this.viewport.invalidate()
-        this.viewport.pump()
+        try {
+          do this.warmOne(jobs.shift()!)
+          while (jobs.length > 0 && deadline !== null && deadline.timeRemaining() > WARM_SLACK_MS)
+        } finally {
+          // The pixel drawn into is the canvas's, whose other pixels are not
+          // kept from the last frame once it was shown: the whole frame is
+          // drawn again before this task ends, so none of that is ever seen
+          // — a job that threw after the pixel was cleared included.
+          this.viewport.invalidate()
+          this.viewport.pump()
+        }
         if (jobs.length === 0) return
       }
       this.warmCancel = inIdle(step)
@@ -1763,7 +1766,12 @@ export class SceneManager {
   }
 
   /** What there is to warm on the stage as it now stands, the section
-   *  view's first, less one already warm from the same material. */
+   *  view's first, less one already warm from the same material. A job
+   *  compiles one program at most, so that one idle turn costs one: a
+   *  see-through surface drawn both sides is drawn by three.js in two
+   *  passes — the back faces, then the front, a program each — and a
+   *  material made one-sided with a pass's side is given that pass's
+   *  program; a cap is three meshes, warmed one by one. */
   private warmJobs(): WarmJob[] {
     const jobs: WarmJob[] = []
     const scan = this.mesh
@@ -1773,54 +1781,66 @@ export class SceneManager {
       if (!mesh) return
       const live = mesh.material as THREE.MeshStandardMaterial
       const geometry = mesh.geometry as THREE.BufferGeometry
-      jobs.push({
-        key: `${name}:${cut ? 'cut' : 'whole'}:${seeThrough ? 'see-through' : 'solid'}`,
-        from: live,
-        make: (scene) => {
-          const m = live.clone()
-          // The amendments, by reference: a copy does not carry them, and
-          // the program is known by their text.
-          m.onBeforeCompile = live.onBeforeCompile
-          m.customProgramCacheKey = live.customProgramCacheKey
-          setSurfaceOpacity(m, seeThrough ? SEE_THROUGH_OPACITY : 1)
-          m.clippingPlanes = cut ? this.clipList : null
-          scene.add(new THREE.Mesh(warmGeometry(geometry), m))
-          return m
-        },
-      })
+      const sides = seeThrough && live.side === THREE.DoubleSide ? [THREE.BackSide, THREE.FrontSide] : [live.side]
+      for (const side of sides) {
+        jobs.push({
+          key: `${name}:${cut ? 'cut' : 'whole'}:${seeThrough ? 'see-through' : 'solid'}:${side}`,
+          from: live,
+          make: (scene) => {
+            const m = live.clone()
+            // The amendments, by reference: a copy does not carry them, and
+            // the program is known by their text.
+            m.onBeforeCompile = live.onBeforeCompile
+            m.customProgramCacheKey = live.customProgramCacheKey
+            setSurfaceOpacity(m, seeThrough ? SEE_THROUGH_OPACITY : 1)
+            m.clippingPlanes = cut ? this.clipList : null
+            m.side = side
+            scene.add(new THREE.Mesh(warmGeometry(geometry), m))
+            return m
+          },
+        })
+      }
     }
     part('scan', scan, true, false)
     if (scan || nominal) {
       // The section view's cap, as updateCaps makes it: flat, in a cut
-      // colour, its counting passes cut by the plane.
+      // colour, its counting passes cut by the plane — the passes up and
+      // down and the sheet, one at a time, the others put out of the way.
       const source = (scan ?? nominal)!.geometry as THREE.BufferGeometry
-      jobs.push({
-        key: 'cap',
-        from: 'cap',
-        make: (scene) => {
-          const target = new THREE.Mesh(warmGeometry(source), new THREE.MeshBasicMaterial({ visible: false }))
-          const cap = new SliceCap(target, this.clipList, this.capGeometry, { slot: CAP_SLOT.scan, color: cutColor(CAP_SLOT.scan), flat: true, theme: this.theme })
-          scene.add(target)
-          return {
-            dispose: () => {
-              cap.dispose()
-              ;(target.material as THREE.Material).dispose()
-            },
-          }
-        },
-      })
+      for (const pass of [0, 1, 2]) {
+        jobs.push({
+          key: `cap:${pass}`,
+          from: 'cap',
+          make: (scene) => {
+            const target = new THREE.Mesh(warmGeometry(source), new THREE.MeshBasicMaterial({ visible: false }))
+            const cap = new SliceCap(target, this.clipList, this.capGeometry, { slot: CAP_SLOT.scan, color: cutColor(CAP_SLOT.scan), flat: true, theme: this.theme })
+            target.children.forEach((mesh, i) => {
+              mesh.visible = i === pass
+            })
+            scene.add(target)
+            return {
+              dispose: () => {
+                cap.dispose()
+                ;(target.material as THREE.Material).dispose()
+              },
+            }
+          },
+        })
+      }
       // The plane's gizmo, as ExtendGrips draws its grips: unlit and
-      // see-through, and the arrow both sides — which three.js draws in two
-      // passes, a program each; a ring is the front pass's.
-      jobs.push({
-        key: 'grips',
-        from: 'grips',
-        make: (scene) => {
-          const m = new THREE.MeshBasicMaterial({ transparent: true, opacity: 0.95, depthTest: false, depthWrite: false, side: THREE.DoubleSide })
-          scene.add(new THREE.Mesh(warmGeometry(this.capGeometry), m))
-          return m
-        },
-      })
+      // see-through, the arrow both sides — two passes, as above — and a
+      // ring the front pass's.
+      for (const side of [THREE.FrontSide, THREE.BackSide]) {
+        jobs.push({
+          key: `grips:${side}`,
+          from: 'grips',
+          make: (scene) => {
+            const m = new THREE.MeshBasicMaterial({ transparent: true, opacity: 0.95, depthTest: false, depthWrite: false, side })
+            scene.add(new THREE.Mesh(warmGeometry(this.capGeometry), m))
+            return m
+          },
+        })
+      }
     }
     part('reference', nominal, false, false)
     if (nominal) {
@@ -1850,64 +1870,73 @@ export class SceneManager {
   }
 
   /** Draw one job's throwaway scene into a pixel, keep its material, and
-   *  let go of the rest. */
+   *  let go of the rest — all of it, the material too, if the job throws. */
   private warmOne(job: WarmJob): void {
     const renderer = this.viewport.renderer
     const scene = new THREE.Scene()
     const lights: THREE.Light[] = []
-    this.scene.traverseVisible((o) => {
-      if (!(o as THREE.Light).isLight) return
-      const light = (o as THREE.Light).clone(false)
-      lights.push(light)
-      scene.add(light)
-    })
-    scene.environment = this.scene.environment
-    scene.fog = this.scene.fog
-    const keep = job.make(scene)
-    // The triangles have no size: kept from the frustum test, which would
-    // otherwise be all that decides whether they are drawn.
-    scene.traverse((o) => {
-      o.frustumCulled = false
-    })
-    const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0.1, 10)
-    camera.position.set(0, 0, 5)
-    const viewport = renderer.getViewport(new THREE.Vector4())
-    const scissor = renderer.getScissor(new THREE.Vector4())
-    const scissorTest = renderer.getScissorTest()
-    renderer.setScissorTest(true)
-    renderer.setScissor(0, 0, 1, 1)
-    renderer.setViewport(0, 0, 1, 1)
+    let keep: { dispose(): void } | null = null
+    let kept = false
     try {
-      renderer.render(scene, camera)
+      this.scene.traverseVisible((o) => {
+        if (!(o as THREE.Light).isLight) return
+        const light = (o as THREE.Light).clone(false)
+        lights.push(light)
+        scene.add(light)
+      })
+      scene.environment = this.scene.environment
+      scene.fog = this.scene.fog
+      keep = job.make(scene)
+      // The triangles have no size: kept from the frustum test, which would
+      // otherwise be all that decides whether they are drawn.
+      scene.traverse((o) => {
+        o.frustumCulled = false
+      })
+      const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0.1, 10)
+      camera.position.set(0, 0, 5)
+      const viewport = renderer.getViewport(new THREE.Vector4())
+      const scissor = renderer.getScissor(new THREE.Vector4())
+      const scissorTest = renderer.getScissorTest()
+      renderer.setScissorTest(true)
+      renderer.setScissor(0, 0, 1, 1)
+      renderer.setViewport(0, 0, 1, 1)
+      try {
+        renderer.render(scene, camera)
+      } finally {
+        renderer.setViewport(viewport)
+        renderer.setScissor(scissor)
+        renderer.setScissorTest(scissorTest)
+      }
+      // The program stays referenced throughout: the new keeper holds it
+      // before the old one lets go.
+      const held = this.warmKeepers.get(job.key)
+      this.warmKeepers.set(job.key, { from: job.from, keep })
+      kept = true
+      held?.keep.dispose()
     } finally {
-      renderer.setViewport(viewport)
-      renderer.setScissor(scissor)
-      renderer.setScissorTest(scissorTest)
+      // The geometries are this job's own but for the cap's sheet, which is
+      // the stage's.
+      scene.traverse((o) => {
+        const geometry = (o as THREE.Mesh).geometry as THREE.BufferGeometry | undefined
+        if (geometry && geometry !== this.capGeometry) geometry.dispose()
+      })
+      for (const light of lights) light.dispose()
+      if (!kept) keep?.dispose()
     }
-    // The geometries are this job's own but for the cap's sheet, which is
-    // the stage's.
-    scene.traverse((o) => {
-      const geometry = (o as THREE.Mesh).geometry as THREE.BufferGeometry | undefined
-      if (geometry && geometry !== this.capGeometry) geometry.dispose()
-    })
-    for (const light of lights) light.dispose()
-    // The program stays referenced throughout: the new keeper holds it
-    // before the old one lets go.
-    const held = this.warmKeepers.get(job.key)
-    this.warmKeepers.set(job.key, { from: job.from, keep })
-    held?.keep.dispose()
   }
 
   /** Have the closed shells of a part just put in place found off the main
    *  thread (see closedShellsFrom), for its first cut to find ready. An
    *  answer is kept only for the geometry it was asked about, still the
-   *  part's; one that comes back for a part since replaced is dropped, and
-   *  that part's cut finds its own. */
+   *  part's and laid out as it was: one that comes back for a part since
+   *  replaced, or split again for shading, is dropped, and that part's cut
+   *  finds its own. */
   private primeClosedShells(which: 'scan' | 'nominal', geometry: THREE.BufferGeometry): void {
+    const index = geometry.getIndex()
     this.closedShellsFrom?.(which).then(
-      (shells) => {
+      (vertices) => {
         const mesh = which === 'scan' ? this.mesh : this.nominalMesh
-        if (mesh?.geometry === geometry) primeClosedPart(geometry, shells)
+        if (mesh?.geometry === geometry && geometry.getIndex() === index) primeClosedPart(geometry, vertices)
       },
       // Not found off the thread: found on it, if a cut comes to need them.
       () => {},
diff --git a/src/viewer/sliceCap.ts b/src/viewer/sliceCap.ts
index edef0d3c..7034bf83 100644
--- a/src/viewer/sliceCap.ts
+++ b/src/viewer/sliceCap.ts
@@ -73,19 +73,28 @@ export function closedPartOf(geometry: THREE.BufferGeometry): ClosedPart {
 
 /**
  * Keep closed shells found elsewhere as this geometry's — the mesh worker's,
- * found on its own welded copy of the same triangles in the same order (a
- * split for shading only repeats corners, bit for bit) — so the first cut
- * of a part loaded does not search it on the main thread. False, and
- * nothing kept, when the answer cannot be about these triangles: a part
- * replaced while it was on its way has another count of them.
+ * a flag for each vertex (see closedVertices) — so the first cut of a part
+ * loaded does not search it on the main thread. A triangle is read off its
+ * first corner, through the index as it stands now: a bounds tree built
+ * over the geometry reorders its triangles and never its vertices. False,
+ * and nothing kept, when the flags cannot be this geometry's: a part
+ * replaced while they were on their way has another count of vertices.
  */
-export function primeClosedPart(geometry: THREE.BufferGeometry, shells: ClosedShells): boolean {
+export function primeClosedPart(geometry: THREE.BufferGeometry, vertices: Uint8Array): boolean {
   const index = geometry.getIndex()
   const position = geometry.getAttribute('position')
-  const total = Math.floor((index ? index.count : position.count) / 3)
-  if (shells.closed.length !== total) return false
+  if (vertices.length !== position.count) return false
   const key = index ?? position
-  if (!closedCache.has(key)) closedCache.set(key, partOf(shells, index))
+  if (closedCache.has(key)) return true
+  const total = Math.floor((index ? index.count : position.count) / 3)
+  const closed = new Uint8Array(total)
+  let count = 0
+  for (let t = 0; t < total; t++) {
+    if (vertices[index ? index.getX(3 * t) : 3 * t] !== 1) continue
+    closed[t] = 1
+    count++
+  }
+  closedCache.set(key, partOf({ closed, count }, index))
   return true
 }
 
diff --git a/tests/closedShells.test.ts b/tests/closedShells.test.ts
index 1af64670..f66bb583 100644
--- a/tests/closedShells.test.ts
+++ b/tests/closedShells.test.ts
@@ -4,7 +4,9 @@
 import * as THREE from 'three'
 import { describe, expect, it } from 'vitest'
 import { buildMeshGraph } from '../src/core/geometry/buildGraph'
-import { closedShells, type ClosedShells } from '../src/core/geometry/closedShells'
+import { computeBoundsTree } from 'three-mesh-bvh'
+import { NominalSurface } from '../src/core/deviation/surface'
+import { closedShells, closedVertices } from '../src/core/geometry/closedShells'
 import { scanRender, splitCreases } from '../src/core/geometry/crease'
 import { wireSlots } from '../src/core/geometry/wireSlots'
 import { closedPartOf, primeClosedPart } from '../src/viewer/sliceCap'
@@ -92,71 +94,109 @@ describe('closedShells', () => {
 
 /** The meshes above, each as it reaches the worker. */
 const fixtures = (): [string, { positions: number[]; indices: number[] }][] => {
-  const holed = cube([5, 0, 0])
-  holed.indices.splice(0, 6)
+  const holed = (at: [number, number, number]) => {
+    const c = cube(at)
+    c.indices.splice(0, 6)
+    return c
+  }
   const fin = cube()
   fin.positions.push(0.5, 1, 2)
   fin.indices.push(6, 7, 8)
+  // Closed and open cubes taken in turn but laid out in another order, so
+  // a bounds tree over them puts the triangles in an order of its own and
+  // a mask in the order they came in reads the wrong cubes.
+  const mixed = [5, 2, 7, 0, 3, 6, 1, 4].map((slot, i) => (i % 2 ? holed : cube)([5 * slot, 3 * (slot % 3), 2 * (i % 3)])).reduce(join)
   return [
     ['a closed cube', cube()],
-    ['a cube with a hole', holed],
-    ['a closed cube beside an open one', join(cube(), holed)],
+    ['a cube with a hole', holed([5, 0, 0])],
+    ['a closed cube beside an open one', join(cube(), holed([5, 0, 0]))],
     ['a cube with a fin', fin],
+    ['closed and open cubes taken in turn', mixed],
   ]
 }
 
 /** A geometry laid out as the viewport lays out a part: the render arrays
- *  the worker posts, indexed. */
-function geometryOf(positions: Float32Array, indices: Uint32Array): THREE.BufferGeometry {
+ *  the worker posts, indexed — and, with `tree`, a bounds tree built over
+ *  it as the viewport builds one before the part is shown, which puts the
+ *  index in an order of its own. */
+function geometryOf(positions: Float32Array, indices: Uint32Array, tree = false): THREE.BufferGeometry {
   const g = new THREE.BufferGeometry()
   g.setAttribute('position', new THREE.BufferAttribute(positions, 3))
   g.setIndex(new THREE.BufferAttribute(indices, 1))
+  if (tree) computeBoundsTree.call(g)
   return g
 }
 
-const plain = (s: ClosedShells) => ({ closed: [...s.closed], count: s.count })
+const welded = (mesh: { positions: number[]; indices: number[] }) =>
+  buildMeshGraph({ kind: 'indexed', positions: new Float32Array(mesh.positions), indices: new Uint32Array(mesh.indices) })
+
+/** Prime a geometry built on `positions`/`indices` as the viewport builds
+ *  it with the worker's `flags`, and hold what it keeps against what the
+ *  viewport would have found on its own on the same arrays. */
+function expectPrimedAsFound(positions: Float32Array, indices: Uint32Array, flags: Uint8Array): void {
+  const primed = geometryOf(positions, indices, true)
+  expect(primeClosedPart(primed, flags)).toBe(true)
+  const found = closedPartOf(geometryOf(positions.slice(), (primed.getIndex()!.array as Uint32Array).slice()))
+  const kept = closedPartOf(primed)
+  expect([...kept.closed]).toEqual([...found.closed])
+  expect(kept.count).toBe(found.count)
+  expect(kept.total).toBe(found.total)
+  expect(kept.index ? [...kept.index] : null).toEqual(found.index ? [...found.index] : null)
+}
 
 describe('closed shells from the worker', () => {
   // The worker finds them on its own welded copy — the scan's graph, the
-  // reference's surface — while the viewport's copy of the same triangles
-  // is split at the sharp edges for shading. The answer has to be the one
-  // the viewport would have found on its own, triangle for triangle.
+  // reference's surface, whose triangles a bounds tree has reordered —
+  // while the viewport's copy is split at the sharp edges for shading and
+  // reordered by a bounds tree of its own. A vertex at a time, the answer
+  // has to come out as the one the viewport would have found, triangle for
+  // triangle.
   for (const [name, mesh] of fixtures()) {
-    it(`agrees with the viewport's own on ${name}`, () => {
-      const graph = buildMeshGraph({ kind: 'indexed', positions: new Float32Array(mesh.positions), indices: new Uint32Array(mesh.indices) })
-      const worker = closedShells(graph.positions, graph.indices)
-      // The scan, split as the setting says, every way it can be.
+    it(`primes the scan as the viewport would find it on ${name}`, () => {
+      const graph = welded(mesh)
       for (const mode of ['on', 'off', 'auto'] as const) {
         const render = scanRender(graph, { mode, angleDeg: 30 })
-        expect(plain(worker), mode).toEqual(plain(closedShells(render.positions, render.indices)))
+        // The worker's index put in another order, as a thickness ray's
+        // tree puts it.
+        const reordered = graph.indices.slice()
+        for (let t = 0, n = reordered.length / 3; t < n / 2; t++) {
+          for (let c = 0; c < 3; c++) {
+            const a = 3 * t + c
+            const b = 3 * (n - 1 - t) + c
+            ;[reordered[a], reordered[b]] = [reordered[b], reordered[a]]
+          }
+        }
+        expectPrimedAsFound(render.positions, render.indices, closedVertices(graph.positions, reordered, render.copyOf))
       }
-      // The reference, always split.
-      const slots = wireSlots(graph.adjOffsets, graph.adjList, graph.vertexCount)
-      const split = splitCreases(graph.positions, graph.indices, slots)
-      if (split) expect(plain(worker)).toEqual(plain(closedShells(split.positions, split.indices)))
     })
 
-    it(`primes the viewport's cache with what it would have found on ${name}`, () => {
-      const graph = buildMeshGraph({ kind: 'indexed', positions: new Float32Array(mesh.positions), indices: new Uint32Array(mesh.indices) })
-      const render = scanRender(graph, { mode: 'on', angleDeg: 30 })
-      const primed = geometryOf(render.positions, render.indices)
-      expect(primeClosedPart(primed, closedShells(graph.positions, graph.indices))).toBe(true)
-      const found = closedPartOf(geometryOf(render.positions.slice(), render.indices.slice()))
-      const kept = closedPartOf(primed)
-      expect([...kept.closed]).toEqual([...found.closed])
-      expect(kept.count).toBe(found.count)
-      expect(kept.total).toBe(found.total)
-      expect(kept.index ? [...kept.index] : null).toEqual(found.index ? [...found.index] : null)
+    it(`primes the reference as the viewport would find it on ${name}`, () => {
+      const graph = welded(mesh)
+      // As the worker loads a reference: its surface first, its picture
+      // split from the welded arrays after.
+      const surface = new NominalSurface(graph.positions, graph.indices)
+      const split = splitCreases(graph.positions, graph.indices, wireSlots(graph.adjOffsets, graph.adjList, graph.vertexCount))
+      const positions = split ? split.positions : graph.positions.slice()
+      const indices = split ? split.indices : graph.indices.slice()
+      expectPrimedAsFound(positions, indices, closedVertices(surface.positions, surface.index, split ? split.copyOf : []))
     })
   }
 
-  it('turns away an answer about other triangles', () => {
+  it("turns away flags that are not this geometry's", () => {
     const m = cube()
     const g = geometryOf(new Float32Array(m.positions), new Uint32Array(m.indices))
-    // One triangle short: a reply about some other mesh.
-    const other = run({ positions: m.positions, indices: m.indices.slice(3) })
-    expect(primeClosedPart(g, other)).toBe(false)
+    // A vertex short: an answer about some other mesh.
+    expect(primeClosedPart(g, new Uint8Array(7).fill(1))).toBe(false)
     // Found on the geometry itself instead.
     expect(closedPartOf(g).count).toBe(12)
   })
+
+  it('reads a vertex at a time as closedShells reads a triangle at a time', () => {
+    for (const [, mesh] of fixtures()) {
+      const p = new Float32Array(mesh.positions)
+      const i = new Uint32Array(mesh.indices)
+      const flags = closedVertices(p, i)
+      expect([...closedShells(p, i).closed]).toEqual(Array.from({ length: i.length / 3 }, (_, t) => flags[i[3 * t]]))
+    }
+  })
 })

From 9ed2979f59132faaf2cccdc7a6c657943d06dd20 Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Wed, 4 Nov 2026 17:48:35 +0000
Subject: [PATCH 15/38] perf(section): say what the vertex count check proves

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/viewer/sliceCap.ts | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/viewer/sliceCap.ts b/src/viewer/sliceCap.ts
index 7034bf83..ae9b65be 100644
--- a/src/viewer/sliceCap.ts
+++ b/src/viewer/sliceCap.ts
@@ -77,8 +77,10 @@ export function closedPartOf(geometry: THREE.BufferGeometry): ClosedPart {
  * loaded does not search it on the main thread. A triangle is read off its
  * first corner, through the index as it stands now: a bounds tree built
  * over the geometry reorders its triangles and never its vertices. False,
- * and nothing kept, when the flags cannot be this geometry's: a part
- * replaced while they were on their way has another count of vertices.
+ * and nothing kept, when the count of flags is not this geometry's count
+ * of vertices. That alone does not prove the flags are this geometry's —
+ * a replacement can have as many — so the caller also checks that the
+ * part and its index are the ones the flags were asked for.
  */
 export function primeClosedPart(geometry: THREE.BufferGeometry, vertices: Uint8Array): boolean {
   const index = geometry.getIndex()

From d4dd88fcea56c4fadc1c90089fd8b627fd897287 Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Wed, 4 Nov 2026 18:30:04 +0000
Subject: [PATCH 16/38] perf(viewports): keep split and 2D views alive after
 first use

Opening the split view or the 2D Measure tab again made a new WebGL context
(and, for the split, a 6.8 MB upload and a shader link). Both viewports are
now mounted at their first opening, hidden and paused while closed, and shown
again with the camera link and the flat sheet re-laid. The reference half is
released when its reference geometry is replaced or cleared. OrthoViewport
ignores a 0x0 container once it has a size, and gives its context back on
dispose.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 scripts/e2e-section-view.mjs |  2 +-
 scripts/e2e-split.mjs        | 13 ++++----
 scripts/perf-probe.mjs       |  5 +--
 src/App.tsx                  | 63 ++++++++++++++++++++++++------------
 src/app/useFlatSceneSync.ts  | 17 ++++++++--
 src/ui/CompareView.tsx       | 26 ++++++++++++++-
 src/ui/FlatViewer.tsx        | 35 ++++++++++++++++++--
 src/viewer/CompareScene.ts   | 19 ++++++++---
 src/viewer/FlatScene.ts      |  8 +++++
 src/viewer/orthoViewport.ts  | 22 +++++++++++--
 10 files changed, 167 insertions(+), 43 deletions(-)

diff --git a/scripts/e2e-section-view.mjs b/scripts/e2e-section-view.mjs
index 03ab0b50..dc715973 100644
--- a/scripts/e2e-section-view.mjs
+++ b/scripts/e2e-section-view.mjs
@@ -202,7 +202,7 @@ check((await capShare()) > 0.02, `the closed scan is filled where it is cut (${(
 await page.screenshot({ path: shotPath('section-view-deviation.png') })
 
 await page.click('[data-test=toggle-split]')
-await page.waitForSelector('[data-test=compare-half]')
+await page.waitForSelector('[data-test=compare-half]:not([hidden])')
 await sleep(900)
 const right = await warmIn('.compareview')
 await page.screenshot({ path: shotPath('section-view-split.png') })
diff --git a/scripts/e2e-split.mjs b/scripts/e2e-split.mjs
index 86feba19..c9a2d67d 100644
--- a/scripts/e2e-split.mjs
+++ b/scripts/e2e-split.mjs
@@ -176,7 +176,7 @@ check(
 // It does not wait for a fit: opening it on an unfitted pair is how you check
 // the reference is the part you meant before spending an alignment on it.
 await page.click('[data-test=toggle-split]')
-await page.waitForSelector('[data-test=compare-half]')
+await page.waitForSelector('[data-test=compare-half]:not([hidden])')
 await sleep(800)
 const unfitted = await bothHalves('before the fit')
 check(
@@ -186,7 +186,8 @@ check(
 check(unfitted.left.coloured < 0.05, 'the scan is bare before anything is measured')
 await page.screenshot({ path: shotPath('split-before-fit.png') })
 await page.click('[data-test=toggle-split]')
-await page.waitForFunction(() => !document.querySelector('[data-test=compare-half]'))
+// The half is kept, hidden, when the split view closes: gone means not shown.
+await page.waitForFunction(() => !document.querySelector('[data-test=compare-half]:not([hidden])'))
 await sleep(400)
 
 // ---- align and measure -----------------------------------------------------
@@ -257,9 +258,9 @@ check(figuresAgain === figures, 'and brings the scale back reading exactly what
 
 // ---- side by side ----------------------------------------------------------
 await page.click('[data-test=toggle-split]')
-await page.waitForSelector('[data-test=compare-half]')
+await page.waitForSelector('[data-test=compare-half]:not([hidden])')
 await sleep(900)
-const canvases = await page.$$eval('.viewslot canvas', (els) => els.length)
+const canvases = await page.$$eval('.viewslot canvas', (els) => els.filter((e) => e.getClientRects().length > 0).length)
 console.log('viewports in the slot:', canvases)
 if (canvases !== 2) fail(`expected two viewports side by side, got ${canvases}`)
 console.log('captions:', JSON.stringify(await page.$$eval('.splitcap', (e) => e.map((c) => c.textContent))))
@@ -351,8 +352,8 @@ await page.screenshot({ path: shotPath('split-zoomed.png') })
 // ---- and back to one viewport ----------------------------------------------
 await page.click('[data-test=toggle-split]')
 await sleep(600)
-check(!(await page.$('[data-test=compare-half]')), 'the reference half goes away with the switch')
-const closed = await page.$$eval('.viewslot canvas', (els) => els.length)
+check(!(await page.$('[data-test=compare-half]:not([hidden])')), 'the reference half goes away with the switch')
+const closed = await page.$$eval('.viewslot canvas', (els) => els.filter((e) => e.getClientRects().length > 0).length)
 if (closed !== 1) fail(`expected one viewport after closing the split view, got ${closed}`)
 check(
   Boolean(await page.$('[data-test=toggle-reference]:not([aria-disabled])')),
diff --git a/scripts/perf-probe.mjs b/scripts/perf-probe.mjs
index 2485353b..7c7629d0 100644
--- a/scripts/perf-probe.mjs
+++ b/scripts/perf-probe.mjs
@@ -649,8 +649,9 @@ try {
   ])
   await ensureProbes()
   await run([
-    // Plan task 6: the split view's second viewport is kept after its first open.
-    { label: 'Deviation: split on', sel: '[data-test=toggle-split]', settle: 3000, budget: { contexts: 0, steady: true, inpMs: { bare: 73, rich: 190 } } },
+    // Plan task 6: the split view's second viewport is kept after its first open, so no later tap
+    // makes a context, links a program or uploads the reference again.
+    { label: 'Deviation: split on', sel: '[data-test=toggle-split]', settle: 3000, budget: { links: 0, uploadMB: 0, contexts: 0, steady: true, inpMs: { bare: 73, rich: 190 } } },
     { label: 'Deviation: split off', sel: '[data-test=toggle-split]', settle: 2000 },
   ])
   await shot('06-split')
diff --git a/src/App.tsx b/src/App.tsx
index 1298f2c5..78cff122 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -8,7 +8,8 @@
 // its edges, project files, each plugin's hook (called in the same order
 // every render) and the agent connection.
 
-import { useEffect, useMemo, useRef } from 'react'
+import { useEffect, useMemo, useRef, useState } from 'react'
+import type { BufferGeometry } from 'three'
 import { useProjectHistory } from './app/useProjectHistory'
 import { clearHistory, historyAction } from './state/historyStore'
 import { MeshWorkerClient } from './core/workerClient'
@@ -158,8 +159,8 @@ export default function App() {
   }
   // The 2D Measure viewport and its decoded scan image. The bitmap stays out
   // of the store like every other big buffer; the scene ref is separate from
-  // sceneRef because this viewport, unlike the 3D one, mounts and unmounts
-  // with its workspace.
+  // sceneRef because this viewport, unlike the 3D one, does not exist until
+  // its workspace has first been opened.
   const flatSceneRef = useRef<FlatScene | null>(null)
   const flatBitmapRef = useRef<ImageBitmap | null>(null)
   // Edge detection: its own worker, the grayscale cached for sensitivity
@@ -1446,6 +1447,11 @@ export default function App() {
   const onDeviation = workspace === 'deviation'
   const onThickness = workspace === 'thickness'
   const onFlat = workspace === 'flat'
+  // Opened once, kept from then on (hidden and paused while another workspace
+  // is up): every new WebGL canvas is a new context, and the tab is one people
+  // switch back and forth with. See the mounts below.
+  const [flatEverOpened, setFlatEverOpened] = useState(false)
+  if (onFlat && !flatEverOpened) setFlatEverOpened(true)
   const flatImageName = useFlat((s) => s.imageName)
   const flatCalSource = useFlat((s) => s.calSource)
 
@@ -1510,6 +1516,16 @@ export default function App() {
   // A plugin's workspace may put a view of its own beside the viewport.
   const pluginSplit = !picking && active?.split ? active.split : null
   const anySplit = splitOpen || pluginSplit !== null
+  // The reference half is kept once the split view has been opened, for as long
+  // as the reference it was built from is the one loaded: another reference, or
+  // none, lets it go (its context with it) the moment that is seen here, and the
+  // next opening builds a new one. A new scan is not in the question: the half
+  // borrows nothing of the scan but its camera, which the scene keeps, and a
+  // reference the session made from the old scan goes with it (scanImport), which
+  // lets the half go the same way.
+  const [splitSeen, setSplitSeen] = useState<BufferGeometry | null>(null)
+  if (splitOpen && splitSeen !== nominalGeometry) setSplitSeen(nominalGeometry)
+  const splitKept = nominalGeometry !== null && splitSeen === nominalGeometry && sceneRef.current !== null
   // Stable, so the readout's subscription is not torn down every render.
   const registerHover = useRef((fn: ((r: HoverReading | null) => void) | null) => {
     hoverSink.current = fn
@@ -1658,27 +1674,34 @@ export default function App() {
             />
             {!splitOpen && pluginSplit}
             {splitOpen && (
-              <>
-                <div className="splitcap">
-                  <b>Scan</b>
-                  <span>{fileName}</span>
-                </div>
-                <CompareView
-                  scene={sceneRef.current!}
-                  geometry={nominalGeometry!}
-                  role="Reference"
-                  name={nominalName ?? 'reference'}
-                />
-              </>
+              <div className="splitcap">
+                <b>Scan</b>
+                <span>{fileName}</span>
+              </div>
+            )}
+            {/* Kept after its first opening — see splitKept. A hidden half costs
+                its context and the reference's vertex buffers, once, where
+                building it anew at every opening cost both each time. */}
+            {splitKept && (
+              <CompareView
+                scene={sceneRef.current!}
+                geometry={nominalGeometry!}
+                role="Reference"
+                name={nominalName ?? 'reference'}
+                active={splitOpen}
+              />
             )}
           </div>
-          {/* The flat viewport mounts with its workspace — there is no BVH to
-              protect here, and a hidden second WebGL canvas would still hold
-              its context. The 3D viewport above merely hides. */}
-          {onFlat && (
-            <div className="viewslot">
+          {/* The flat viewport comes with its workspace's first opening and is
+              kept: it holds a context, but a new one at every switch of tab
+              costs more than this one idles at, since it draws nothing and
+              reads no layout while hidden. */}
+          {flatEverOpened && (
+            <div className="viewslot" hidden={!onFlat}>
               <FlatViewer
+                active={onFlat}
                 onReady={flatSync.onReady}
+                onResync={flatSync.resync}
                 onPick={(p, meta) => useFlat.getState().stageClick(p, meta, activeEdgeIndex())}
                 onPickDrag={(i, p, meta) =>
                   useFlat.getState().stageDrag(i, p, meta, activeEdgeIndex())
diff --git a/src/app/useFlatSceneSync.ts b/src/app/useFlatSceneSync.ts
index 8ddf262c..8afe2bfa 100644
--- a/src/app/useFlatSceneSync.ts
+++ b/src/app/useFlatSceneSync.ts
@@ -146,13 +146,24 @@ export function useFlatSceneSync({
   const turns = useFlat((s) => s.turns)
   useEffect(() => scene()?.setTurns(turns), [turns])
 
+  /** Lay the subject and every layer on a viewport afresh, as when it mounts. */
+  const resync = (view: FlatScene) => {
+    sceneRef.current = view
+    pushAll()
+  }
+
   return {
     /** The viewport has mounted — take it and lay the sheet out on it — or
-     *  unmounted with its workspace (null). */
+     *  unmounted (null): with the app, or never before then, as it is kept
+     *  once its workspace has been opened. */
     onReady: (view: FlatScene | null) => {
-      sceneRef.current = view
-      if (view) pushAll()
+      if (view) resync(view)
+      else sceneRef.current = null
     },
+    /** The kept viewport is shown again: the sheet is framed afresh, as a
+     *  mounted one was, and every layer is laid on it once more in case a
+     *  push landed while it was out of the layout. */
+    resync,
     /** The cursor over the sheet — the alignment tool's live grid preview. */
     onHover: (cursor: Vec2 | null) => {
       const grid = sheetDatumPreview(useFlat.getState(), cursor)
diff --git a/src/ui/CompareView.tsx b/src/ui/CompareView.tsx
index 6008bfb0..a01feb5b 100644
--- a/src/ui/CompareView.tsx
+++ b/src/ui/CompareView.tsx
@@ -7,6 +7,15 @@
 // Viewer keeps its exact place in the tree when the split opens; moved into a
 // wrapper it would be unmounted and remounted, and a scan's BVH costs seconds
 // to build.
+//
+// Once opened it is kept, hidden, when the split view closes: a new half is a
+// new WebGL context and a new upload of the reference's vertex buffers, and the
+// stage needs both again at the next tap of the switch. Hidden, it draws
+// nothing and reads no layout. What changes in the stores meanwhile is applied
+// as it arrives (the effects below keep running, and setting a uniform on a
+// paused viewport is only a flag), except for the camera and the section
+// plane, which are read off the scan every frame and so are caught up when
+// the half is shown again.
 
 import { useEffect, useRef } from 'react'
 import type * as THREE from 'three'
@@ -23,6 +32,7 @@ export function CompareView({
   geometry,
   role,
   name,
+  active,
 }: {
   /** The main viewport, whose camera this half follows — and which follows it
    *  back when the hand is on this side. */
@@ -30,6 +40,9 @@ export function CompareView({
   geometry: THREE.BufferGeometry
   role: string
   name: string
+  /** Whether the half is on the stage. False keeps it, and its context, alive
+   *  but paused and out of the layout. */
+  active: boolean
 }) {
   const holder = useRef<HTMLDivElement>(null)
   const compareRef = useRef<CompareScene | null>(null)
@@ -63,6 +76,17 @@ export function CompareView({
     }
   }, [geometry, scene])
 
+  // Shown again: the scan's camera has moved on while this half stood still, so
+  // the link is made afresh, which puts this half in the scan's pose (see
+  // CameraLink). Runs after the effect above on a fresh half, which is then
+  // linked twice; one pose copy.
+  useEffect(() => {
+    const compare = compareRef.current
+    if (!compare) return
+    compare.setPaused(!active)
+    if (active) compare.linkTo(scene.viewLink())
+  }, [active, geometry, scene])
+
   useEffect(() => {
     compareRef.current?.setNavScheme(schemeById(navScheme))
   }, [navScheme])
@@ -86,7 +110,7 @@ export function CompareView({
   }, [wireframe])
 
   return (
-    <div className="comparehalf" data-test="compare-half">
+    <div className="comparehalf" data-test="compare-half" hidden={!active}>
       <div className="compareview" ref={holder} />
       <div className="splitcap">
         <b>{role}</b>
diff --git a/src/ui/FlatViewer.tsx b/src/ui/FlatViewer.tsx
index ea5f1c4e..1493cf0d 100644
--- a/src/ui/FlatViewer.tsx
+++ b/src/ui/FlatViewer.tsx
@@ -45,11 +45,14 @@ export function useFlatSceneSettings(sceneRef: RefObject<FlatScene | null>): voi
 
 /** The 2D Measure viewport, in the same thin-wrapper shape as Viewer:
  *  construct once, wire callbacks through refs so prop changes never
- *  re-create the scene. Mounted only while its workspace is up — unlike the
- *  3D viewport there is no expensive BVH to protect, and a dropped image
- *  redecodes in well under a second. */
+ *  re-create the scene. Mounted when its workspace is first opened and kept
+ *  from then on: there is no BVH to protect here, but a new viewport is a new
+ *  WebGL context, and the tab is one people switch back and forth with. While
+ *  its workspace is not up it is paused and out of the layout. */
 export function FlatViewer({
+  active,
   onReady,
+  onResync,
   onPick,
   onPickDrag,
   onPinClick,
@@ -61,9 +64,15 @@ export function FlatViewer({
   onHover,
   loupe,
 }: {
+  /** Whether the workspace is on screen. False pauses the scene; the owner
+   *  hides the viewport's slot. */
+  active: boolean
   /** The scene when it comes up, null when the viewport unmounts — so the
    *  owner never holds a disposed scene. */
   onReady: (scene: FlatScene | null) => void
+  /** The scene is shown again after being kept: lay the sheet out on it once
+   *  more, as onReady did when it was new. */
+  onResync: (scene: FlatScene) => void
   onPick: (p: Vec2, meta: { alt: boolean; unitsPerScreenPx: number }) => void
   /** A draft pin dragged to a new spot, by index. */
   onPickDrag: (index: number, p: Vec2, meta: { alt: boolean; unitsPerScreenPx: number }) => void
@@ -113,6 +122,12 @@ export function FlatViewer({
   hoverRef.current = onHover
   const readyRef = useRef(onReady)
   readyRef.current = onReady
+  const resyncRef = useRef(onResync)
+  resyncRef.current = onResync
+  const activeRef = useRef(active)
+  activeRef.current = active
+  /** The state the scene was last put in, so that only a change is acted on. */
+  const wasActive = useRef(active)
   const loupeOpts = useRef(loupe)
   loupeOpts.current = loupe
 
@@ -202,6 +217,8 @@ export function FlatViewer({
       ctx.stroke()
     }
     sceneRef.current = scene
+    scene.setPaused(!activeRef.current)
+    wasActive.current = activeRef.current
     readyRef.current(scene)
     return () => {
       sceneRef.current = null
@@ -210,6 +227,18 @@ export function FlatViewer({
     }
   }, [])
 
+  // Shown again after being kept. The sheet and its layers were pushed as the
+  // stores changed, hidden or not, but the sheet is framed as a fresh viewport
+  // frames it, and a layer that was pushed against a collapsed layout is laid
+  // again at the real size.
+  useEffect(() => {
+    const scene = sceneRef.current
+    if (!scene || wasActive.current === active) return
+    wasActive.current = active
+    scene.setPaused(!active)
+    if (active) resyncRef.current(scene)
+  }, [active])
+
   // The scheme and theme settings live in the settings dialog and serve every
   // viewport; this one follows them the same way the main view does.
   useFlatSceneSettings(sceneRef)
diff --git a/src/viewer/CompareScene.ts b/src/viewer/CompareScene.ts
index 34956145..a05518d2 100644
--- a/src/viewer/CompareScene.ts
+++ b/src/viewer/CompareScene.ts
@@ -4,10 +4,13 @@
 //
 // A viewport of its own rather than a second pass over the main scene, for the
 // same reason the point picker's halves are: the two parts have to be looked at
-// apart from each other, and three.js keeps GPU state per renderer, so the
-// reference geometry — BVH and all — is drawn here without a second copy of it.
-// Borrowed, never owned: disposing it here would take the main view's reference
-// with it.
+// apart from each other. The CPU side of the reference geometry — its arrays and
+// BVH — is shared, so there is no second copy of that here. The GPU side is not:
+// three.js keeps buffers and programs per renderer, so this half's own renderer
+// uploads the geometry again and links its own shader. That is paid once per
+// half, which is why the half is kept alive when the split view closes and shown
+// again rather than rebuilt. Borrowed, never owned: disposing it here would take
+// the main view's reference with it.
 
 import * as THREE from 'three'
 import { CameraLink, type LinkedView } from './cameraLink'
@@ -197,6 +200,14 @@ export class CompareScene {
     this.viewport.invalidate()
   }
 
+  /** Held back while the half is not on screen: no frame is drawn and no layout
+   *  is read, and what the stores changed in the meantime is drawn on the first
+   *  frame after it comes back. */
+  setPaused(paused: boolean): void {
+    this.viewport.paused = paused
+    if (!paused) this.viewport.resize()
+  }
+
   dispose(): void {
     this.cap?.dispose()
     this.capGeometry.dispose()
diff --git a/src/viewer/FlatScene.ts b/src/viewer/FlatScene.ts
index a1c54885..b39e539c 100644
--- a/src/viewer/FlatScene.ts
+++ b/src/viewer/FlatScene.ts
@@ -1885,6 +1885,14 @@ export class FlatScene {
     this.viewport.invalidate()
   }
 
+  /** Held back while the sheet is not on screen: no frame is drawn and no
+   *  layout is read. What the stores pushed in the meantime is on the sheet
+   *  already and is drawn on the first frame after it comes back. */
+  setPaused(paused: boolean): void {
+    this.viewport.paused = paused
+    if (!paused) this.viewport.resize()
+  }
+
   dispose(): void {
     this.container.removeEventListener('pointermove', this.hoverMove)
     this.container.style.cursor = ''
diff --git a/src/viewer/orthoViewport.ts b/src/viewer/orthoViewport.ts
index dd459b42..dfbd3269 100644
--- a/src/viewer/orthoViewport.ts
+++ b/src/viewer/orthoViewport.ts
@@ -161,13 +161,17 @@ export class OrthoViewport {
    *  re-framing a new model just writes to it. */
   readonly clipSphere = { center: new THREE.Vector3(), radius: 1 }
   /** Skips rendering entirely while the viewport is hidden (behind the
-   *  split-screen picker); everything loaded stays loaded. */
+   *  split-screen picker, or kept alive behind `hidden` after its split or 2D
+   *  view was closed); everything loaded stays loaded. A paused tick reads no
+   *  layout and draws nothing. */
   paused = false
   /** Half-extents of the model on the screen plane at the framing camera
    *  orientation; the frustum is rebuilt from these on every resize so the
    *  user's zoom survives. */
   private fitExtent = { halfW: 1, halfH: 1 }
   private resizeObserver: ResizeObserver
+  /** Whether the container has ever had a size — see resize. */
+  private sized = false
   private rafId = 0
   private pointerDown: { x: number; y: number } | null = null
   /** Fingers down on the canvas, and whether this touch has been more than one
@@ -809,8 +813,15 @@ export class OrthoViewport {
   }
 
   resize(): void {
-    const w = this.container.clientWidth || 1
-    const h = this.container.clientHeight || 1
+    const cw = this.container.clientWidth
+    const ch = this.container.clientHeight
+    // A viewport kept alive behind `hidden` reports 0 × 0, and resizing to that
+    // would reallocate both buffers for a size nobody sees; it keeps the last
+    // one, and the real size arrives with the first resize after it is shown.
+    if (cw === 0 && ch === 0 && this.sized) return
+    if (cw > 0 && ch > 0) this.sized = true
+    const w = cw || 1
+    const h = ch || 1
     this.renderer.setSize(w, h)
     this.labelRenderer.setSize(w, h)
     this.applyFrustum()
@@ -826,6 +837,11 @@ export class OrthoViewport {
     this.nav.dispose()
     this.controls.dispose()
     this.renderer.dispose()
+    // Dropping the renderer leaves its context to the garbage collector, and
+    // the browser counts it against its cap on live contexts until then. The
+    // split and 2D viewports now live as long as their geometry does, so one
+    // replaced under a long session must give its context back at once.
+    this.renderer.forceContextLoss()
     // Only what this viewport put there. Emptying the container instead would
     // also take out whatever React had rendered into it — the fit-to-view
     // button — and React, having not been told, would never put it back. Which

From 88edc597119c3b5e05729565f48a132eb673393b Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Wed, 4 Nov 2026 18:51:32 +0000
Subject: [PATCH 17/38] perf(viewports): drop a replaced reference's kept
 split; 2D shows without re-laying

The kept split state held the old reference geometry until the split was next
opened; it is now dropped as soon as the reference changes while the split is
closed. A kept 2D viewport shown again is only unpaused and resized unless its
sheet was laid anew since (image, subject or section cut), so the image is not
uploaded again and the user's pan and zoom survive a tab round trip.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 scripts/e2e-split.mjs       |  6 ++++++
 src/App.tsx                 |  6 +++++-
 src/app/useFlatSceneSync.ts | 33 ++++++++++++++++++++++++++++-----
 3 files changed, 39 insertions(+), 6 deletions(-)

diff --git a/scripts/e2e-split.mjs b/scripts/e2e-split.mjs
index c9a2d67d..bb1b76c3 100644
--- a/scripts/e2e-split.mjs
+++ b/scripts/e2e-split.mjs
@@ -177,6 +177,8 @@ check(
 // the reference is the part you meant before spending an alignment on it.
 await page.click('[data-test=toggle-split]')
 await page.waitForSelector('[data-test=compare-half]:not([hidden])')
+// The half is kept when the split view closes, so a later opening is this same canvas.
+await page.$eval('.compareview canvas', (el) => el.setAttribute('data-kept-marker', '1'))
 await sleep(800)
 const unfitted = await bothHalves('before the fit')
 check(
@@ -260,6 +262,10 @@ check(figuresAgain === figures, 'and brings the scale back reading exactly what
 await page.click('[data-test=toggle-split]')
 await page.waitForSelector('[data-test=compare-half]:not([hidden])')
 await sleep(900)
+check(
+  Boolean(await page.$('[data-test=compare-half]:not([hidden]) .compareview canvas[data-kept-marker="1"]')),
+  'the split canvas is the same element after a close and reopen',
+)
 const canvases = await page.$$eval('.viewslot canvas', (els) => els.filter((e) => e.getClientRects().length > 0).length)
 console.log('viewports in the slot:', canvases)
 if (canvases !== 2) fail(`expected two viewports side by side, got ${canvases}`)
diff --git a/src/App.tsx b/src/App.tsx
index 78cff122..cc015619 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -1524,7 +1524,11 @@ export default function App() {
   // reference the session made from the old scan goes with it (scanImport), which
   // lets the half go the same way.
   const [splitSeen, setSplitSeen] = useState<BufferGeometry | null>(null)
-  if (splitOpen && splitSeen !== nominalGeometry) setSplitSeen(nominalGeometry)
+  // A reference let go while the split is closed is dropped from here as well,
+  // not held until the split is next opened: its arrays are tens of MB.
+  if (splitSeen !== nominalGeometry && (splitOpen || splitSeen !== null)) {
+    setSplitSeen(splitOpen ? nominalGeometry : null)
+  }
   const splitKept = nominalGeometry !== null && splitSeen === nominalGeometry && sceneRef.current !== null
   // Stable, so the readout's subscription is not torn down every render.
   const registerHover = useRef((fn: ((r: HoverReading | null) => void) | null) => {
diff --git a/src/app/useFlatSceneSync.ts b/src/app/useFlatSceneSync.ts
index 8afe2bfa..47589684 100644
--- a/src/app/useFlatSceneSync.ts
+++ b/src/app/useFlatSceneSync.ts
@@ -4,7 +4,7 @@
 // What each layer draws is computed by app/flatSheet — this hook only
 // decides when to push. The 3D twin is useSceneSync.
 
-import { useEffect, type MutableRefObject } from 'react'
+import { useEffect, useRef, type MutableRefObject } from 'react'
 import type { EdgeChains } from '../core/flat/edges'
 import type { Vec2 } from '../core/flat/types'
 import { useFlat } from '../state/flatStore'
@@ -68,6 +68,22 @@ export function useFlatSceneSync({
     view.setRegionMode(draft.regionMode)
   }
 
+  /** What lays the sheet afresh, read off the stores as the effect below keys
+   *  on it: a new image, a new subject, or a section's cut landing. */
+  const sheetKey = () => {
+    const { subject, imageVersion, subjectVersion } = useFlat.getState()
+    const cut =
+      subject.kind === 'section'
+        ? (useStore.getState().sections.find((x) => x.id === subject.id)?.cutKey ?? null)
+        : null
+    return `${imageVersion}|${subjectVersion}|${cut}`
+  }
+  /** The viewport the sheet was last laid on, and under which key — so that
+   *  a kept viewport shown again, whose sheet nothing has changed, is not laid
+   *  again: that would upload the image once more and take the user's pan and
+   *  zoom away. */
+  const laid = useRef<{ view: FlatScene; key: string } | null>(null)
+
   /** Lay the subject on the sheet and every layer over it — once both it
    *  and the viewport exist, in whichever order they got there: the image
    *  may be dropped before the workspace has ever been opened, and the
@@ -76,6 +92,7 @@ export function useFlatSceneSync({
     const sheet = sheetOf()
     const view = scene()
     if (!sheet || !view) return
+    laid.current = { view, key: sheetKey() }
     // The alignment, the mirror and the turn first, so the sheet is framed
     // the way it is to be looked at rather than framed and then turned.
     view.setAlignment(sheetAlignment(useFlat.getState()))
@@ -151,6 +168,14 @@ export function useFlatSceneSync({
     sceneRef.current = view
     pushAll()
   }
+  /** A kept viewport is shown again. Every layer was pushed as its store
+   *  changed, hidden or not, so unless the sheet itself was laid anew since
+   *  (which a change while hidden does as well, on the viewport that is there)
+   *  there is nothing to do. */
+  const show = (view: FlatScene) => {
+    if (laid.current?.view === view && laid.current.key === sheetKey()) return
+    resync(view)
+  }
 
   return {
     /** The viewport has mounted — take it and lay the sheet out on it — or
@@ -160,10 +185,8 @@ export function useFlatSceneSync({
       if (view) resync(view)
       else sceneRef.current = null
     },
-    /** The kept viewport is shown again: the sheet is framed afresh, as a
-     *  mounted one was, and every layer is laid on it once more in case a
-     *  push landed while it was out of the layout. */
-    resync,
+    /** The kept viewport is shown again — see show. */
+    resync: show,
     /** The cursor over the sheet — the alignment tool's live grid preview. */
     onHover: (cursor: Vec2 | null) => {
       const grid = sheetDatumPreview(useFlat.getState(), cursor)

From 8effcf768e5e272fcb64ef8472f80db04c9d6cf4 Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Wed, 4 Nov 2026 19:11:39 +0000
Subject: [PATCH 18/38] perf(overlays): skip unchanged rebuilds, reuse
 materials

A tab or the map's switch rebuilt every element overlay, re-ran
evaluateDimensions outside the workspace that shows its output, and disposed
and recreated the overlay materials, which released their shader programs to
be compiled again on the next tap into 3D Measure.

- Overlays.updateOverlays draws nothing when the input says what is drawn
  already (compared by content, since it is built afresh each time) and
  reports whether it drew.
- An element's materials live as long as the element, drawn or not, with
  colour and opacity set in place; the callout lines and the selection
  strokes share one material each.
- The same for a finished section's materials, and the volume layer's two.
- evaluateDimensions runs only in the measure workspace.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 src/app/useSceneSync.ts        |  39 ++--
 src/viewer/SceneManager.ts     |   7 +-
 src/viewer/clipTree.ts         |  14 ++
 src/viewer/overlays.ts         | 261 +++++++++++++++++----------
 src/viewer/sections.ts         | 156 ++++++++++------
 src/viewer/volumeLayer.ts      |  16 +-
 tests/overlayMaterials.test.ts | 314 +++++++++++++++++++++++++++++++++
 7 files changed, 639 insertions(+), 168 deletions(-)
 create mode 100644 tests/overlayMaterials.test.ts

diff --git a/src/app/useSceneSync.ts b/src/app/useSceneSync.ts
index 1dbf275e..779230ff 100644
--- a/src/app/useSceneSync.ts
+++ b/src/app/useSceneSync.ts
@@ -346,13 +346,19 @@ export function useSceneSync({
         muted: !showElements && e.id !== targetId,
       }))
     // Distances draw as a line between their two anchor points, angles as an
-    // arc at their hinge.
-    const rows = evaluateDimensions(
-      dimensions.filter((d) => d.visible !== false && d.id !== editingDimensionId),
-      dimensionRefsOf(elements, sections),
-      surfaceSource,
-      units,
-    ).filter((r) => !r.value.invalid)
+    // arc at their hinge. They are the measure workspace's alone — a distance
+    // between two elements has nothing to say about a map, and its leader
+    // lines would cross the reading — so nowhere else are they worked out:
+    // everything below that reads a dimension (the panels, the agent's
+    // commands) evaluates its own.
+    const rows = elementsWorkspace
+      ? evaluateDimensions(
+          dimensions.filter((d) => d.visible !== false && d.id !== editingDimensionId),
+          dimensionRefsOf(elements, sections),
+          surfaceSource,
+          units,
+        ).filter((r) => !r.value.invalid)
+      : []
     const verdictOf = (r: EvaluatedDimension) => ({
       notes: pinNotes(r),
       over: r.verdict ? !r.verdict.pass : false,
@@ -390,15 +396,18 @@ export function useSceneSync({
         },
       ]
     })
-    // Dimensions are the measure workspace's alone: a distance between two
-    // elements has nothing to say about a map, and its leader lines would cross
-    // the reading.
-    sceneRef.current?.updateOverlays(
+    // Overlays that would be drawn exactly as they stand are not drawn again —
+    // most of what sets this effect off, a tab or the map's switch, leaves the
+    // elements as they were — and one that does come back to the stage finds
+    // its materials kept, since `existing` says which elements still exist
+    // though none of them is drawn.
+    const drew = sceneRef.current?.updateOverlays(
       items,
-      elementsWorkspace ? pairs : [],
-      elementsWorkspace ? angles : [],
-      elementsWorkspace ? tags : [],
+      pairs,
+      angles,
+      tags,
       (showElements || items.length > 0) && !elementsKeyHides,
+      new Set(elements.map((e) => e.id)),
     )
     // A hidden element's surface tint goes with its overlay — and outside the
     // measure workspace that is every element, so the scan is bare underneath
@@ -416,7 +425,7 @@ export function useSceneSync({
       ).map((e) => e.id),
     )
     // Overlays were rebuilt, so the selection glow has to be re-applied.
-    sceneRef.current?.setHighlightedElements(highlightIds)
+    if (drew) sceneRef.current?.setHighlightedElements(highlightIds)
     // Runs on the listed dependencies only, not on everything it reads.
   }, [
     elements,
diff --git a/src/viewer/SceneManager.ts b/src/viewer/SceneManager.ts
index 053e4673..f2674d35 100644
--- a/src/viewer/SceneManager.ts
+++ b/src/viewer/SceneManager.ts
@@ -2410,14 +2410,17 @@ export class SceneManager {
     if (had !== has) this.viewport.nav.setPaintMode(has)
   }
 
+  /** The measured elements and their dimensions, drawn or put away; whether
+   *  that drew anything — see Overlays.updateOverlays. */
   updateOverlays(
     elements: OverlayElement[],
     pairs: OverlayPair[],
     angles: OverlayAngle[],
     tags: OverlayTag[],
     visible: boolean,
-  ): void {
-    this.overlays.updateOverlays(elements, pairs, angles, tags, visible)
+    existing?: ReadonlySet<number>,
+  ): boolean {
+    return this.overlays.updateOverlays(elements, pairs, angles, tags, visible, existing)
   }
 
   setPaused(paused: boolean): void {
diff --git a/src/viewer/clipTree.ts b/src/viewer/clipTree.ts
index 69233517..6790dc8b 100644
--- a/src/viewer/clipTree.ts
+++ b/src/viewer/clipTree.ts
@@ -22,3 +22,17 @@ export function clipTree(root: THREE.Object3D, planes: THREE.Plane[] | null, vis
   }
   for (const child of root.children) clipTree(child, planes, visit)
 }
+
+/** A material kept across rebuilds, taken back into the scene as it was first
+ *  made: unclipped. The section view dresses only what is in the scene when it
+ *  is looked at, and one closed while a material was put away leaves it
+ *  holding a plane that no longer cuts. A rebuild that finds the view open
+ *  dresses it again before the frame, and the material keeps the programs it
+ *  has already compiled for either state. */
+export function unclip<T extends THREE.Material>(material: T): T {
+  if (material.clippingPlanes !== null) {
+    material.clippingPlanes = null
+    material.needsUpdate = true
+  }
+  return material
+}
diff --git a/src/viewer/overlays.ts b/src/viewer/overlays.ts
index b4399c8c..dc745561 100644
--- a/src/viewer/overlays.ts
+++ b/src/viewer/overlays.ts
@@ -13,6 +13,7 @@ import type { FitData, Vec3 } from '../core/types'
 import type { PickMarker } from './PickScene'
 import { DEFAULT_THEME, type ViewTheme } from './viewThemes'
 import { frameQuaternion } from './frameBasis'
+import { unclip } from './clipTree'
 import { pinLabel, pinValue, type PinVerdict } from './pinLabel'
 export { pinLabel, type PinVerdict } from './pinLabel'
 
@@ -139,6 +140,48 @@ function ownedGeometry(mesh: THREE.Mesh): THREE.BufferGeometry | undefined {
   return mesh.userData.ownedGeometry as THREE.BufferGeometry | undefined
 }
 
+/** What one element's marks are drawn with, kept for as long as the element
+ *  exists, drawn or not. A material let go takes its shader program with it
+ *  once nothing else holds that program, and the next one drawn compiles it
+ *  again in the middle of whatever tap asked for it. So a rebuild sets the
+ *  colour and the opacity of what it finds here and makes only what is
+ *  missing. Nothing else about these materials ever changes — the flags that
+ *  pick a program are fixed where they are made — so none of this needs a new
+ *  program. */
+interface ElementMaterials {
+  shell?: THREE.MeshStandardMaterial
+  dot?: THREE.MeshBasicMaterial
+  guide?: THREE.LineBasicMaterial
+  outline?: THREE.LineBasicMaterial
+}
+
+/** Everything updateOverlays reads, kept to tell whether the next call would
+ *  draw the same thing. */
+interface OverlayInput {
+  elements: readonly OverlayElement[]
+  pairs: readonly OverlayPair[]
+  angles: readonly OverlayAngle[]
+  tags: readonly OverlayTag[]
+  visible: boolean
+}
+
+/** Whether two plain values — numbers, strings, flags, and arrays and objects
+ *  of them — say the same. The overlay input is built afresh on every
+ *  update, so what matters is what it says and not which object says it. A
+ *  difference this cannot see (a NaN, a key held as undefined) reads as a
+ *  change, which only costs a rebuild. */
+function sameData(a: unknown, b: unknown): boolean {
+  if (a === b) return true
+  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false
+  if (Array.isArray(a) !== Array.isArray(b)) return false
+  const x = a as Record<string, unknown>
+  const y = b as Record<string, unknown>
+  const keys = Object.keys(x)
+  if (keys.length !== Object.keys(y).length) return false
+  for (const k of keys) if (!(k in y) || !sameData(x[k], y[k])) return false
+  return true
+}
+
 /** What the overlays need from the viewport around them. */
 export interface OverlaysContext {
   partGroup: THREE.Group
@@ -199,13 +242,21 @@ export class Overlays {
    *  materials to restyle when that element is selected. */
   private overlayPickables: THREE.Mesh[] = []
   private shellMaterials = new Map<number, { material: THREE.MeshStandardMaterial; color: string }>()
+  /** The materials of every element that exists — see ElementMaterials. */
+  private elementMaterials = new Map<number, ElementMaterials>()
+  /** The same for the marks that are alike for every element: the callout
+   *  lines, and the white strokes of a selection, which are rebuilt on every
+   *  hover and every change of zoom. */
+  private calloutMaterial: THREE.LineBasicMaterial | null = null
+  private strokeMaterials: { hull?: THREE.MeshBasicMaterial; frame?: THREE.MeshBasicMaterial } = {}
+  /** What was last drawn, and whether something has moved the overlays since
+   *  without going through updateOverlays — see setShown. */
+  private lastInput: OverlayInput | null = null
+  private touched = false
   /** The scheme's colours for the marks that carry no reading of their own —
    *  callout lines, the ghost of a pending fit. Element tints, and the labels'
    *  CSS, are not the theme's to touch. */
   private accents: ViewTheme['accents'] = DEFAULT_THEME.accents
-  /** The callout materials on screen, kept so a scheme switch can recolour
-   *  them in place instead of waiting for the next rebuild. */
-  private calloutMaterials: THREE.LineBasicMaterial[] = []
   private highlightIds = new Set<number>()
   private lastOverlayElements: OverlayElement[] = []
   private previewShape: THREE.Mesh | null = null
@@ -257,6 +308,9 @@ export class Overlays {
    *  pending fit, which are elements too. The next updateOverlays sets it
    *  again as the workspace has it. */
   setShown(on: boolean): void {
+    // What is on screen no longer says what the last update asked for, so the
+    // next update must be drawn even if it asks for the same again.
+    this.touched = true
     this.overlayGroup.visible = on
     this.selectionGroup.visible = on
     this.previewGroup.visible = on
@@ -268,13 +322,33 @@ export class Overlays {
     return this.overlayGroup.visible ? [...this.overlayPickables] : []
   }
 
+  /**
+   * Draw the elements, the dimensions between them and the pins of both, or
+   * put them away.
+   *
+   * `existing` names every element that still exists, drawn or not: the
+   * materials of those are kept for the next time they are drawn (see
+   * ElementMaterials), and only an element's own going releases its
+   * materials. Left out, the elements given are all that exist.
+   *
+   * An update that would draw what is already drawn is not drawn again.
+   * Returns whether it drew. The arrays must not be changed afterwards.
+   */
   updateOverlays(
     elements: OverlayElement[],
     pairs: OverlayPair[],
     angles: OverlayAngle[],
     tags: OverlayTag[],
     visible: boolean,
-  ): void {
+    existing?: ReadonlySet<number>,
+  ): boolean {
+    const keep = new Set(existing)
+    for (const el of elements) keep.add(el.id)
+    this.releaseMaterials(keep)
+    const input: OverlayInput = { elements, pairs, angles, tags, visible }
+    if (!this.touched && this.lastInput && sameData(this.lastInput, input)) return false
+    this.lastInput = input
+    this.touched = false
     this.ctx.invalidate()
     for (const fn of this.overlayCleanup) fn()
     this.overlayCleanup = []
@@ -282,33 +356,28 @@ export class Overlays {
     this.overlayGroup.clear()
     this.overlayPickables = []
     this.shellMaterials.clear()
-    this.calloutMaterials = []
     this.overlayGroup.visible = visible
     this.selectionGroup.visible = true
     this.previewGroup.visible = true
     this.lastOverlayElements = visible ? elements : []
     if (!visible) {
       this.rebuildSelectionOutlines()
-      return
+      return true
     }
 
     for (const el of elements) {
+      const mats = this.materialsOf(el.id)
       if (el.style === 'outline') {
-        const outline = this.buildOutline(el.fit, el.color, el.muted === true)
-        if (outline) {
-          this.overlayGroup.add(outline.line)
-          this.overlayCleanup.push(outline.dispose)
-        }
+        const outline = this.buildOutline(el.fit, el.color, el.muted === true, mats)
+        if (outline) this.overlayGroup.add(outline)
       } else {
         // The fitted element itself stays on screen — translucent and without
         // depth writes so the scan surface, centre marker and distance lines
         // stay readable through it. The polygon offset is what keeps it from
         // fighting the depth buffer along a surface it was fitted to and lies
         // exactly on: coplanar with the scan, the two would stripe.
-        const shell = new THREE.MeshStandardMaterial({
-          color: el.color,
+        const shell = (mats.shell ??= new THREE.MeshStandardMaterial({
           transparent: true,
-          opacity: el.muted ? 0.22 : 0.3,
           depthWrite: false,
           polygonOffset: true,
           polygonOffsetFactor: -1,
@@ -316,7 +385,10 @@ export class Overlays {
           roughness: 0.4,
           metalness: 0,
           side: THREE.DoubleSide,
-        })
+        }))
+        unclip(shell)
+        shell.color.set(el.color)
+        shell.opacity = el.muted ? 0.22 : 0.3
         const shape = this.buildShape(el.fit, shell)
         this.holdShape(this.overlayHeld, shape, el.fit)
         shape.userData.elementId = el.id
@@ -325,24 +397,21 @@ export class Overlays {
         const entry = { material: shell, color: el.color }
         this.shellMaterials.set(el.id, entry)
         this.applyHighlight(el.id, entry)
-        this.overlayCleanup.push(() => {
-          shell.dispose()
-          ownedGeometry(shape)?.dispose()
-        })
+        this.overlayCleanup.push(() => ownedGeometry(shape)?.dispose())
       }
 
-      const dotMat = new THREE.MeshBasicMaterial({ color: el.color })
+      const dotMat = (mats.dot ??= new THREE.MeshBasicMaterial())
+      unclip(dotMat).color.set(el.color)
       const marker = new THREE.Mesh(this.unitSphere, dotMat)
       marker.position.set(...el.fit.center)
       this.hold(this.overlayHeld, () => marker.scale.setScalar(this.px(CENTRE_PX)))
       marker.userData.elementId = el.id
       this.overlayGroup.add(marker)
       this.overlayPickables.push(marker)
-      this.overlayCleanup.push(() => dotMat.dispose())
 
       // The line a cylinder is measured along, and the direction a plane
       // faces, are results in their own right — both get drawn.
-      const guide = this.buildGuide(el.fit, el.color)
+      const guide = this.buildGuide(el.fit, el.color, mats)
       if (guide) {
         this.overlayGroup.add(guide.line)
         this.overlayCleanup.push(guide.dispose)
@@ -359,17 +428,8 @@ export class Overlays {
         new THREE.Vector3(...p.a),
         new THREE.Vector3(...p.b),
       ])
-      const mat = new THREE.LineBasicMaterial({
-        color: this.accents.callout,
-        transparent: true,
-        opacity: 0.8,
-      })
-      this.calloutMaterials.push(mat)
-      this.overlayGroup.add(new THREE.Line(geo, mat))
-      this.overlayCleanup.push(() => {
-        geo.dispose()
-        mat.dispose()
-      })
+      this.overlayGroup.add(new THREE.Line(geo, this.calloutMaterialOf()))
+      this.overlayCleanup.push(() => geo.dispose())
 
       const label = pinLabel('distance-label', p.title, p.value, undefined, p)
       label.position.set((p.a[0] + p.b[0]) / 2, (p.a[1] + p.b[1]) / 2, (p.a[2] + p.b[2]) / 2)
@@ -380,6 +440,58 @@ export class Overlays {
     for (const a of angles) this.addAngle(a)
     for (const t of tags) this.addTag(t)
     this.rebuildSelectionOutlines()
+    return true
+  }
+
+  /** What an element's marks are drawn with: the one set it has had since it
+   *  was first drawn, or a new one. */
+  private materialsOf(id: number): ElementMaterials {
+    let mats = this.elementMaterials.get(id)
+    if (!mats) this.elementMaterials.set(id, (mats = {}))
+    return mats
+  }
+
+  /** Let go of the materials of every element not in `keep`. */
+  private releaseMaterials(keep: ReadonlySet<number>): void {
+    for (const [id, mats] of this.elementMaterials) {
+      if (keep.has(id)) continue
+      for (const m of Object.values(mats)) m.dispose()
+      this.elementMaterials.delete(id)
+    }
+  }
+
+  /** The callout lines are alike, so every one of them wears the same
+   *  material: the scheme's colour. */
+  private calloutMaterialOf(): THREE.LineBasicMaterial {
+    this.calloutMaterial ??= new THREE.LineBasicMaterial({
+      color: this.accents.callout,
+      transparent: true,
+      opacity: 0.8,
+    })
+    return unclip(this.calloutMaterial)
+  }
+
+  /** The white of a selection's stroke, the same for every element it
+   *  surrounds: the hull of a volume, or the frame of a flat patch. */
+  private strokeMaterialOf(kind: 'hull' | 'frame'): THREE.MeshBasicMaterial {
+    this.strokeMaterials[kind] ??=
+      kind === 'hull'
+        ? new THREE.MeshBasicMaterial({
+            color: 0xffffff,
+            side: THREE.BackSide,
+            transparent: true,
+            opacity: 0.9,
+            depthWrite: false,
+          })
+        : new THREE.MeshBasicMaterial({
+            color: 0xffffff,
+            side: THREE.DoubleSide,
+            transparent: true,
+            opacity: 0.9,
+            depthWrite: false,
+            depthTest: false,
+          })
+    return unclip(this.strokeMaterials[kind]!)
   }
 
   /** A pin beside the feature, floated off it the way its name tag is; the
@@ -396,13 +508,7 @@ export class Overlays {
     const vertex = new THREE.Vector3(...a.vertex)
     const dirA = new THREE.Vector3(...a.dirA).normalize()
     const dirB = new THREE.Vector3(...a.dirB).normalize()
-    const mat = new THREE.LineBasicMaterial({
-      color: this.accents.callout,
-      transparent: true,
-      opacity: 0.8,
-    })
-    this.calloutMaterials.push(mat)
-    this.overlayCleanup.push(() => mat.dispose())
+    const mat = this.calloutMaterialOf()
 
     // Drawn out to 1 about the vertex, and scaled to its reach on the screen.
     const fan = new THREE.Group()
@@ -453,7 +559,7 @@ export class Overlays {
    *  screen, not wait for the next rebuild. */
   setTheme(theme: ViewTheme): void {
     this.accents = theme.accents
-    for (const mat of this.calloutMaterials) mat.color.setHex(theme.accents.callout)
+    this.calloutMaterial?.color.setHex(theme.accents.callout)
     if (this.previewShape)
       (this.previewShape.material as THREE.MeshStandardMaterial).color.setHex(theme.accents.ghost)
     this.ctx.invalidate()
@@ -510,33 +616,16 @@ export class Overlays {
       hole.closePath()
       shape.holes.push(hole)
       const geo = new THREE.ShapeGeometry(shape)
-      const mat = new THREE.MeshBasicMaterial({
-        color: 0xffffff,
-        side: THREE.DoubleSide,
-        transparent: true,
-        opacity: 0.9,
-        depthWrite: false,
-        depthTest: false,
-      })
-      const mesh = new THREE.Mesh(geo, mat)
+      const mesh = new THREE.Mesh(geo, this.strokeMaterialOf('frame'))
       mesh.quaternion.copy(frameQuaternion(fit))
       mesh.position.set(...fit.center)
       mesh.renderOrder = 3
       this.selectionGroup.add(mesh)
-      this.selectionCleanup.push(() => {
-        geo.dispose()
-        mat.dispose()
-      })
+      this.selectionCleanup.push(() => geo.dispose())
       return
     }
 
-    const mat = new THREE.MeshBasicMaterial({
-      color: 0xffffff,
-      side: THREE.BackSide,
-      transparent: true,
-      opacity: 0.9,
-      depthWrite: false,
-    })
+    const mat = this.strokeMaterialOf('hull')
 
     if (fit.kind === 'cone') {
       // The stroke has to grow both radii by the same margin, which no scale
@@ -556,10 +645,7 @@ export class Overlays {
         new THREE.Vector3(...fit.axis).normalize(),
       )
       this.selectionGroup.add(mesh)
-      this.selectionCleanup.push(() => {
-        geo.dispose()
-        mat.dispose()
-      })
+      this.selectionCleanup.push(() => geo.dispose())
       return
     }
 
@@ -571,10 +657,7 @@ export class Overlays {
       mesh.position.set(...fit.center)
       mesh.quaternion.setFromUnitVectors(new THREE.Vector3(0, 0, 1), new THREE.Vector3(...fit.axis).normalize())
       this.selectionGroup.add(mesh)
-      this.selectionCleanup.push(() => {
-        geo.dispose()
-        mat.dispose()
-      })
+      this.selectionCleanup.push(() => geo.dispose())
       return
     }
 
@@ -591,10 +674,7 @@ export class Overlays {
       mesh.scale.set(r, Math.max(fit.length * 1.05, 1e-5) + 2 * t, r)
     }
     this.selectionGroup.add(mesh)
-    this.selectionCleanup.push(() => {
-      mat.dispose()
-      ownedGeometry(mesh)?.dispose()
-    })
+    this.selectionCleanup.push(() => ownedGeometry(mesh)?.dispose())
   }
 
   /** A ring of unit radius about Z, to be scaled to `radius`, whose tube is
@@ -747,11 +827,7 @@ export class Overlays {
    *  Muted is an element merely on offer rather than the one in use: the same
    *  border, drawn back, so which of them the reading is measured against is
    *  still legible at a glance. */
-  private buildOutline(
-    fit: FitData,
-    color: string,
-    muted = false,
-  ): { line: THREE.LineSegments; dispose: () => void } | null {
+  private buildOutline(fit: FitData, color: string, muted: boolean, mats: ElementMaterials): THREE.LineSegments | null {
     const edges =
       fit.kind === 'plane'
         ? this.unitPlaneEdges
@@ -759,20 +835,21 @@ export class Overlays {
           ? this.unitCylinderEdges
           : null
     if (!edges) return null
-    const material = new THREE.LineBasicMaterial({
-      color,
+    const material = (mats.outline ??= new THREE.LineBasicMaterial({
       transparent: true,
-      opacity: muted ? 0.5 : 0.95,
       depthWrite: false,
       depthTest: false,
-    })
+    }))
+    unclip(material)
+    material.color.set(color)
+    material.opacity = muted ? 0.5 : 0.95
     const line = new THREE.LineSegments(edges, material)
     const placed = this.buildShape(fit, material)
     line.position.copy(placed.position)
     line.quaternion.copy(placed.quaternion)
     line.scale.copy(placed.scale)
     line.renderOrder = 3
-    return { line, dispose: () => material.dispose() }
+    return line
   }
 
   /** How far off the element's centre its label should float.
@@ -821,7 +898,7 @@ export class Overlays {
 
   /** A cylinder's axis, or a plane's or circle's normal, drawn as a line from
    *  the centre. */
-  private buildGuide(fit: FitData, color: string): { line: THREE.Line; dispose: () => void } | null {
+  private buildGuide(fit: FitData, color: string, mats: ElementMaterials): { line: THREE.Line; dispose: () => void } | null {
     if (fit.kind === 'sphere' || fit.kind === 'point' || fit.kind === 'line') return null
     const center = new THREE.Vector3(...fit.center)
     let a: THREE.Vector3
@@ -847,14 +924,9 @@ export class Overlays {
       b = center.clone().addScaledVector(dir, Math.max(fit.extentU, fit.extentV) * 0.35)
     }
     const geo = new THREE.BufferGeometry().setFromPoints([a, b])
-    const mat = new THREE.LineBasicMaterial({ color, transparent: true, opacity: 0.9 })
-    return {
-      line: new THREE.Line(geo, mat),
-      dispose: () => {
-        geo.dispose()
-        mat.dispose()
-      },
-    }
+    const mat = (mats.guide ??= new THREE.LineBasicMaterial({ transparent: true, opacity: 0.9 }))
+    unclip(mat).color.set(color)
+    return { line: new THREE.Line(geo, mat), dispose: () => geo.dispose() }
   }
 
   /** Translucent ghost of the element a pending fit produced. */
@@ -1128,7 +1200,12 @@ export class Overlays {
   }
 
   dispose(): void {
+    this.lastInput = null
     this.updateOverlays([], [], [], [], false)
+    this.calloutMaterial?.dispose()
+    this.calloutMaterial = null
+    for (const m of Object.values(this.strokeMaterials)) m.dispose()
+    this.strokeMaterials = {}
     this.setPreview(null)
     this.setProbes([])
     this.setPickMarkers([])
diff --git a/src/viewer/sections.ts b/src/viewer/sections.ts
index 9ce46c6d..8b75de95 100644
--- a/src/viewer/sections.ts
+++ b/src/viewer/sections.ts
@@ -40,6 +40,7 @@ import type { Vec3 } from '../core/types'
 import { AXIS_COLORS } from './axisGizmo'
 import { SECTION_LINE_DEFAULT } from './lineWidths'
 import { pinLabel } from './overlays'
+import { unclip } from './clipTree'
 import { onFramePlane, planeSheet } from './frameBasis'
 import { LineWidthRegistry } from './lineWidthRegistry'
 
@@ -67,6 +68,22 @@ export interface SectionOverlayItem {
   extrude?: boolean
 }
 
+/** What one finished section is drawn with, kept for as long as the section is
+ *  on offer, drawn or not. A material let go takes its shader program with it
+ *  once nothing else holds that program, and the next one drawn compiles it
+ *  again in the middle of whatever tap asked for it — so a rebuild sets the
+ *  colour, width and opacity of what it finds here and makes only what is
+ *  missing. The flags that pick a program are fixed where each is made. */
+interface SectionMaterials {
+  cut?: LineMaterial
+  elements?: LineMaterial
+  dot?: THREE.MeshBasicMaterial
+  block?: THREE.MeshBasicMaterial
+  edge?: THREE.LineBasicMaterial
+  /** Lets the fat lines above go from the registry that keeps them sized. */
+  letGo: (() => void)[]
+}
+
 export interface SectionOverlayContext {
   partGroup: THREE.Group
   /** Half the scan's bounding-box diagonal — what the preview sheet is sized to. */
@@ -81,6 +98,9 @@ export class SectionOverlay {
   private group = new THREE.Group()
   private previewGroup = new THREE.Group()
   private cleanup: (() => void)[] = []
+  /** The materials of every finished section on offer, by its id — see
+   *  SectionMaterials. */
+  private materials = new Map<number, SectionMaterials>()
   /** The dots of points on the sections, and what a pixel is worth. */
   private pointDots = new Set<THREE.Mesh>()
   private worldPerPixel = 0
@@ -160,6 +180,14 @@ export class SectionOverlay {
   /** The finished sections, rebuilt wholesale when anything about them
    *  changes — the same policy as the element overlays. */
   setSections(items: readonly SectionOverlayItem[], visible: boolean): void {
+    // A section on offer keeps its materials, drawn or not; only one that goes
+    // from the list lets them go.
+    for (const [id, mats] of this.materials) {
+      if (items.some((item) => item.id === id)) continue
+      for (const letGo of mats.letGo) letGo()
+      for (const m of [mats.cut, mats.elements, mats.dot, mats.block, mats.edge]) m?.dispose()
+      this.materials.delete(id)
+    }
     for (const fn of this.cleanup) fn()
     this.cleanup = []
     this.group.clear()
@@ -168,12 +196,14 @@ export class SectionOverlay {
     this.cuts = visible ? items.flatMap((item) => (item.cut ? [{ id: item.id, points: item.cut.points }] : [])) : []
     if (!visible) return
     for (const item of items) {
+      let held = this.materials.get(item.id)
+      if (!held) this.materials.set(item.id, (held = { letGo: [] }))
       // On the surface it was cut from, and hidden with it: a section on the
       // far side of the part is read by turning the part, like its tint.
       if (item.cut)
-        this.addPolylines(this.group, this.cleanup, item.cut, item.color, 0.95, SECTION_LINE_DEFAULT, !item.cut.shadow)
-      if (item.extrude && item.cut?.shadow) this.addBlock(this.group, this.cleanup, item.cut.shadow, item.color)
-      if (item.elements.length > 0) this.addElements(this.group, this.cleanup, item.elements, item.color)
+        this.addPolylines(this.group, this.cleanup, item.cut, item.color, 0.95, SECTION_LINE_DEFAULT, !item.cut.shadow, held)
+      if (item.extrude && item.cut?.shadow) this.addBlock(this.group, this.cleanup, item.cut.shadow, item.color, held)
+      if (item.elements.length > 0) this.addElements(this.group, this.cleanup, item.elements, item.color, held)
       const label = pinLabel('element-label', item.name, '', item.color)
       const lift = this.ctx.modelRadius() * 0.02
       label.position.set(
@@ -282,7 +312,13 @@ export class SectionOverlay {
   /** A shadow extruded: each outer loop with its holes as a shape on the
    *  sheet, stood up from the part's lowest point along the normal to its
    *  highest — translucent, so the part shows through it. */
-  private addBlock(group: THREE.Group, cleanup: (() => void)[], sh: ShadowShape, color: string): void {
+  private addBlock(
+    group: THREE.Group,
+    cleanup: (() => void)[],
+    sh: ShadowShape,
+    color: string,
+    held?: SectionMaterials,
+  ): void {
     const depth = sh.extent.max - sh.extent.min
     if (!(depth > 0)) return
     const step = Math.PI / 36
@@ -301,26 +337,29 @@ export class SectionOverlay {
     geo.applyMatrix4(
       new THREE.Matrix4().makeBasis(new THREE.Vector3(...basisU), new THREE.Vector3(...basisV), new THREE.Vector3(...normal)).setPosition(base),
     )
-    const mat = new THREE.MeshBasicMaterial({
-      color,
-      transparent: true,
-      opacity: 0.18,
-      depthWrite: false,
-      side: THREE.DoubleSide,
-    })
+    // The preview's block is made afresh each time and goes with its cleanup;
+    // a finished section's is its own for as long as it is on offer.
+    const makeBlock = () =>
+      new THREE.MeshBasicMaterial({ transparent: true, opacity: 0.18, depthWrite: false, side: THREE.DoubleSide })
+    const mat = held ? (held.block ??= makeBlock()) : makeBlock()
+    unclip(mat).color.set(color)
     const block = new THREE.Mesh(geo, mat)
     block.renderOrder = 2
     group.add(block)
     const edges = new THREE.EdgesGeometry(geo, 30)
-    const edgeMat = new THREE.LineBasicMaterial({ color, transparent: true, opacity: 0.6, depthWrite: false })
+    const makeEdge = () => new THREE.LineBasicMaterial({ transparent: true, opacity: 0.6, depthWrite: false })
+    const edgeMat = held ? (held.edge ??= makeEdge()) : makeEdge()
+    unclip(edgeMat).color.set(color)
     const outline = new THREE.LineSegments(edges, edgeMat)
     outline.renderOrder = 3
     group.add(outline)
     cleanup.push(() => {
       geo.dispose()
-      mat.dispose()
       edges.dispose()
-      edgeMat.dispose()
+      if (!held) {
+        mat.dispose()
+        edgeMat.dispose()
+      }
     })
   }
 
@@ -425,6 +464,47 @@ export class SectionOverlay {
     this.ctx.invalidate()
   }
 
+  /** A fat-line material for a section's cut or for its elements, set as
+   *  asked. A finished section's (`held`) is the one it has had since it was
+   *  first drawn, made if it has none; the preview's is made afresh and goes
+   *  with its cleanup. `offset` is the polygon offset pulling it in front of
+   *  the surface it lies on, none for 0. */
+  private fatLine(
+    cleanup: (() => void)[],
+    held: SectionMaterials | undefined,
+    slot: 'cut' | 'elements',
+    color: string,
+    opacity: number,
+    width: number,
+    depthTest: boolean,
+    offset: number,
+  ): LineMaterial {
+    let mat = held?.[slot]
+    if (!mat) {
+      mat = new LineMaterial({ transparent: true, depthWrite: false, worldUnits: false })
+      const letGo = this.fatLines.track(mat, width)
+      if (held) {
+        held[slot] = mat
+        held.letGo.push(letGo)
+      } else {
+        const own = mat
+        cleanup.push(() => {
+          letGo()
+          own.dispose()
+        })
+      }
+    }
+    unclip(mat)
+    mat.color.set(new THREE.Color(color).getHex())
+    mat.linewidth = width * this.fatLines.scale
+    mat.opacity = opacity
+    mat.depthTest = depthTest
+    mat.polygonOffset = offset !== 0
+    mat.polygonOffsetFactor = offset
+    mat.polygonOffsetUnits = offset
+    return mat
+  }
+
   /** The chains of a cut as screen-space fat lines. `onSurface` hides them
    *  behind the part like anything else on it; otherwise they draw ahead of
    *  the depth buffer. */
@@ -436,28 +516,11 @@ export class SectionOverlay {
     opacity: number,
     width: number,
     onSurface: boolean,
+    held?: SectionMaterials,
   ): void {
-    const mat = new LineMaterial({
-      color: new THREE.Color(color).getHex(),
-      linewidth: width * this.fatLines.scale,
-      transparent: true,
-      opacity,
-      depthTest: onSurface,
-      depthWrite: false,
-      worldUnits: false,
-    })
     // On the surface, a hair in front of it: the curve lies exactly on the
     // triangles it was cut from and would stripe with them otherwise.
-    if (onSurface) {
-      mat.polygonOffset = true
-      mat.polygonOffsetFactor = -2
-      mat.polygonOffsetUnits = -2
-    }
-    const letGo = this.fatLines.track(mat, width)
-    cleanup.push(() => {
-      letGo()
-      mat.dispose()
-    })
+    const mat = this.fatLine(cleanup, held, 'cut', color, opacity, width, onSurface, onSurface ? -2 : 0)
     for (let c = 0; c + 1 < cut.offsets.length; c++) {
       const start = cut.offsets[c]
       const end = cut.offsets[c + 1]
@@ -481,32 +544,19 @@ export class SectionOverlay {
     cleanup: (() => void)[],
     elements: readonly SectionGeometry[],
     color: string,
+    held?: SectionMaterials,
   ): void {
-    const width = SECTION_LINE_DEFAULT + 1
-    const mat = new LineMaterial({
-      color: new THREE.Color(color).getHex(),
-      linewidth: width * this.fatLines.scale,
-      transparent: true,
-      opacity: 1,
-      depthTest: true,
-      depthWrite: false,
-      worldUnits: false,
-    })
-    mat.polygonOffset = true
-    mat.polygonOffsetFactor = -3
-    mat.polygonOffsetUnits = -3
-    const letGo = this.fatLines.track(mat, width)
-    cleanup.push(() => {
-      letGo()
-      mat.dispose()
-    })
+    const mat = this.fatLine(cleanup, held, 'elements', color, 1, SECTION_LINE_DEFAULT + 1, true, -3)
     let dotMat: THREE.MeshBasicMaterial | null = null
     for (const g of elements) {
       const stroke = sectionStroke(g)
       if (!stroke) {
         // Only a point has no stroke — it is a dot where it was picked.
         if (g.kind !== 'point') continue
-        dotMat ??= new THREE.MeshBasicMaterial({ color })
+        if (!dotMat) {
+          dotMat = held ? (held.dot ??= new THREE.MeshBasicMaterial()) : new THREE.MeshBasicMaterial()
+          unclip(dotMat).color.set(color)
+        }
         const dot = new THREE.Mesh(this.unitSphere, dotMat)
         dot.position.set(g.center[0], g.center[1], g.center[2])
         this.pointDots.add(dot)
@@ -524,7 +574,7 @@ export class SectionOverlay {
       group.add(line)
       cleanup.push(() => geo.dispose())
     }
-    if (dotMat) {
+    if (dotMat && !held) {
       const m = dotMat
       cleanup.push(() => m.dispose())
     }
diff --git a/src/viewer/volumeLayer.ts b/src/viewer/volumeLayer.ts
index 0e57f64c..4588516b 100644
--- a/src/viewer/volumeLayer.ts
+++ b/src/viewer/volumeLayer.ts
@@ -20,7 +20,11 @@ const KINDS: VolumeKind[] = ['excess', 'missing', 'unsure']
 export class VolumeLayer {
   readonly group = new THREE.Group()
   private shells: { kind: VolumeKind; shell: VolumeShell; colors: THREE.BufferAttribute }[] = []
-  private materials: THREE.Material[] = []
+  /** The two materials every measurement is drawn with, kept for the layer's
+   *  life: a measurement replaced would otherwise let them go and, with them,
+   *  the shader programs they hold, to be compiled again for the next. */
+  private front: THREE.MeshStandardMaterial | null = null
+  private through: THREE.MeshBasicMaterial | null = null
   private geometries: THREE.BufferGeometry[] = []
   private hovered: number | null = null
 
@@ -33,9 +37,8 @@ export class VolumeLayer {
   set(volume: VolumeDeviation | null): void {
     this.clear()
     if (!volume?.meshes) return
-    const front = new THREE.MeshStandardMaterial({ vertexColors: true, transparent: true, opacity: 0.85, side: THREE.DoubleSide, roughness: 1, metalness: 0, polygonOffset: true, polygonOffsetFactor: -1 })
-    const through = new THREE.MeshBasicMaterial({ vertexColors: true, transparent: true, opacity: 0.28, side: THREE.DoubleSide, depthTest: false, depthWrite: false })
-    this.materials = [front, through]
+    const front = (this.front ??= new THREE.MeshStandardMaterial({ vertexColors: true, transparent: true, opacity: 0.85, side: THREE.DoubleSide, roughness: 1, metalness: 0, polygonOffset: true, polygonOffsetFactor: -1 }))
+    const through = (this.through ??= new THREE.MeshBasicMaterial({ vertexColors: true, transparent: true, opacity: 0.28, side: THREE.DoubleSide, depthTest: false, depthWrite: false }))
     for (const kind of KINDS) {
       const shell = volume.meshes[kind]
       if (shell.indices.length === 0) continue
@@ -88,9 +91,7 @@ export class VolumeLayer {
   private clear(): void {
     this.group.clear()
     for (const g of this.geometries) g.dispose()
-    for (const m of this.materials) m.dispose()
     this.geometries = []
-    this.materials = []
     this.shells = []
     this.hovered = null
     this.group.visible = false
@@ -98,5 +99,8 @@ export class VolumeLayer {
 
   dispose(): void {
     this.clear()
+    this.front?.dispose()
+    this.through?.dispose()
+    this.front = this.through = null
   }
 }
diff --git a/tests/overlayMaterials.test.ts b/tests/overlayMaterials.test.ts
new file mode 100644
index 00000000..9b2a9723
--- /dev/null
+++ b/tests/overlayMaterials.test.ts
@@ -0,0 +1,314 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// The overlays draw the measured elements, and the sections the cuts, over and
+// over as the workspace changes — and a material let go on each rebuild takes
+// its shader program with it, to be compiled again on the tap that draws it
+// next. So: an update that would draw what is drawn already draws nothing,
+// a rebuild keeps the materials of the elements that exist and sets their
+// colour in place, and only an element's own going lets its materials go.
+import * as THREE from 'three'
+import { Line2 } from 'three/addons/lines/Line2.js'
+import { describe, expect, it, vi } from 'vitest'
+import type { FitData } from '../src/core/types'
+import { Overlays, type OverlayElement, type OverlayPair } from '../src/viewer/overlays'
+import { SectionOverlay, type SectionOverlayItem } from '../src/viewer/sections'
+
+// A pin is an HTML label; there is no page to make it on here, and what it
+// says is not what is tested.
+vi.mock('../src/viewer/pinLabel', async (original) => ({
+  ...(await original<typeof import('../src/viewer/pinLabel')>()),
+  pinLabel: () => Object.assign(new THREE.Object3D(), { element: { remove() {} } }),
+}))
+
+const plane: FitData = {
+  kind: 'plane',
+  center: [0, 0, 0],
+  normal: [0, 0, 1],
+  basisU: [1, 0, 0],
+  basisV: [0, 1, 0],
+  extentU: 5,
+  extentV: 4,
+  sigma: 0.01,
+  usedPoints: 100,
+  regionSize: 100,
+}
+const cylinder: FitData = {
+  kind: 'cylinder',
+  center: [10, 0, 0],
+  axis: [0, 0, 1],
+  radius: 3,
+  length: 8,
+  coverage: 180,
+  sigma: 0.01,
+  usedPoints: 100,
+  regionSize: 100,
+}
+
+const element = (id: number, fit: FitData, over: Partial<OverlayElement> = {}): OverlayElement => ({
+  id,
+  name: `E${id}`,
+  color: '#3366cc',
+  fit,
+  style: 'shell',
+  ...over,
+})
+
+function makeOverlays() {
+  const partGroup = new THREE.Group()
+  const camera = new THREE.PerspectiveCamera()
+  const overlays = new Overlays({
+    partGroup,
+    modelRadius: () => 10,
+    invalidate: () => {},
+    camera,
+    raycaster: new THREE.Raycaster(),
+    occluder: () => null,
+  })
+  return { overlays, root: overlays.clipRoots()[0] }
+}
+
+/** Every material under the element overlays, once each. */
+function materialsUnder(root: THREE.Object3D): Set<THREE.Material> {
+  const found = new Set<THREE.Material>()
+  root.traverse((o) => {
+    const m = (o as THREE.Mesh).material as THREE.Material | undefined
+    if (m) found.add(m)
+  })
+  return found
+}
+
+/** Which materials are disposed from now on. */
+function watchDisposal(materials: Iterable<THREE.Material>): Set<THREE.Material> {
+  const gone = new Set<THREE.Material>()
+  for (const m of materials) m.addEventListener('dispose', () => gone.add(m))
+  return gone
+}
+
+describe('the element overlays', () => {
+  it('draw nothing again when asked for what is drawn, though the input is made afresh', () => {
+    const { overlays, root } = makeOverlays()
+    expect(overlays.updateOverlays([element(1, plane), element(2, cylinder)], [], [], [], true)).toBe(true)
+    const meshes = [...root.children]
+    // The same again, in objects of its own.
+    expect(
+      overlays.updateOverlays([element(1, { ...plane }), element(2, { ...cylinder })], [], [], [], true),
+    ).toBe(false)
+    expect(root.children.length).toBe(meshes.length)
+    expect(root.children.every((c, i) => c === meshes[i])).toBe(true)
+  })
+
+  it('draw again for each thing they draw from changing', () => {
+    const { overlays } = makeOverlays()
+    const base = () => [element(1, plane), element(2, cylinder)]
+    overlays.updateOverlays(base(), [], [], [], true)
+    const changed: [string, OverlayElement[], boolean][] = [
+      ['a name', [element(1, plane, { name: 'other' }), element(2, cylinder)], true],
+      ['a colour', [element(1, plane, { color: '#cc3333' }), element(2, cylinder)], true],
+      ['a style', [element(1, plane, { style: 'outline' }), element(2, cylinder)], true],
+      ['muting', [element(1, plane, { muted: true }), element(2, cylinder)], true],
+      ['a figure', [element(1, plane, { value: '12.5' }), element(2, cylinder)], true],
+      ['a fit', [element(1, { ...plane, extentU: 6 }), element(2, cylinder)], true],
+      ['an element gone', [element(2, cylinder)], true],
+      ['an element added', [element(2, cylinder), element(3, plane)], true],
+      ['visibility', [element(2, cylinder), element(3, plane)], false],
+    ]
+    for (const [what, input, visible] of changed) {
+      expect(overlays.updateOverlays(input, [], [], [], visible), what).toBe(true)
+      expect(overlays.updateOverlays(structuredClone(input), [], [], [], visible), `${what}, then the same`).toBe(false)
+    }
+  })
+
+  it('draw again for a dimension that changes, a pair, an angle or a pin', () => {
+    const { overlays } = makeOverlays()
+    const els = [element(1, plane)]
+    const pair: OverlayPair = { a: [0, 0, 0], b: [10, 0, 0], title: 'D1', value: '10.000' }
+    overlays.updateOverlays(els, [pair], [], [], true)
+    expect(overlays.updateOverlays(els, [{ ...pair }], [], [], true)).toBe(false)
+    expect(overlays.updateOverlays(els, [{ ...pair, value: '10.500' }], [], [], true)).toBe(true)
+    expect(overlays.updateOverlays(els, [{ ...pair, value: '10.500', over: true }], [], [], true)).toBe(true)
+    expect(overlays.updateOverlays(els, [], [], [], true)).toBe(true)
+  })
+
+  it('draw again after being put away by hand, though asked for what they were', () => {
+    const { overlays } = makeOverlays()
+    const [elements] = overlays.clipRoots()
+    overlays.updateOverlays([element(1, plane)], [], [], [], true)
+    overlays.setShown(false)
+    expect(elements.visible).toBe(false)
+    expect(overlays.updateOverlays([element(1, plane)], [], [], [], true)).toBe(true)
+    expect(elements.visible).toBe(true)
+  })
+
+  it('keep the same materials across a rebuild, setting the colour in place', () => {
+    const { overlays, root } = makeOverlays()
+    overlays.updateOverlays([element(1, plane), element(2, cylinder)], [], [], [], true)
+    const first = materialsUnder(root)
+    expect(first.size).toBeGreaterThan(2)
+    const gone = watchDisposal(first)
+    const shellOf = (c: THREE.Object3D) => (c as THREE.Mesh).material as THREE.MeshStandardMaterial
+    const shell = [...root.children].map(shellOf).find((m) => m.isMeshStandardMaterial)!
+    const flags = { transparent: shell.transparent, side: shell.side, depthWrite: shell.depthWrite, polygonOffset: shell.polygonOffset }
+
+    overlays.updateOverlays([element(1, plane, { color: '#cc3333' }), element(2, cylinder)], [], [], [], true)
+    const second = materialsUnder(root)
+    expect([...second].every((m) => first.has(m))).toBe(true)
+    expect(second.size).toBe(first.size)
+    expect(gone.size).toBe(0)
+    expect(shell.color.getHexString()).toBe(new THREE.Color('#cc3333').getHexString())
+    // Nothing that picks a program was touched.
+    expect({ transparent: shell.transparent, side: shell.side, depthWrite: shell.depthWrite, polygonOffset: shell.polygonOffset }).toEqual(flags)
+  })
+
+  it('let go of the materials of an element that is gone, and of no other', () => {
+    const { overlays, root } = makeOverlays()
+    overlays.updateOverlays([element(1, plane), element(2, cylinder)], [], [], [], true)
+    const mine = (id: number) =>
+      new Set(
+        overlays
+          .pickTargets()
+          .filter((o) => o.userData.elementId === id)
+          .map((o) => (o as THREE.Mesh).material as THREE.Material),
+      )
+    const first = mine(1)
+    const second = mine(2)
+    const all = materialsUnder(root)
+    const gone = watchDisposal(all)
+
+    overlays.updateOverlays([element(2, cylinder)], [], [], [], true)
+    for (const m of first) expect(gone.has(m)).toBe(true)
+    for (const m of second) expect(gone.has(m)).toBe(false)
+  })
+
+  it('keep the materials of an element that exists though it is not drawn', () => {
+    const { overlays, root } = makeOverlays()
+    const exists = new Set([1, 2])
+    overlays.updateOverlays([element(1, plane), element(2, cylinder)], [], [], [], true, exists)
+    const drawn = materialsUnder(root)
+    const gone = watchDisposal(drawn)
+
+    // Away to a workspace that draws none of them, and back.
+    overlays.updateOverlays([], [], [], [], false, exists)
+    expect(root.children.length).toBe(0)
+    expect(gone.size).toBe(0)
+    overlays.updateOverlays([element(1, plane), element(2, cylinder)], [], [], [], true, exists)
+    expect([...materialsUnder(root)].every((m) => drawn.has(m))).toBe(true)
+    expect(gone.size).toBe(0)
+
+    // One of them goes for good while the other is away.
+    overlays.updateOverlays([], [], [], [], false, new Set([2]))
+    expect(gone.size).toBeGreaterThan(0)
+    overlays.updateOverlays([element(2, cylinder)], [], [], [], true, new Set([2]))
+    const back = materialsUnder(root)
+    expect([...back].some((m) => gone.has(m))).toBe(false)
+  })
+
+  it('take a material back unclipped, whatever the section view left it holding', () => {
+    const { overlays, root } = makeOverlays()
+    overlays.updateOverlays([element(1, plane)], [], [], [], true)
+    const cut = [new THREE.Plane(new THREE.Vector3(0, 0, 1), 0)]
+    for (const m of materialsUnder(root)) m.clippingPlanes = cut
+    overlays.updateOverlays([element(1, plane, { color: '#cc3333' })], [], [], [], true)
+    for (const m of materialsUnder(root)) expect(m.clippingPlanes).toBeNull()
+  })
+
+  it('draw every callout and every selection stroke with one material, kept', () => {
+    const { overlays, root } = makeOverlays()
+    const [, strokes] = overlays.clipRoots()
+    const a: OverlayPair = { a: [0, 0, 0], b: [10, 0, 0], title: 'D1', value: '10' }
+    const b: OverlayPair = { a: [0, 0, 0], b: [0, 10, 0], title: 'D2', value: '10' }
+    overlays.updateOverlays([element(1, plane), element(2, cylinder)], [a, b], [], [], true)
+    const lines = root.children.filter((c) => (c as THREE.Line).isLine && !(c as THREE.LineSegments).isLineSegments)
+    // The guides are lines too, each with a material of its own: the callouts
+    // are the lines that share one.
+    const callouts = new Set(lines.map((l) => (l as THREE.Line).material as THREE.Material))
+    const shared = [...callouts].filter((m) => lines.filter((l) => (l as THREE.Line).material === m).length >= 2)
+    expect(shared.length).toBe(1)
+
+    overlays.setHighlightedElements([1, 2])
+    const hulls = new Set(strokes.children.map((c) => (c as THREE.Mesh).material as THREE.Material))
+    expect(hulls.size).toBe(2)
+    const gone = watchDisposal([...hulls, ...shared])
+    // Hover moves the selection about, and the zoom rebuilds it.
+    overlays.setHighlightedElements([2])
+    overlays.setHighlightedElements([1, 2])
+    overlays.setPixelScale(0.5)
+    expect(gone.size).toBe(0)
+    expect(new Set(strokes.children.map((c) => (c as THREE.Mesh).material as THREE.Material))).toEqual(hulls)
+  })
+
+  it('let go of everything when put away for good', () => {
+    const { overlays, root } = makeOverlays()
+    overlays.updateOverlays([element(1, plane)], [{ a: [0, 0, 0], b: [1, 0, 0], title: 'D', value: '1' }], [], [], true)
+    overlays.setHighlightedElements([1])
+    const [, strokes] = overlays.clipRoots()
+    const all = new Set([...materialsUnder(root), ...materialsUnder(strokes)])
+    const gone = watchDisposal(all)
+    overlays.dispose()
+    expect([...all].every((m) => gone.has(m))).toBe(true)
+  })
+})
+
+describe('the sections', () => {
+  const section = (id: number, color = '#22aa66'): SectionOverlayItem => ({
+    id,
+    name: `S${id}`,
+    color,
+    frame: { origin: [0, 0, 0], normal: [0, 0, 1], basisU: [1, 0, 0], basisV: [0, 1, 0] },
+    cut: { points: new Float32Array([0, 0, 0, 1, 0, 0, 1, 1, 0]), offsets: new Uint32Array([0, 3]) },
+    elements: [{ kind: 'point', center: [0.5, 0.5, 0] } as never],
+  })
+  function makeSections() {
+    const sections = new SectionOverlay({
+      partGroup: new THREE.Group(),
+      modelRadius: () => 10,
+      modelCenter: () => [0, 0, 0],
+      invalidate: () => {},
+    })
+    const root = sections.clipRoots()[0]
+    return { sections, root }
+  }
+
+  it('keep a section’s materials across rebuilds and across being put away', () => {
+    const { sections, root } = makeSections()
+    sections.setSections([section(1), section(2)], true)
+    const first = materialsUnder(root)
+    expect(first.size).toBeGreaterThan(2)
+    const gone = watchDisposal(first)
+    const cutLine = root.children.find((c) => (c as Line2).isLine2) as Line2
+    const flags = { transparent: cutLine.material.transparent, depthTest: cutLine.material.depthTest }
+
+    sections.setSections([section(1, '#aa2266'), section(2)], true)
+    expect([...materialsUnder(root)].every((m) => first.has(m))).toBe(true)
+    expect(gone.size).toBe(0)
+    // Put away with the workspace and shown again.
+    sections.setSections([section(1), section(2)], false)
+    expect(root.children.length).toBe(0)
+    sections.setSections([section(1), section(2)], true)
+    expect([...materialsUnder(root)].every((m) => first.has(m))).toBe(true)
+    expect(gone.size).toBe(0)
+    expect({ transparent: cutLine.material.transparent, depthTest: cutLine.material.depthTest }).toEqual(flags)
+  })
+
+  it('set the colour in place and let go of a section that is gone', () => {
+    const { sections, root } = makeSections()
+    sections.setSections([section(1), section(2)], true)
+    const lineOf = (id: number) => root.children.filter((c) => (c as Line2).isLine2)[id - 1] as Line2
+    const one = lineOf(1).material
+    const two = lineOf(2).material
+    const gone = watchDisposal([one, two])
+
+    sections.setSections([section(1, '#aa2266')], true)
+    expect(lineOf(1).material).toBe(one)
+    expect(one.color.getHex()).toBe(new THREE.Color('#aa2266').getHex())
+    expect(gone.has(one)).toBe(false)
+    expect(gone.has(two)).toBe(true)
+  })
+
+  it('let go of everything when put away for good', () => {
+    const { sections, root } = makeSections()
+    sections.setSections([section(1)], true)
+    const all = materialsUnder(root)
+    const gone = watchDisposal(all)
+    sections.dispose()
+    expect([...all].every((m) => gone.has(m))).toBe(true)
+  })
+})

From 92e4e096529e3d28d491db12b9946849b6b743d2 Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Wed, 4 Nov 2026 19:45:47 +0000
Subject: [PATCH 19/38] perf(overlays): say sameData is for plain data only

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/viewer/overlays.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/viewer/overlays.ts b/src/viewer/overlays.ts
index dc745561..0216183a 100644
--- a/src/viewer/overlays.ts
+++ b/src/viewer/overlays.ts
@@ -169,7 +169,8 @@ interface OverlayInput {
  *  of them — say the same. The overlay input is built afresh on every
  *  update, so what matters is what it says and not which object says it. A
  *  difference this cannot see (a NaN, a key held as undefined) reads as a
- *  change, which only costs a rebuild. */
+ *  change, which only costs a rebuild. Plain data only: a Map, a Set or a
+ *  Date has no keys to read and would always pass for the same. */
 function sameData(a: unknown, b: unknown): boolean {
   if (a === b) return true
   if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false

From 6d1243cf92524d7e77d913401b3222b590a0e075 Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Wed, 4 Nov 2026 21:27:58 +0000
Subject: [PATCH 20/38] perf(ui): narrow subscriptions, compute the hint ladder
 once

ThicknessPanel, MarkTools, the split picker and its pick tools read their
whole store; each now picks only the fields it draws. The hint ladder was
built by every usePulse caller; a HintsProvider above the app builds it
once and usePulse/useHintChip read it from context.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 src/App.tsx               | 13 ++++++++++-
 src/app/useHints.ts       | 45 ++++++++++++++++++++++++++++++++-------
 src/ui/MarkTools.tsx      | 18 +++++++++++++++-
 src/ui/SplitPicker.tsx    | 32 ++++++++++++++++++++++++++--
 src/ui/ThicknessPanel.tsx | 34 ++++++++++++++++++++++++++++-
 5 files changed, 129 insertions(+), 13 deletions(-)

diff --git a/src/App.tsx b/src/App.tsx
index cc015619..ec79e5b0 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -102,7 +102,7 @@ import { creaseNote } from './app/scanImport'
 import { useFlatSceneSync, type SheetView } from './app/useFlatSceneSync'
 import { buildFlatCsvFile, drawnSummary, flatExportStem, flatReportInput } from './app/flatReport'
 import { sheetAlignment, sheetElements, sheetFrame, sheetLoupeActive, sheetNotes, sheetPoseOf, sheetScale } from './app/flatSheet'
-import { useHintChip } from './app/useHints'
+import { HintsProvider, useHintChip } from './app/useHints'
 import { useGlobalShortcuts } from './app/useGlobalShortcuts'
 import { useDragDrop } from './app/useDragDrop'
 import { useOpenFromAddress } from './app/useOpenFromAddress'
@@ -119,7 +119,18 @@ const NO_RUNTIME: PluginRuntime = {}
  *  split for it again, ms: a slider dragged across splits it once. */
 const CREASE_SETTLE_MS = 250
 
+/** The hint ladder is asked once, here, and handed down to every control that
+ *  can ring (usePulse) and to the chip over the model (useHintChip). It sits
+ *  above the whole app so a portal or a plugin's panel is under it too. */
 export default function App() {
+  return (
+    <HintsProvider>
+      <Workbench />
+    </HintsProvider>
+  )
+}
+
+function Workbench() {
   const clientRef = useRef<MeshWorkerClient | null>(null)
   if (!clientRef.current) clientRef.current = new MeshWorkerClient()
   const sceneRef = useRef<SceneManager | null>(null)
diff --git a/src/app/useHints.ts b/src/app/useHints.ts
index 4a4ff227..949bdf41 100644
--- a/src/app/useHints.ts
+++ b/src/app/useHints.ts
@@ -3,7 +3,7 @@
 // ladder in core/hints what is still missing, and hands the answer to whichever
 // control is that step.
 
-import { useEffect } from 'react'
+import { createContext, createElement, useContext, useEffect, useMemo, type ReactNode } from 'react'
 import { isDeviationTarget } from '../core/deviation/elementField'
 import { nextHint, type HintInput, type HintResult, type HintTrack } from '../core/hints'
 import { useDeviation } from '../state/deviationStore'
@@ -124,27 +124,56 @@ export function hintNow(): HintResult {
   })
 }
 
+/** What the ladder says right now, boiled down to the three primitives the
+ *  controls need: the control to ring, the sentence for the chip, and whether
+ *  the workspace has been carried through. */
+interface Ladder {
+  active: string | null
+  text: string | null
+  done: boolean
+}
+
+/** Outside a HintsProvider nothing rings and nothing is said, which is what a
+ *  control rendered on its own (a test, a story) should do. */
+const SILENT: Ladder = { active: null, text: null, done: false }
+const LadderContext = createContext<Ladder>(SILENT)
+
+/** Asks the ladder once for the whole app. It used to be asked by every
+ *  control that can ring — one copy of the same twenty-odd store
+ *  subscriptions per control, each re-rendering its control on every change to
+ *  any of them — and the answer is the same for all of them. The value only changes when
+ *  the answer does, so a control is drawn again when its ring or the chip's
+ *  sentence moves, not when something the ladder merely looked at did. */
+export function HintsProvider({ children }: { children: ReactNode }) {
+  const result = useLadder()
+  const step = typeof result === 'object' && result !== null ? result : null
+  const active = step?.target ?? null
+  const text = step?.text ?? null
+  const done = result === 'done'
+  const value = useMemo(() => ({ active, text, done }), [active, text, done])
+  return createElement(LadderContext.Provider, { value }, children)
+}
+
 /** True when this control is the step to press next. Give it the control's own
  *  data-test id and put the returned class on the element — see `.pulse`. */
 export function usePulse(target: string): boolean {
-  const result = useLadder()
-  return typeof result === 'object' && result !== null && result.target === target
+  return useContext(LadderContext).active === target
 }
 
 /** The line for the chip over the model, or null when there is nothing to say
  *  or something on the stage is already saying it.
  *
- *  App's alone, and called exactly once: this is also where a workspace is
- *  recorded as carried through, which is what eventually retires its ring. */
+ *  App's alone, and called exactly once, under the HintsProvider: this is also
+ *  where a workspace is recorded as carried through, which is what eventually
+ *  retires its ring. */
 export function useHintChip(): string | null {
-  const result = useLadder()
+  const { text, done } = useContext(LadderContext)
   const workspace = useShell((s) => s.workspace)
   const markRun = useHintPrefs((s) => s.markRun)
-  const done = result === 'done'
 
   useEffect(() => {
     if (done) markRun(workspace)
   }, [done, workspace, markRun])
 
-  return typeof result === 'object' && result !== null ? result.text : null
+  return text
 }
diff --git a/src/ui/MarkTools.tsx b/src/ui/MarkTools.tsx
index 960b0fd8..a4e2f5e8 100644
--- a/src/ui/MarkTools.tsx
+++ b/src/ui/MarkTools.tsx
@@ -10,6 +10,7 @@
 // quietly holds the mouse hostage in one workspace but not the other is worse
 // than either behaviour on its own.
 
+import { useShallow } from 'zustand/react/shallow'
 import { brushRange, useMark, type MarkGesture } from '../state/markStore'
 import { useStore } from '../state/store'
 import { Icon, type IconName } from './icons'
@@ -87,7 +88,22 @@ export function MarkTools({
   /** Rub out the whole marking. */
   onClear: () => void
 }) {
-  const m = useMark()
+  // Everything the controls draw, and not `inverts`: that is a request counter for the
+  // viewport that holds the marking, bumped on every Invert and drawn by nobody here.
+  const m = useMark(
+    useShallow((s) => ({
+      backfaces: s.backfaces,
+      count: s.count,
+      diameter: s.diameter,
+      erase: s.erase,
+      gesture: s.gesture,
+      invert: s.invert,
+      setBackfaces: s.setBackfaces,
+      setDiameter: s.setDiameter,
+      setErase: s.setErase,
+      setGesture: s.setGesture,
+    })),
+  )
   const modelSize = useStore((s) => s.modelSize)
   const brush = brushRange(modelSize)
   const len = useLength()
diff --git a/src/ui/SplitPicker.tsx b/src/ui/SplitPicker.tsx
index eb55c161..bb4db93b 100644
--- a/src/ui/SplitPicker.tsx
+++ b/src/ui/SplitPicker.tsx
@@ -9,6 +9,7 @@
 // selected means the whole scan, which is what nearly every part wants.
 
 import { useEffect, useMemo, useRef, type ReactNode } from 'react'
+import { useShallow } from 'zustand/react/shallow'
 import * as THREE from 'three'
 import { PickScene, type PickMarker } from '../viewer/PickScene'
 import { schemeById } from '../viewer/navSchemes'
@@ -161,7 +162,21 @@ function Half({
 /** The scan half's second line: what the left button does on it, and what has
  *  been selected so far. */
 function PickTools({ onClear }: { onClear: () => void }) {
-  const m = useMark()
+  // The same slice MarkTools draws: `inverts` is nothing this strip shows.
+  const m = useMark(
+    useShallow((s) => ({
+      backfaces: s.backfaces,
+      count: s.count,
+      diameter: s.diameter,
+      erase: s.erase,
+      gesture: s.gesture,
+      invert: s.invert,
+      setBackfaces: s.setBackfaces,
+      setDiameter: s.setDiameter,
+      setErase: s.setErase,
+      setGesture: s.setGesture,
+    })),
+  )
   const modelSize = useStore((s) => s.modelSize)
   const brush = brushRange(modelSize)
   const short = m.count > 0 && m.count < MIN_LOCAL_POINTS
@@ -260,6 +275,8 @@ export function SplitPicker({
   onClearSelection: () => void
   onCancel: () => void
 }) {
+  // The picker's own slice: the store is also written on every map repaint,
+  // probe and band change, and none of those is drawn here.
   const {
     pairs,
     pendingScan,
@@ -269,7 +286,18 @@ export function SplitPicker({
     alignStatus,
     alignStopping,
     alignMessage,
-  } = useDeviation()
+  } = useDeviation(
+    useShallow((s) => ({
+      addPickPoint: s.addPickPoint,
+      alignMessage: s.alignMessage,
+      alignStatus: s.alignStatus,
+      alignStopping: s.alignStopping,
+      clearPairs: s.clearPairs,
+      pairs: s.pairs,
+      pendingScan: s.pendingScan,
+      undoPair: s.undoPair,
+    })),
+  )
   const markCount = useMark((s) => s.count)
   const markGesture = useMark((s) => s.gesture)
   const len = useLength()
diff --git a/src/ui/ThicknessPanel.tsx b/src/ui/ThicknessPanel.tsx
index 21d646b8..6d0bf801 100644
--- a/src/ui/ThicknessPanel.tsx
+++ b/src/ui/ThicknessPanel.tsx
@@ -5,6 +5,7 @@
 // as it is turned. Laid out like the deviation panel next door, because it is
 // the same instrument pointed at a different question.
 
+import { useShallow } from 'zustand/react/shallow'
 import { CONE_CHOICES, useThickness } from '../state/thicknessStore'
 import { useStore } from '../state/store'
 import { usePulse } from '../app/useHints'
@@ -29,7 +30,38 @@ export function ThicknessPanel({
   const scanName = useStore((s) => s.fileName)
   const scanTriangles = useStore((s) => s.triangleCount)
   const scanBusy = useStore((s) => s.busy)
-  const t = useThickness()
+  // Only what the panel shows and sets: the store is also written when a map
+  // lands (stats, histogram, mapVersion), none of which this panel reads, and
+  // the actions are stable, so picking them costs no re-render.
+  const t = useThickness(
+    useShallow((s) => ({
+      bands: s.bands,
+      clearProbes: s.clearProbes,
+      coneAngleDeg: s.coneAngleDeg,
+      coneRays: s.coneRays,
+      high: s.high,
+      limit: s.limit,
+      low: s.low,
+      maxThickness: s.maxThickness,
+      message: s.message,
+      method: s.method,
+      normalDeviationDeg: s.normalDeviationDeg,
+      probes: s.probes,
+      removeProbe: s.removeProbe,
+      setBands: s.setBands,
+      setConeAngle: s.setConeAngle,
+      setConeRays: s.setConeRays,
+      setHigh: s.setHigh,
+      setLimit: s.setLimit,
+      setLow: s.setLow,
+      setMaxThickness: s.setMaxThickness,
+      setMethod: s.setMethod,
+      setNormalDeviation: s.setNormalDeviation,
+      setShowHistogram: s.setShowHistogram,
+      showHistogram: s.showHistogram,
+      status: s.status,
+    })),
+  )
   // Lengths are held in millimetres and shown in the units shown.
   const len = useLength()
   const pulse = usePulse('measure-thickness')

From ab762ba7cd6bb02a6f29b5b9eaf9f65eab971c53 Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Wed, 4 Nov 2026 22:01:35 +0000
Subject: [PATCH 21/38] perf(animate): keep the deflect buffer, compute motion
 in the worker

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 scripts/e2e-element-deviation.mjs |   5 +-
 src/App.tsx                       |   1 +
 src/app/useSceneSync.ts           |  53 ++++++---
 src/core/meshWorker.ts            |  21 ++++
 src/core/workerClient.ts          |  52 +++++++++
 src/core/workerProtocol.ts        |  19 +++
 src/viewer/SceneManager.ts        |  35 +++++-
 tests/deflection.test.ts          | 184 +++++++++++++++++++++++++++++-
 8 files changed, 347 insertions(+), 23 deletions(-)

diff --git a/scripts/e2e-element-deviation.mjs b/scripts/e2e-element-deviation.mjs
index 12b2cbda..035a908b 100644
--- a/scripts/e2e-element-deviation.mjs
+++ b/scripts/e2e-element-deviation.mjs
@@ -221,7 +221,10 @@ console.log(`animation: the underside moves ${lowest} mm (range ±${range})`)
 check(lowest !== null && lowest < 0 && lowest >= -range - 1e-6, 'the element map plays as motion, as far as the colour range')
 await click(page, '[data-test=animate-deformation]')
 await sleep(500)
-check((await deflection()) === null, 'and stopping it takes the motion off the scan')
+// The buffer the motion was laid in stays on the scan for the next play while
+// the workspace is up — stopping uploads nothing — so what shows the motion is
+// off the scan is the picture.
+check((await deflection()) !== null, 'and stopping it keeps the motion\'s buffer for the next play')
 check((await pixelDiff(page, await frame(), atRest)) < 0.01, 'and puts the part back as measured')
 
 await click(page, '[data-test=toggle-facing]')
diff --git a/src/App.tsx b/src/App.tsx
index ec79e5b0..fa24f7fe 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -1267,6 +1267,7 @@ function Workbench() {
 
   useSceneSync({
     sceneRef,
+    clientRef,
     deviation,
     deviationRgb,
     referenceMap: maps.referenceMap,
diff --git a/src/app/useSceneSync.ts b/src/app/useSceneSync.ts
index 779230ff..fab2af4f 100644
--- a/src/app/useSceneSync.ts
+++ b/src/app/useSceneSync.ts
@@ -6,7 +6,7 @@
 import { useEffect, useMemo, useRef } from 'react'
 import { creationMethod, takesSurface } from '../core/elements/construct'
 import { translationToOrigin } from '../core/alignment'
-import type { ReferenceDeviationResult } from '../core/workerClient'
+import { StaleScan, type MeshWorkerClient, type ReferenceDeviationResult } from '../core/workerClient'
 import { referenceScale } from '../core/deviation/onReference'
 import { isDeviationTarget } from '../core/deviation/elementField'
 import { isExtendable } from '../core/elements/extend'
@@ -63,6 +63,7 @@ const DEFLECTION_SETTLE_MS = 150
 
 export function useSceneSync({
   sceneRef,
+  clientRef,
   deviation,
   deviationRgb,
   referenceMap,
@@ -77,6 +78,9 @@ export function useSceneSync({
   cancelDraft,
 }: {
   sceneRef: RefObject<SceneManager | null>
+  /** The mesh worker, where the deformation animation's motion is worked
+   *  out. */
+  clientRef: RefObject<MeshWorkerClient | null>
   deviation: RefObject<Float32Array | null>
   deviationRgb: RefObject<Uint8Array | null>
   /** The map the other way round, on the reference cut finer, and its
@@ -1053,25 +1057,46 @@ export function useSceneSync({
     // over the space around each point — a pass over the whole scan, a moment
     // on a large one. So it is put off until whatever moved has come to rest:
     // a range dragged along its slider is one new motion, not one per step,
-    // and the loop plays the last one meanwhile.
+    // and the loop plays the last one meanwhile. And it is worked out in the
+    // mesh worker, over its own copy of the scan's vertices, so the pass
+    // never holds up the next tap.
+    let cancelled = false
     const timer = setTimeout(() => {
-      // The scale first, so a loop that is starting starts from the scan as
-      // it is on screen rather than wherever the old scale put it.
       const dev = useDeviation.getState()
       if (dev.animScaleAuto) dev.suggestAnimScale(suggestDeflectionScale(range, 2 * modelSize))
-      scene.setDeflectionScale(useDeviation.getState().animScale)
-      scene.setDeflection(
-        deflectionVectors(showing.values, directions, {
-          limit: range,
-          maxDistance,
-          positions: scene.scanPositions(),
-          smoothing: DEFLECTION_SMOOTHING * 2 * modelSize,
-        }),
-      )
+      const opts = { limit: range, maxDistance, smoothing: DEFLECTION_SMOOTHING * 2 * modelSize }
+      const play = (vectors: Float32Array) => {
+        if (cancelled) return
+        // The scale first, so a loop that is starting starts from the scan as
+        // it is on screen rather than wherever the old scale put it.
+        scene.setDeflectionScale(useDeviation.getState().animScale)
+        scene.setDeflection(vectors)
+      }
+      // Without the worker, or with a worker that could not answer, the
+      // motion is worked out here as it always could be.
+      const here = () => play(deflectionVectors(showing.values, directions, { ...opts, positions: scene.scanPositions() }))
+      const client = clientRef.current
+      if (!client) return here()
+      client.deflection(showing.values, directions, opts, () => scene.scanPositions()).then(play, (e) => {
+        // About a scan since moved or replaced: whatever moved it runs this
+        // again for the scan in hand.
+        if (e instanceof StaleScan || cancelled) return
+        here()
+      })
     }, DEFLECTION_SETTLE_MS)
-    return () => clearTimeout(timer)
+    return () => {
+      cancelled = true
+      clearTimeout(timer)
+    }
     // Runs on the listed dependencies only, not on everything it reads.
   }, [playing, source, mapVersion, elementVersion, range, maxDistance, modelSize])
+  // The motion's buffer stays on the scan between plays while the deviation
+  // workspace is up — stopping and starting the loop then costs no upload of
+  // the whole scan — and goes when it is left.
+  const deviationWorkspace = workspace === 'deviation'
+  useEffect(() => {
+    sceneRef.current?.setDeflectionHeld(deviationWorkspace)
+  }, [deviationWorkspace])
   useEffect(() => {
     sceneRef.current?.setDeflectionScale(animScale)
   }, [animScale])
diff --git a/src/core/meshWorker.ts b/src/core/meshWorker.ts
index 088384e6..ff237178 100644
--- a/src/core/meshWorker.ts
+++ b/src/core/meshWorker.ts
@@ -30,6 +30,7 @@ import {
 } from './deviation/align'
 import type { Steps } from './deviation/steps'
 import { computeDeviation, defaultMaxDistance, suggestRange } from './deviation/deviation'
+import { deflectionVectors } from './deviation/deflection'
 import { rigidApplyToPoints, rigidInvert, rigidRotateVectors, type Rigid } from './deviation/rigid'
 import { meshArea, meshLongEdges, readReference, sampleSpacing, subdivideForMap } from './deviation/onReference'
 import { buildSolidIndex, computeThickness, suggestThicknessScale } from './thickness/thickness'
@@ -574,6 +575,26 @@ function handle(msg: Exclude<WorkerRequest, { type: 'align-abort' }>): void {
     return
   }
 
+  if (msg.type === 'deflection') {
+    // Smoothed over the scan's vertices as held here: the render thread's
+    // own, bit for bit — the first `vertexCount` of what it was posted,
+    // moved since by the same transforms — so the motion is the one it
+    // would have worked out itself, without the pass over the whole scan
+    // landing on the thread that answers the user.
+    if (!graph) {
+      post({ type: 'error', requestId: msg.requestId, message: 'No model loaded.' })
+      return
+    }
+    const vectors = deflectionVectors(msg.values, msg.directions, {
+      limit: msg.limit,
+      maxDistance: msg.maxDistance,
+      positions: msg.positions ?? graph.positions,
+      smoothing: msg.smoothing,
+    })
+    post({ type: 'deflection-ok', requestId: msg.requestId, vectors }, [vectors.buffer])
+    return
+  }
+
   if (msg.type === 'bounds') {
     if (!graph) {
       post({ type: 'error', requestId: msg.requestId, message: 'No model loaded.' })
diff --git a/src/core/workerClient.ts b/src/core/workerClient.ts
index b42a9436..341b99f1 100644
--- a/src/core/workerClient.ts
+++ b/src/core/workerClient.ts
@@ -102,6 +102,16 @@ export interface RestoreChannel {
   call(plugin: string, op: string, payload: unknown): Promise<unknown>
 }
 
+/** An answer about the scan's vertices as they were when it was asked for,
+ *  that came back after they moved or were replaced — see deflection. Not a
+ *  failure: whoever asked asks again about the scan in hand, and drops it. */
+export class StaleScan extends Error {
+  constructor() {
+    super('The scan moved or was replaced before its answer came back.')
+    this.name = 'StaleScan'
+  }
+}
+
 /** A message that expects an answer — everything but the abort signal, which
  *  carries no id and is never replied to on its own. */
 type Request = Exclude<WorkerRequest, { type: 'align-abort' }>
@@ -129,6 +139,15 @@ export class MeshWorkerClient {
   /** Async callers must not apply a result to a different imported session. */
   scanVersion = 0
   nominalVersion = 0
+  /** Moves on whenever the worker's scan vertices do — another scan put in
+   *  place, a datum baked in — at the moment it is asked for, so an answer
+   *  about them asked before can be told from one asked after. */
+  private scanToken = 0
+  /** Whether the worker's scan vertices are the render thread's bit for bit:
+   *  they are while the render arrays in use came from the worker and both
+   *  have been moved by the same transforms since. A restart reads the scan
+   *  back in under its whole alignment at once, which rounds differently. */
+  private renderParity = true
   onProgress: ((text: string, fraction?: number) => void) | null = null
   /** Poses from part-way through an alignment. Not a request result — they
    *  arrive while the request is still open, so they must not settle it. */
@@ -151,6 +170,7 @@ export class MeshWorkerClient {
       this.rpc.restart()
       const state = this.restoreState?.()
       if (state?.scan) {
+        this.renderParity = false
         const { name, bytes, crease, transform, units } = state.scan
         const buffer = bytes.slice().buffer
         await this.rpc.request({ type: 'load', requestId: this.nextId++, name, buffer, crease, transform: transform ?? undefined, scale: mmPerUnit(units ?? 'mm') } as Request, [buffer]) // units-ok: the file's own units, an id
@@ -204,6 +224,11 @@ export class MeshWorkerClient {
   }
 
   async commitImport(slots: { scan?: number | null; nominal?: number | null }): Promise<void> {
+    if (slots.scan !== undefined) {
+      // The render thread lays out the arrays this scan was posted with.
+      this.scanToken++
+      this.renderParity = true
+    }
     await this.request({ type: 'commit-import', requestId: this.nextId++, ...slots })
     if (slots.scan !== undefined) this.scanVersion++
     if (slots.nominal !== undefined) this.nominalVersion++
@@ -403,6 +428,7 @@ export class MeshWorkerClient {
 
   /** Bake a datum alignment into the worker's copy of the scan. */
   async transform(transform: Rigid): Promise<void> {
+    this.scanToken++
     const requestId = this.nextId++
     await this.request({ type: 'transform', requestId, transform })
   }
@@ -502,6 +528,32 @@ export class MeshWorkerClient {
     return res.closed
   }
 
+  /** How far each scan vertex moves to play a map as motion — see
+   *  deviation/deflection.ts deflectionVectors — worked out in the worker,
+   *  over its own copy of the scan's vertices. Where that copy may not be
+   *  the viewport's bit for bit (see renderParity), `positions` is asked
+   *  for and a copy of it goes with the request instead. The map is copied,
+   *  not transferred: the caller keeps showing it. An answer about vertices
+   *  since moved or replaced rejects with StaleScan. */
+  async deflection(
+    values: Float32Array,
+    directions: Int8Array,
+    opts: { limit: number; maxDistance: number; smoothing: number },
+    positions?: () => Float32Array | null,
+  ): Promise<Float32Array> {
+    // A restart this request would wait on reads the scan back in first.
+    await this.ready()
+    const asked = this.scanToken
+    const own = this.renderParity ? null : (positions?.()?.slice() ?? null)
+    const requestId = this.nextId++
+    const res = await this.request<Extract<WorkerResponse, { type: 'deflection-ok' }>>(
+      { type: 'deflection', requestId, values, directions, ...opts, ...(own ? { positions: own } : {}) },
+      own ? [own.buffer] : [],
+    )
+    if (this.scanToken !== asked) throw new StaleScan()
+    return res.vectors
+  }
+
   /** The box around the scan as it now stands, mm. */
   async bounds(): Promise<{ min: Vec3; max: Vec3 }> {
     const requestId = this.nextId++
diff --git a/src/core/workerProtocol.ts b/src/core/workerProtocol.ts
index 92b6b293..5d39e991 100644
--- a/src/core/workerProtocol.ts
+++ b/src/core/workerProtocol.ts
@@ -208,6 +208,23 @@ export type WorkerRequest =
    *  triangles in an order of its own, and so does the reference's here,
    *  but neither moves a vertex. */
   | { type: 'closed-shells'; requestId: number; which: 'scan' | 'nominal' }
+  /** A map played as motion: how far each scan vertex moves — see
+   *  deviation/deflection.ts deflectionVectors — smoothed over the scan's
+   *  vertices as held here, which are the render thread's own bit for bit
+   *  (loaded from here, moved by the same datum transforms in the same
+   *  order). `positions` is sent only where that may not hold — a worker
+   *  restarted and the scan read back in under its alignment in one step —
+   *  and is the render thread's copy, smoothed over instead. */
+  | {
+      type: 'deflection'
+      requestId: number
+      values: Float32Array
+      directions: Int8Array
+      limit: number
+      maxDistance: number
+      smoothing: number
+      positions?: Float32Array
+    }
   /** A request for a plugin's part of the worker — see workerPluginApi.ts.
    *  `op` names the plugin's operation, `payload` is its own. */
   | { type: 'plugin'; requestId: number; plugin: string; op: string; payload: unknown }
@@ -334,6 +351,8 @@ export type WorkerResponse =
   | { type: 'scan-rim-ok'; requestId: number; rim: { vertices: Uint32Array; positions: Float32Array; corners: Uint32Array; closed: boolean; length: number; circle?: RimCircle } | null }
   /** 1 for each render vertex of a closed shell. */
   | { type: 'closed-shells-ok'; requestId: number; closed: Uint8Array }
+  /** Three floats per scan vertex, the offset to draw it moved by. */
+  | { type: 'deflection-ok'; requestId: number; vectors: Float32Array }
   /** A plugin's answer. */
   | { type: 'plugin-ok'; requestId: number; result: unknown }
   | { type: 'error'; requestId: number; message: string }
diff --git a/src/viewer/SceneManager.ts b/src/viewer/SceneManager.ts
index f2674d35..686f195f 100644
--- a/src/viewer/SceneManager.ts
+++ b/src/viewer/SceneManager.ts
@@ -451,6 +451,9 @@ export class SceneManager {
   /** When the loop began, in performance.now() time. */
   private deflectStart = 0
   private uDeflect: DeflectionUniform = { value: 0 }
+  /** Whether the offsets' buffer stays on the scan at rest — see
+   *  setDeflectionHeld. */
+  private deflectHeld = false
   /** See-through surfaces, so what is inside the part — the reference, the
    *  fitted elements, the pinned readings — shows: the scan's and the
    *  reference's, each from its own key. Held here as well as on the
@@ -1173,7 +1176,10 @@ export class SceneManager {
     )
     this.regions.rebind(colors, paint, tint, this.scanVertices)
     // The offsets are the scan's own, laid out again over the new copies.
-    this.layOutDeflection()
+    // A buffer kept at rest is the old layout's, and the geometry was just
+    // disposed: it goes, and the next play lays a new one.
+    if (this.deflection?.geometry === geometry) this.layOutDeflection()
+    else geometry.deleteAttribute('deflect')
     geometry.computeBoundsTree()
     // A cap over the closed shells alone is cut from the old triangles.
     this.applySlice()
@@ -3013,8 +3019,10 @@ export class SceneManager {
     const geometry = this.mesh.geometry as THREE.BufferGeometry
     this.marking.meshDisposed()
     // Keyed by vertex number, like the colouring: whoever moves this scan
-    // lays them on again.
+    // lays them on again, over its own count of vertices — the buffer kept
+    // between plays goes too.
     this.dropDeflection()
+    this.releaseDeflect(geometry)
     for (const layer of this.layers) layer.scanReplaced?.()
     geometry.disposeBoundsTree?.()
     geometry.dispose()
@@ -3149,20 +3157,37 @@ export class SceneManager {
     attr.needsUpdate = true
   }
 
-  /** Back at rest, with the offsets taken off the geometry they were laid on. */
+  /** Back at rest. While held (see setDeflectionHeld) the offsets' buffer
+   *  stays on the geometry, drawn with nothing added: letting it go means
+   *  disposing the geometry and sending the whole scan to the GPU again, and
+   *  while the map is up the loop is stopped and started again often. Not
+   *  held, it is taken off the geometry it was laid on. */
   private dropDeflection(): void {
     const d = this.deflection
     this.deflection = null
     this.uDeflect.value = 0
     if (this.mesh) this.mesh.frustumCulled = true
-    if (d) this.releaseDeflect(d.geometry)
+    if (d && !this.deflectHeld) this.releaseDeflect(d.geometry)
+  }
+
+  /** Keep the offsets' buffer on the scan between plays — while the
+   *  deviation workspace is on screen — or stop keeping it. Let go, it is
+   *  released at once from the scan and from an edited copy waiting beside
+   *  it, whichever it was laid on, but for a loop still playing, which lets
+   *  its own go when it stops. */
+  setDeflectionHeld(held: boolean): void {
+    this.deflectHeld = held
+    if (held) return
+    for (const geometry of [this.mesh?.geometry, this.other?.geometry]) {
+      if (geometry && geometry !== this.deflection?.geometry) this.releaseDeflect(geometry as THREE.BufferGeometry)
+    }
   }
 
   /** Take the offsets' attribute off a geometry, GPU buffer and all. three.js
    *  lets an attribute's buffer go only when its geometry is disposed, so it
    *  is: the rest of the scan is uploaded again on the next frame it is
    *  drawn — once, the price of not keeping a buffer the size of the
-   *  positions for a loop nobody is playing. */
+   *  positions once the map is put away. */
   private releaseDeflect(geometry: THREE.BufferGeometry): void {
     if (!geometry.getAttribute('deflect')) return
     geometry.dispose()
diff --git a/tests/deflection.test.ts b/tests/deflection.test.ts
index b666c968..1b280e6a 100644
--- a/tests/deflection.test.ts
+++ b/tests/deflection.test.ts
@@ -5,7 +5,8 @@
 // pose the scan was fitted in — because the animation takes that offset away
 // to draw the ideal shape and multiplies it to draw the exaggerated one. A
 // direction off by its sign would play the whole part inside out.
-import { describe, expect, it } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { buildMeshGraph } from '../src/core/geometry/buildGraph'
 import { NominalSurface, emptyHit } from '../src/core/deviation/surface'
 import { computeDeviation } from '../src/core/deviation/deviation'
@@ -18,9 +19,12 @@ import {
   suggestDeflectionScale,
   writeDirection,
 } from '../src/core/deviation/deflection'
-import { rigidApply, rigidFromAxisAngle, rigidInvert } from '../src/core/deviation/rigid'
+import { rigidApply, rigidApplyToPoints, rigidFromAxisAngle, rigidInvert } from '../src/core/deviation/rigid'
 import type { PlaneFit, Vec3 } from '../src/core/types'
-import { boxMesh } from './helpers'
+import type { WorkerRequest, WorkerResponse } from '../src/core/workerProtocol'
+import { MeshWorkerClient, StaleScan } from '../src/core/workerClient'
+import { boxMesh, cylinderMesh } from './helpers'
+import { fixture } from './fixtures'
 
 /** Reading times direction, decoded the way the shader decodes it. */
 function offsetOf(values: Float32Array, directions: Int8Array, v: number): Vec3 {
@@ -285,3 +289,177 @@ describe('the loop', () => {
     expect(deflectionFactor(deflectionStartPhase(0.5), 0.5)).toBeCloseTo(0.5, 12)
   })
 })
+
+/** A soup of triangles as a binary STL, the way a scan reaches the worker. */
+function stl(soup: Float32Array): ArrayBuffer {
+  const triangles = soup.length / 9
+  const buffer = new ArrayBuffer(84 + triangles * 50)
+  const view = new DataView(buffer)
+  view.setUint32(80, triangles, true)
+  for (let t = 0; t < triangles; t++) {
+    const at = 84 + t * 50 + 12
+    for (let k = 0; k < 9; k++) view.setFloat32(at + k * 4, soup[t * 9 + k], true)
+  }
+  return buffer
+}
+
+/** The bits of a float array, for comparing two of them exactly — a
+ *  negative zero and all. */
+const bits = (a: Float32Array) => new Uint32Array(a.buffer, a.byteOffset, a.length)
+
+/** A deviation map with every kind of reading in it: in range, past the end
+ *  of the colour scale, past the search distance, and none at all. */
+function someMap(n: number): { values: Float32Array; directions: Int8Array } {
+  let seed = 7
+  const rand = () => (seed = (Math.imul(seed, 1103515245) + 12345) >>> 0) / 2 ** 32
+  const values = new Float32Array(n)
+  const directions = new Int8Array(n * 3)
+  for (let v = 0; v < n; v++) {
+    const r = rand()
+    values[v] = r < 0.05 ? NaN : r < 0.1 ? 9 : (rand() - 0.5) * 0.6
+    for (let k = 0; k < 3; k++) directions[v * 3 + k] = Math.round((rand() - 0.5) * 254)
+  }
+  return { values, directions }
+}
+
+const ballbar = fixture('ballbar.stl')
+/** The scans the motion is checked on: a noisy cylinder whose rims split
+ *  for shading, and the ball bar where it is on hand. */
+const scans: [string, () => ArrayBuffer][] = [
+  ['a noisy cylinder, its rims split', () => stl(cylinderMesh(10, 30, 48, 12, 0.02).positions)],
+]
+if (ballbar.exists) {
+  scans.push(['the ball bar', () => {
+    const b = readFileSync(ballbar.path)
+    return b.buffer.slice(b.byteOffset, b.byteOffset + b.byteLength)
+  }])
+}
+
+describe('the motion worked out in the worker', () => {
+  let scope: { onmessage: ((event: { data: WorkerRequest }) => void) | null; postMessage: (msg: WorkerResponse) => void }
+  let replies: WorkerResponse[]
+  beforeEach(async () => {
+    replies = []
+    scope = { onmessage: null, postMessage: (msg) => replies.push(msg) }
+    vi.stubGlobal('self', scope)
+    vi.resetModules()
+    await import('../src/core/meshWorker')
+  })
+  afterEach(() => vi.unstubAllGlobals())
+  const send = (msg: WorkerRequest) => {
+    replies.length = 0
+    scope.onmessage!({ data: msg })
+    return replies.at(-1)!
+  }
+
+  /** Load a scan with its sharp edges split, as the app does, and bake a
+   *  datum alignment into it on both sides, as partAlignment does: the
+   *  render thread's positions, as the viewport would hold them. */
+  const loadAndMove = (buffer: ArrayBuffer) => {
+    const loaded = send({ type: 'load', requestId: 1, name: 'scan.stl', buffer, crease: { mode: 'on', angleDeg: 30 } })
+    if (loaded.type !== 'loaded') throw new Error(JSON.stringify(loaded))
+    expect(loaded.copyOf.length).toBeGreaterThan(0)
+    const datum = rigidFromAxisAngle([0.3, -0.5, 0.8], 0.7)
+    datum.t[0] = 12.5
+    datum.t[1] = -3.25
+    datum.t[2] = 101
+    rigidApplyToPoints(datum, loaded.positions)
+    expect(send({ type: 'transform', requestId: 2, transform: datum }).type).toBe('transform-ok')
+    return { render: loaded.positions.subarray(0, loaded.vertexCount * 3), vertexCount: loaded.vertexCount }
+  }
+
+  for (const [name, file] of scans) {
+    it(`holds the scan's vertices bit for bit as the viewport does: ${name}`, () => {
+      const { render, vertexCount } = loadAndMove(file())
+      const all = send({ type: 'query', requestId: 3, min: [-1e9, -1e9, -1e9], max: [1e9, 1e9, 1e9], limit: vertexCount })
+      if (all.type !== 'query-ok') throw new Error(JSON.stringify(all))
+      expect(all.vertices.length).toBe(vertexCount)
+      expect(all.vertices.every((v, i) => v === i)).toBe(true)
+      expect(bits(all.positions)).toEqual(bits(render))
+    })
+
+    it(`moves the scan exactly as the render thread would: ${name}`, () => {
+      const { render, vertexCount } = loadAndMove(file())
+      const { values, directions } = someMap(vertexCount)
+      const options = { limit: 0.2, maxDistance: 5, smoothing: 1.5 }
+      const here = deflectionVectors(values, directions, { ...options, positions: render })
+      const there = send({ type: 'deflection', requestId: 3, values, directions, ...options })
+      if (there.type !== 'deflection-ok') throw new Error(JSON.stringify(there))
+      expect(there.vectors.length).toBe(vertexCount * 3)
+      expect(bits(there.vectors)).toEqual(bits(here))
+      // And over positions sent with the request, where those are not the
+      // worker's own.
+      const shifted = render.map((x) => x + 0.375)
+      const sent = send({ type: 'deflection', requestId: 4, values, directions, ...options, positions: shifted })
+      if (sent.type !== 'deflection-ok') throw new Error(JSON.stringify(sent))
+      expect(bits(sent.vectors)).toEqual(bits(deflectionVectors(values, directions, { ...options, positions: shifted })))
+    })
+  }
+})
+
+describe('the motion asked of the worker', () => {
+  /** A client without its worker: the requests it would post, kept, each
+   *  answered when the test says. */
+  function clientOf() {
+    const sent: Record<string, unknown>[] = []
+    const answers: (() => void)[] = []
+    const client = Object.create(MeshWorkerClient.prototype) as MeshWorkerClient
+    Object.assign(client, {
+      nextId: 1,
+      scanVersion: 0,
+      nominalVersion: 0,
+      scanToken: 0,
+      renderParity: true,
+      ready: () => Promise.resolve(),
+      request: (msg: Record<string, unknown>) => {
+        sent.push(msg)
+        return new Promise((resolve) => answers.push(() => resolve({ vectors: new Float32Array(3) })))
+      },
+    })
+    const settle = async () => {
+      await new Promise((r) => setTimeout(r, 0))
+      for (const answer of answers.splice(0)) answer()
+      await new Promise((r) => setTimeout(r, 0))
+    }
+    return { client, sent, settle }
+  }
+  const values = Float32Array.of(0.1)
+  const directions = Int8Array.of(0, 0, 127)
+  const options = { limit: 1, maxDistance: 2, smoothing: 0.5 }
+
+  it('turns away an answer about a scan since moved or replaced', async () => {
+    const { client, settle } = clientOf()
+    const moved = client.deflection(values, directions, options)
+    const movedSettled = expect(moved).rejects.toBeInstanceOf(StaleScan)
+    await new Promise((r) => setTimeout(r, 0))
+    void client.transform(rigidFromAxisAngle([0, 0, 1], 0.5))
+    await settle()
+    await movedSettled
+
+    const replaced = client.deflection(values, directions, options)
+    const replacedSettled = expect(replaced).rejects.toBeInstanceOf(StaleScan)
+    await new Promise((r) => setTimeout(r, 0))
+    void client.commitImport({ scan: 7 })
+    await settle()
+    await replacedSettled
+
+    const kept = client.deflection(values, directions, options)
+    await settle()
+    await expect(kept).resolves.toHaveLength(3)
+  })
+
+  it("sends the viewport's positions only when the worker's may not match them", async () => {
+    const { client, sent, settle } = clientOf()
+    const render = Float32Array.of(1, 2, 3)
+    const a = client.deflection(values, directions, options, () => render)
+    await settle()
+    await a
+    ;(client as unknown as { renderParity: boolean }).renderParity = false
+    const b = client.deflection(values, directions, options, () => render)
+    await settle()
+    await b
+    expect(sent[0].positions).toBeUndefined()
+    expect([...(sent[1].positions as Float32Array)]).toEqual([1, 2, 3])
+    expect(sent[1].positions).not.toBe(render)
+  })
+})

From 4ba7212161b464fe12d83454fa071cddd1a44286 Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Wed, 4 Nov 2026 22:31:19 +0000
Subject: [PATCH 22/38] perf(animate): retry a stale motion once, parity after
 the commit lands

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 scripts/e2e-element-deviation.mjs |  5 ++++
 src/app/useSceneSync.ts           | 41 +++++++++++++++++++++++++------
 src/core/workerClient.ts          | 10 +++++---
 tests/deflection.test.ts          | 27 ++++++++++----------
 4 files changed, 57 insertions(+), 26 deletions(-)

diff --git a/scripts/e2e-element-deviation.mjs b/scripts/e2e-element-deviation.mjs
index 035a908b..ebfd79f1 100644
--- a/scripts/e2e-element-deviation.mjs
+++ b/scripts/e2e-element-deviation.mjs
@@ -333,8 +333,13 @@ await page.screenshot({ path: shotPath('element-deviation-back.png') })
 // Extending it in the other workspace must grow the measured region, and
 // deleting it must take the map with it rather than leaving a scale over
 // nothing.
+// The motion's buffer, kept on the scan while the deviation workspace is up,
+// goes with it.
+const keptInDeviation = (await deflection()) !== null
 await click(page, '[data-test=workspace-elements]')
 await page.waitForSelector('[data-test=fit-plane]')
+await sleep(200)
+check(keptInDeviation && (await deflection()) === null, 'leaving the workspace releases the motion\'s buffer')
 const measuredBefore = 190
 await click(page, '[data-test=element-row] [data-test=edit-element]')
 await page.waitForSelector('[data-test=extend-uMin]')
diff --git a/src/app/useSceneSync.ts b/src/app/useSceneSync.ts
index fab2af4f..d15403af 100644
--- a/src/app/useSceneSync.ts
+++ b/src/app/useSceneSync.ts
@@ -1073,16 +1073,41 @@ export function useSceneSync({
         scene.setDeflection(vectors)
       }
       // Without the worker, or with a worker that could not answer, the
-      // motion is worked out here as it always could be.
-      const here = () => play(deflectionVectors(showing.values, directions, { ...opts, positions: scene.scanPositions() }))
+      // motion is worked out here as it always could be. A map that cannot
+      // be played leaves the scan at rest rather than an error unhandled.
+      const here = () => {
+        try {
+          play(deflectionVectors(showing.values, directions, { ...opts, positions: scene.scanPositions() }))
+        } catch (e) {
+          console.warn('The deformation animation could not be worked out.', e)
+        }
+      }
       const client = clientRef.current
       if (!client) return here()
-      client.deflection(showing.values, directions, opts, () => scene.scanPositions()).then(play, (e) => {
-        // About a scan since moved or replaced: whatever moved it runs this
-        // again for the scan in hand.
-        if (e instanceof StaleScan || cancelled) return
-        here()
-      })
+      const ask = (retry: boolean) => {
+        const version = client.scanVersion
+        client.deflection(showing.values, directions, opts, () => scene.scanPositions()).then(
+          // A retry's answer is played only for the scan it was asked
+          // about: one put in its place since leaves the map to whoever
+          // measures it again.
+          (vectors) => {
+            if (!retry || client.scanVersion === version) play(vectors)
+          },
+          (e) => {
+            if (cancelled) return
+            // About a scan moved or replaced while it was worked out. What
+            // moved it does not always run this again — a datum baked in
+            // with the map left as it is, a replacement that failed — so it
+            // is asked once more, of the scan as it is now.
+            if (e instanceof StaleScan) {
+              if (!retry) ask(true)
+              return
+            }
+            here()
+          },
+        )
+      }
+      ask(false)
     }, DEFLECTION_SETTLE_MS)
     return () => {
       cancelled = true
diff --git a/src/core/workerClient.ts b/src/core/workerClient.ts
index 341b99f1..0e8893ce 100644
--- a/src/core/workerClient.ts
+++ b/src/core/workerClient.ts
@@ -224,13 +224,15 @@ export class MeshWorkerClient {
   }
 
   async commitImport(slots: { scan?: number | null; nominal?: number | null }): Promise<void> {
+    // Before the commit is sent, so an answer asked ahead of it is told from
+    // one asked behind it.
+    if (slots.scan !== undefined) this.scanToken++
+    await this.request({ type: 'commit-import', requestId: this.nextId++, ...slots })
     if (slots.scan !== undefined) {
-      // The render thread lays out the arrays this scan was posted with.
-      this.scanToken++
+      this.scanVersion++
+      // In place: the render thread lays out the arrays it was posted with.
       this.renderParity = true
     }
-    await this.request({ type: 'commit-import', requestId: this.nextId++, ...slots })
-    if (slots.scan !== undefined) this.scanVersion++
     if (slots.nominal !== undefined) this.nominalVersion++
   }
 
diff --git a/tests/deflection.test.ts b/tests/deflection.test.ts
index 1b280e6a..48b2796d 100644
--- a/tests/deflection.test.ts
+++ b/tests/deflection.test.ts
@@ -25,6 +25,7 @@ import type { WorkerRequest, WorkerResponse } from '../src/core/workerProtocol'
 import { MeshWorkerClient, StaleScan } from '../src/core/workerClient'
 import { boxMesh, cylinderMesh } from './helpers'
 import { fixture } from './fixtures'
+import { buildBinaryStl } from '../src/core/exportStl'
 
 /** Reading times direction, decoded the way the shader decodes it. */
 function offsetOf(values: Float32Array, directions: Int8Array, v: number): Vec3 {
@@ -290,19 +291,6 @@ describe('the loop', () => {
   })
 })
 
-/** A soup of triangles as a binary STL, the way a scan reaches the worker. */
-function stl(soup: Float32Array): ArrayBuffer {
-  const triangles = soup.length / 9
-  const buffer = new ArrayBuffer(84 + triangles * 50)
-  const view = new DataView(buffer)
-  view.setUint32(80, triangles, true)
-  for (let t = 0; t < triangles; t++) {
-    const at = 84 + t * 50 + 12
-    for (let k = 0; k < 9; k++) view.setFloat32(at + k * 4, soup[t * 9 + k], true)
-  }
-  return buffer
-}
-
 /** The bits of a float array, for comparing two of them exactly — a
  *  negative zero and all. */
 const bits = (a: Float32Array) => new Uint32Array(a.buffer, a.byteOffset, a.length)
@@ -326,7 +314,8 @@ const ballbar = fixture('ballbar.stl')
 /** The scans the motion is checked on: a noisy cylinder whose rims split
  *  for shading, and the ball bar where it is on hand. */
 const scans: [string, () => ArrayBuffer][] = [
-  ['a noisy cylinder, its rims split', () => stl(cylinderMesh(10, 30, 48, 12, 0.02).positions)],
+  // A soup of triangles as a binary STL, the way a scan reaches the worker.
+  ['a noisy cylinder, its rims split', () => buildBinaryStl(cylinderMesh(10, 30, 48, 12, 0.02).positions, null, null, '')],
 ]
 if (ballbar.exists) {
   scans.push(['the ball bar', () => {
@@ -461,5 +450,15 @@ describe('the motion asked of the worker', () => {
     expect(sent[0].positions).toBeUndefined()
     expect([...(sent[1].positions as Float32Array)]).toEqual([1, 2, 3])
     expect(sent[1].positions).not.toBe(render)
+    // A scan put in place is laid out from the worker's own arrays again —
+    // once the commit has landed.
+    const committed = client.commitImport({ scan: 7 })
+    await settle()
+    await committed
+    const c = client.deflection(values, directions, options, () => render)
+    await settle()
+    await c
+    expect(sent.at(-1)!.type).toBe('deflection')
+    expect(sent.at(-1)!.positions).toBeUndefined()
   })
 })

From 2810af8cd48559c8b554581c8a9253fa76951d9f Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Wed, 4 Nov 2026 23:06:10 +0000
Subject: [PATCH 23/38] perf(element-map): measure against an element in the
 worker

The element map was a pass over every scan vertex on the main thread, a long
task on a phone that the next tap waited behind. It now goes to the mesh
worker as the motion did: a request keyed on the scan token (StaleScan on a
scan moved or replaced, one retry, then the main thread), the render thread's
normals always sent as they are not the ones its sharp edges were shaded
with, its positions only where the worker's may not match. Requests coalesce
to the newest, a stale reply is dropped, and the status can never be left at
running. The panel, view bar and hover keep the map in hand while it is
re-measured so a dragged slider is not unmounted.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 src/App.tsx                      |   8 +-
 src/app/useElementField.ts       | 152 +++++++++++---
 src/app/useSceneSync.ts          |   6 +-
 src/commands/core/deviation.ts   |   8 +-
 src/core/meshWorker.ts           |  34 ++++
 src/core/workerClient.ts         |  32 +++
 src/core/workerProtocol.ts       |  25 +++
 src/state/deviationStore.ts      |  26 ++-
 src/ui/DeviationPanel.tsx        |   5 +-
 src/ui/ViewBar.tsx               |   6 +-
 tests/elementFieldWorker.test.ts | 339 +++++++++++++++++++++++++++++++
 11 files changed, 597 insertions(+), 44 deletions(-)
 create mode 100644 tests/elementFieldWorker.test.ts

diff --git a/src/App.tsx b/src/App.tsx
index fa24f7fe..eef8de67 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -76,7 +76,7 @@ import { CompareView } from './ui/CompareView'
 import { formatSigned } from './ui/format'
 import { HoverReadout, type HoverReading } from './ui/HoverReadout'
 import { SplitPicker } from './ui/SplitPicker'
-import { MARK_COLOR, useDeviation } from './state/deviationStore'
+import { MARK_COLOR, mapHeld, useDeviation } from './state/deviationStore'
 import { usePrefs } from './state/prefsStore'
 import { boundLength, useLength } from './app/useUnits'
 import { lengthInputText, unitWord, type DisplayUnits } from './core/units'
@@ -625,7 +625,7 @@ function Workbench() {
 
   // ---- Deviation from a fitted element -------------------------------------
 
-  useElementField({ sceneRef, elementField, elementRgb, elementScope, fieldDirections })
+  useElementField({ sceneRef, clientRef, elementField, elementRgb, elementScope, fieldDirections })
 
 
   /** Switch the element map between measuring the whole scan and measuring a
@@ -1444,9 +1444,7 @@ function Workbench() {
   const targetId = useDeviation((s) => s.targetId)
   // Whichever map this workspace is reading — the legend, the hover readout and
   // the pins all follow the source rather than whichever was measured last.
-  const mapReady = useDeviation((s) =>
-    s.source === 'element' ? s.elementStatus === 'ready' : s.mapStatus === 'ready',
-  )
+  const mapReady = useDeviation(mapHeld)
   const showHistogram = useDeviation((s) => s.showHistogram)
   const stats = useDeviation((s) => s.stats)
   const histogram = useDeviation((s) => s.histogram)
diff --git a/src/app/useElementField.ts b/src/app/useElementField.ts
index 706267e5..a001e387 100644
--- a/src/app/useElementField.ts
+++ b/src/app/useElementField.ts
@@ -2,13 +2,16 @@
 // The element deviation map: kept in step with the element it is measured
 // against, so there is no "measure" button to press.
 //
-// The reference map goes to the worker because a signed closest point against a
-// whole nominal part is a BVH descent per vertex. An element is a plane, a
-// cylinder or a sphere — a handful of flops per vertex, a few milliseconds over
-// a large scan — so it is computed here on the main thread and simply recomputed
-// whenever anything it depends on moves. That is what lets the grips resize the
-// measured region and the facing limit tighten it with the map following along,
-// instead of a round trip and a progress bar for each.
+// Both maps go to the mesh worker, which is where a pass over the whole scan
+// belongs: the reference map because a signed closest point against a whole
+// nominal part is a BVH descent per vertex, this one because even a handful of
+// flops per vertex is tens of milliseconds over a large scan on a phone — a
+// task the next tap waits behind. It is recomputed whenever anything it depends
+// on moves, which is what lets the grips resize the measured region and the
+// facing limit tighten it with the map following along, instead of a button to
+// press. The map in hand stays on screen until the new one lands, and the
+// requests coalesce: one is worked out at a time, and of those that arrive
+// meanwhile only the newest is asked.
 
 import { useEffect, useMemo, useRef } from 'react'
 import type { RefObject } from 'react'
@@ -19,6 +22,7 @@ import {
   type ElementTarget,
 } from '../core/deviation/elementField'
 import { suggestRange } from '../core/deviation/deviation'
+import { StaleScan, type MeshWorkerClient } from '../core/workerClient'
 import { useDeviation } from '../state/deviationStore'
 import { useHistory } from '../state/historyStore'
 import { useStore, type Element } from '../state/store'
@@ -43,6 +47,79 @@ function scanArrays(
   }
 }
 
+/** What measuring the map comes to: the readings, the direction each was taken
+ *  along, and the colour scale the tool would choose for them. */
+export interface ElementMapResult {
+  values: Float32Array
+  directions: Int8Array
+  suggestedRange: number
+}
+
+/** Measure the map once and say what became of it: `settle` with the map, or
+ *  `fail` — never neither, so the status is never left saying "running" for a
+ *  map nobody is working on. Nothing is said at all for a question that has
+ *  moved on (`current` no longer true), because whatever moved it has the
+ *  status now. `ask` is the worker; where there is none, or it cannot answer,
+ *  `here` measures it on this thread as it always could. A scan that moved
+ *  while the worker answered is asked about once more, as it now is. */
+export async function runElementMap({
+  ask,
+  here,
+  current,
+  settle,
+  fail,
+}: {
+  ask: (() => Promise<ElementMapResult>) | null
+  here: () => ElementMapResult | null
+  current: () => boolean
+  settle: (result: ElementMapResult) => void
+  fail: () => void
+}): Promise<void> {
+  if (!current()) return
+  let result: ElementMapResult | null = null
+  for (let attempt = 0; ask && attempt < 2 && !result; attempt++) {
+    try {
+      result = await ask()
+    } catch (e) {
+      if (!current()) return
+      if (!(e instanceof StaleScan)) break
+    }
+  }
+  if (!current()) return
+  if (!result) {
+    try {
+      result = here()
+    } catch (e) {
+      console.warn('The map against the element could not be measured.', e)
+    }
+  }
+  if (result) settle(result)
+  else fail()
+}
+
+/** One job at a time, and of those that arrive while one is running only the
+ *  newest kept — a facing limit dragged along its slider asks for a map per
+ *  step, and the ones in between are answers to questions already out of date.
+ *  A job that throws does not stop the next. */
+export function latestWins(): (job: () => Promise<void>) => void {
+  let busy = false
+  let waiting: (() => Promise<void>) | null = null
+  const start = (job: () => Promise<void>): void => {
+    busy = true
+    const next = (): void => {
+      busy = false
+      const after = waiting
+      waiting = null
+      if (after) start(after)
+    }
+    job().then(next, next)
+  }
+  return (job) => {
+    if (busy) waiting = job
+    else start(job)
+  }
+}
+
 /** The element the deviation is measured against, as drawn: the extension is
  *  part of the question, because it is what bounds the measured region. */
 export function targetFitOf(elements: Element[], targetId: number | null): ElementTarget | null {
@@ -55,12 +132,15 @@ export function targetFitOf(elements: Element[], targetId: number | null): Eleme
 
 export function useElementField({
   sceneRef,
+  clientRef,
   elementField,
   elementRgb,
   elementScope,
   fieldDirections,
 }: {
   sceneRef: RefObject<SceneManager | null>
+  /** The mesh worker, where the map is measured. */
+  clientRef: RefObject<MeshWorkerClient | null>
   elementField: RefObject<Float32Array | null>
   elementRgb: RefObject<Uint8Array | null>
   /** The hand-marked scan region the map is restricted to, when the scope says
@@ -80,6 +160,8 @@ export function useElementField({
   const revision = useHistory((s) => s.revision)
   const seenRevision = useRef(revision)
   const previousInputs = useRef<unknown[] | null>(null)
+  const queue = useRef<ReturnType<typeof latestWins> | null>(null)
+  if (!queue.current) queue.current = latestWins()
 
   // Held stable across renders: applyExtension builds a fresh object every call,
   // so depending on it directly would recompute the field on every render.
@@ -115,23 +197,47 @@ export function useElementField({
       return
     }
     const scan = scanArrays(sceneRef.current)
-    if (!scan) return
+    if (!scan) {
+      // Whatever was being measured is not wanted any more and nothing is
+      // taking its place: it must not leave the status waiting for it.
+      if (useDeviation.getState().elementStatus === 'running') useDeviation.getState().failElementMap()
+      return
+    }
 
-    const directions = new Int8Array(scan.positions.length)
-    const values = computeElementDeviation(target, scan.positions, scan.normals, {
-      side: targetSide,
-      maxNormalDeviation: targetFacingDeg === null ? null : (targetFacingDeg * Math.PI) / 180,
-      // A marked scope with nothing marked yet is an empty map, not the whole
-      // scan: the hint in the panel says to mark, and the map follows the brush.
-      subset: targetScope === 'marked' ? (elementScope.current ?? new Uint32Array(0)) : null,
-      directions,
-    })
-    elementField.current = values
-    fieldDirections.set(values, directions)
-    elementRgb.current = null
-    useDeviation.getState().resolveElementMap(
-      suggestRange(values, useDeviation.getState().maxDistance),
-      restoring,
+    // Everything the map is a function of is taken now, at the change: the
+    // answer is painted only if `inputs` is still what is wanted when it lands,
+    // and `restoring` is the history's word about this change, not a later one.
+    const side = targetSide
+    const maxNormalDeviation = targetFacingDeg === null ? null : (targetFacingDeg * Math.PI) / 180
+    // A marked scope with nothing marked yet is an empty map, not the whole
+    // scan: the hint in the panel says to mark, and the map follows the brush.
+    const subset = targetScope === 'marked' ? (elementScope.current ?? new Uint32Array(0)) : null
+    const maxDistance = useDeviation.getState().maxDistance
+    useDeviation.getState().beginElementMap()
+    queue.current!(() =>
+      runElementMap({
+        ask: clientRef.current
+          ? () => clientRef.current!.elementDeviation(target, { side, maxNormalDeviation, subset, maxDistance }, () => scanArrays(sceneRef.current))
+          : null,
+        here: () => {
+          const now = scanArrays(sceneRef.current)
+          if (!now) return null
+          const directions = new Int8Array(now.positions.length)
+          const values = computeElementDeviation(target, now.positions, now.normals, { side, maxNormalDeviation, subset, directions })
+          return { values, directions, suggestedRange: suggestRange(values, useDeviation.getState().maxDistance) }
+        },
+        current: () => previousInputs.current === inputs,
+        settle: ({ values, directions, suggestedRange }) => {
+          elementField.current = values
+          fieldDirections.set(values, directions)
+          elementRgb.current = null
+          // The scale is suggested within the search distance, which may have
+          // been dragged while the worker measured.
+          const held = useDeviation.getState()
+          held.resolveElementMap(held.maxDistance === maxDistance ? suggestedRange : suggestRange(values, held.maxDistance), restoring)
+        },
+        fail: () => useDeviation.getState().failElementMap(),
+      }),
     )
     // Runs on the listed dependencies only, not on everything it reads.
   }, [target, targetId, targetSide, targetFacingDeg, targetScope, scopeVersion, revision])
diff --git a/src/app/useSceneSync.ts b/src/app/useSceneSync.ts
index d15403af..6fd6f609 100644
--- a/src/app/useSceneSync.ts
+++ b/src/app/useSceneSync.ts
@@ -39,7 +39,7 @@ import { pinValue } from '../viewer/pinLabel'
 import { fmtLen, unitWord } from '../core/units'
 import { useUnits } from './useUnits'
 import { providersFor } from '../ui/RefSelect'
-import { MARK_COLOR, useDeviation } from '../state/deviationStore'
+import { MARK_COLOR, mapHeld, useDeviation } from '../state/deviationStore'
 import { sectionElementsOf, useFlat } from '../state/flatStore'
 import { useShell } from '../state/shellStore'
 import { useMark } from '../state/markStore'
@@ -1025,9 +1025,7 @@ export function useSceneSync({
   }, [picking])
 
   // Hover testing only earns its frame when there is a map to read.
-  const hasDeviationMap = useDeviation((s) =>
-    s.source === 'element' ? s.elementStatus === 'ready' : s.mapStatus === 'ready',
-  )
+  const hasDeviationMap = useDeviation(mapHeld)
   const hasThicknessMap = useThickness((s) => s.status === 'ready')
   const hasMap =
     (workspace === 'deviation' && hasDeviationMap) ||
diff --git a/src/commands/core/deviation.ts b/src/commands/core/deviation.ts
index 5fdca44e..d95a618d 100644
--- a/src/commands/core/deviation.ts
+++ b/src/commands/core/deviation.ts
@@ -18,7 +18,7 @@ import { elementRefSchema, measuredElement, requireScan, type ElementRef } from
 import { arr, bool, bytes, enumOf, int, num, obj, oneOf, vec3, type JsonSchema } from '../schema'
 import { describeDeviation } from '../state'
 import { CommandError, type Command } from '../types'
-import { fileNameSchema, fileOf, lastError, showWorkspace, waitFor } from './common'
+import { fileNameSchema, fileOf, lastError, nextFrame, showWorkspace, waitFor } from './common'
 import { unitsSchema } from './scan'
 import { round3 } from '../../core/round'
 import { deviationFileBytes, isMeasured, type DeviationFormat } from '../../core/deviation/exportDeviation'
@@ -146,7 +146,7 @@ const setTarget: Command<{ element: ElementRef | null; side?: 'outward' | 'inwar
   label: () => 'measure against element',
   run: async ({ element, side, facingDeg }) => {
     requireScan()
-    requireScene('A map against an element')
+    const scene = requireScene('A map against an element')
     showWorkspace('deviation')
     const { session } = commandHost()
     if (element === null) {
@@ -161,7 +161,9 @@ const setTarget: Command<{ element: ElementRef | null; side?: 'outward' | 'inwar
     const want = side === undefined ? undefined : side === 'outward' ? 1 : -1
     if (want !== undefined && useDeviation.getState().targetSide !== want) useDeviation.getState().flipTargetSide()
     if (facingDeg !== undefined) useDeviation.getState().setTargetFacing(facingDeg)
-    // The map follows the choice on its own (useElementField).
+    // The map follows the choice on its own (useElementField), once the stores' change has reached it: a
+    // frame first, so a map measured before is not taken for the one asked for.
+    await nextFrame(scene)
     await waitFor(() => useDeviation.getState().elementStatus === 'ready', 'the map against the element', 30_000)
     return { deviation: describeDeviation() }
   },
diff --git a/src/core/meshWorker.ts b/src/core/meshWorker.ts
index ff237178..0fb8863f 100644
--- a/src/core/meshWorker.ts
+++ b/src/core/meshWorker.ts
@@ -31,6 +31,7 @@ import {
 import type { Steps } from './deviation/steps'
 import { computeDeviation, defaultMaxDistance, suggestRange } from './deviation/deviation'
 import { deflectionVectors } from './deviation/deflection'
+import { computeElementDeviation } from './deviation/elementField'
 import { rigidApplyToPoints, rigidInvert, rigidRotateVectors, type Rigid } from './deviation/rigid'
 import { meshArea, meshLongEdges, readReference, sampleSpacing, subdivideForMap } from './deviation/onReference'
 import { buildSolidIndex, computeThickness, suggestThicknessScale } from './thickness/thickness'
@@ -595,6 +596,39 @@ function handle(msg: Exclude<WorkerRequest, { type: 'align-abort' }>): void {
     return
   }
 
+  if (msg.type === 'element-deviation') {
+    // Over the scan's vertices as held here, which are the render thread's
+    // own bit for bit (see `deflection`), and the normals it sent, which are
+    // not the ones held here — so that the map is the one it would have
+    // measured itself, without the pass over the whole scan landing on the
+    // thread that answers the user.
+    if (!graph) {
+      post({ type: 'error', requestId: msg.requestId, message: 'No model loaded.' })
+      return
+    }
+    const positions = msg.positions ?? graph.positions
+    if (msg.normals.length !== positions.length) {
+      post({ type: 'error', requestId: msg.requestId, message: 'The normals sent are not the scan’s.' })
+      return
+    }
+    try {
+      const directions = new Int8Array(positions.length)
+      const values = computeElementDeviation(msg.target, positions, msg.normals, {
+        side: msg.side,
+        maxNormalDeviation: msg.maxNormalDeviation,
+        subset: msg.subset,
+        directions,
+      })
+      post(
+        { type: 'element-deviation-ok', requestId: msg.requestId, values, directions, suggestedRange: suggestRange(values, msg.maxDistance) },
+        [values.buffer, directions.buffer],
+      )
+    } catch (e) {
+      post({ type: 'error', requestId: msg.requestId, message: errorText(e) })
+    }
+    return
+  }
+
   if (msg.type === 'bounds') {
     if (!graph) {
       post({ type: 'error', requestId: msg.requestId, message: 'No model loaded.' })
diff --git a/src/core/workerClient.ts b/src/core/workerClient.ts
index 0e8893ce..bfc7c9cb 100644
--- a/src/core/workerClient.ts
+++ b/src/core/workerClient.ts
@@ -16,6 +16,7 @@ import type { AutoAlignResult } from './autoAlign'
 import type { AlignResult, PointPair } from './deviation/align'
 import type { Rigid } from './deviation/rigid'
 import type { VolumeDeviation } from './deviation/volume'
+import type { ElementTarget, MaterialSide } from './deviation/elementField'
 import { mmPerUnit, type MeshUnits } from './meshUnits'
 import type { StepInfo } from './parsers/step'
 import type { SectionFrame } from './section/frame'
@@ -556,6 +557,37 @@ export class MeshWorkerClient {
     return res.vectors
   }
 
+  /** The map against a fitted element — see deviation/elementField.ts
+   *  computeElementDeviation — measured in the worker, over its own copy of
+   *  the scan's vertices. `render` is asked for the viewport's own arrays:
+   *  its normals always go with the request (a copy — the worker's are not
+   *  the ones its sharp edges were split for), and its positions only where
+   *  the worker's may not match them (see renderParity). The marked region
+   *  is copied too: the brush goes on writing into it. An answer about
+   *  vertices since moved or replaced rejects with StaleScan. */
+  async elementDeviation(
+    target: ElementTarget,
+    opts: { side: MaterialSide; maxNormalDeviation: number | null; subset: Uint32Array | null; maxDistance: number },
+    render: () => { positions: Float32Array; normals: Float32Array } | null,
+  ): Promise<{ values: Float32Array; directions: Int8Array; suggestedRange: number }> {
+    // A restart this request would wait on reads the scan back in first.
+    await this.ready()
+    const asked = this.scanToken
+    const arrays = render()
+    if (!arrays) throw new Error('There is no scan to measure.')
+    const normals = arrays.normals.slice()
+    const positions = this.renderParity ? null : arrays.positions.slice()
+    const subset = opts.subset ? opts.subset.slice() : null
+    const transfer = [normals.buffer, ...(positions ? [positions.buffer] : []), ...(subset ? [subset.buffer] : [])] as ArrayBuffer[]
+    const requestId = this.nextId++
+    const res = await this.request<Extract<WorkerResponse, { type: 'element-deviation-ok' }>>(
+      { type: 'element-deviation', requestId, target, ...opts, subset, normals, ...(positions ? { positions } : {}) },
+      transfer,
+    )
+    if (this.scanToken !== asked) throw new StaleScan()
+    return { values: res.values, directions: res.directions, suggestedRange: res.suggestedRange }
+  }
+
   /** The box around the scan as it now stands, mm. */
   async bounds(): Promise<{ min: Vec3; max: Vec3 }> {
     const requestId = this.nextId++
diff --git a/src/core/workerProtocol.ts b/src/core/workerProtocol.ts
index 5d39e991..80a26e2c 100644
--- a/src/core/workerProtocol.ts
+++ b/src/core/workerProtocol.ts
@@ -9,6 +9,7 @@
 import type { AlignResult, PointPair } from './deviation/align'
 import type { Rigid } from './deviation/rigid'
 import type { VolumeDeviation } from './deviation/volume'
+import type { ElementTarget, MaterialSide } from './deviation/elementField'
 import type { StepInfo } from './parsers/step'
 import type { ThicknessMethod } from './thickness/thickness'
 import type { AxialWindow, ElementKind, FitOutput, FitSettings, TextureNote, Vec3 } from './types'
@@ -225,6 +226,27 @@ export type WorkerRequest =
       smoothing: number
       positions?: Float32Array
     }
+  /** The map against a fitted element — see deviation/elementField.ts
+   *  computeElementDeviation — measured here, off the main thread, over the
+   *  scan's vertices as held here: the render thread's own bit for bit, as
+   *  for `deflection`. `normals` are the render thread's and always sent:
+   *  its sharp edges were split for shading and the ones held here are the
+   *  average of the faces that meet, so a facing limit read off them would
+   *  be a different map. `positions` is sent only where the vertices may
+   *  not match, as for `deflection`. `subset` is the hand-marked region the
+   *  map is restricted to, when it is; `maxDistance` is the search distance
+   *  the suggested colour scale is read within. */
+  | {
+      type: 'element-deviation'
+      requestId: number
+      target: ElementTarget
+      side: MaterialSide
+      maxNormalDeviation: number | null
+      subset: Uint32Array | null
+      maxDistance: number
+      normals: Float32Array
+      positions?: Float32Array
+    }
   /** A request for a plugin's part of the worker — see workerPluginApi.ts.
    *  `op` names the plugin's operation, `payload` is its own. */
   | { type: 'plugin'; requestId: number; plugin: string; op: string; payload: unknown }
@@ -353,6 +375,9 @@ export type WorkerResponse =
   | { type: 'closed-shells-ok'; requestId: number; closed: Uint8Array }
   /** Three floats per scan vertex, the offset to draw it moved by. */
   | { type: 'deflection-ok'; requestId: number; vectors: Float32Array }
+  /** The map against an element, the direction each reading was taken
+   *  along, and the colour scale the tool would choose for it, in mm. */
+  | { type: 'element-deviation-ok'; requestId: number; values: Float32Array; directions: Int8Array; suggestedRange: number }
   /** A plugin's answer. */
   | { type: 'plugin-ok'; requestId: number; result: unknown }
   | { type: 'error'; requestId: number; message: string }
diff --git a/src/state/deviationStore.ts b/src/state/deviationStore.ts
index 873dbf7c..daafe4a4 100644
--- a/src/state/deviationStore.ts
+++ b/src/state/deviationStore.ts
@@ -39,6 +39,18 @@ export type MapSide = 'scan' | 'reference'
 export type AlignStatus = 'idle' | 'running' | 'done' | 'failed'
 export type MapStatus = 'idle' | 'running' | 'ready'
 
+/** Whether the map this workspace reads is on screen to be read: measured, or
+ *  being measured again with the readout of the one before still up — a facing
+ *  limit dragged, a region brushed. A map that is only being measured the first
+ *  time has no readout yet. That is what lets the panel and the scale beside
+ *  the slider stay mounted while it is re-measured, and not under the finger
+ *  that is dragging it. What reads the map itself asks for 'ready'. */
+export function mapHeld(s: Pick<DeviationState, 'source' | 'elementStatus' | 'mapStatus' | 'stats'>): boolean {
+  return s.source === 'element'
+    ? s.elementStatus === 'ready' || (s.elementStatus === 'running' && s.stats !== null)
+    : s.mapStatus === 'ready'
+}
+
 /** Colour of a point pair in the split view — the same pair gets the same
  *  colour on both sides, which is the only thing tying them together visually. */
 export function pairColor(index: number): string {
@@ -191,10 +203,14 @@ interface DeviationState extends ProbeSlice {
   setTarget: (id: number | null, side?: MaterialSide) => void
   flipTargetSide: () => void
   setTargetFacing: (deg: number | null) => void
-  /** A fresh element field has landed. Cheap enough to be computed on the main
-   *  thread, so unlike the reference map there is no running state to pass
-   *  through — it is ready by the time anything can ask. */
+  /** The map against the element is being measured, in the worker: nothing
+   *  that reads it as ready may take the one in hand for the one wanted. */
+  beginElementMap: () => void
+  /** A fresh element field has landed. */
   resolveElementMap: (range: number, preserveProbes?: boolean) => void
+  /** The map could not be measured at all. Back to idle, so that nothing waits
+   *  on a status that will never change; the element chosen stays chosen. */
+  failElementMap: () => void
   clearElementMap: () => void
   setShowElement: (v: boolean) => void
   setTargetScope: (scope: 'all' | 'marked') => void
@@ -418,6 +434,10 @@ export const useDeviation = create<DeviationState>()((set, get) => ({
   // The scale and the pins belong to whichever map is being read, and this one
   // is also recomputed behind the reference map whenever the element it measures
   // against changes under it — so neither is touched unless it is this map's.
+  beginElementMap: () => set({ elementStatus: 'running' }),
+
+  failElementMap: () => set({ elementStatus: 'idle' }),
+
   resolveElementMap: (range, preserveProbes = false) =>
     set((s) => ({
       elementStatus: 'ready',
diff --git a/src/ui/DeviationPanel.tsx b/src/ui/DeviationPanel.tsx
index eebc5a0e..dee713fb 100644
--- a/src/ui/DeviationPanel.tsx
+++ b/src/ui/DeviationPanel.tsx
@@ -10,7 +10,7 @@ import { MIN_LOCAL_POINTS } from '../core/deviation/align'
 import { MAX_DEFLECTION_SCALE, MIN_DEFLECTION_SCALE } from '../core/deviation/deflection'
 import { DEFAULT_MAP_FACING_DEG } from '../core/deviation/deviation'
 import { REFERENCE_ACCEPT, REFERENCE_FORMATS } from '../core/formats'
-import { useDeviation, type DeviationSource } from '../state/deviationStore'
+import { mapHeld, useDeviation, type DeviationSource } from '../state/deviationStore'
 import { useMark } from '../state/markStore'
 import { useStore } from '../state/store'
 import { targetFitOf } from '../app/useElementField'
@@ -150,6 +150,7 @@ export function DeviationPanel({
       showHistogram: s.showHistogram,
       showScan: s.showScan,
       source: s.source,
+      stats: s.stats,
       targetFacingDeg: s.targetFacingDeg,
       targetId: s.targetId,
       targetSide: s.targetSide,
@@ -168,7 +169,7 @@ export function DeviationPanel({
   // Whichever map this panel is reading. The two are held side by side, so the
   // scale, the figures and the pins below follow the source rather than
   // whichever was measured last.
-  const hasMap = onElement ? d.elementStatus === 'ready' : d.mapStatus === 'ready'
+  const hasMap = mapHeld(d)
   const target = targetFitOf(elements, d.targetId)
 
   // A fit that lands far from the surface, or that had a near-tie for the best
diff --git a/src/ui/ViewBar.tsx b/src/ui/ViewBar.tsx
index 3dc168d2..1a57e6fb 100644
--- a/src/ui/ViewBar.tsx
+++ b/src/ui/ViewBar.tsx
@@ -14,7 +14,7 @@
 import type { ReactNode } from 'react'
 import type { Vec3 } from '../core/types'
 import type { PluginRuntime } from '../plugins/api'
-import { useDeviation } from '../state/deviationStore'
+import { mapHeld, useDeviation } from '../state/deviationStore'
 import { useSectionView } from '../state/sectionViewStore'
 import { useShell } from '../state/shellStore'
 import { useStore } from '../state/store'
@@ -90,9 +90,7 @@ export function ViewBar({
   const referenceRunning = useDeviation((s) => s.referenceStatus === 'running')
   const nominalName = useDeviation((s) => s.nominalName)
   const nominalBusy = useDeviation((s) => s.nominalBusy)
-  const hasMap = useDeviation((s) =>
-    s.source === 'element' ? s.elementStatus === 'ready' : s.mapStatus === 'ready',
-  )
+  const hasMap = useDeviation(mapHeld)
   const nominalReady = Boolean(nominalName) && !nominalBusy
   // Nothing to stand a second viewport up with until both parts are in.
   const canSplit = Boolean(fileName) && nominalReady
diff --git a/tests/elementFieldWorker.test.ts b/tests/elementFieldWorker.test.ts
new file mode 100644
index 00000000..c2a56509
--- /dev/null
+++ b/tests/elementFieldWorker.test.ts
@@ -0,0 +1,339 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// The map against an element, measured in the mesh worker. What has to hold is
+// that it is the map the main thread would have measured, bit for bit — the
+// worker is only somewhere else to do the same sum — and that an answer which
+// cannot be the one wanted any more (the inputs moved on, the scan moved or
+// was replaced) is never painted, and never leaves the status stuck at
+// "running" either.
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { computeElementDeviation, type ElementTarget } from '../src/core/deviation/elementField'
+import { suggestRange } from '../src/core/deviation/deviation'
+import { rigidApply, rigidApplyToPoints, rigidFromAxisAngle, rigidRotate, rigidRotateVectors } from '../src/core/deviation/rigid'
+import { buildBinaryStl } from '../src/core/exportStl'
+import { latestWins, runElementMap, type ElementMapResult } from '../src/app/useElementField'
+import { MeshWorkerClient, StaleScan } from '../src/core/workerClient'
+import type { Vec3 } from '../src/core/types'
+import type { WorkerRequest, WorkerResponse } from '../src/core/workerProtocol'
+import { cylinderMesh } from './helpers'
+
+const bits = (a: Float32Array | Int8Array) => Array.from(new Uint8Array(a.buffer, a.byteOffset, a.byteLength))
+
+const NO_RESIDUALS = { sigma: 0, usedPoints: 0, regionSize: 0 }
+/** The scan's own pose: a cylinder of radius 10 and length 30 about Z, moved
+ *  by a datum alignment, as it sits in the viewport. */
+const DATUM = (() => {
+  const datum = rigidFromAxisAngle([0.3, -0.5, 0.8], 0.7)
+  datum.t[0] = 12.5
+  datum.t[1] = -3.25
+  datum.t[2] = 101
+  return datum
+})()
+const at = (p: Vec3): Vec3 => {
+  const out = new Float64Array(3)
+  rigidApply(DATUM, p[0], p[1], p[2], out)
+  return [out[0], out[1], out[2]]
+}
+const along = (v: Vec3): Vec3 => {
+  const out = new Float64Array(3)
+  rigidRotate(DATUM, v[0], v[1], v[2], out)
+  return [out[0], out[1], out[2]]
+}
+/** Elements laid against that scan where it is: on its cap, round its wall,
+ *  a ball about its middle and a ring round its waist. */
+const targets: [string, ElementTarget][] = [
+  ['a plane', { kind: 'plane', ...NO_RESIDUALS, center: at([0, 0, 15]), normal: along([0, 0, 1]), basisU: along([1, 0, 0]), basisV: along([0, 1, 0]), extentU: 9, extentV: 9 }],
+  ['a cylinder', { kind: 'cylinder', ...NO_RESIDUALS, center: at([0, 0, 0]), axis: along([0, 0, 1]), radius: 10, length: 20, coverage: 360 }],
+  ['a sphere', { kind: 'sphere', ...NO_RESIDUALS, center: at([0, 0, 0]), radius: 12 }],
+  ['a torus', { kind: 'torus', ...NO_RESIDUALS, center: at([0, 0, 0]), axis: along([0, 0, 1]), majorRadius: 8, minorRadius: 3, tubeCoverage: 360, spineCoverage: 360 }],
+]
+
+describe('the map against an element, worked out in the worker', () => {
+  let scope: { onmessage: ((event: { data: WorkerRequest }) => void) | null; postMessage: (msg: WorkerResponse) => void }
+  let replies: WorkerResponse[]
+  beforeEach(async () => {
+    replies = []
+    scope = { onmessage: null, postMessage: (msg) => replies.push(msg) }
+    vi.stubGlobal('self', scope)
+    vi.resetModules()
+    await import('../src/core/meshWorker')
+  })
+  afterEach(() => vi.unstubAllGlobals())
+  const send = (msg: WorkerRequest) => {
+    replies.length = 0
+    scope.onmessage!({ data: msg })
+    return replies.at(-1)!
+  }
+
+  /** A scan with its sharp edges split, as the app loads one, and a datum
+   *  alignment baked in on both sides — the worker's copy by its transform
+   *  message, the viewport's own by the same rotation of its arrays. */
+  const loadAndMove = () => {
+    const buffer = buildBinaryStl(cylinderMesh(10, 30, 48, 12, 0.02).positions, null, null, '')
+    const loaded = send({ type: 'load', requestId: 1, name: 'scan.stl', buffer, crease: { mode: 'on', angleDeg: 30 } })
+    if (loaded.type !== 'loaded') throw new Error(JSON.stringify(loaded))
+    expect(loaded.copyOf.length).toBeGreaterThan(0)
+    rigidApplyToPoints(DATUM, loaded.positions)
+    rigidRotateVectors(DATUM, loaded.normals)
+    expect(send({ type: 'transform', requestId: 2, transform: DATUM }).type).toBe('transform-ok')
+    const own = loaded.vertexCount * 3
+    return { positions: loaded.positions.subarray(0, own), normals: loaded.normals.subarray(0, own), vertexCount: loaded.vertexCount }
+  }
+
+  it("is not the worker's own normals the viewport shades with, which is why they are sent", () => {
+    const { normals, vertexCount } = loadAndMove()
+    const held = send({ type: 'query', requestId: 3, min: [-1e9, -1e9, -1e9], max: [1e9, 1e9, 1e9], limit: vertexCount })
+    if (held.type !== 'query-ok') throw new Error(JSON.stringify(held))
+    expect(held.normals.length).toBe(normals.length)
+    // The rims were split for shading: the viewport's normal there is the face's,
+    // the worker's the average of the faces that meet.
+    expect(bits(held.normals)).not.toEqual(bits(normals))
+  })
+
+  const options = [
+    ['facing 60°, outward', { side: 1 as const, maxNormalDeviation: Math.PI / 3 }],
+    ['any facing, inward', { side: -1 as const, maxNormalDeviation: null }],
+  ] as const
+
+  for (const [name, target] of targets) {
+    for (const [what, opts] of options) {
+      it(`measures what the render thread would, bit for bit: ${name}, ${what}`, () => {
+        const { positions, normals, vertexCount } = loadAndMove()
+        const directions = new Int8Array(vertexCount * 3)
+        const here = computeElementDeviation(target, positions, normals, { ...opts, subset: null, directions })
+        const there = send({
+          type: 'element-deviation', requestId: 3, target, ...opts, subset: null, maxDistance: 5, normals: normals.slice(),
+        })
+        if (there.type !== 'element-deviation-ok') throw new Error(JSON.stringify(there))
+        expect(there.values.length).toBe(vertexCount)
+        expect(bits(there.values)).toEqual(bits(here))
+        expect(bits(there.directions)).toEqual(bits(directions))
+        expect(there.suggestedRange).toBe(suggestRange(here, 5))
+        // Something was measured, and something left out.
+        expect(here.some((v) => Number.isFinite(v))).toBe(true)
+      })
+    }
+  }
+
+  it('measures only the marked vertices when it is given them', () => {
+    const { positions, normals, vertexCount } = loadAndMove()
+    const subset = Uint32Array.from({ length: Math.floor(vertexCount / 3) }, (_, i) => i * 3)
+    const target = targets[2][1]
+    const opts = { side: 1 as const, maxNormalDeviation: null, subset }
+    const here = computeElementDeviation(target, positions, normals, opts)
+    const there = send({ type: 'element-deviation', requestId: 3, target, ...opts, subset: subset.slice(), maxDistance: 5, normals: normals.slice() })
+    if (there.type !== 'element-deviation-ok') throw new Error(JSON.stringify(there))
+    expect(bits(there.values)).toEqual(bits(here))
+    expect(there.values.filter((v) => !Number.isNaN(v)).length).toBe(subset.length)
+    // And an empty mark is an empty map, not the whole scan.
+    const none = send({ type: 'element-deviation', requestId: 4, target, side: 1, maxNormalDeviation: null, subset: new Uint32Array(0), maxDistance: 5, normals: normals.slice() })
+    if (none.type !== 'element-deviation-ok') throw new Error(JSON.stringify(none))
+    expect(none.values.every((v) => Number.isNaN(v))).toBe(true)
+  })
+
+  it("measures over the positions sent with the request, where the worker's are not the viewport's", () => {
+    const { positions, normals } = loadAndMove()
+    const shifted = positions.map((x) => x + 0.375)
+    const target = targets[1][1]
+    const opts = { side: 1 as const, maxNormalDeviation: null, subset: null }
+    const there = send({ type: 'element-deviation', requestId: 3, target, ...opts, maxDistance: 5, normals: normals.slice(), positions: shifted })
+    if (there.type !== 'element-deviation-ok') throw new Error(JSON.stringify(there))
+    expect(bits(there.values)).toEqual(bits(computeElementDeviation(target, shifted, normals, opts)))
+  })
+
+  it('says so when there is no scan, or the normals are not the scan’s', () => {
+    expect(send({ type: 'element-deviation', requestId: 1, target: targets[0][1], side: 1, maxNormalDeviation: null, subset: null, maxDistance: 5, normals: new Float32Array(3) }).type).toBe('error')
+    const { normals } = loadAndMove()
+    const wrong = send({ type: 'element-deviation', requestId: 2, target: targets[0][1], side: 1, maxNormalDeviation: null, subset: null, maxDistance: 5, normals: normals.slice(0, 30) })
+    expect(wrong.type).toBe('error')
+  })
+})
+
+describe('the map asked of the worker', () => {
+  /** A client without its worker: the requests it would post, kept, each
+   *  answered when the test says. */
+  function clientOf() {
+    const sent: Record<string, unknown>[] = []
+    const answers: (() => void)[] = []
+    const client = Object.create(MeshWorkerClient.prototype) as MeshWorkerClient
+    Object.assign(client, {
+      nextId: 1,
+      scanVersion: 0,
+      nominalVersion: 0,
+      scanToken: 0,
+      renderParity: true,
+      ready: () => Promise.resolve(),
+      request: (msg: Record<string, unknown>) => {
+        sent.push(msg)
+        return new Promise((resolve) => answers.push(() => resolve({ values: new Float32Array(1), directions: new Int8Array(3), suggestedRange: 0.25 })))
+      },
+    })
+    const settle = async () => {
+      await new Promise((r) => setTimeout(r, 0))
+      for (const answer of answers.splice(0)) answer()
+      await new Promise((r) => setTimeout(r, 0))
+    }
+    return { client, sent, settle }
+  }
+  const target = targets[0][1]
+  const opts = { side: 1 as const, maxNormalDeviation: null, subset: null, maxDistance: 2 }
+  const render = () => ({ positions: Float32Array.of(1, 2, 3), normals: Float32Array.of(0, 0, 1) })
+
+  it('turns away an answer about a scan since moved or replaced', async () => {
+    const { client, settle } = clientOf()
+    const moved = client.elementDeviation(target, opts, render)
+    const movedSettled = expect(moved).rejects.toBeInstanceOf(StaleScan)
+    await new Promise((r) => setTimeout(r, 0))
+    void client.transform(rigidFromAxisAngle([0, 0, 1], 0.5))
+    await settle()
+    await movedSettled
+
+    const replaced = client.elementDeviation(target, opts, render)
+    const replacedSettled = expect(replaced).rejects.toBeInstanceOf(StaleScan)
+    await new Promise((r) => setTimeout(r, 0))
+    void client.commitImport({ scan: 7 })
+    await settle()
+    await replacedSettled
+
+    const kept = client.elementDeviation(target, opts, render)
+    await settle()
+    await expect(kept).resolves.toMatchObject({ suggestedRange: 0.25 })
+  })
+
+  it("sends the viewport's normals always and its positions only where the worker's may not match", async () => {
+    const { client, sent, settle } = clientOf()
+    const a = client.elementDeviation(target, opts, render)
+    await settle()
+    await a
+    ;(client as unknown as { renderParity: boolean }).renderParity = false
+    const b = client.elementDeviation(target, opts, render)
+    await settle()
+    await b
+    expect(sent[0].positions).toBeUndefined()
+    expect([...(sent[0].normals as Float32Array)]).toEqual([0, 0, 1])
+    expect([...(sent[1].positions as Float32Array)]).toEqual([1, 2, 3])
+    expect([...(sent[1].normals as Float32Array)]).toEqual([0, 0, 1])
+  })
+
+  it('hands over copies, so what the viewport and the mark hold stay theirs', async () => {
+    const { client, sent, settle } = clientOf()
+    const held = render()
+    const marked = Uint32Array.of(4, 5, 6)
+    ;(client as unknown as { renderParity: boolean }).renderParity = false
+    const a = client.elementDeviation(target, { ...opts, subset: marked }, () => held)
+    await settle()
+    await a
+    expect(sent[0].normals).not.toBe(held.normals)
+    expect(sent[0].positions).not.toBe(held.positions)
+    expect(sent[0].subset).not.toBe(marked)
+    expect([...(sent[0].subset as Uint32Array)]).toEqual([4, 5, 6])
+  })
+})
+
+describe('what is done with the answer', () => {
+  const result = (range = 0.5): ElementMapResult => ({ values: new Float32Array(2), directions: new Int8Array(6), suggestedRange: range })
+  const flush = () => new Promise((r) => setTimeout(r, 0))
+
+  /** One run's surroundings: whether it is still the one wanted, and what was
+   *  settled or failed. */
+  function run(opts: { ask?: (() => Promise<ElementMapResult>) | null; here?: () => ElementMapResult | null; current?: () => boolean }) {
+    const log: string[] = []
+    const done = runElementMap({
+      ask: opts.ask === undefined ? null : opts.ask,
+      here: opts.here ?? (() => result(0.1)),
+      current: opts.current ?? (() => true),
+      settle: (r) => log.push(`settled ${r.suggestedRange}`),
+      fail: () => log.push('failed'),
+    })
+    return { log, done }
+  }
+
+  it("settles with the worker's answer", async () => {
+    const { log, done } = run({ ask: async () => result(0.5) })
+    await done
+    expect(log).toEqual(['settled 0.5'])
+  })
+
+  it('drops an answer to a question that has moved on, and settles nothing', async () => {
+    let current = true
+    const { log, done } = run({ ask: async () => { current = false; return result() }, current: () => current })
+    await done
+    expect(log).toEqual([])
+  })
+
+  it('asks again once of a scan that moved, then measures it here', async () => {
+    let asked = 0
+    const { log, done } = run({ ask: async () => { asked++; throw new StaleScan() } })
+    await done
+    expect(asked).toBe(2)
+    expect(log).toEqual(['settled 0.1'])
+    // The second ask can answer.
+    asked = 0
+    const again = run({ ask: async () => { if (++asked === 1) throw new StaleScan(); return result(0.7) } })
+    await again.done
+    expect(again.log).toEqual(['settled 0.7'])
+  })
+
+  it('measures it here when the worker cannot, or there is none', async () => {
+    const broken = run({ ask: async () => { throw new Error('worker gone') } })
+    await broken.done
+    expect(broken.log).toEqual(['settled 0.1'])
+    const none = run({ ask: null })
+    await none.done
+    expect(none.log).toEqual(['settled 0.1'])
+  })
+
+  it('never leaves the map running: a failure all round fails it', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const thrown = run({ ask: async () => { throw new Error('worker gone') }, here: () => { throw new Error('and here') } })
+    await thrown.done
+    expect(thrown.log).toEqual(['failed'])
+    const empty = run({ ask: null, here: () => null })
+    await empty.done
+    expect(empty.log).toEqual(['failed'])
+    warn.mockRestore()
+  })
+
+  it('does not fail a map that something newer has taken over', async () => {
+    let current = true
+    const { log, done } = run({ ask: async () => { current = false; throw new Error('worker gone') }, current: () => current })
+    await done
+    expect(log).toEqual([])
+  })
+
+  it('keeps only the newest of what arrives while one is being worked out', async () => {
+    const order: string[] = []
+    const releases: (() => void)[] = []
+    const queue = latestWins()
+    const job = (name: string) => () => {
+      order.push(`start ${name}`)
+      return new Promise<void>((resolve) => releases.push(() => { order.push(`end ${name}`); resolve() }))
+    }
+    queue(job('a'))
+    queue(job('b'))
+    queue(job('c'))
+    expect(order).toEqual(['start a'])
+    releases.shift()!()
+    await flush()
+    // b was never asked: c is the newest.
+    expect(order).toEqual(['start a', 'end a', 'start c'])
+    releases.shift()!()
+    await flush()
+    expect(order).toEqual(['start a', 'end a', 'start c', 'end c'])
+    // Idle again, the next goes straight away.
+    queue(job('d'))
+    expect(order.at(-1)).toBe('start d')
+  })
+
+  it('carries on after a job that throws', async () => {
+    const order: string[] = []
+    const queue = latestWins()
+    queue(async () => { order.push('a'); throw new Error('boom') })
+    queue(async () => { order.push('b') })
+    await flush()
+    await flush()
+    expect(order).toEqual(['a', 'b'])
+    queue(async () => { order.push('c') })
+    await flush()
+    expect(order).toEqual(['a', 'b', 'c'])
+  })
+})

From 2de55679248138cf217fa7b8ec50bd9811b1aaa3 Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Wed, 4 Nov 2026 23:16:54 +0000
Subject: [PATCH 24/38] perf(element-map): commands wait for the map being
 measured

The map against an element lands a worker round trip after its inputs move, so a
command that read it in the frame after saw "running" and answered "no map", an
empty list of patches, or a report pairing the old figures with the new settings.
mapSettled (a frame, then not running) is awaited by each reader: hotspots, feature
patches, export, the relief and height reads, the picture's map note, session state
and the report. set_target throws at once when the map could not be measured instead
of waiting out 30 s. Copy report is off while the map is measured, an unmounted hook
no longer settles, and a worker error falling back to the main thread is logged.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 src/app/useElementField.ts       | 16 ++++++++-
 src/commands/core/common.ts      | 14 ++++++++
 src/commands/core/deviation.ts   | 14 ++++----
 src/commands/core/scan.ts        |  5 +--
 src/commands/core/session.ts     | 17 +++++++---
 src/commands/core/view.ts        |  6 +++-
 src/ui/DeviationPanel.tsx        |  6 +++-
 tests/commandsMapSettled.test.ts | 56 ++++++++++++++++++++++++++++++++
 tests/elementFieldWorker.test.ts |  6 +++-
 9 files changed, 123 insertions(+), 17 deletions(-)
 create mode 100644 tests/commandsMapSettled.test.ts

diff --git a/src/app/useElementField.ts b/src/app/useElementField.ts
index a001e387..41eb1dce 100644
--- a/src/app/useElementField.ts
+++ b/src/app/useElementField.ts
@@ -82,7 +82,12 @@ export async function runElementMap({
       result = await ask()
     } catch (e) {
       if (!current()) return
-      if (!(e instanceof StaleScan)) break
+      if (!(e instanceof StaleScan)) {
+        // Measured here instead, which is the cost this moved off the main
+        // thread: a worker that keeps failing should not do so unheard.
+        console.warn('The worker could not measure the map against the element; measuring it here.', e)
+        break
+      }
     }
   }
   if (!current()) return
@@ -163,6 +168,15 @@ export function useElementField({
   const queue = useRef<ReturnType<typeof latestWins> | null>(null)
   if (!queue.current) queue.current = latestWins()
 
+  // A map still being measured when this goes away must not be settled by
+  // it: whoever mounts next measures its own, and it owns the status.
+  useEffect(
+    () => () => {
+      previousInputs.current = null
+    },
+    [],
+  )
+
   // Held stable across renders: applyExtension builds a fresh object every call,
   // so depending on it directly would recompute the field on every render.
   const target = useMemo(() => {
diff --git a/src/commands/core/common.ts b/src/commands/core/common.ts
index a4ab99a6..a94b9509 100644
--- a/src/commands/core/common.ts
+++ b/src/commands/core/common.ts
@@ -9,6 +9,7 @@ import { dimHolds } from '../../state/historyStore'
 import { useShell, type Workspace } from '../../state/shellStore'
 import { draftHolds, useStore } from '../../state/store'
 import { useFlat, flatDraftHolds } from '../../state/flatStore'
+import { useDeviation } from '../../state/deviationStore'
 import { bool, str, type JsonSchema } from '../schema'
 import { CommandError, type FileOut } from '../types'
 import { watchSession } from '../activity'
@@ -168,3 +169,16 @@ export async function nextFrame(scene?: { pumpFrame(): void } | null): Promise<v
   await nextTask()
   scene?.pumpFrame()
 }
+
+/** The map against an element, measured: what any command that reads it waits
+ *  for first. The map follows its inputs in the mesh worker, so it is not in
+ *  step with them in the frame after they change — a datum moved, a facing
+ *  limit set, an undo — and a reader that took the status for the measure of
+ *  what it was just told would read the one before, or none. A frame first,
+ *  for the stores' change to reach the effect that asks; then the wait, which
+ *  is over at once when nothing is being measured. Settled is not measured:
+ *  the caller looks at the status for that. */
+export async function mapSettled(scene?: { pumpFrame(): void } | null): Promise<void> {
+  await nextFrame(scene)
+  await waitFor(() => useDeviation.getState().elementStatus !== 'running', 'the map against the element', 30_000)
+}
diff --git a/src/commands/core/deviation.ts b/src/commands/core/deviation.ts
index d95a618d..ea40d0cf 100644
--- a/src/commands/core/deviation.ts
+++ b/src/commands/core/deviation.ts
@@ -13,12 +13,12 @@ import { usePrefs } from '../../state/prefsStore'
 import { COLORMAPS, type ColormapId } from '../../core/field/colormap'
 import { useMark } from '../../state/markStore'
 import { useStore } from '../../state/store'
-import { commandHost, requireScene } from '../host'
+import { commandHost, requireScene, sceneOf } from '../host'
 import { elementRefSchema, measuredElement, requireScan, type ElementRef } from '../refs'
 import { arr, bool, bytes, enumOf, int, num, obj, oneOf, vec3, type JsonSchema } from '../schema'
 import { describeDeviation } from '../state'
 import { CommandError, type Command } from '../types'
-import { fileNameSchema, fileOf, lastError, nextFrame, showWorkspace, waitFor } from './common'
+import { fileNameSchema, fileOf, lastError, mapSettled, showWorkspace, waitFor } from './common'
 import { unitsSchema } from './scan'
 import { round3 } from '../../core/round'
 import { deviationFileBytes, isMeasured, type DeviationFormat } from '../../core/deviation/exportDeviation'
@@ -161,10 +161,9 @@ const setTarget: Command<{ element: ElementRef | null; side?: 'outward' | 'inwar
     const want = side === undefined ? undefined : side === 'outward' ? 1 : -1
     if (want !== undefined && useDeviation.getState().targetSide !== want) useDeviation.getState().flipTargetSide()
     if (facingDeg !== undefined) useDeviation.getState().setTargetFacing(facingDeg)
-    // The map follows the choice on its own (useElementField), once the stores' change has reached it: a
-    // frame first, so a map measured before is not taken for the one asked for.
-    await nextFrame(scene)
-    await waitFor(() => useDeviation.getState().elementStatus === 'ready', 'the map against the element', 30_000)
+    // The map follows the choice on its own (useElementField), once the stores' change has reached it.
+    await mapSettled(scene)
+    if (useDeviation.getState().elementStatus !== 'ready') throw new CommandError('failed', 'The map against the element could not be measured.')
     return { deviation: describeDeviation() }
   },
 }
@@ -279,6 +278,7 @@ const hotspotsCommand: Command<{ tolerance?: number; patches?: number; grain?: n
   run: async ({ tolerance, patches = HOTSPOT_PATCHES, grain, on = 'scan' }) => {
     requireScan()
     if (on === 'reference') return referenceHotspots(tolerance, patches, grain)
+    await mapSettled(sceneOf())
     const d = useDeviation.getState()
     const maps = commandHost().session.maps
     const values = d.source === 'element' ? maps.elementField.current : maps.deviation.current
@@ -354,6 +354,7 @@ const hotspotsCommand: Command<{ tolerance?: number; patches?: number; grain?: n
  *  material missing, misplaced or extra, as hotspotsCommand reads it,
  *  for a judgement on the model as a whole. Empty with no map to read. */
 export async function scanFeaturePatches(tolerance: number | undefined, limit = 50): Promise<{ at: Vec3; depth: number; far: boolean; outside: boolean }[]> {
+  await mapSettled(sceneOf())
   const d = useDeviation.getState()
   const maps = commandHost().session.maps
   const values = d.source === 'element' ? maps.elementField.current : maps.deviation.current
@@ -446,6 +447,7 @@ const exportCommand: Command<{ side?: MapSide; format?: DeviationFormat }> = {
   returnsFile: true,
   run: async ({ side = 'scan', format = 'ply' }) => {
     requireScan()
+    await mapSettled(sceneOf())
     const d = useDeviation.getState()
     const { session } = commandHost()
     let positions: Float32Array
diff --git a/src/commands/core/scan.ts b/src/commands/core/scan.ts
index bec4f31c..f9cc0e3f 100644
--- a/src/commands/core/scan.ts
+++ b/src/commands/core/scan.ts
@@ -5,7 +5,7 @@ import { MESH_UNITS, type MeshUnits } from '../../core/meshUnits'
 import type { Vec3 } from '../../core/types'
 import { useStore } from '../../state/store'
 import { useDeviation } from '../../state/deviationStore'
-import { commandHost } from '../host'
+import { commandHost, sceneOf } from '../host'
 import { locationSchema, requireScan, resolveLocation, type Location } from '../refs'
 import { arr, bool, bytes, enumOf, int, num, obj, oneOf, str, vec3 } from '../schema'
 import { acrossAxes, dominantFacing, type RimCircle, robustPlane } from '../../core/geometry/scanQa'
@@ -13,7 +13,7 @@ import { orthoBasis } from '../../core/fit/linalg'
 import { niceCeil } from '../../core/field/stats'
 import { scanBounds } from '../state'
 import { CommandError, type Command } from '../types'
-import { discardSchema, fileNameSchema, fileOf, lastError, requireDiscardable } from './common'
+import { discardSchema, fileNameSchema, fileOf, lastError, mapSettled, requireDiscardable } from './common'
 import { roundTo } from '../../core/round'
 import { cellNoise, heightLevels, rampsOf, reliefGrid, slopedCells } from '../../core/geometry/heightGrid'
 import { basePlaneOf } from '../../core/basePlanes'
@@ -679,6 +679,7 @@ const heightmap: Command<{
     const showPicture = picture || grid === false
     const boxed = boxOf(box)
     // Read up front, so a map with nothing to read refuses before it rays.
+    if (of === 'deviation') await mapSettled(sceneOf())
     const dev = of === 'deviation' ? deviationValues() : null
     const side = showGrid ? HEIGHT_SIDE : HEIGHT_SIDE_FINE
     const most = showGrid ? HEIGHT_CELLS : HEIGHT_CELLS_FINE
diff --git a/src/commands/core/session.ts b/src/commands/core/session.ts
index 60fd2bd3..83bfe9af 100644
--- a/src/commands/core/session.ts
+++ b/src/commands/core/session.ts
@@ -7,13 +7,13 @@ import { runImport } from '../../app/imports'
 import { historyBlocked, redo, undo, useHistory } from '../../state/historyStore'
 import { useShell } from '../../state/shellStore'
 import { useStore } from '../../state/store'
-import { commandHost } from '../host'
+import { commandHost, sceneOf } from '../host'
 import { reportJson, reportText, REPORT_WORKSPACES, type ReportWorkspace } from '../report'
 import { RECENT_KEPT, RECENT_RESULT_CHARS, recentOutcomes } from '../registry'
 import { enumOf, int, obj, str } from '../schema'
 import { internalWorkspace, publicWorkspace, sessionAfterStep, sessionState, workspaceNames } from '../state'
 import { CommandError, type Command } from '../types'
-import { discardSchema, requireDiscardable, waitFor } from './common'
+import { discardSchema, mapSettled, requireDiscardable, waitFor } from './common'
 
 const state: Command = {
   name: 'state',
@@ -23,7 +23,10 @@ const state: Command = {
   input: obj({}),
   readOnly: true,
   headless: true,
-  run: () => sessionState(),
+  run: async () => {
+    await mapSettled(sceneOf())
+    return sessionState()
+  },
 }
 
 const reset: Command<{ discard?: boolean }> = {
@@ -73,8 +76,12 @@ const report: Command<{ format?: 'json' | 'text'; workspace?: ReportWorkspace }>
     workspace: enumOf(REPORT_WORKSPACES, 'For text: whose report — measure (the default), deviation, thickness or flat.'),
   }),
   readOnly: true,
-  run: async ({ format = 'json', workspace: w = 'measure' }) =>
-    format === 'text' ? { format, workspace: w, text: reportText(w) } : { format, report: reportJson() },
+  run: async ({ format = 'json', workspace: w = 'measure' }) => {
+    // The report pairs the map's figures with the settings it was measured
+    // under: the one measured, not the one before.
+    await mapSettled(sceneOf())
+    return format === 'text' ? { format, workspace: w, text: reportText(w) } : { format, report: reportJson() }
+  },
 }
 
 /** What a step of the history answers with: the session in brief, or the
diff --git a/src/commands/core/view.ts b/src/commands/core/view.ts
index 633f4fb0..d284eb9d 100644
--- a/src/commands/core/view.ts
+++ b/src/commands/core/view.ts
@@ -25,7 +25,7 @@ import { arr, bool, enumOf, int, num, obj, oneOf, vec3, type JsonSchema } from '
 import { publicWorkspace } from '../state'
 import { CommandError, type Command } from '../types'
 import { applyShow, settleShown, viewToggles, whyNotShown, type ShowApplied, type ViewToggle } from '../viewToggles'
-import { nextFrame, waitFor } from './common'
+import { mapSettled, nextFrame, waitFor } from './common'
 
 const VIEWS: readonly StandardView[] = ['iso', 'iso-front-left', 'iso-rear-left', 'iso-rear-right', 'top', 'bottom', 'front', 'rear', 'left', 'right']
 
@@ -316,6 +316,9 @@ const render: Command<{ width?: number; height?: number; view?: StandardView; vi
       const pictured = views ? await sheetOfViews(scene, views, width, height, show) : await picture(scene, width, height, view, show)
       // A sheet of views fits each; otherwise only fit: true does.
       const framed = framing(scaleOf(scene), frame, Boolean(views) || (!frame && fit === true))
+      // What the picture says of the map is said of the one measured, not of
+      // the one before it.
+      await mapSettled(scene)
       return { ...pictured, ...framed, ...whyOf(scene, show), ...absentOf(done), ...describeMapPainted(scene.mapPainted()) }
     } finally {
       // What was put away or cut for the picture comes back; the frame stays.
@@ -418,6 +421,7 @@ export function describeMapPainted(painted: MapPainted): Record<string, unknown>
   const none = (mapWhy: string) => ({ map: null, mapWhy })
   if (!d.showMap) return none('the map switch is off — deviation.settings { show: true } puts it on.')
   if (d.source === 'element') {
+    if (d.elementStatus === 'running') return none('the map against the element is still being measured — ask again in a moment.')
     if (d.elementStatus !== 'ready') return none('no map against an element is measured — deviation.set_target measures one.')
   } else {
     if (!d.nominalName) return none('no reference part is open — deviation.open_reference, then deviation.align.')
diff --git a/src/ui/DeviationPanel.tsx b/src/ui/DeviationPanel.tsx
index dee713fb..221f6891 100644
--- a/src/ui/DeviationPanel.tsx
+++ b/src/ui/DeviationPanel.tsx
@@ -831,7 +831,11 @@ export function DeviationPanel({
       {scanName && (
         <div className={'tailrow' + (d.marking ? ' muted' : '')}>
           <div className="divider" />
-          {hasMap && <CopyButton className="block" label="Copy report" onCopy={onCopy} />}
+          {hasMap && (
+            // Its figures are the map in hand's and its settings the new ones'
+            // until the map being measured lands.
+            <CopyButton className="block" label="Copy report" disabled={onElement && d.elementStatus === 'running'} onCopy={onCopy} />
+          )}
           <ExportMeshButton
             block
             testId="export-mesh"
diff --git a/tests/commandsMapSettled.test.ts b/tests/commandsMapSettled.test.ts
new file mode 100644
index 00000000..076ce5d8
--- /dev/null
+++ b/tests/commandsMapSettled.test.ts
@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// The map against an element is measured in the mesh worker, so after its
+// inputs change it is not in step with them for a round trip. A command that
+// reads it must wait for that, and not take the status for a refusal ("no
+// map") or hand back the figures of the map before. On a 40 mm box, in the
+// in-process worker — see commandKit.ts.
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { useDeviation } from '../src/state/deviationStore'
+import { runCommand } from '../src/commands/registry'
+import { boxMesh } from './helpers'
+import { run, startHeadless, stlBytes, type Headless } from './commandKit'
+
+let headless: Headless
+beforeAll(async () => {
+  headless = await startHeadless()
+  await run('scan.open', { bytes: stlBytes(boxMesh(40, 40)), name: 'box.stl', discard: true })
+})
+afterAll(() => headless.stop())
+
+const later = (ms: number) => new Promise((r) => setTimeout(r, ms))
+/** Whether a promise has settled, without waiting for it. */
+const settledAfter = async (p: Promise<unknown>, ms: number): Promise<boolean> => {
+  let settled = false
+  p.then(() => (settled = true), () => (settled = true))
+  await later(ms)
+  return settled
+}
+
+describe('a command that reads the map against an element', () => {
+  it('waits for it while it is being measured, and reads what landed', async () => {
+    useDeviation.setState({ source: 'element', elementStatus: 'running' })
+    const state = runCommand('session.state', {}) as Promise<{ deviation: { map: string } }>
+    // Not answered with the map as it stands.
+    expect(await settledAfter(state, 150)).toBe(false)
+    useDeviation.getState().failElementMap()
+    const read = await state
+    expect(read.deviation.map).toBe('idle')
+  })
+
+  it('does not take a map being measured for one that is not there', async () => {
+    useDeviation.setState({ source: 'element', elementStatus: 'running' })
+    const hotspots = runCommand('deviation.hotspots', {})
+    const refusal = hotspots.then(() => null, (e: Error) => e)
+    expect(await settledAfter(hotspots, 150)).toBe(false)
+    // The measure failed: now it is refused for what it is.
+    useDeviation.getState().failElementMap()
+    expect((await refusal)?.message).toContain('no deviation map')
+  })
+
+  it('goes straight on when nothing is being measured', async () => {
+    useDeviation.setState({ source: 'element', elementStatus: 'idle' })
+    const started = Date.now()
+    await runCommand('session.state', {})
+    expect(Date.now() - started).toBeLessThan(2000)
+  })
+})
diff --git a/tests/elementFieldWorker.test.ts b/tests/elementFieldWorker.test.ts
index c2a56509..a8c99b25 100644
--- a/tests/elementFieldWorker.test.ts
+++ b/tests/elementFieldWorker.test.ts
@@ -108,8 +108,12 @@ describe('the map against an element, worked out in the worker', () => {
         expect(bits(there.values)).toEqual(bits(here))
         expect(bits(there.directions)).toEqual(bits(directions))
         expect(there.suggestedRange).toBe(suggestRange(here, 5))
-        // Something was measured, and something left out.
+        // Something was measured, and, under the facing limit, something left
+        // out by which way the scan faces — so the normals sent are in play. A
+        // ball about the cylinder's middle takes every face of it, whichever
+        // way it faces, so it is the one left whole.
         expect(here.some((v) => Number.isFinite(v))).toBe(true)
+        if (opts.maxNormalDeviation !== null && name !== 'a sphere') expect(here.some((v) => Number.isNaN(v))).toBe(true)
       })
     }
   }

From f43708ed7c56717e766fd09036f87ab53e079532 Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Wed, 4 Nov 2026 23:19:14 +0000
Subject: [PATCH 25/38] perf(view): settle the element map before the picture,
 not after

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/commands/core/view.ts | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/commands/core/view.ts b/src/commands/core/view.ts
index d284eb9d..db80458f 100644
--- a/src/commands/core/view.ts
+++ b/src/commands/core/view.ts
@@ -313,12 +313,12 @@ const render: Command<{ width?: number; height?: number; view?: StandardView; vi
         await nextFrame(scene)
       }
       await sectioned(scene, section)
+      // The map in the picture, and what is said of it, is the one measured
+      // for what the view was just told, not the one before it.
+      await mapSettled(scene)
       const pictured = views ? await sheetOfViews(scene, views, width, height, show) : await picture(scene, width, height, view, show)
       // A sheet of views fits each; otherwise only fit: true does.
       const framed = framing(scaleOf(scene), frame, Boolean(views) || (!frame && fit === true))
-      // What the picture says of the map is said of the one measured, not of
-      // the one before it.
-      await mapSettled(scene)
       return { ...pictured, ...framed, ...whyOf(scene, show), ...absentOf(done), ...describeMapPainted(scene.mapPainted()) }
     } finally {
       // What was put away or cut for the picture comes back; the frame stays.

From 8ae5c375824f5d1a81a5f922fd551828deace244 Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Wed, 4 Nov 2026 23:34:54 +0000
Subject: [PATCH 26/38] perf(app): scene sync in a leaf component

useSceneSync and useElementField subscribe to some seventy store fields; called from the Workbench every write to one re-rendered the whole workspace. They now live in a memoised SceneSync that draws nothing, mounted after the viewport.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 src/App.tsx           | 47 +++++++++++++++++-----------------
 src/app/SceneSync.tsx | 59 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 82 insertions(+), 24 deletions(-)
 create mode 100644 src/app/SceneSync.tsx

diff --git a/src/App.tsx b/src/App.tsx
index eef8de67..360c01c2 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -92,8 +92,7 @@ import { rigidToColumnMajor } from './core/deviation/rigid'
 import { exportElementsStep, exportScanMesh, exportScanPointCloud, runExport, saveBuilt, textBytes, type BuiltFile } from './app/exports'
 import type { MeshFormat } from './core/exportMesh'
 import { PICK_MARK_TOOL_STATUS } from './app/deviationWorkspace'
-import { useElementField } from './app/useElementField'
-import { useSceneSync } from './app/useSceneSync'
+import { SceneSync } from './app/SceneSync'
 import { createSession, type AppSession } from './app/session'
 import { installCommandHost, type FlatHost, type FlatSheetView, type ProjectHost } from './commands/host'
 import { commandRunning } from './commands/activity'
@@ -624,9 +623,7 @@ function Workbench() {
   } = session.deviation
 
   // ---- Deviation from a fitted element -------------------------------------
-
-  useElementField({ sceneRef, clientRef, elementField, elementRgb, elementScope, fieldDirections })
-
+  // The map against an element follows its target in SceneSync, below.
 
   /** Switch the element map between measuring the whole scan and measuring a
    *  hand-marked region of it. Choosing the marked scope opens the marking
@@ -1221,8 +1218,9 @@ function Workbench() {
     // Runs on the listed dependencies only, not on everything it reads.
   }, [draftOpen, windowKey])
 
-  // Everything the scene is told after a render lives in useSceneSync; the
-  // subscriptions here are the ones the JSX below still reads itself.
+  // Everything the scene is told after a render lives in useSceneSync, called
+  // from SceneSync so its subscriptions wake that and not this; the ones here
+  // are the ones the JSX below still reads itself.
   const elements = useStore((s) => s.elements)
   const storeSections = useStore((s) => s.sections)
   const draft = useStore((s) => s.draft)
@@ -1265,23 +1263,6 @@ function Workbench() {
   const split = useDeviation((s) => s.split)
   const hasThicknessMap = useThickness((s) => s.status === 'ready')
 
-  useSceneSync({
-    sceneRef,
-    clientRef,
-    deviation,
-    deviationRgb,
-    referenceMap: maps.referenceMap,
-    referenceRgb: maps.referenceRgb,
-    elementField,
-    elementRgb,
-    fieldDirections,
-    thickness,
-    thicknessRgb,
-    thickScale,
-    plugin: active,
-    cancelDraft: handleCancelDraft,
-  })
-
   // Error toasts clear themselves.
   const errorText = useStore((s) => s.errorText)
   useEffect(() => {
@@ -1686,6 +1667,24 @@ function Workbench() {
               onPaintChange={handlePaintChange}
               onExtendDrag={handleExtendDrag}
             />
+            {/* After the viewport, so the scene exists when its effects first run. */}
+            <SceneSync
+              sceneRef={sceneRef}
+              clientRef={clientRef}
+              deviation={deviation}
+              deviationRgb={deviationRgb}
+              referenceMap={maps.referenceMap}
+              referenceRgb={maps.referenceRgb}
+              elementField={elementField}
+              elementRgb={elementRgb}
+              elementScope={elementScope}
+              fieldDirections={fieldDirections}
+              thickness={thickness}
+              thicknessRgb={thicknessRgb}
+              thickScale={thickScale}
+              plugin={active}
+              cancelDraft={handleCancelDraft}
+            />
             {!splitOpen && pluginSplit}
             {splitOpen && (
               <div className="splitcap">
diff --git a/src/app/SceneSync.tsx b/src/app/SceneSync.tsx
new file mode 100644
index 00000000..5e54edf0
--- /dev/null
+++ b/src/app/SceneSync.tsx
@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// The scene's follower, as a component of its own. useSceneSync and
+// useElementField subscribe to some seventy store fields between them — the
+// brush, the overlays' inputs, every map's version — and a hook's subscriptions
+// belong to whoever calls it: called from the Workbench, each of those writes
+// re-rendered the whole workspace (the panels, the legends, the stage prompts)
+// only to repeat itself to the viewport as effects. Here they wake nothing but
+// this component, which draws nothing.
+//
+// It is mounted after the viewport, so on the first commit the scene exists by
+// the time these effects first run, exactly as it did when they ran in the
+// Workbench; its effects now run ahead of the Workbench's own in a commit,
+// which nothing there depends on (they act on the stores, the worker and the
+// 2D sheet, not on what the viewport was last told).
+import { memo } from 'react'
+import { useElementField } from './useElementField'
+import { useSceneSync } from './useSceneSync'
+
+export type SceneSyncProps = Parameters<typeof useSceneSync>[0] & Parameters<typeof useElementField>[0]
+
+export const SceneSync = memo(function SceneSync({
+  sceneRef,
+  clientRef,
+  deviation,
+  deviationRgb,
+  referenceMap,
+  referenceRgb,
+  elementField,
+  elementRgb,
+  elementScope,
+  fieldDirections,
+  thickness,
+  thicknessRgb,
+  thickScale,
+  plugin,
+  cancelDraft,
+}: SceneSyncProps): null {
+  // The element map before the rest of the scene's follower, as the Workbench
+  // called them: it measures on a change of target, and the repaint below
+  // paints whatever it settles.
+  useElementField({ sceneRef, clientRef, elementField, elementRgb, elementScope, fieldDirections })
+  useSceneSync({
+    sceneRef,
+    clientRef,
+    deviation,
+    deviationRgb,
+    referenceMap,
+    referenceRgb,
+    elementField,
+    elementRgb,
+    fieldDirections,
+    thickness,
+    thicknessRgb,
+    thickScale,
+    plugin,
+    cancelDraft,
+  })
+  return null
+})

From 02505cc989f7a0cbb8b6d4dfb1ee339d2e3d33c1 Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Thu, 5 Nov 2026 00:11:29 +0000
Subject: [PATCH 27/38] perf(probe): idle row after a second's grace, 0 frame
 callbacks wanted

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 scripts/perf-probe.mjs | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/scripts/perf-probe.mjs b/scripts/perf-probe.mjs
index 7c7629d0..3898ba44 100644
--- a/scripts/perf-probe.mjs
+++ b/scripts/perf-probe.mjs
@@ -798,6 +798,11 @@ try {
   if (rich && probesPinned < 5) budgetFails.push(`BUDGET FAIL: rich scenario: ${probesPinned === Infinity ? 'no' : probesPinned} deviation probes pinned, 5 wanted`)
 
   // ---- idle cost: what the page burns doing nothing ---------------------------------
+  // A second's grace first: a viewport winds its loop down over a few dozen
+  // frames after the last thing that moved, and those frames are the end of
+  // the last tap, not idling. After that an idle page runs no frame callback
+  // at all — a phone's battery pays for every one.
+  await sleep(1000)
   await page.evaluate(() => (window.__idle0 = window.__gl.raf))
   await cdp.send('Profiler.start')
   await sleep(3000)
@@ -807,8 +812,9 @@ try {
     const nd = idleProfile.nodes.find((n) => n.id === idleProfile.samples[i])
     return nd.callFrame.functionName === '(idle)' ? s : s + d
   }, 0) / 1000
-  console.log(`\n## Idle (3 s, nothing touched): ${idleRaf} animation-frame callbacks ran, main thread busy ${idleBusy.toFixed(0)}ms`)
+  console.log(`\n## Idle (3 s after 1 s idle, nothing touched): ${idleRaf} animation-frame callbacks ran, main thread busy ${idleBusy.toFixed(0)}ms`)
   for (const h of hot(idleProfile, 6)) console.log('   cpu:', h)
+  if (idleRaf > 0) budgetFails.push(`BUDGET FAIL: idle: ${idleRaf} frame callbacks in 3 s, 0 wanted`)
 
   // ---- summary --------------------------------------------------------------------------
   console.log(`\n## Summary — ${isDev ? 'dev' : 'production'}, ${SCENARIO}, PERF_RUNS=${RUNS}, ${THROTTLE}x throttle, ${fileInfo}`)

From c5ebab2ccab528ced7e1d048eb8a8e924d6562ec Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Thu, 5 Nov 2026 00:42:31 +0000
Subject: [PATCH 28/38] perf(viewport): sleep when idle, no per-frame layout
 reads

The viewport loop asked for a frame 60 times a second per viewport even
with nothing to draw (1305 frame callbacks in 3 s idle on the probe).
It now sleeps after 30 idle frames; invalidate, canvas pointer/touch/
wheel, window keys, resize, tab shown, SpaceMouse attach, animateLook,
un-pause and a linked view's invalidate wake it. keepAwake holds it for
the deviation motion, a queued stroke and a pending section dressing.

The canvas size is cached in resize() (0x0 never cached over a real
size), so worldPerPixel, the frame, the frustum and the ticks read no
layout; followView no longer forces a layout pass per frame. spreadLabels
measures a label again only when its text or classes change; the
navigator's rect cache also expires per task; hover hit tests use it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 plugins/reverse/tests/reSceneBlocks.test.ts |   1 +
 plugins/reverse/viewer/networkLayer.ts      |   2 +-
 plugins/reverse/viewer/notePins.ts          |   2 +-
 src/viewer/CompareScene.ts                  |   4 +
 src/viewer/FlatScene.ts                     |  12 +-
 src/viewer/PickScene.ts                     |   4 +
 src/viewer/SceneManager.ts                  |  72 ++++++----
 src/viewer/cameraLink.ts                    |  18 +++
 src/viewer/frameLoop.ts                     |  77 +++++++++++
 src/viewer/labelSpread.ts                   |  22 ++-
 src/viewer/marking.ts                       |  10 ++
 src/viewer/orthoNav.ts                      |  27 +++-
 src/viewer/orthoViewport.ts                 | 145 ++++++++++++++++----
 src/viewer/sceneLayers.ts                   |   5 +
 tests/frameLoop.test.ts                     | 110 +++++++++++++++
 tests/labelSpread.test.ts                   |  28 ++++
 16 files changed, 467 insertions(+), 72 deletions(-)
 create mode 100644 src/viewer/frameLoop.ts
 create mode 100644 tests/frameLoop.test.ts

diff --git a/plugins/reverse/tests/reSceneBlocks.test.ts b/plugins/reverse/tests/reSceneBlocks.test.ts
index da683bcb..c0733ddf 100644
--- a/plugins/reverse/tests/reSceneBlocks.test.ts
+++ b/plugins/reverse/tests/reSceneBlocks.test.ts
@@ -44,6 +44,7 @@ function stage(): { scene: SceneManager; part: THREE.Group } {
     partGroup: part,
     raycaster: new THREE.Raycaster(),
     canvas: { getBoundingClientRect: () => ({ left: 0, top: 0, width: 800, height: 600 }) } as unknown as HTMLCanvasElement,
+    canvasRect: () => ({ left: 0, top: 0, width: 800, height: 600 }) as DOMRect,
     container: {} as HTMLElement,
     camera: () => camera,
     setPickRay: () => {},
diff --git a/plugins/reverse/viewer/networkLayer.ts b/plugins/reverse/viewer/networkLayer.ts
index d3b48526..2dc39ee3 100644
--- a/plugins/reverse/viewer/networkLayer.ts
+++ b/plugins/reverse/viewer/networkLayer.ts
@@ -789,7 +789,7 @@ export class NetworkLayer {
   private projector(): (p: ArrayLike<number>, i?: number) => { x: number; y: number } {
     const camera = this.host.camera()
     const e = new THREE.Matrix4().multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse).multiply(this.host.partGroup.matrixWorld).elements
-    const r = this.host.canvas.getBoundingClientRect()
+    const r = this.host.canvasRect()
     return (p, i = 0) => {
       const x = p[i], y = p[i + 1], z = p[i + 2]
       const w = e[3] * x + e[7] * y + e[11] * z + e[15]
diff --git a/plugins/reverse/viewer/notePins.ts b/plugins/reverse/viewer/notePins.ts
index ea77d4d2..d1132286 100644
--- a/plugins/reverse/viewer/notePins.ts
+++ b/plugins/reverse/viewer/notePins.ts
@@ -297,7 +297,7 @@ export class NotePins {
   /** A pin's badge centre on the screen, in client pixels. */
   private badgeCentre(pin: Pin): { x: number; y: number } {
     const p = pin.badge.getWorldPosition(new THREE.Vector3()).project(this.host.camera())
-    const r = this.host.canvas.getBoundingClientRect()
+    const r = this.host.canvasRect()
     const off = (BADGE_OFFSET + 0.5) * badgePx(pin)
     return { x: r.left + ((p.x + 1) / 2) * r.width + off, y: r.top + ((1 - p.y) / 2) * r.height - off }
   }
diff --git a/src/viewer/CompareScene.ts b/src/viewer/CompareScene.ts
index a05518d2..9981d4f6 100644
--- a/src/viewer/CompareScene.ts
+++ b/src/viewer/CompareScene.ts
@@ -103,6 +103,8 @@ export class CompareScene {
   /** Hold this half in the same pose as the scan's viewport, in both
    *  directions: either half can be the one under the hand. */
   linkTo(scan: LinkedView): void {
+    // The link before goes: it would go on waking both halves.
+    this.link?.dispose()
     this.link = new CameraLink(scan, this.viewport.viewLink())
   }
 
@@ -209,6 +211,8 @@ export class CompareScene {
   }
 
   dispose(): void {
+    this.link?.dispose()
+    this.link = null
     this.cap?.dispose()
     this.capGeometry.dispose()
     this.material.dispose()
diff --git a/src/viewer/FlatScene.ts b/src/viewer/FlatScene.ts
index b39e539c..53d2a37c 100644
--- a/src/viewer/FlatScene.ts
+++ b/src/viewer/FlatScene.ts
@@ -323,10 +323,10 @@ export class FlatScene {
         // ruled over.
         if (this.gridFrame && this.gridStale()) this.rebuildGrid()
         if (this.sketchDims && Math.abs(this.unitsPerScreenPx() / this.sketchDims.px - 1) > 0.01) this.rebuildDimStrokes()
-        // Fat lines are sized in screen pixels and need to know the canvas.
-        const el = this.viewport.renderer.domElement
-        const w = el.clientWidth || 1
-        const h = el.clientHeight || 1
+        // Fat lines are sized in screen pixels and need to know the canvas:
+        // its cached size, as a read of the layout every frame is a forced
+        // layout pass after any DOM write.
+        const { w, h } = this.viewport.size
         if (this.fatLines.setResolution(w, h)) {
           this.edgeMaterial.resolution.copy(this.fatLines.resolution)
           this.viewport.invalidate()
@@ -1109,9 +1109,7 @@ export class FlatScene {
   /** Document units per screen pixel at the current zoom — what turns a snap
    *  radius the hand understands into one the sheet understands. */
   unitsPerScreenPx(): number {
-    const cam = this.viewport.camera
-    const h = this.viewport.renderer.domElement.clientHeight || 1
-    return (cam.top - cam.bottom) / cam.zoom / h
+    return this.viewport.worldPerPixel()
   }
 
   /** The polyline a fit draws as: a segment, a full circle, an arc. A point
diff --git a/src/viewer/PickScene.ts b/src/viewer/PickScene.ts
index 5f836b4a..5bdbeaff 100644
--- a/src/viewer/PickScene.ts
+++ b/src/viewer/PickScene.ts
@@ -89,6 +89,8 @@ export class PickScene {
         this.marking?.drainStroke()
         this.updateHover()
       },
+      // A stroke's positions still queued for the next frame to land.
+      keepAwake: () => this.marking?.strokePending() === true,
       onClick: (x, y) => {
         const point = this.pick(x, y)
         if (point) this.onPick?.(point)
@@ -151,9 +153,11 @@ export class PickScene {
         this.viewport.invalidate()
       },
       invalidate: this.viewport.invalidate,
+      wake: this.viewport.wake,
       claimDrag: (on) => this.viewport.nav.setPaintMode(on),
       requestHover: () => {
         this.hoverDirty = true
+        this.viewport.wake()
       },
       onPaintChange: (count) => this.onPaintChange?.(count),
     })
diff --git a/src/viewer/SceneManager.ts b/src/viewer/SceneManager.ts
index 686f195f..6ec63c2f 100644
--- a/src/viewer/SceneManager.ts
+++ b/src/viewer/SceneManager.ts
@@ -531,19 +531,22 @@ export class SceneManager {
         // Anything held at a fixed size on screen — the picked-point markers —
         // has to be re-scaled when the zoom changes. A no-op on the frames it
         // has not.
-        this.overlays.setPixelScale(this.viewport.worldPerPixel())
-        this.sections.setPixelScale(this.viewport.worldPerPixel())
+        const pixel = this.viewport.worldPerPixel()
+        this.overlays.setPixelScale(pixel)
+        this.sections.setPixelScale(pixel)
         // Pins on the far side of the part go away as it turns, if asked to;
         // a no-op unless the view moved.
         this.overlays.updateProbeOcclusion()
-        // The section curves are fat lines sized in pixels and need the canvas.
-        const el = this.viewport.renderer.domElement
-        this.sections.setResolution(el.clientWidth || 1, el.clientHeight || 1)
-        for (const layer of this.layers) layer.tick?.(el.clientWidth || 1, el.clientHeight || 1)
+        // The section curves are fat lines sized in pixels and need the
+        // canvas's size: the viewport's cached one, since a read of the
+        // layout every frame is a forced layout pass after any DOM write.
+        const { w, h } = this.viewport.size
+        this.sections.setResolution(w, h)
+        for (const layer of this.layers) layer.tick?.(w, h)
         // A viewport that follows a sheet re-reads its scale when its own
         // size changes — shown again after being put away, or the window
         // resized — since the scale is millimetres per pixel.
-        if (this.sheetFollow && (el.clientWidth !== this.followedSize.w || el.clientHeight !== this.followedSize.h)) {
+        if (this.sheetFollow && this.viewport.shown && (w !== this.followedSize.w || h !== this.followedSize.h)) {
           this.applyFollow(0)
         }
         this.stepDeflection()
@@ -557,6 +560,10 @@ export class SceneManager {
         this.syncCopies()
       },
       onAfterRender: (w, h) => this.drawGizmo(w, h),
+      // What wants frames although nothing is marked yet: the motion of the
+      // deviation map, a stroke's positions still queued, and what is drawn
+      // on the part waiting to be dressed for the section view's cut.
+      keepAwake: () => this.deflectionPlaying() || this.marking.strokePending() || this.clipDirty,
     })
     this.container = container
     this.gizmo = new AxisGizmo()
@@ -584,10 +591,9 @@ export class SceneManager {
         this.invalidate()
       },
       invalidate: this.invalidate,
+      wake: this.viewport.wake,
       claimDrag: (on) => this.claimDrag('paint', on),
-      requestHover: () => {
-        this.hoverDirty = true
-      },
+      requestHover: this.requestHover,
       onPaintChange: (count) => this.onPaintChange?.(count),
     })
     this.overlays = new Overlays({
@@ -617,9 +623,7 @@ export class SceneManager {
       modelRadius: () => this.modelRadius,
       invalidate: this.invalidate,
       claimDrag: (on) => this.claimDrag('handle', on),
-      requestHover: () => {
-        this.hoverDirty = true
-      },
+      requestHover: this.requestHover,
       onExtendDrag: (side, delta, phase) => this.onExtendDrag?.(side, delta, phase),
       // Only an element's ghost has ends to mark; a section plane's gizmo
       // stands on a sheet that is its own mark, and a plugin's grips are on
@@ -663,6 +667,13 @@ export class SceneManager {
     this.viewport.invalidate()
   }
 
+  /** What is under the cursor is to be looked at again on the next frame —
+   *  which the loop may have stopped asking for. */
+  private requestHover = (): void => {
+    this.hoverDirty = true
+    this.viewport.wake()
+  }
+
   /** Swap the pointer-button control scheme (dropdown in the settings dialog). */
   setNavScheme(scheme: ControlScheme): void {
     this.viewport.setNavScheme(scheme)
@@ -730,7 +741,7 @@ export class SceneManager {
 
   /** The gizmo arrow under a client point, if any. */
   private gizmoAt(clientX: number, clientY: number): GizmoAxis | null {
-    const rect = this.viewport.renderer.domElement.getBoundingClientRect()
+    const rect = this.viewport.canvasRect()
     return this.gizmo.hitTest(clientX - rect.left, clientY - rect.top)
   }
 
@@ -1393,8 +1404,7 @@ export class SceneManager {
   }
 
   viewSize(): { width: number; height: number } {
-    const el = this.viewport.renderer.domElement
-    return { width: el.clientWidth || 1, height: el.clientHeight || 1 }
+    return { width: this.viewport.size.w, height: this.viewport.size.h }
   }
 
   /** What a picture of the view as it stands spans at `width` × `height`
@@ -1455,12 +1465,10 @@ export class SceneManager {
   private applyFollow(ms: number): void {
     const f = this.sheetFollow
     if (!f) return
-    const el = this.viewport.renderer.domElement
-    const w = el.clientWidth
-    const h = el.clientHeight
     // Put away: nothing to size by until it is shown again — the tick
     // applies it then.
-    if (!w || !h) return
+    if (!this.viewport.shown) return
+    const { w, h } = this.viewport.size
     this.followedSize = { w, h }
     this.partGroup.updateMatrixWorld(true)
     const m = this.partGroup.matrixWorld
@@ -2119,14 +2127,14 @@ export class SceneManager {
 
   setElementPickEnabled(enabled: boolean): void {
     this.elementPickEnabled = enabled
-    this.hoverDirty = true
+    this.requestHover()
   }
 
   /** Narrow element picking to the given elements (null: any) — see
    *  elementPickOnly. */
   setElementPickOnly(ids: ReadonlySet<number> | null): void {
     this.elementPickOnly = ids
-    this.hoverDirty = true
+    this.requestHover()
   }
 
   /** Whether the element under the cursor lights while element picking is
@@ -2257,7 +2265,7 @@ export class SceneManager {
   setSectionPickEnabled(enabled: boolean): void {
     if (this.sectionPickEnabled === enabled) return
     this.sectionPickEnabled = enabled
-    this.hoverDirty = true
+    this.requestHover()
   }
 
   /** Make the given elements read as selected: their translucent shells get
@@ -2386,7 +2394,7 @@ export class SceneManager {
     this.sections.setWorldPlanes(centre)
     // The cursor may be over a plane that has just gone, or one that has
     // just arrived under it.
-    this.hoverDirty = true
+    this.requestHover()
   }
 
   /** The coordinate plane under a client point, if one is on offer there.
@@ -3197,9 +3205,7 @@ export class SceneManager {
   /** Where the loop is this frame. Playing, it draws every frame — that is
    *  what it is for; at rest it costs a comparison. */
   private stepDeflection(): void {
-    const d = this.deflection
-    const playing = d !== null && this.mesh !== null && this.mesh.visible && d.geometry === this.mesh.geometry
-    if (!playing) {
+    if (!this.deflectionPlaying()) {
       // Off the geometry on screen, the attribute is not there to be read
       // and the shader must not add anything at all.
       if (this.uDeflect.value !== 0) {
@@ -3213,6 +3219,13 @@ export class SceneManager {
     this.invalidate()
   }
 
+  /** Whether the loop is playing: there is motion, laid on the geometry on
+   *  screen, and the scan is shown. */
+  private deflectionPlaying(): boolean {
+    const d = this.deflection
+    return d !== null && this.mesh !== null && this.mesh.visible && d.geometry === this.mesh.geometry
+  }
+
   /** Paint a reading on some of the scan's vertices, leaving the rest as
    *  they are, or pass null to lift it. See regionColors.setSparseField. */
   setSparseField(subset: Uint32Array | null, rgb: Uint8Array | null): void {
@@ -3339,13 +3352,12 @@ export class SceneManager {
       partGroup: this.partGroup,
       raycaster: this.raycaster,
       canvas: this.viewport.renderer.domElement,
+      canvasRect: () => this.viewport.canvasRect(),
       container: this.container,
       camera: () => this.camera,
       setPickRay: (x, y) => this.setPickRay(x, y),
       invalidate: this.invalidate,
-      requestHover: () => {
-        this.hoverDirty = true
-      },
+      requestHover: this.requestHover,
       setCursor: (cursor) => {
         this.viewport.renderer.domElement.style.cursor = cursor
       },
diff --git a/src/viewer/cameraLink.ts b/src/viewer/cameraLink.ts
index b32aa231..04859d14 100644
--- a/src/viewer/cameraLink.ts
+++ b/src/viewer/cameraLink.ts
@@ -27,6 +27,11 @@ export interface LinkedView {
   extents: () => { halfW: number; halfH: number }
   setExtents: (halfW: number, halfH: number) => void
   invalidate: () => void
+  /** Run this view's frames again if they had stopped — see FrameLoop. */
+  wake: () => void
+  /** Be told whenever this view is marked for drawing, which a move of its
+   *  camera always is; returns the unsubscribe. */
+  watch: (fn: () => void) => () => void
 }
 
 interface Pose {
@@ -99,10 +104,16 @@ function push(from: LinkedView, to: LinkedView): void {
  * telling that echo apart from a genuine gesture costs more than the dozen
  * float comparisons a tick does here. Whoever has moved since the last tick is
  * the driver; a frame in which neither has costs nothing.
+ *
+ * A view's frames stop while nothing changes in it (see FrameLoop), and the
+ * loop polling the link may be the one standing still while the other half
+ * is dragged. So each half wakes the other whenever it is marked for
+ * drawing, which a move of its camera always is.
  */
 export class CameraLink {
   private poseA = emptyPose()
   private poseB = emptyPose()
+  private unwatch: (() => void)[]
 
   constructor(
     private a: LinkedView,
@@ -111,6 +122,13 @@ export class CameraLink {
     push(a, b)
     readPose(a, this.poseA)
     readPose(b, this.poseB)
+    this.unwatch = [a.watch(b.wake), b.watch(a.wake)]
+  }
+
+  /** Let go of both views: a link replaced, or its half closed. */
+  dispose(): void {
+    for (const off of this.unwatch) off()
+    this.unwatch = []
   }
 
   tick(): void {
diff --git a/src/viewer/frameLoop.ts b/src/viewer/frameLoop.ts
new file mode 100644
index 00000000..9853139a
--- /dev/null
+++ b/src/viewer/frameLoop.ts
@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * A viewport's frame loop that goes to sleep when there is nothing to draw.
+ *
+ * Render-on-demand already skipped the drawing on a still frame, but the
+ * loop itself kept asking the browser for a frame sixty times a second, and
+ * every one of those ran the owner's tick: a phone held still on a part was
+ * waking its CPU for nothing, for as long as the page was open. So after a
+ * run of frames with nothing to do the loop stops asking, and the first thing
+ * that could change the picture — an invalidate, a hand on the canvas, a key,
+ * a resize — wakes it again.
+ *
+ * Kept apart from the viewport so the sleeping and waking can be tested
+ * without a WebGL context.
+ */
+
+/** How many frames in a row with nothing to do before the loop sleeps:
+ *  half a second at 60 Hz. Long enough that whatever settles a frame or two
+ *  after the last change — a hover pass, a grip re-scaled to the zoom, a
+ *  layer's tick catching up with the camera — still gets its frames, short
+ *  enough that a still screen costs nothing soon after. */
+export const IDLE_FRAMES = 30
+
+export interface FrameScheduler {
+  request(cb: () => void): number
+  cancel(id: number): void
+}
+
+const browserFrames: FrameScheduler = {
+  request: (cb) => requestAnimationFrame(cb),
+  cancel: (id) => cancelAnimationFrame(id),
+}
+
+export class FrameLoop {
+  private id = 0
+  private idle = 0
+  private stopped = false
+
+  /** `step` runs once a frame and says whether the frame had anything to do
+   *  — drew, or has something under way that will want the next one. */
+  constructor(
+    private step: () => boolean,
+    private frames: FrameScheduler = browserFrames,
+  ) {}
+
+  /** Whether a frame is asked for: false while the loop sleeps. */
+  get awake(): boolean {
+    return this.id !== 0
+  }
+
+  /** Something may have changed: run frames again, if they had stopped,
+   *  and count the idle run from here. Cheap enough to call on every
+   *  invalidate and every pointer move. */
+  wake = (): void => {
+    this.idle = 0
+    if (this.id !== 0 || this.stopped) return
+    this.id = this.frames.request(this.tick)
+  }
+
+  /** For good: the viewport is going. */
+  stop(): void {
+    this.stopped = true
+    if (this.id !== 0) this.frames.cancel(this.id)
+    this.id = 0
+  }
+
+  private tick = (): void => {
+    // Asked for ahead of the step, so a wake from inside it finds the next
+    // frame already asked for rather than asking a second time.
+    this.id = this.frames.request(this.tick)
+    if (this.step()) this.idle = 0
+    else if (++this.idle >= IDLE_FRAMES) {
+      this.frames.cancel(this.id)
+      this.id = 0
+    }
+  }
+}
diff --git a/src/viewer/labelSpread.ts b/src/viewer/labelSpread.ts
index 7833b833..9e93930f 100644
--- a/src/viewer/labelSpread.ts
+++ b/src/viewer/labelSpread.ts
@@ -13,6 +13,25 @@
 /** Sub-pixel distances two labels may still be apart and count as clear. */
 const SLACK = 1e-6
 
+/** Each label's size as last measured, with the text and classes it was
+ *  measured with. A label's offsetWidth read after the renderer has just
+ *  written every label's transform is a forced layout pass — every frame
+ *  the view moves, for sizes that only change when the text does. So a
+ *  label is measured again only when its text or its classes changed (an
+ *  empty note's italic, a pin cut away). A label measured at nothing — out
+ *  of the layout at the time — is not kept, and is measured again. */
+const sizes = new WeakMap<HTMLElement, { w: number; h: number; text: string | null; cls: string }>()
+
+function sizeOf(el: HTMLElement): { w: number; h: number } {
+  const text = el.textContent
+  const cls = el.className
+  const known = sizes.get(el)
+  if (known && known.text === text && known.cls === cls) return known
+  const measured = { w: el.offsetWidth, h: el.offsetHeight, text, cls }
+  if (measured.w > 0 || measured.h > 0) sizes.set(el, measured)
+  return measured
+}
+
 export function spreadLabels(labelDom: HTMLElement, gap = 2): void {
   const els = Array.from(labelDom.querySelectorAll<HTMLElement>('.viewport-label')).filter(
     (el) => el.style.display !== 'none',
@@ -25,8 +44,7 @@ export function spreadLabels(labelDom: HTMLElement, gap = 2): void {
     const m = /translate\((-?[\d.]+)px,\s*(-?[\d.]+)px\)\s*$/.exec(el.style.transform)
     const cx = m ? parseFloat(m[1]) : 0
     const cy = m ? parseFloat(m[2]) : 0
-    const w = el.offsetWidth
-    const h = el.offsetHeight
+    const { w, h } = sizeOf(el)
     return { el, x0: cx - w / 2, x1: cx + w / 2, y0: cy - h / 2, y1: cy + h / 2, dy: 0 }
   })
   boxes.sort((a, b) => b.y1 - a.y1)
diff --git a/src/viewer/marking.ts b/src/viewer/marking.ts
index 734b8c3e..abebe0ed 100644
--- a/src/viewer/marking.ts
+++ b/src/viewer/marking.ts
@@ -155,6 +155,10 @@ export interface MarkingContext {
    *  costs nothing per vertex. */
   setPaintColor(rgb: [number, number, number]): void
   invalidate(): void
+  /** Run the viewport's frames again, if they had stopped: a stroke's
+   *  positions are queued for the next frame to land, and a stroke carried
+   *  off the canvas wakes nothing there. */
+  wake(): void
   /** Take the plain drags off the camera while a gesture is live. */
   claimDrag(on: boolean): void
   /** Ask for a hover pass on the next frame (the footprint follows settings
@@ -656,6 +660,12 @@ export class SurfaceMarking {
     // gets.
     this.flushPendingDab()
     this.strokeQueue.push({ x: e.clientX, y: e.clientY, erase: erasing })
+    this.ctx.wake()
+  }
+
+  /** Whether a stroke has positions buffered for the next frame to land. */
+  strokePending(): boolean {
+    return this.strokeQueue.length > 0
   }
 
   /** Land the dabs for every position a stroke buffered since the last frame.
diff --git a/src/viewer/orthoNav.ts b/src/viewer/orthoNav.ts
index 0a54545d..c090bbc0 100644
--- a/src/viewer/orthoNav.ts
+++ b/src/viewer/orthoNav.ts
@@ -113,10 +113,11 @@ export class OrthoNavigator {
   private q2 = new THREE.Quaternion()
   private q3 = new THREE.Quaternion()
   private pickNdc = new THREE.Vector2()
-  /** The canvas rect, asked of the layout engine at most once per frame:
-   *  getBoundingClientRect can force a layout pass, and setPickRay runs for
-   *  every dab of a brush stroke. Cleared in updateClipPlanes, which the owner
-   *  already calls once per frame. */
+  /** The canvas rect, asked of the layout engine at most once per frame or
+   *  task: getBoundingClientRect can force a layout pass, and setPickRay runs
+   *  for every dab of a brush stroke. Cleared in updateClipPlanes, which the
+   *  owner already calls once per frame, and at the end of the task that
+   *  read it — see canvasRect. */
   private rect: DOMRect | null = null
 
   constructor(
@@ -129,6 +130,9 @@ export class OrthoNavigator {
      *  hiding a model takes it out of reach. */
     private orbitTargets: () => THREE.Object3D[],
     private clipSphere: ClipSphere,
+    /** The canvas's height in CSS pixels: the viewport's cached size, so a
+     *  pan step reads no layout. */
+    private canvasHeight: () => number = () => canvas.clientHeight,
   ) {
     this.pivotMarker = new THREE.Mesh(
       new THREE.SphereGeometry(1, 16, 10),
@@ -309,8 +313,17 @@ export class OrthoNavigator {
     if (back < 0) ray.recast(back)
   }
 
-  private canvasRect(): DOMRect {
-    if (!this.rect) this.rect = this.canvas.getBoundingClientRect()
+  canvasRect(): DOMRect {
+    if (!this.rect) {
+      this.rect = this.canvas.getBoundingClientRect()
+      // And forgotten once this task is done as well: the frames that clear
+      // it stop while the view stands still, and the canvas can be moved
+      // under a still view — a panel opening beside it — before the next
+      // pick, which would aim through where the canvas was.
+      queueMicrotask(() => {
+        this.rect = null
+      })
+    }
     return this.rect
   }
 
@@ -637,7 +650,7 @@ export class OrthoNavigator {
     if (dx === 0 && dy === 0) return
     // Every pan is a drag's: a mouse chord's, one finger on a sheet, two.
     this.moving = true
-    const h = Math.max(1, this.canvas.clientHeight)
+    const h = Math.max(1, this.canvasHeight())
     const worldPerPx = (this.camera.top - this.camera.bottom) / this.camera.zoom / h
     this.camera.updateMatrixWorld()
     this.right.setFromMatrixColumn(this.camera.matrixWorld, 0).normalize()
diff --git a/src/viewer/orthoViewport.ts b/src/viewer/orthoViewport.ts
index dfbd3269..a970e2b0 100644
--- a/src/viewer/orthoViewport.ts
+++ b/src/viewer/orthoViewport.ts
@@ -11,6 +11,7 @@ import { OrbitControls } from 'three/addons/controls/OrbitControls.js'
 import { CSS2DRenderer } from 'three/addons/renderers/CSS2DRenderer.js'
 import { spreadLabels } from './labelSpread'
 import type { LinkedView } from './cameraLink'
+import { FrameLoop } from './frameLoop'
 import type { ControlScheme } from './navSchemes'
 import { OrthoNavigator } from './orthoNav'
 import {
@@ -19,6 +20,7 @@ import {
   readSpaceMouse,
   releaseSpaceMouse,
   spaceMouseAttached,
+  watchSpaceMouse,
 } from './spaceMouse'
 import type { ViewTheme } from './viewThemes'
 
@@ -134,6 +136,10 @@ export interface OrthoViewportOptions {
   /** Runs after the scene render, before the labels — a corner gizmo drawn
    *  into the same canvas goes here. */
   onAfterRender?: (width: number, height: number) => void
+  /** Whether the owner has something under way that wants frames although
+   *  nothing is marked for drawing yet — a stroke still queued, a motion
+   *  playing. Asked before the loop goes to sleep; see FrameLoop. */
+  keepAwake?: () => boolean
   /** A see-through canvas with no stage of its own: what a viewport laid
    *  over another one is — the sketch sheet over the 3D view. */
   transparent?: boolean
@@ -162,9 +168,30 @@ export class OrthoViewport {
   readonly clipSphere = { center: new THREE.Vector3(), radius: 1 }
   /** Skips rendering entirely while the viewport is hidden (behind the
    *  split-screen picker, or kept alive behind `hidden` after its split or 2D
-   *  view was closed); everything loaded stays loaded. A paused tick reads no
-   *  layout and draws nothing. */
-  paused = false
+   *  view was closed); everything loaded stays loaded. A paused viewport asks
+   *  for no frames at all — its loop winds down and nothing wakes it — and
+   *  lets go of the SpaceMouse; shown again, it wakes. */
+  get paused(): boolean {
+    return this.isPaused
+  }
+  set paused(paused: boolean) {
+    if (paused === this.isPaused) return
+    this.isPaused = paused
+    if (paused) releaseSpaceMouse(this)
+    else this.wake()
+  }
+  private isPaused = false
+  /** The container's size in CSS pixels as of the last resize — what the
+   *  frame, the frustum and worldPerPixel read rather than asking the layout
+   *  engine, which after any DOM write is a forced layout pass on the spot.
+   *  The ResizeObserver keeps it current. Never 1 × 1 past a real size: a
+   *  viewport put away behind `hidden` keeps the size it was last shown at
+   *  (see resize). */
+  readonly size = { w: 1, h: 1 }
+  /** Whether the container has a size on the page now, as of the last
+   *  resize: false while it is put away behind `hidden`, where `size` still
+   *  holds the size it was shown at. */
+  shown = false
   /** Half-extents of the model on the screen plane at the framing camera
    *  orientation; the frustum is rebuilt from these on every resize so the
    *  user's zoom survives. */
@@ -172,7 +199,16 @@ export class OrthoViewport {
   private resizeObserver: ResizeObserver
   /** Whether the container has ever had a size — see resize. */
   private sized = false
-  private rafId = 0
+  /** The frame loop, asleep whenever there is nothing to draw — see
+   *  FrameLoop. What could change the picture wakes it: invalidate, a hand
+   *  on the canvas or the keyboard, a resize, the tab shown again, a puck
+   *  attached. */
+  private loop: FrameLoop
+  /** Told on every invalidate — a view linked to this one, which has to
+   *  look whether this one moved (see CameraLink). */
+  private invalidateWatchers = new Set<() => void>()
+  /** What dispose takes down besides the canvas's own listeners. */
+  private unlisten: (() => void)[] = []
   private pointerDown: { x: number; y: number } | null = null
   /** Fingers down on the canvas, and whether this touch has been more than one
    *  of them at any point. A tap picks, but the moment a second finger lands
@@ -180,10 +216,11 @@ export class OrthoViewport {
    *  and end within the drag threshold must not also fit a sphere. */
   private touchIds = new Set<number>()
   private multiTouch = false
-  /** Render-on-demand: the rAF loop keeps ticking (the early-out is nearly
-   *  free) but the scene is only drawn on frames something marked. A missed
-   *  mark shows as a stale image, so every path that could change what is on
-   *  screen calls invalidate — an extra repaint costs nothing. */
+  /** Render-on-demand: the scene is only drawn on frames something marked,
+   *  and once nothing has been marked for a while the loop stops asking for
+   *  frames at all. A missed mark shows as a stale image, so every path that
+   *  could change what is on screen calls invalidate — an extra repaint
+   *  costs nothing — and invalidate wakes the loop. */
   private needsRender = true
   /** A turn of the camera under way — see animateLook. `from` is how far
    *  along the eased way the pose q0, t0, zoom0 was taken: 0 for a turn
@@ -203,9 +240,19 @@ export class OrthoViewport {
 
   invalidate = (): void => {
     this.needsRender = true
+    this.wake()
+    for (const fn of this.invalidateWatchers) fn()
+  }
+
+  /** Run frames again, if the loop had gone to sleep. A paused viewport
+   *  stays asleep: it draws nothing, and showing it wakes it. */
+  wake = (): void => {
+    if (!this.isPaused) this.loop?.wake()
   }
 
   constructor(private container: HTMLDivElement, private opts: OrthoViewportOptions) {
+    // Built first: everything below may already invalidate.
+    this.loop = new FrameLoop(() => this.frame())
     // A stencil buffer, for the cap that closes a part cut open at a plane
     // — three.js leaves it out unless asked.
     this.renderer = new THREE.WebGLRenderer({ antialias: true, powerPreference: 'high-performance', alpha: Boolean(opts.transparent), stencil: true })
@@ -235,6 +282,31 @@ export class OrthoViewport {
     this.scene.add(this.keyLight.target)
     this.setTheme(opts.theme)
 
+    // A hand on the canvas wakes the loop before anything else hears of it —
+    // capture, and ahead of the navigator's own listeners — so the hover
+    // pass, the stroke queue and the drag it starts all find frames running.
+    // A pointer leaving wakes it too: the hover it lit has to go out.
+    const canvas = this.renderer.domElement
+    for (const type of ['pointerdown', 'pointermove', 'pointerup', 'pointerleave', 'pointercancel', 'wheel', 'touchstart', 'touchmove'])
+      canvas.addEventListener(type, this.wake, { capture: true, passive: true })
+    // Keys move the view and step what is lit under the cursor, whichever
+    // element has the focus; a modifier held changes what a click would do.
+    window.addEventListener('keydown', this.wake)
+    window.addEventListener('keyup', this.wake)
+    // Shown again, the tab draws whatever was marked while it was not.
+    const visible = (): void => {
+      if (document.visibilityState === 'visible') this.wake()
+    }
+    document.addEventListener('visibilitychange', visible)
+    this.unlisten.push(
+      () => window.removeEventListener('keydown', this.wake),
+      () => window.removeEventListener('keyup', this.wake),
+      () => document.removeEventListener('visibilitychange', visible),
+      // A puck has no events to wake on: attached, it is read every frame,
+      // so the loop stays awake while one is there.
+      watchSpaceMouse(this.wake),
+    )
+
     // OrbitControls owns the target and the per-frame lookAt, nothing else:
     // its own rotate/pan/zoom are off because the control scheme decides which
     // buttons do what, and because orbiting has to happen about the point
@@ -252,6 +324,7 @@ export class OrthoViewport {
       this.renderer.domElement,
       opts.navTargets,
       this.clipSphere,
+      () => this.size.h,
     )
     this.scene.add(this.nav.pivotMarker)
     // The navigator says when a gesture changed the view; the controls'
@@ -305,7 +378,10 @@ export class OrthoViewport {
       this.endTouch(e)
     })
 
-    this.resizeObserver = new ResizeObserver(() => this.resize())
+    this.resizeObserver = new ResizeObserver(() => {
+      this.resize()
+      this.wake()
+    })
     this.resizeObserver.observe(this.container)
     this.resize()
 
@@ -313,14 +389,10 @@ export class OrthoViewport {
       this.flight = null
     })
 
-    const animate = (): void => {
-      this.rafId = requestAnimationFrame(animate)
-      this.frame()
-    }
     // Scheduled, not run inline: the owner composing this viewport is still
     // mid-constructor here, and its tick hooks reach for modules it has not
     // built yet. The first frame is one rAF away either way.
-    this.rafId = requestAnimationFrame(animate)
+    this.wake()
   }
 
   /** One frame drawn now, out of the browser's turn — while the tab is
@@ -330,10 +402,13 @@ export class OrthoViewport {
     this.frame()
   }
 
-  private frame(): void {
+  /** One frame; whether it had anything to do — drew, or has something
+   *  under way that wants the next frame — which is what keeps the loop
+   *  from going to sleep. */
+  private frame(): boolean {
     // Ahead of the pause, so that a paused viewport lets go of the puck.
     if (spaceMouseAttached()) this.stepSpaceMouse()
-    if (this.paused) return
+    if (this.isPaused) return false
     // These run every tick, rendered or not: a turn under way moves the
     // camera a step, the clip planes track the camera (and let the
     // navigator drop its cached canvas rect), update() is what notices
@@ -343,10 +418,9 @@ export class OrthoViewport {
     this.nav.updateClipPlanes()
     this.controls.update()
     this.opts.onTick?.()
-    if (!this.needsRender) return
+    if (!this.needsRender) return this.flight !== null || spaceMouseAttached() || this.opts.keepAwake?.() === true
     this.needsRender = false
-    const w = this.container.clientWidth || 1
-    const h = this.container.clientHeight || 1
+    const { w, h } = this.size
     this.keyLight.position.copy(this.camera.position)
     this.keyLight.target.position.copy(this.controls.target)
     this.renderer.setViewport(0, 0, w, h)
@@ -354,6 +428,7 @@ export class OrthoViewport {
     this.opts.onAfterRender?.(w, h)
     this.labelRenderer.render(this.scene, this.camera)
     spreadLabels(this.labelRenderer.domElement)
+    return true
   }
 
   /** One frame of the SpaceMouse. A viewport that is paused or hidden — the 3D
@@ -361,7 +436,7 @@ export class OrthoViewport {
    *  view. The puck takes the camera back from a turn under way, as a hand on
    *  the canvas does. */
   private stepSpaceMouse(): void {
-    const m = readSpaceMouse(this, !this.paused && this.container.clientWidth > 0)
+    const m = readSpaceMouse(this, !this.isPaused && this.shown)
     if (m) this.flight = null
     this.nav.stepSpaceMouse(m)
   }
@@ -400,6 +475,13 @@ export class OrthoViewport {
     return this.nav.navigating()
   }
 
+  /** The canvas's box on the page, read of the layout once a frame or a
+   *  task at most — what a hit test that runs on every hover pass measures
+   *  client points against. */
+  canvasRect(): DOMRect {
+    return this.nav.canvasRect()
+  }
+
   /** Aim the shared raycaster through the cursor. */
   setPickRay(clientX: number, clientY: number): void {
     this.nav.setPickRay(this.raycaster, clientX, clientY)
@@ -410,8 +492,10 @@ export class OrthoViewport {
    *  part — a picked-point marker — is scaled by. Parallel projection, so the
    *  figure is the same everywhere in the frame and at every depth. */
   worldPerPixel(): number {
-    const h = this.container.clientHeight || 1
-    return (this.camera.top - this.camera.bottom) / this.camera.zoom / h
+    // The cached size: this runs every frame and on every grip and marker
+    // re-scale, and a read of the layout here after any DOM write was a
+    // whole forced layout pass, most of what a tap cost.
+    return (this.camera.top - this.camera.bottom) / this.camera.zoom / this.size.h
   }
 
   /**
@@ -574,6 +658,8 @@ export class OrthoViewport {
       zoom1: goal.zoom,
       dist: goal.dist,
     }
+    // The turn plays over frames the loop may have stopped asking for.
+    this.wake()
     this.stepFlight()
   }
 
@@ -745,13 +831,18 @@ export class OrthoViewport {
       extents: () => this.fitExtent,
       setExtents: (halfW, halfH) => this.setExtents(halfW, halfH),
       invalidate: this.invalidate,
+      wake: this.wake,
+      watch: (fn) => {
+        this.invalidateWatchers.add(fn)
+        return () => this.invalidateWatchers.delete(fn)
+      },
     }
   }
 
   /** Rebuild the orthographic frustum for the current viewport aspect,
    *  leaving camera.zoom (the user's zoom) alone. */
   private applyFrustum(): void {
-    const aspect = (this.container.clientWidth || 1) / (this.container.clientHeight || 1)
+    const aspect = this.size.w / this.size.h
     const h = viewHalfHeight(this.fitExtent, aspect)
     this.camera.top = h
     this.camera.bottom = -h
@@ -815,13 +906,17 @@ export class OrthoViewport {
   resize(): void {
     const cw = this.container.clientWidth
     const ch = this.container.clientHeight
+    this.shown = cw > 0
     // A viewport kept alive behind `hidden` reports 0 × 0, and resizing to that
     // would reallocate both buffers for a size nobody sees; it keeps the last
     // one, and the real size arrives with the first resize after it is shown.
+    // So does the cached size: a 0 × 0 is never written over a real one.
     if (cw === 0 && ch === 0 && this.sized) return
     if (cw > 0 && ch > 0) this.sized = true
     const w = cw || 1
     const h = ch || 1
+    this.size.w = w
+    this.size.h = h
     this.renderer.setSize(w, h)
     this.labelRenderer.setSize(w, h)
     this.applyFrustum()
@@ -829,9 +924,11 @@ export class OrthoViewport {
   }
 
   dispose(): void {
-    cancelAnimationFrame(this.rafId)
+    this.loop.stop()
     releaseSpaceMouse(this)
     this.resizeObserver.disconnect()
+    for (const off of this.unlisten) off()
+    this.invalidateWatchers.clear()
     // The navigator listens on the document so drags can leave the canvas;
     // nothing else takes those down with the container.
     this.nav.dispose()
diff --git a/src/viewer/sceneLayers.ts b/src/viewer/sceneLayers.ts
index 120eae1f..26ccf3b9 100644
--- a/src/viewer/sceneLayers.ts
+++ b/src/viewer/sceneLayers.ts
@@ -34,6 +34,11 @@ export interface SceneLayerHost {
   readonly partGroup: THREE.Group
   readonly raycaster: THREE.Raycaster
   readonly canvas: HTMLCanvasElement
+  /** The canvas's box on the page, read of the layout at most once a frame
+   *  or a task: what a hit test run on every hover pass measures against,
+   *  rather than a getBoundingClientRect of its own that may force a layout
+   *  pass. */
+  canvasRect(): DOMRect
   /** The viewport's element, for anything laid over the canvas. */
   readonly container: HTMLElement
   camera(): THREE.OrthographicCamera
diff --git a/tests/frameLoop.test.ts b/tests/frameLoop.test.ts
new file mode 100644
index 00000000..3138c5ea
--- /dev/null
+++ b/tests/frameLoop.test.ts
@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// The viewport's frame loop: it runs while there is something to draw, sleeps
+// after a run of idle frames, and wakes on the first sign of change.
+import { describe, expect, it } from 'vitest'
+import { FrameLoop, IDLE_FRAMES, type FrameScheduler } from '../src/viewer/frameLoop'
+
+/** A stand-in for requestAnimationFrame: frames run only when `flush` says,
+ *  one browser frame at a time. */
+function fakeFrames() {
+  let next = 1
+  let queue = new Map<number, () => void>()
+  const scheduler: FrameScheduler = {
+    request: (cb) => {
+      queue.set(next, cb)
+      return next++
+    },
+    cancel: (id) => {
+      queue.delete(id)
+    },
+  }
+  /** Run `n` browser frames; how many callbacks ran. */
+  const flush = (n = 1): number => {
+    let ran = 0
+    for (let i = 0; i < n; i++) {
+      const due = queue
+      queue = new Map()
+      for (const cb of due.values()) {
+        cb()
+        ran++
+      }
+    }
+    return ran
+  }
+  return { scheduler, flush, pending: () => queue.size }
+}
+
+describe('FrameLoop', () => {
+  it('runs nothing until woken', () => {
+    const f = fakeFrames()
+    let steps = 0
+    const loop = new FrameLoop(() => (steps++, false), f.scheduler)
+    expect(loop.awake).toBe(false)
+    expect(f.flush(5)).toBe(0)
+    expect(steps).toBe(0)
+  })
+
+  it('sleeps after a run of idle frames, and asks for no frame while asleep', () => {
+    const f = fakeFrames()
+    let steps = 0
+    const loop = new FrameLoop(() => (steps++, false), f.scheduler)
+    loop.wake()
+    expect(f.flush(IDLE_FRAMES + 10)).toBe(IDLE_FRAMES)
+    expect(steps).toBe(IDLE_FRAMES)
+    expect(loop.awake).toBe(false)
+    expect(f.pending()).toBe(0)
+  })
+
+  it('stays awake while every frame has work, and counts the idle run from the last one', () => {
+    const f = fakeFrames()
+    let busy = 100
+    const loop = new FrameLoop(() => busy-- > 0, f.scheduler)
+    loop.wake()
+    expect(f.flush(100)).toBe(100)
+    expect(loop.awake).toBe(true)
+    expect(f.flush(IDLE_FRAMES + 5)).toBe(IDLE_FRAMES)
+    expect(loop.awake).toBe(false)
+  })
+
+  it('a wake mid-run starts the idle count over', () => {
+    const f = fakeFrames()
+    const loop = new FrameLoop(() => false, f.scheduler)
+    loop.wake()
+    f.flush(IDLE_FRAMES - 1)
+    loop.wake()
+    expect(f.flush(IDLE_FRAMES + 5)).toBe(IDLE_FRAMES)
+  })
+
+  it('wakes again after sleeping, one frame a frame however often it is woken', () => {
+    const f = fakeFrames()
+    let steps = 0
+    const loop = new FrameLoop(() => (steps++, false), f.scheduler)
+    loop.wake()
+    f.flush(IDLE_FRAMES)
+    expect(loop.awake).toBe(false)
+    loop.wake()
+    loop.wake()
+    loop.wake()
+    expect(f.pending()).toBe(1)
+    expect(f.flush(1)).toBe(1)
+  })
+
+  it('a wake from inside a step does not ask for a second frame', () => {
+    const f = fakeFrames()
+    const loop: FrameLoop = new FrameLoop(() => (loop.wake(), false), f.scheduler)
+    loop.wake()
+    f.flush(1)
+    expect(f.pending()).toBe(1)
+  })
+
+  it('stops for good: no frame after, and a wake does nothing', () => {
+    const f = fakeFrames()
+    const loop = new FrameLoop(() => true, f.scheduler)
+    loop.wake()
+    f.flush(3)
+    loop.stop()
+    expect(f.pending()).toBe(0)
+    loop.wake()
+    expect(f.flush(3)).toBe(0)
+  })
+})
diff --git a/tests/labelSpread.test.ts b/tests/labelSpread.test.ts
index c5f93b9a..89dd953a 100644
--- a/tests/labelSpread.test.ts
+++ b/tests/labelSpread.test.ts
@@ -108,4 +108,32 @@ describe('spreadLabels', () => {
       expect(overlapping(pins)).toEqual([])
     }
   })
+
+  it('measures a label once, and again only when its text or classes change', () => {
+    // A pin whose size reads are counted: each one is a forced layout pass
+    // in the browser.
+    const counted = (x: number, y: number, text: string) => {
+      const p = { style: { display: '', transform: `translate(${x}px, ${y}px)`, top: '' }, textContent: text, className: 'viewport-label', w: 100, reads: 0 }
+      return Object.defineProperties(p, {
+        offsetWidth: { get: () => (p.reads++, p.w) },
+        offsetHeight: { get: () => (p.reads++, 22) },
+      }) as typeof p & { offsetWidth: number; offsetHeight: number }
+    }
+    const a = counted(100, 100, '12.00')
+    const b = counted(100, 100, '3.00')
+    const run = () => spreadLabels({ querySelectorAll: () => [a, b] } as unknown as HTMLElement)
+    run()
+    expect([a.reads, b.reads]).toEqual([2, 2])
+    for (let frame = 0; frame < 10; frame++) run()
+    expect([a.reads, b.reads]).toEqual([2, 2])
+    expect(b.style.top).toBe('-24px')
+    // New text, a new size: measured again, and the layout follows it.
+    a.textContent = '12.000 mm'
+    a.w = 300
+    run()
+    expect([a.reads, b.reads]).toEqual([4, 2])
+    b.className = 'viewport-label over'
+    run()
+    expect([a.reads, b.reads]).toEqual([4, 4])
+  })
 })

From 5ad8cf39430072b3cdb51be5ef67eeecf8b2c69d Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Thu, 5 Nov 2026 01:14:55 +0000
Subject: [PATCH 29/38] perf(viewport): review fixes for the sleeping loop

- labelSpread: sizes re-measured after web fonts finish loading; labels
  cut away by the section view are left out, and nothing is measured
  with the Labels key off.
- nextFrame wakes the viewport (SceneManager.wakeFrame) before asking
  for its own frame, so the viewport's frame is queued first, as before
  the loop could sleep.
- shown needs both sides and is read-only; onTick / SceneLayer.tick docs
  say ticks stop while asleep; keepAwake's belt-and-braces noted.
- Tests: CameraLink wake/dispose, labels measured at nothing not kept,
  cut-away and Labels-off skipped, nextFrame wake order.
- scripts/e2e-sleep.mjs (npm run e2e:sleep): idle frames, wheel and
  pinch after sleep, the deviation motion, the split view link.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 package.json                |   1 +
 scripts/e2e-sleep.mjs       | 200 ++++++++++++++++++++++++++++++++++++
 src/commands/core/common.ts |  20 +++-
 src/viewer/SceneManager.ts  |  14 ++-
 src/viewer/labelSpread.ts   |  40 ++++++--
 src/viewer/orthoViewport.ts |  16 ++-
 src/viewer/sceneLayers.ts   |   6 +-
 tests/cameraLink.test.ts    |  72 +++++++++++++
 tests/commandWaits.test.ts  |  13 +++
 tests/labelSpread.test.ts   |  36 +++++++
 10 files changed, 397 insertions(+), 21 deletions(-)
 create mode 100644 scripts/e2e-sleep.mjs
 create mode 100644 tests/cameraLink.test.ts

diff --git a/package.json b/package.json
index fa10b2b3..0491829e 100644
--- a/package.json
+++ b/package.json
@@ -42,6 +42,7 @@
     "e2e:units": "node scripts/e2e-units.mjs",
     "e2e:deviation": "node scripts/e2e-deviation.mjs",
     "e2e:split": "node scripts/e2e-split.mjs",
+    "e2e:sleep": "node scripts/e2e-sleep.mjs",
     "e2e:pick-fit": "node scripts/e2e-pick-fit.mjs",
     "e2e:element-deviation": "node scripts/e2e-element-deviation.mjs",
     "e2e:circle": "node scripts/e2e-circle.mjs",
diff --git a/scripts/e2e-sleep.mjs b/scripts/e2e-sleep.mjs
new file mode 100644
index 00000000..b9f04740
--- /dev/null
+++ b/scripts/e2e-sleep.mjs
@@ -0,0 +1,200 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// End-to-end check that the viewports stop asking for frames when nothing
+// changes, and that everything that should move the picture still does after
+// they have: a wheel, a pinch, the deviation map played as motion, and a drag
+// in either half of the split view moving the other.
+//
+// The frames are counted by wrapping requestAnimationFrame before the app's
+// first script runs. An idle page should run none at all. A phone pays for
+// every one in battery, and the loops used to run sixty a second each
+// whether anything moved or not.
+//
+// The pair is built here, the same way e2e-split.mjs builds it: a STEP cube as
+// the reference and a fine mesh of the same cube, two faces displaced, as the
+// scan, so there is a map with something in it to play.
+//
+// Prereqs: dev server running (npm run dev), Chrome installed. Reads the
+// camera through the development hook, window.__scanruler.
+//   node scripts/e2e-sleep.mjs
+// Env: CHROME (chrome.exe path), APP_URL, SHOT_DIR.
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { importStep, writeBinarySTL } from 'meshstep'
+import { cubeStep } from '../tests/stepFixtures.ts'
+import { check, finish, launchApp, loadScan, pixelDiff, sleep } from './e2e-lib.mjs'
+
+const SIZE = 20
+
+// ---- the pair --------------------------------------------------------------
+const dir = mkdtempSync(join(tmpdir(), 'scanruler-sleep-'))
+const stepText = cubeStep(SIZE)
+const stepPath = join(dir, 'cube.step')
+writeFileSync(stepPath, stepText)
+const dense = importStep(stepText, { surfaceDeviation: 0.001, maxEdge: 0.8 })
+const p = dense.mesh.positions
+for (let i = 0; i < p.length; i += 3) {
+  if (Math.abs(p[i + 2] - SIZE) < 1e-6) p[i + 2] += 0.2
+  if (Math.abs(p[i] - SIZE) < 1e-6) p[i] -= 0.15
+}
+const scanPath = join(dir, 'cube-scan.stl')
+writeFileSync(scanPath, Buffer.from(writeBinarySTL(dense.mesh)))
+
+// Touch on, for the pinch; the mouse still works alongside it.
+const { browser, page, consoleErrors } = await launchApp({ width: 1500, height: 950 })
+await page.setViewport({ width: 1500, height: 950, hasTouch: true, deviceScaleFactor: 1 })
+await page.evaluateOnNewDocument(() => {
+  window.__raf = 0
+  const raf = window.requestAnimationFrame.bind(window)
+  window.requestAnimationFrame = (cb) =>
+    raf((t) => {
+      window.__raf++
+      cb(t)
+    })
+})
+await page.reload({ waitUntil: 'networkidle0' })
+await page.waitForSelector('.panel')
+
+/** Frame callbacks that ran over `ms`. */
+const framesOver = async (ms) => {
+  const a = await page.evaluate(() => window.__raf)
+  await sleep(ms)
+  return (await page.evaluate(() => window.__raf)) - a
+}
+/** Long enough for every loop to have wound down after the last change. */
+const SETTLE = 1500
+const clipOf = (sel) =>
+  page.$eval(sel, (el) => {
+    const r = el.getBoundingClientRect()
+    return { x: r.x, y: r.y, width: r.width, height: r.height }
+  })
+const shot = (clip) => page.screenshot({ clip, encoding: 'base64' })
+const camera = () =>
+  page.evaluate(() => {
+    const v = window.__scanruler.scene().viewport
+    const at = v.camera.position
+    return { at: [at.x, at.y, at.z], zoom: v.camera.zoom }
+  })
+const apart = (a, b) => Math.hypot(a.at[0] - b.at[0], a.at[1] - b.at[1], a.at[2] - b.at[2]) + Math.abs(a.zoom - b.zoom)
+
+// ---- a map on the stage ------------------------------------------------------
+await page.click('[data-test=workspace-deviation]')
+await page.waitForSelector('[data-test=start-pane]')
+await loadScan(page, scanPath, { inputSelector: '[data-test=start-scan] input[type=file]', timeout: 300_000, settle: 600 })
+await (await page.$('[data-test=slot-reference] input[type=file]')).uploadFile(stepPath)
+await page.waitForFunction(() => document.querySelector('[data-test=align-auto]')?.disabled === false, { timeout: 300_000 })
+await sleep(900)
+await page.click('[data-test=align-auto]')
+await page.waitForSelector('[data-test=deviation-legend]', { timeout: 300_000 })
+await page.waitForFunction(() => !document.querySelector('[data-test=fitting-chip]'), { timeout: 300_000 })
+await sleep(SETTLE)
+
+let n = await framesOver(2000)
+check(n === 0, `idle with a map on, no frames run (${n} in 2 s)`)
+
+// ---- a wheel after sleeping -------------------------------------------------
+const view = await clipOf('.viewslot canvas')
+const middle = [view.x + view.width / 2, view.y + view.height / 2]
+await page.mouse.move(...middle)
+await sleep(SETTLE)
+let before = await shot(view)
+let from = await camera()
+await page.mouse.wheel({ deltaY: -240 })
+await sleep(500)
+let to = await camera()
+check(to.zoom > from.zoom, `a wheel after sleeping zooms (zoom ${from.zoom.toFixed(3)} → ${to.zoom.toFixed(3)})`)
+check((await pixelDiff(page, before, await shot(view))) > 1, 'and the picture follows it')
+await page.mouse.wheel({ deltaY: 240 })
+await sleep(SETTLE)
+
+// ---- a pinch after sleeping -------------------------------------------------
+// Two fingers dispatched over CDP, as e2e-touch.mjs does: Puppeteer's own
+// touchscreen has one.
+const cdp = await page.createCDPSession()
+const touch = (type, points) =>
+  cdp.send('Input.dispatchTouchEvent', {
+    type,
+    touchPoints: points.map(([x, y], i) => ({ x, y, id: i + 1, radiusX: 12, radiusY: 12, force: 1 })),
+  })
+n = await framesOver(1000)
+check(n === 0, `asleep before the pinch (${n} frames in 1 s)`)
+before = await shot(view)
+from = await camera()
+const spread = (d) => [
+  [middle[0] - d, middle[1]],
+  [middle[0] + d, middle[1]],
+]
+async function pinch(d0, d1) {
+  await touch('touchStart', spread(d0))
+  await sleep(40)
+  for (let s = 1; s <= 10; s++) {
+    await touch('touchMove', spread(d0 + ((d1 - d0) * s) / 10))
+    await sleep(22)
+  }
+  await touch('touchEnd', [])
+  await sleep(500)
+}
+await pinch(55, 190)
+to = await camera()
+check(to.zoom > from.zoom * 1.3, `a pinch after sleeping zooms in (zoom ${from.zoom.toFixed(3)} → ${to.zoom.toFixed(3)})`)
+check((await pixelDiff(page, before, await shot(view))) > 1, 'and the picture follows the fingers')
+await sleep(SETTLE)
+n = await framesOver(2000)
+check(n === 0, `asleep again after the pinch (${n} frames in 2 s)`)
+// Back out, so the motion below plays on the whole part: zoomed into the
+// middle of a face, the displaced faces are off the screen.
+await pinch(190, 55)
+const back = await camera()
+check(back.zoom < to.zoom / 1.3, `pinching back zooms out again (zoom ${to.zoom.toFixed(3)} → ${back.zoom.toFixed(3)})`)
+await sleep(SETTLE)
+
+// ---- the map played as motion -------------------------------------------------
+await page.click('[data-test=animate-deformation]')
+await sleep(800)
+n = await framesOver(1000)
+const a = await shot(view)
+await sleep(350)
+const moved = await pixelDiff(page, a, await shot(view))
+check(n >= 20 && moved > 0.5, `the motion keeps the frames running (${n} in 1 s, ${moved.toFixed(2)} % of the view changed in 350 ms)`)
+await page.click('[data-test=animate-deformation]')
+await sleep(SETTLE)
+n = await framesOver(2000)
+check(n === 0, `stopped, the loop sleeps again (${n} frames in 2 s)`)
+
+// ---- the split view: either half moves the other ------------------------------
+await page.click('[data-test=toggle-split]')
+await page.waitForSelector('.compareview canvas')
+await sleep(SETTLE)
+n = await framesOver(2000)
+check(n === 0, `the split view open and idle (${n} frames in 2 s)`)
+const half = await clipOf('.compareview canvas')
+const scanHalf = await clipOf('.viewslot canvas')
+async function orbit(r) {
+  await page.mouse.move(r.x + r.width * 0.5, r.y + r.height * 0.5)
+  await page.mouse.down()
+  for (let i = 1; i <= 8; i++) {
+    await page.mouse.move(r.x + r.width * 0.5 + (150 * i) / 8, r.y + r.height * 0.5 + (70 * i) / 8)
+    await sleep(30)
+  }
+  await page.mouse.up()
+  await sleep(600)
+}
+from = await camera()
+before = await shot(scanHalf)
+await orbit(half)
+to = await camera()
+check(apart(from, to) > 1e-3, `a drag in the reference half turns the scan half's camera (${apart(from, to).toFixed(3)})`)
+check((await pixelDiff(page, before, await shot(scanHalf))) > 1, 'and the scan half is drawn turned')
+await sleep(SETTLE)
+before = await shot(half)
+await orbit(scanHalf)
+check((await pixelDiff(page, before, await shot(half))) > 1, 'a drag in the scan half redraws the reference half turned')
+await sleep(SETTLE)
+n = await framesOver(2000)
+check(n === 0, `linked and idle again (${n} frames in 2 s)`)
+await page.click('[data-test=toggle-split]')
+await sleep(SETTLE)
+n = await framesOver(2000)
+check(n === 0, `the split view closed, its half kept and paused (${n} frames in 2 s)`)
+
+await finish(browser, consoleErrors)
diff --git a/src/commands/core/common.ts b/src/commands/core/common.ts
index a94b9509..83df5c34 100644
--- a/src/commands/core/common.ts
+++ b/src/commands/core/common.ts
@@ -156,13 +156,27 @@ export const nextTask = (): Promise<void> =>
     channel.port2.postMessage(null)
   })
 
+/** What a wait on the stage asks of the viewport — SceneManager. */
+export interface FrameSource {
+  pumpFrame(): void
+  wakeFrame?(): void
+}
+
 /** A frame for the stage to follow the stores: the browser's next one — or,
  *  while the tab is hidden and the browser draws none, a task's turn and
  *  then the viewport's frame drawn by hand (SceneManager.pumpFrame), so a
- *  wait on the screen does not stall in a background tab. */
-export async function nextFrame(scene?: { pumpFrame(): void } | null): Promise<void> {
+ *  wait on the screen does not stall in a background tab.
+ *
+ *  The viewport's frames stop while nothing changes in it, and one woken
+ *  only by what the stores set off — a React effect, in the microtasks
+ *  after this call — would ask for its frame after this wait asked for
+ *  its own, and draw after the wait was over. So the viewport is woken
+ *  first: its frame is asked for ahead of this one, and the frame this
+ *  wait ends on is one the stage was drawn in. */
+export async function nextFrame(scene?: FrameSource | null): Promise<void> {
   const hidden = typeof document === 'undefined' || document.visibilityState === 'hidden'
   if (!hidden && typeof requestAnimationFrame === 'function') {
+    scene?.wakeFrame?.()
     await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()))
     return
   }
@@ -178,7 +192,7 @@ export async function nextFrame(scene?: { pumpFrame(): void } | null): Promise<v
  *  for the stores' change to reach the effect that asks; then the wait, which
  *  is over at once when nothing is being measured. Settled is not measured:
  *  the caller looks at the status for that. */
-export async function mapSettled(scene?: { pumpFrame(): void } | null): Promise<void> {
+export async function mapSettled(scene?: FrameSource | null): Promise<void> {
   await nextFrame(scene)
   await waitFor(() => useDeviation.getState().elementStatus !== 'running', 'the map against the element', 30_000)
 }
diff --git a/src/viewer/SceneManager.ts b/src/viewer/SceneManager.ts
index 6ec63c2f..2e382662 100644
--- a/src/viewer/SceneManager.ts
+++ b/src/viewer/SceneManager.ts
@@ -562,7 +562,12 @@ export class SceneManager {
       onAfterRender: (w, h) => this.drawGizmo(w, h),
       // What wants frames although nothing is marked yet: the motion of the
       // deviation map, a stroke's positions still queued, and what is drawn
-      // on the part waiting to be dressed for the section view's cut.
+      // on the part waiting to be dressed for the section view's cut. The
+      // last two are belt and braces: the tick above has drained the queue
+      // and dressed the cut by the time this is asked, and what sets them
+      // wakes the loop itself (the marking's wake, invalidate). The motion
+      // invalidates every frame it plays as well; it is named here so the
+      // loop's reasons to stay up are read in one place.
       keepAwake: () => this.deflectionPlaying() || this.marking.strokePending() || this.clipDirty,
     })
     this.container = container
@@ -1403,6 +1408,13 @@ export class SceneManager {
     this.viewport.pump()
   }
 
+  /** Have the viewport's next frame asked for now, if its loop had gone to
+   *  sleep — ahead of a wait on the browser's next frame (commands'
+   *  nextFrame), so the frame waited for is one the stage is drawn in. */
+  wakeFrame(): void {
+    this.viewport.wake()
+  }
+
   viewSize(): { width: number; height: number } {
     return { width: this.viewport.size.w, height: this.viewport.size.h }
   }
diff --git a/src/viewer/labelSpread.ts b/src/viewer/labelSpread.ts
index 9e93930f..41f28397 100644
--- a/src/viewer/labelSpread.ts
+++ b/src/viewer/labelSpread.ts
@@ -13,28 +13,46 @@
 /** Sub-pixel distances two labels may still be apart and count as clear. */
 const SLACK = 1e-6
 
-/** Each label's size as last measured, with the text and classes it was
- *  measured with. A label's offsetWidth read after the renderer has just
- *  written every label's transform is a forced layout pass — every frame
- *  the view moves, for sizes that only change when the text does. So a
- *  label is measured again only when its text or its classes changed (an
- *  empty note's italic, a pin cut away). A label measured at nothing — out
- *  of the layout at the time — is not kept, and is measured again. */
-const sizes = new WeakMap<HTMLElement, { w: number; h: number; text: string | null; cls: string }>()
+/** Each label's size as last measured, with the text, the classes and the
+ *  font generation it was measured with. A label's offsetWidth read after
+ *  the renderer has just written every label's transform is a forced layout
+ *  pass — every frame the view moves, for sizes that only change when the
+ *  text does. So a label is measured again only when its text or its
+ *  classes changed (an empty note's italic), or a web font arrived and
+ *  swapped in for the fallback it was measured in. A label measured at
+ *  nothing — out of the layout at the time — is not kept, and is measured
+ *  again. */
+const sizes = new WeakMap<HTMLElement, { w: number; h: number; text: string | null; cls: string; fonts: number }>()
+
+/** Bumped whenever the document finishes loading fonts: the self-hosted
+ *  faces swap in over their fallbacks, and every label measured before
+ *  then is the wrong width. */
+let fontGeneration = 0
+if (typeof document !== 'undefined' && document.fonts) {
+  document.fonts.addEventListener('loadingdone', () => {
+    fontGeneration++
+  })
+}
 
 function sizeOf(el: HTMLElement): { w: number; h: number } {
   const text = el.textContent
   const cls = el.className
   const known = sizes.get(el)
-  if (known && known.text === text && known.cls === cls) return known
-  const measured = { w: el.offsetWidth, h: el.offsetHeight, text, cls }
+  if (known && known.text === text && known.cls === cls && known.fonts === fontGeneration) return known
+  const measured = { w: el.offsetWidth, h: el.offsetHeight, text, cls, fonts: fontGeneration }
   if (measured.w > 0 || measured.h > 0) sizes.set(el, measured)
   return measured
 }
 
 export function spreadLabels(labelDom: HTMLElement, gap = 2): void {
+  // The Labels key off: every tag is out of the layout, and measuring them
+  // would read nothing, every frame.
+  if (labelDom.closest?.('.nolabels')) return
+  // Out of the layout too: a label the renderer put away, and one on the
+  // side the section view cuts away — which would measure at nothing, and
+  // be measured again every frame for it.
   const els = Array.from(labelDom.querySelectorAll<HTMLElement>('.viewport-label')).filter(
-    (el) => el.style.display !== 'none',
+    (el) => el.style.display !== 'none' && !el.classList?.contains('cut-away'),
   )
   if (els.length < 2) {
     for (const el of els) el.style.top = ''
diff --git a/src/viewer/orthoViewport.ts b/src/viewer/orthoViewport.ts
index a970e2b0..78ff655c 100644
--- a/src/viewer/orthoViewport.ts
+++ b/src/viewer/orthoViewport.ts
@@ -130,8 +130,12 @@ export interface OrthoViewportOptions {
   /** A second finger has landed: whatever one-finger gesture was live is over,
    *  because the hand has moved on to navigating. */
   onMultiTouch?: () => void
-  /** Runs every animation tick, rendered or not — this is where the owner
-   *  drains its per-frame queues and decides whether to invalidate. */
+  /** Runs on every frame the loop runs, rendered or not — this is where the
+   *  owner drains its per-frame queues and decides whether to invalidate.
+   *  Not every animation tick: the loop sleeps while nothing changes (see
+   *  FrameLoop), so state polled here must, when it changes, wake the loop
+   *  — invalidate, or the owner's requestHover — or it is not looked at
+   *  until something else does. */
   onTick?: () => void
   /** Runs after the scene render, before the labels — a corner gizmo drawn
    *  into the same canvas goes here. */
@@ -191,7 +195,10 @@ export class OrthoViewport {
   /** Whether the container has a size on the page now, as of the last
    *  resize: false while it is put away behind `hidden`, where `size` still
    *  holds the size it was shown at. */
-  shown = false
+  get shown(): boolean {
+    return this.isShown
+  }
+  private isShown = false
   /** Half-extents of the model on the screen plane at the framing camera
    *  orientation; the frustum is rebuilt from these on every resize so the
    *  user's zoom survives. */
@@ -406,7 +413,6 @@ export class OrthoViewport {
    *  under way that wants the next frame — which is what keeps the loop
    *  from going to sleep. */
   private frame(): boolean {
-    // Ahead of the pause, so that a paused viewport lets go of the puck.
     if (spaceMouseAttached()) this.stepSpaceMouse()
     if (this.isPaused) return false
     // These run every tick, rendered or not: a turn under way moves the
@@ -906,7 +912,7 @@ export class OrthoViewport {
   resize(): void {
     const cw = this.container.clientWidth
     const ch = this.container.clientHeight
-    this.shown = cw > 0
+    this.isShown = cw > 0 && ch > 0
     // A viewport kept alive behind `hidden` reports 0 × 0, and resizing to that
     // would reallocate both buffers for a size nobody sees; it keeps the last
     // one, and the real size arrives with the first resize after it is shown.
diff --git a/src/viewer/sceneLayers.ts b/src/viewer/sceneLayers.ts
index 26ccf3b9..74da2ef4 100644
--- a/src/viewer/sceneLayers.ts
+++ b/src/viewer/sceneLayers.ts
@@ -111,7 +111,11 @@ export interface SceneLayer {
    *  While it holds, the layer alone lights under the cursor and takes the
    *  next click, ahead of every layer before it. */
   cycling?(at: { x: number; y: number } | null): boolean
-  /** Every frame, before it is drawn, with the canvas's size in pixels. */
+  /** On every frame the viewport runs, before it is drawn, with the
+   *  canvas's size in pixels. Not every animation tick: the viewport's
+   *  frames stop while nothing changes, so what a layer polls here must,
+   *  when it changes, call the host's invalidate or requestHover to be
+   *  looked at. */
   tick?(width: number, height: number): void
   themeChanged?(theme: ViewTheme): void
   /** The part was cut open at a plane — or closed again, with null. The
diff --git a/tests/cameraLink.test.ts b/tests/cameraLink.test.ts
new file mode 100644
index 00000000..2875a342
--- /dev/null
+++ b/tests/cameraLink.test.ts
@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Two views held in one pose, each with a frame loop that sleeps while
+// nothing changes in it: whichever half is moved has to wake the other, or
+// the half polling the link stands still while its partner is dragged.
+import * as THREE from 'three'
+import { describe, expect, it } from 'vitest'
+import { CameraLink, type LinkedView } from '../src/viewer/cameraLink'
+
+/** A view whose invalidate tells its watchers, as OrthoViewport's does, and
+ *  which counts the times it was woken. */
+function fakeView() {
+  const watchers = new Set<() => void>()
+  let extents = { halfW: 10, halfH: 10 }
+  const view = {
+    camera: new THREE.OrthographicCamera(-1, 1, 1, -1, 0.1, 100),
+    target: new THREE.Vector3(),
+    extents: () => extents,
+    setExtents: (halfW: number, halfH: number) => {
+      extents = { halfW, halfH }
+    },
+    invalidate: () => {
+      for (const fn of watchers) fn()
+    },
+    woken: 0,
+    wake: () => {
+      view.woken++
+    },
+    watch: (fn: () => void) => {
+      watchers.add(fn)
+      return () => watchers.delete(fn)
+    },
+    watchers,
+  }
+  view.camera.position.set(0, 0, 10)
+  return view satisfies LinkedView
+}
+
+describe('CameraLink waking', () => {
+  it('wakes each half when the other is marked for drawing', () => {
+    const a = fakeView()
+    const b = fakeView()
+    new CameraLink(a, b)
+    const [wa, wb] = [a.woken, b.woken]
+    a.invalidate()
+    expect(b.woken).toBe(wb + 1)
+    expect(a.woken).toBe(wa)
+    b.invalidate()
+    expect(a.woken).toBe(wa + 1)
+  })
+
+  it('a gesture on one half carries to the other on the tick it wakes', () => {
+    const a = fakeView()
+    const b = fakeView()
+    const link = new CameraLink(a, b)
+    a.camera.position.set(5, 0, 10)
+    a.invalidate()
+    link.tick()
+    expect(b.camera.position.x).toBeCloseTo(5)
+  })
+
+  it('wakes nothing once disposed, and lets go of both views', () => {
+    const a = fakeView()
+    const b = fakeView()
+    const link = new CameraLink(a, b)
+    link.dispose()
+    const [wa, wb] = [a.woken, b.woken]
+    a.invalidate()
+    b.invalidate()
+    expect([a.woken, b.woken]).toEqual([wa, wb])
+    expect([a.watchers.size, b.watchers.size]).toEqual([0, 0])
+  })
+})
diff --git a/tests/commandWaits.test.ts b/tests/commandWaits.test.ts
index 478499e2..d74c5555 100644
--- a/tests/commandWaits.test.ts
+++ b/tests/commandWaits.test.ts
@@ -66,3 +66,16 @@ describe('waits in a hidden tab', () => {
     expect(pumpFrame).toHaveBeenCalledTimes(1)
   })
 })
+
+describe('a frame waited for while the page is shown', () => {
+  it('wakes the viewport first, so its frame is asked for ahead of the wait’s', async () => {
+    vi.stubGlobal('document', { visibilityState: 'visible' })
+    const asked: string[] = []
+    vi.stubGlobal('requestAnimationFrame', (f: () => void) => {
+      asked.push('wait')
+      return setTimeout(f, 0)
+    })
+    await nextFrame({ pumpFrame: () => asked.push('pump'), wakeFrame: () => asked.push('wake') })
+    expect(asked).toEqual(['wake', 'wait'])
+  })
+})
diff --git a/tests/labelSpread.test.ts b/tests/labelSpread.test.ts
index 89dd953a..175c1325 100644
--- a/tests/labelSpread.test.ts
+++ b/tests/labelSpread.test.ts
@@ -136,4 +136,40 @@ describe('spreadLabels', () => {
     run()
     expect([a.reads, b.reads]).toEqual([4, 4])
   })
+
+  it('keeps no size measured at nothing, and measures that label again', () => {
+    // Out of the layout when first measured — a parent not yet shown — and
+    // then in it: the size read at nothing must not stand for it.
+    let w = 0
+    let reads = 0
+    const p = { style: { display: '', transform: 'translate(100px, 100px)', top: '' }, textContent: 'a', className: 'viewport-label' }
+    const late = Object.defineProperties(p, {
+      offsetWidth: { get: () => (reads++, w) },
+      offsetHeight: { get: () => (reads++, w ? 22 : 0) },
+    }) as typeof p & { offsetWidth: number; offsetHeight: number }
+    const other = pin(100, 100)
+    const run = () => spreadLabels({ querySelectorAll: () => [late, other] } as unknown as HTMLElement)
+    run()
+    expect(reads).toBe(2)
+    expect(other.style.top).toBe('')
+    w = 100
+    run()
+    expect(reads).toBe(4)
+    // Measured now, it stacks with the other one.
+    expect([late.style.top, other.style.top].sort()).toEqual(['', '-24px'])
+    run()
+    expect(reads).toBe(4)
+  })
+
+  it('leaves out labels cut away by the section view, and does nothing with the labels off', () => {
+    const cut = { ...pin(100, 100), classList: { contains: (c: string) => c === 'cut-away' } }
+    const a = pin(100, 100)
+    const b = pin(100, 100)
+    spreadLabels({ querySelectorAll: () => [cut, a, b] } as unknown as HTMLElement)
+    expect(tops([cut, a, b])).toEqual(['', '', '-24px'])
+    const c = pin(100, 100)
+    const d = pin(100, 100)
+    spreadLabels({ closest: (sel: string) => (sel === '.nolabels' ? {} : null), querySelectorAll: () => [c, d] } as unknown as HTMLElement)
+    expect(tops([c, d])).toEqual(['', ''])
+  })
 })

From c1470498c7a9050ef1a275582c7ed3de973d8eed Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Thu, 5 Nov 2026 01:28:47 +0000
Subject: [PATCH 30/38] perf(bvh): build the scan's tree in the worker

The scan's bounds tree was the longest single task in opening it. The
mesh worker now builds it (indirect, over copies of the render positions
and index, crease copies included) once the part is in place, and the
viewport lays it over the geometry with MeshBVH.deserialize, setIndex
off: the drawn index is never reordered. A tree landing on a geometry
laid out again, given a tree of its own or taken off the stage is turned
away; one landing after a rigid move is refitted. Until it lands, the
pointer tests a frame makes skip the scan (sparingRays) while clicks
fall back to three's raycast, and the tree's arrival wakes the loop to
look at the hover and the pins again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/App.tsx                |   3 +
 src/core/meshWorker.ts     |  20 ++-
 src/core/workerClient.ts   |  17 ++-
 src/core/workerProtocol.ts |  21 +++
 src/viewer/PickScene.ts    |   6 +-
 src/viewer/SceneManager.ts |  41 +++++-
 src/viewer/bvh.ts          | 112 ++++++++++++++-
 src/viewer/clipRaycast.ts  |   4 +
 src/viewer/marking.ts      |  11 +-
 src/viewer/orthoNav.ts     |   8 +-
 tests/bvhWorker.test.ts    | 275 +++++++++++++++++++++++++++++++++++++
 11 files changed, 499 insertions(+), 19 deletions(-)
 create mode 100644 tests/bvhWorker.test.ts

diff --git a/src/App.tsx b/src/App.tsx
index 360c01c2..c38a5c3f 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -1656,6 +1656,9 @@ function Workbench() {
                 // A part's closed shells are searched in the worker as it
                 // loads, not on the main thread at the first cut.
                 s.closedShellsFrom = (which) => clientRef.current!.closedShells(which)
+                // And the scan's bounds tree, the longest single task in
+                // opening it.
+                s.boundsTreeFrom = (positions, indices) => clientRef.current!.boundsTree(positions, indices)
                 s.setNavScheme(schemeById(useStore.getState().navScheme))
                 s.setViewTheme(sceneTheme(useStore.getState().viewTheme, usePrefs.getState().dark))
                 s.setSectionLineWidth(usePrefs.getState().sectionLines)
diff --git a/src/core/meshWorker.ts b/src/core/meshWorker.ts
index 0fb8863f..77313d9f 100644
--- a/src/core/meshWorker.ts
+++ b/src/core/meshWorker.ts
@@ -9,7 +9,7 @@
 // prepared beside the models in use, put in their place when committed.
 
 import type { MeshGraph, ParsedMesh, TextureNote, Vec3 } from './types'
-import type { WorkerRequest, WorkerResponse } from './workerProtocol'
+import type { SerializedTree, WorkerRequest, WorkerResponse } from './workerProtocol'
 import { parseSTL } from './parsers/stl'
 import { parsePLY } from './parsers/ply'
 import { parseOBJ } from './parsers/obj'
@@ -50,7 +50,8 @@ import { findSymmetryPlane } from './symmetry'
 import { autoAlign } from './autoAlign'
 import { workerPlugins } from './workerPlugins'
 import type { WorkerContext } from './workerPluginApi'
-import type { MeshBVH } from 'three-mesh-bvh'
+import * as THREE from 'three'
+import { MeshBVH, type MeshBVHOptions } from 'three-mesh-bvh'
 import { reply } from './workerRpc'
 import { firstHits, firstHitsAt, localNoise, scanRim, scanRims } from './geometry/scanQa'
 import { rimLoops, type RimLoop } from './geometry/openEdges'
@@ -576,6 +577,21 @@ function handle(msg: Exclude<WorkerRequest, { type: 'align-abort' }>): void {
     return
   }
 
+  if (msg.type === 'bounds-tree') {
+    // Indirect, so that the tree sorts a list of triangle numbers of its own
+    // and leaves the index alone: the render thread lays the tree over a
+    // geometry whose index is already drawn, and read by triangle by the
+    // section caps and the picks, as it was sent. The positions and index
+    // sent are this request's own; the tree takes them over and only its
+    // nodes and its triangle order go back.
+    const geometry = new THREE.BufferGeometry()
+    geometry.setAttribute('position', new THREE.BufferAttribute(msg.positions, 3))
+    geometry.setIndex(new THREE.BufferAttribute(msg.indices, 1))
+    const { roots, indirectBuffer } = MeshBVH.serialize(new MeshBVH(geometry, { indirect: true } as MeshBVHOptions), { cloneBuffers: false }) as unknown as SerializedTree
+    post({ type: 'bounds-tree-ok', requestId: msg.requestId, tree: { roots, indirectBuffer } }, [...roots, indirectBuffer.buffer as ArrayBuffer])
+    return
+  }
+
   if (msg.type === 'deflection') {
     // Smoothed over the scan's vertices as held here: the render thread's
     // own, bit for bit — the first `vertexCount` of what it was posted,
diff --git a/src/core/workerClient.ts b/src/core/workerClient.ts
index bfc7c9cb..61b4f49e 100644
--- a/src/core/workerClient.ts
+++ b/src/core/workerClient.ts
@@ -26,7 +26,7 @@ import type { ObjCompanions } from './parsers/objTexture'
 import type { FitGuide } from './fit/guide'
 import type { PlaneRegionReport, Segmentation, SegmentOptions } from './fit/segment'
 import type { RayGrid } from './geometry/scanQa'
-import type { WorkerRequest, WorkerResponse } from './workerProtocol'
+import type { SerializedTree, WorkerRequest, WorkerResponse } from './workerProtocol'
 
 export interface LoadedMesh {
   positions: Float32Array
@@ -531,6 +531,21 @@ export class MeshWorkerClient {
     return res.closed
   }
 
+  /** A bounds tree over a mesh as the viewport lays it out, built in the
+   *  worker — see viewer/bvh.ts treeOffThread. The arrays are handed over,
+   *  so the caller sends copies. Nothing of the scan the worker holds goes
+   *  into it, so nothing about that can go stale here: whether the tree
+   *  still fits the geometry it was asked for is the viewport's to judge
+   *  when it lands. */
+  async boundsTree(positions: Float32Array, indices: Uint32Array): Promise<SerializedTree> {
+    const requestId = this.nextId++
+    const res = await this.request<Extract<WorkerResponse, { type: 'bounds-tree-ok' }>>(
+      { type: 'bounds-tree', requestId, positions, indices },
+      [positions.buffer, indices.buffer],
+    )
+    return res.tree
+  }
+
   /** How far each scan vertex moves to play a map as motion — see
    *  deviation/deflection.ts deflectionVectors — worked out in the worker,
    *  over its own copy of the scan's vertices. Where that copy may not be
diff --git a/src/core/workerProtocol.ts b/src/core/workerProtocol.ts
index 80a26e2c..cf3e59df 100644
--- a/src/core/workerProtocol.ts
+++ b/src/core/workerProtocol.ts
@@ -247,6 +247,13 @@ export type WorkerRequest =
       normals: Float32Array
       positions?: Float32Array
     }
+  /** A bounds tree over a mesh as the render thread lays it out — its
+   *  positions and its index as drawn, shading copies and all — built here
+   *  so that a million triangles are not sorted on the thread that answers
+   *  the user (see viewer/bvh.ts treeOffThread). The arrays are the render
+   *  thread's own, copied and sent over: the tree describes them whatever
+   *  this worker holds of the scan, or whether it holds it at all. */
+  | { type: 'bounds-tree'; requestId: number; positions: Float32Array; indices: Uint32Array }
   /** A request for a plugin's part of the worker — see workerPluginApi.ts.
    *  `op` names the plugin's operation, `payload` is its own. */
   | { type: 'plugin'; requestId: number; plugin: string; op: string; payload: unknown }
@@ -378,6 +385,20 @@ export type WorkerResponse =
   /** The map against an element, the direction each reading was taken
    *  along, and the colour scale the tool would choose for it, in mm. */
   | { type: 'element-deviation-ok'; requestId: number; values: Float32Array; directions: Int8Array; suggestedRange: number }
+  /** The tree, serialized — see SerializedTree. */
+  | { type: 'bounds-tree-ok'; requestId: number; tree: SerializedTree }
   /** A plugin's answer. */
   | { type: 'plugin-ok'; requestId: number; result: unknown }
   | { type: 'error'; requestId: number; message: string }
+
+/** A bounds tree as it crosses between threads: its nodes, and the order it
+ *  keeps the triangles in. Indirect — the tree sorts that list of triangle
+ *  numbers and never the index it was built over — so it is laid back over
+ *  the render thread's geometry as it stands, and the index already drawn
+ *  and read by triangle keeps every triangle where it was. See three-mesh-bvh
+ *  MeshBVH.serialize; the index it would carry is left out, being the render
+ *  thread's own. */
+export interface SerializedTree {
+  roots: ArrayBuffer[]
+  indirectBuffer: Uint32Array | Uint16Array
+}
diff --git a/src/viewer/PickScene.ts b/src/viewer/PickScene.ts
index 5bdbeaff..5a6439a6 100644
--- a/src/viewer/PickScene.ts
+++ b/src/viewer/PickScene.ts
@@ -10,6 +10,7 @@ import type { Vec3 } from '../core/types'
 import { SurfaceMarking, type PaintBrush } from './marking'
 import type { ControlScheme } from './navSchemes'
 import { OrthoViewport } from './orthoViewport'
+import { sparingRays } from './bvh'
 import { paintUniform, patchPaintTint, setPaintUniform } from './paintTint'
 import type { MarkingChannel } from './SceneManager'
 import { applyFinish, setSurfaceColor, type ViewTheme } from './viewThemes'
@@ -218,7 +219,10 @@ export class PickScene {
   private updateHover(): void {
     if (!this.hoverDirty || !this.marking) return
     this.hoverDirty = false
-    if (this.marking.armed()) this.marking.updateBrushRing(this.hoverAt)
+    // The scan is the main viewport's, and its tree may still be on its way
+    // — see bvh.ts sparingRays.
+    const marking = this.marking
+    if (marking.armed()) sparingRays(() => marking.updateBrushRing(this.hoverAt))
   }
 
   private pick(clientX: number, clientY: number): Vec3 | null {
diff --git a/src/viewer/SceneManager.ts b/src/viewer/SceneManager.ts
index 2e382662..f3e3fa03 100644
--- a/src/viewer/SceneManager.ts
+++ b/src/viewer/SceneManager.ts
@@ -33,7 +33,8 @@ import type { SectionCut } from '../core/section/slice'
 import type { ControlScheme } from './navSchemes'
 import type { PickMarker } from './PickScene'
 import { computeBoundsTree, disposeBoundsTree } from 'three-mesh-bvh'
-import { refitAfterRigid } from './bvh'
+import { forgetTree, refitAfterRigid, sparingRays, treeOffThread } from './bvh'
+import type { SerializedTree } from '../core/workerProtocol'
 import type { FitData, Vec3 } from '../core/types'
 import { rigidApplyToPoints, rigidRotate, rigidRotateVectors, type Rigid } from '../core/deviation/rigid'
 import { deflectionFactor, deflectionStartPhase } from '../core/deviation/deflection'
@@ -371,6 +372,11 @@ export class SceneManager {
    *  — the mesh worker, wired by the app — for the section view's caps (see
    *  sliceCap primeClosedPart). Without it, a cut finds them itself. */
   closedShellsFrom: ((which: 'scan' | 'nominal') => Promise<Uint8Array>) | null = null
+  /** Where a scan's bounds tree is built off the main thread — the mesh
+   *  worker, wired by the app — from copies of its positions and index; see
+   *  bvh.ts treeOffThread. Without it, the tree is built here as the scan is
+   *  prepared. */
+  boundsTreeFrom: ((positions: Float32Array, indices: Uint32Array) => Promise<SerializedTree>) | null = null
   /** Elements lit because something being built refers to them, and
    *  elements lit because a picker's option is hovered — two reasons, one
    *  look; the overlays hear the union. */
@@ -527,7 +533,9 @@ export class SceneManager {
         this.grips.followView()
         this.grips.putAwayWhile(this.marking.gestureArmed())
         this.overlays.setPreviewBrushing(this.marking.gestureArmed())
-        this.updateHover()
+        // The pointer tests a frame makes skip a scan whose tree is still on
+        // its way, rather than run through its every triangle.
+        sparingRays(() => this.updateHover())
         // Anything held at a fixed size on screen — the picked-point markers —
         // has to be re-scaled when the zoom changes. A no-op on the frames it
         // has not.
@@ -536,7 +544,7 @@ export class SceneManager {
         this.sections.setPixelScale(pixel)
         // Pins on the far side of the part go away as it turns, if asked to;
         // a no-op unless the view moved.
-        this.overlays.updateProbeOcclusion()
+        sparingRays(() => this.overlays.updateProbeOcclusion())
         // The section curves are fat lines sized in pixels and need the
         // canvas's size: the viewport's cached one, since a read of the
         // layout every frame is a forced layout pass after any DOM write.
@@ -961,7 +969,8 @@ export class SceneManager {
   }
 
   /** Replace the displayed mesh. Synchronous and heavy (includes the BVH
-   *  build) — callers should show a status message and yield a frame first.
+   *  build where no worker builds it — see boundsTreeFrom) — callers should
+   *  show a status message and yield a frame first.
    *  `copyOf` names the scan vertex behind each render vertex past the
    *  scan's own — the copies its sharp edges were split into for shading. */
   setMesh(
@@ -998,7 +1007,13 @@ export class SceneManager {
       false,
       surface,
     )
-    try { geometry.computeBoundsTree() } catch (e) { geometry.dispose(); throw e }
+    // A scan's tree is the longest single task in opening it: built in the
+    // worker once the part is in place, where the app has wired one — the
+    // part is on screen and turns meanwhile — and here otherwise.
+    const offThread = this.boundsTreeFrom
+    if (!offThread) {
+      try { geometry.computeBoundsTree() } catch (e) { geometry.dispose(); throw e }
+    }
     const axis = principalAxis(positions)
 
     // Scans have holes; double-sided rendering keeps interior surfaces
@@ -1035,11 +1050,26 @@ export class SceneManager {
       )
       this.scanAxis = axis
       this.frameCamera(geometry.boundingBox!, this.scanAxis)
+      // Asked for before the closed shells, which only a cut needs: a pick
+      // needs the tree.
+      if (offThread) this.treeFrom(offThread, geometry)
       this.primeClosedShells('scan', geometry)
       this.warmPrograms()
     })
   }
 
+  /** Have a part's tree built off the thread (see bvh.ts treeOffThread), and
+   *  when it lands, look again at what the frames skipped while it was out:
+   *  what is under the cursor, and the pins' line of sight. The loop may be
+   *  asleep by then. */
+  private treeFrom(build: NonNullable<SceneManager['boundsTreeFrom']>, geometry: THREE.BufferGeometry): void {
+    treeOffThread(geometry, build, () => {
+      this.overlays.retestOcclusion()
+      this.requestHover()
+      this.invalidate()
+    })
+  }
+
   /**
    * Fill a geometry with the scan's arrays and fresh colour, tint and paint
    * buffers, sized to the render vertex count. `keep` is the previous
@@ -3310,6 +3340,7 @@ export class SceneManager {
     if (!this.mesh) return
     this.scanCap = this.keepCap(this.scanCap, null)
     const geometry = this.mesh.geometry as THREE.BufferGeometry
+    forgetTree(geometry)
     geometry.disposeBoundsTree?.()
     geometry.dispose()
     ;(this.mesh.material as THREE.Material).dispose()
diff --git a/src/viewer/bvh.ts b/src/viewer/bvh.ts
index 2ca7196c..b3acc25d 100644
--- a/src/viewer/bvh.ts
+++ b/src/viewer/bvh.ts
@@ -1,8 +1,10 @@
 // SPDX-License-Identifier: AGPL-3.0-only
-// Keeping a geometry's bounds tree in step with positions that moved.
+// Keeping a geometry's bounds tree in step with positions that moved, and
+// building one off the main thread.
 
 import type * as THREE from 'three'
-import { computeBoundsTree } from 'three-mesh-bvh'
+import { computeBoundsTree, MeshBVH, type MeshBVHOptions } from 'three-mesh-bvh'
+import type { SerializedTree } from '../core/workerProtocol'
 
 /**
  * Bring a geometry's culling bounds and bounds tree up to date after a rigid
@@ -24,10 +26,114 @@ import { computeBoundsTree } from 'three-mesh-bvh'
  * The bounding box and sphere are renewed here too, before anything reads
  * them: a new tree only ever sets the box on a geometry that has none, so the
  * stale ones would otherwise outlive a fallback build as well.
+ *
+ * A geometry whose tree is being built off the thread (see treeOffThread) is
+ * left to it: the tree is refitted to the move when it lands, which costs a
+ * walk over it rather than the build it is there to spare.
  */
 export function refitAfterRigid(geometry: THREE.BufferGeometry): void {
   geometry.computeBoundingBox()
   geometry.computeBoundingSphere()
   if (geometry.boundsTree) geometry.boundsTree.refit()
-  else computeBoundsTree.call(geometry)
+  else if (!treeAwaited(geometry)) computeBoundsTree.call(geometry)
+}
+
+/** The geometries whose tree is being built off the thread, each with the
+ *  build it waits for — a later one supersedes it. */
+const awaiting = new WeakMap<THREE.BufferGeometry, object>()
+
+/** Whether a geometry's tree is on its way from off the thread, and it has
+ *  none in the meantime. */
+export function treeAwaited(geometry: THREE.BufferGeometry): boolean {
+  return !geometry.boundsTree && awaiting.has(geometry)
+}
+
+/**
+ * Have a geometry's bounds tree built elsewhere — the mesh worker, through
+ * `build` — and laid over it when it comes back, rather than built here in
+ * one long task. `build` is handed copies of the positions and the index as
+ * they are now. The tree is indirect: it keeps its own order of the
+ * triangles and never sorts the index, which is drawn and read by triangle
+ * — the section caps and the picks — from the moment the part is shown.
+ *
+ * Until it lands the geometry has no tree: a pick takes three.js's ray
+ * through every triangle, and the pointer tests a frame makes skip the part
+ * (see sparingRays). A tree is laid over the geometry only if that is still
+ * the geometry it was built for — the same index and the same positions
+ * attribute — and the geometry has not been given a tree of its own since;
+ * positions moved in place by a rigid move in the meantime are refitted to.
+ * If the build fails, the tree is built here after all, as late as it is,
+ * and over the index as it stands. `landed` is called once a tree is in
+ * place, for whoever has something to look at again.
+ */
+export function treeOffThread(
+  geometry: THREE.BufferGeometry,
+  build: (positions: Float32Array, indices: Uint32Array) => Promise<SerializedTree>,
+  landed: () => void,
+): void {
+  const index = geometry.getIndex()
+  const position = geometry.getAttribute('position') as THREE.BufferAttribute
+  if (!index) {
+    computeBoundsTree.call(geometry)
+    return
+  }
+  const ticket = {}
+  awaiting.set(geometry, ticket)
+  const version = position.version
+  // Still the geometry the tree describes, and still without one: anything
+  // else that laid it out again built its own.
+  const current = () => {
+    if (awaiting.get(geometry) !== ticket) return false
+    awaiting.delete(geometry)
+    return !geometry.boundsTree && geometry.getIndex() === index && geometry.getAttribute('position') === position
+  }
+  // A build that throws as it is asked fails like one that answers so.
+  new Promise<SerializedTree>((resolve) => resolve(build((position.array as Float32Array).slice(), new Uint32Array(index.array)))).then(
+    (tree) => {
+      if (!current()) return
+      const bvh = MeshBVH.deserialize(tree as never, geometry, { setIndex: false })
+      // Moved while the tree was out: the same triangles, boxes elsewhere.
+      if (position.version !== version) bvh.refit()
+      geometry.boundsTree = bvh
+      landed()
+    },
+    () => {
+      if (!current()) return
+      computeBoundsTree.call(geometry, { indirect: true } as MeshBVHOptions)
+      landed()
+    },
+  )
+}
+
+/** Turn away the tree on its way to a geometry given up — see treeOffThread.
+ *  For a part taken off the stage: a geometry is disposed, too, to free its
+ *  GPU buffers while it goes on being drawn, so that says nothing. */
+export function forgetTree(geometry: THREE.BufferGeometry): void {
+  awaiting.delete(geometry)
+}
+
+/** How many pointer tests a frame makes are running — see sparingRays. */
+let sparing = 0
+
+/**
+ * Run the pointer tests a frame makes — the hover, the brush's footprint,
+ * the pins' line of sight — so that a ray meets nothing on a geometry whose
+ * tree is still being built off the thread (see treeOffThread). Without a
+ * tree, a ray goes through every triangle; on a scan of a million that is
+ * far more than a frame has, paid on every frame the cursor moves. A click
+ * is not run this way: it is made once, and finds the part the slow way.
+ * When the tree lands, the tests are run again.
+ */
+export function sparingRays<T>(test: () => T): T {
+  sparing++
+  try {
+    return test()
+  } finally {
+    sparing--
+  }
+}
+
+/** Whether a ray at this geometry is to meet nothing — see sparingRays. */
+export function raySpared(geometry: THREE.BufferGeometry): boolean {
+  return sparing > 0 && treeAwaited(geometry)
 }
diff --git a/src/viewer/clipRaycast.ts b/src/viewer/clipRaycast.ts
index 6ab47a55..34f3599d 100644
--- a/src/viewer/clipRaycast.ts
+++ b/src/viewer/clipRaycast.ts
@@ -9,6 +9,7 @@
 
 import type * as THREE from 'three'
 import { acceleratedRaycast } from 'three-mesh-bvh'
+import { raySpared } from './bvh'
 
 /** How far behind a plane a hit may lie and still count as on it, mm: the
  *  clip in the shader and the hit off the BVH are worked out apart. */
@@ -57,6 +58,9 @@ export function keptHits(
 
 /** Mesh.raycast for every mesh: three-mesh-bvh's, holding to the clip. */
 export function clippedRaycast(this: THREE.Mesh, raycaster: THREE.Raycaster, intersects: THREE.Intersection[]): void {
+  // A frame's pointer test does not go through every triangle of a part
+  // whose tree is still on its way — see bvh.ts sparingRays.
+  if (raySpared(this.geometry)) return
   const planes = clipPlanesOf(this.material)
   if (!planes) {
     acceleratedRaycast.call(this, raycaster, intersects)
diff --git a/src/viewer/marking.ts b/src/viewer/marking.ts
index abebe0ed..a0b4f701 100644
--- a/src/viewer/marking.ts
+++ b/src/viewer/marking.ts
@@ -431,15 +431,16 @@ export class SurfaceMarking {
     const mesh = this.ctx.mesh()
     const brush = this.paint
     if (!mesh || !brush || !this.ctx.paintAttr()) return
-
-    this.ctx.setPickRay(clientX, clientY)
-    const hit = this.ctx.raycaster.intersectObject(mesh, false)[0]
-    if (!hit || hit.faceIndex === undefined || hit.faceIndex === null) return
-
+    // The sweep needs the tree; without it — still being built off the
+    // thread — the ray would go through every triangle for nothing.
     const geometry = mesh.geometry as THREE.BufferGeometry
     const bvh = geometry.boundsTree
     const index = geometry.getIndex()
     if (!bvh || !index) return
+
+    this.ctx.setPickRay(clientX, clientY)
+    const hit = this.ctx.raycaster.intersectObject(mesh, false)[0]
+    if (!hit || hit.faceIndex === undefined || hit.faceIndex === null) return
     const idx = index.array as ArrayLike<number>
     const pos = (geometry.getAttribute('position') as THREE.BufferAttribute).array as Float32Array
 
diff --git a/src/viewer/orthoNav.ts b/src/viewer/orthoNav.ts
index c090bbc0..1232e1fc 100644
--- a/src/viewer/orthoNav.ts
+++ b/src/viewer/orthoNav.ts
@@ -27,6 +27,7 @@ import {
   type NavAction,
 } from './navSchemes'
 import { spaceMouseBusy, type SpaceMouseMotion } from './spaceMouse'
+import { sparingRays } from './bvh'
 
 // SpaceMouse speeds at full deflection, BumpMesh's.
 const PUCK_TURN_RAD_PER_S = 2.4
@@ -545,12 +546,15 @@ export class OrthoNavigator {
     this.orbiting = false // promoted once the drag passes the threshold
   }
 
-  /** The point on the model under a client position, if the model is there. */
+  /** The point on the model under a client position, if the model is there.
+   *  A pivot has somewhere to fall back to, so a part whose tree is still on
+   *  its way is not run through triangle by triangle to find one — see
+   *  bvh.ts sparingRays. */
   surfaceAt(clientX: number, clientY: number): THREE.Vector3 | null {
     const targets = this.orbitTargets()
     if (!targets.length) return null
     this.setPickRay(this.orbitRaycaster, clientX, clientY)
-    const hits = this.orbitRaycaster.intersectObjects(targets, false)
+    const hits = sparingRays(() => this.orbitRaycaster.intersectObjects(targets, false))
     return hits.length ? hits[0].point.clone() : null
   }
 
diff --git a/tests/bvhWorker.test.ts b/tests/bvhWorker.test.ts
new file mode 100644
index 00000000..c2f833d0
--- /dev/null
+++ b/tests/bvhWorker.test.ts
@@ -0,0 +1,275 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// The scan's bounds tree is built in the mesh worker and laid over the render
+// thread's geometry when it comes back (viewer/bvh.ts treeOffThread). What has
+// to hold: a ray through that tree meets exactly what it meets through a tree
+// built on the render thread, the index the tree came back for is not touched
+// — it is already on the GPU, and the section caps and the picks read it by
+// triangle — and a tree that lands on a geometry since moved, laid out again
+// or given up is made to fit it or turned away.
+import { readFileSync } from 'node:fs'
+import * as THREE from 'three'
+import { acceleratedRaycast, computeBoundsTree, MeshBVH } from 'three-mesh-bvh'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { SerializedTree, WorkerRequest, WorkerResponse } from '../src/core/workerProtocol'
+import { buildBinaryStl } from '../src/core/exportStl'
+import { forgetTree, refitAfterRigid, sparingRays, treeAwaited, treeOffThread } from '../src/viewer/bvh'
+import { clippedRaycast } from '../src/viewer/clipRaycast'
+import { cylinderMesh } from './helpers'
+import { fixture } from './fixtures'
+
+const ballbar = fixture('ballbar.stl')
+
+/** A seeded generator, so a failure is the same failure on every run. */
+function mulberry32(seed: number): () => number {
+  let a = seed >>> 0
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0
+    let t = a
+    t = Math.imul(t ^ (t >>> 15), t | 1)
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+  }
+}
+
+/** The scan's render geometry as the viewport lays it out: positions and the
+ *  index as drawn, over arrays of its own. */
+function renderGeometry(positions: Float32Array, indices: Uint32Array): THREE.BufferGeometry {
+  const geometry = new THREE.BufferGeometry()
+  geometry.setAttribute('position', new THREE.BufferAttribute(positions.slice(), 3))
+  geometry.setIndex(new THREE.BufferAttribute(indices.slice(), 1))
+  geometry.computeBoundingBox()
+  geometry.computeBoundingSphere()
+  return geometry
+}
+
+/** Every hit of 600 rays aimed at the part from a shell around it, through a
+ *  mesh as the viewport picks — each hit the distance and the triangle's
+ *  corners, read off the geometry's own index at the face the hit names, so
+ *  the trees are compared by the triangles they find and not by the order
+ *  they keep them in. */
+function hitsThrough(geometry: THREE.BufferGeometry, seed: number): string[][] {
+  const rand = mulberry32(seed)
+  const mesh = new THREE.Mesh(geometry, new THREE.MeshBasicMaterial({ side: THREE.DoubleSide }))
+  mesh.raycast = acceleratedRaycast
+  const sphere = geometry.boundingSphere!
+  const raycaster = new THREE.Raycaster()
+  const index = geometry.getIndex()!
+  const out: string[][] = []
+  for (let i = 0; i < 600; i++) {
+    const z = rand() * 2 - 1
+    const phi = rand() * Math.PI * 2
+    const r = Math.sqrt(1 - z * z)
+    const dir = new THREE.Vector3(r * Math.cos(phi), r * Math.sin(phi), z)
+    const aim = new THREE.Vector3(rand() - 0.5, rand() - 0.5, rand() - 0.5).multiplyScalar(sphere.radius * 1.6).add(sphere.center)
+    raycaster.ray.origin.copy(aim).addScaledVector(dir, -sphere.radius * 4)
+    raycaster.ray.direction.copy(dir)
+    const hits = raycaster.intersectObject(mesh, false)
+    out.push(
+      hits
+        .map((h) => {
+          const f = h.faceIndex! * 3
+          const corners = [index.getX(f), index.getX(f + 1), index.getX(f + 2)].sort((a, b) => a - b)
+          return `${h.distance.toFixed(9)}:${corners.join(',')}`
+        })
+        .sort(),
+    )
+  }
+  return out
+}
+
+/** The worker's tree laid over a geometry, as the render thread lays it. */
+function adopt(geometry: THREE.BufferGeometry, tree: SerializedTree): void {
+  geometry.boundsTree = MeshBVH.deserialize(tree as never, geometry, { setIndex: false })
+}
+
+/** The scans: a cylinder split for sharp shading, one large enough that the
+ *  tree numbers its triangles in 32 bits, and the ball bar where it is on
+ *  hand. */
+const scans: [string, () => ArrayBuffer][] = [
+  ['a noisy cylinder, its rims split', () => buildBinaryStl(cylinderMesh(10, 30, 48, 12, 0.02).positions, null, null, '')],
+  ['a cylinder past 65536 triangles', () => buildBinaryStl(cylinderMesh(10, 30, 256, 160, 0.02).positions, null, null, '')],
+]
+if (ballbar.exists) {
+  scans.push(['the ball bar', () => {
+    const b = readFileSync(ballbar.path)
+    return b.buffer.slice(b.byteOffset, b.byteOffset + b.byteLength)
+  }])
+}
+
+describe('the scan\'s bounds tree built in the worker', () => {
+  let scope: { onmessage: ((event: { data: WorkerRequest }) => void) | null; postMessage: (msg: WorkerResponse) => void }
+  let replies: WorkerResponse[]
+  beforeEach(async () => {
+    replies = []
+    scope = { onmessage: null, postMessage: (msg) => replies.push(msg) }
+    vi.stubGlobal('self', scope)
+    vi.resetModules()
+    await import('../src/core/meshWorker')
+  })
+  afterEach(() => vi.unstubAllGlobals())
+  const send = (msg: WorkerRequest) => {
+    replies.length = 0
+    scope.onmessage!({ data: msg })
+    return replies.at(-1)!
+  }
+
+  for (const [name, file] of scans) {
+    it(`meets what a tree built on the render thread meets, the index untouched: ${name}`, () => {
+      const loaded = send({ type: 'load', requestId: 1, name: 'scan.stl', buffer: file(), crease: { mode: 'on', angleDeg: 30 } })
+      if (loaded.type !== 'loaded') throw new Error(JSON.stringify(loaded))
+      expect(loaded.copyOf.length).toBeGreaterThan(0)
+
+      const geometry = renderGeometry(loaded.positions, loaded.indices)
+      const drawn = (geometry.getIndex()!.array as Uint32Array).slice()
+      const reply = send({ type: 'bounds-tree', requestId: 2, positions: loaded.positions.slice(), indices: loaded.indices.slice() })
+      if (reply.type !== 'bounds-tree-ok') throw new Error(JSON.stringify(reply))
+      adopt(geometry, reply.tree)
+      expect((geometry.boundsTree as unknown as { indirect: boolean }).indirect).toBe(true)
+
+      const here = renderGeometry(loaded.positions, loaded.indices)
+      here.computeBoundsTree = computeBoundsTree
+      here.computeBoundsTree()
+
+      const got = hitsThrough(geometry, 7)
+      const want = hitsThrough(here, 7)
+      // The ground truth must not be vacuous: most rays hit the part.
+      expect(want.filter((h) => h.length > 0).length).toBeGreaterThan(200)
+      expect(got).toEqual(want)
+      // The index drawn is the index sent, triangle for triangle.
+      expect(geometry.getIndex()!.array).toEqual(drawn)
+    })
+  }
+})
+
+describe('a tree built off the thread, landing', () => {
+  /** A part, and a build of its tree that comes back when the test says,
+   *  over the arrays as they were when it was asked for. */
+  function pending(seed: number) {
+    const sphere = new THREE.SphereGeometry(10, 48, 32)
+    const rand = mulberry32(seed)
+    const p = sphere.getAttribute('position') as THREE.BufferAttribute
+    for (let i = 0; i < p.count; i++) {
+      const k = 1 + (rand() - 0.5) * 0.2
+      p.setXYZ(i, p.getX(i) * k, p.getY(i) * k, p.getZ(i) * k)
+    }
+    const geometry = renderGeometry(p.array as Float32Array, Uint32Array.from(sphere.getIndex()!.array))
+    let land: (fail?: boolean) => Promise<void> = async () => {}
+    let asked = 0
+    const landed = vi.fn()
+    treeOffThread(
+      geometry,
+      (positions, indices) => {
+        asked++
+        return new Promise<SerializedTree>((resolve, reject) => {
+          land = async (fail = false) => {
+            if (fail) reject(new Error('The mesh worker failed.'))
+            else {
+              const g = new THREE.BufferGeometry()
+              g.setAttribute('position', new THREE.BufferAttribute(positions, 3))
+              g.setIndex(new THREE.BufferAttribute(indices, 1))
+              const tree = MeshBVH.serialize(new MeshBVH(g, { indirect: true } as never), { cloneBuffers: false }) as unknown as SerializedTree
+              resolve(tree)
+            }
+            await new Promise((r) => setTimeout(r, 0))
+          }
+        })
+      },
+      landed,
+    )
+    expect(asked).toBe(1)
+    return { geometry, land: (fail?: boolean) => land(fail), landed }
+  }
+
+  const rigid = new THREE.Matrix4()
+    .makeTranslation(37, -21, 14)
+    .multiply(new THREE.Matrix4().makeRotationFromEuler(new THREE.Euler(0.7, -1.1, 2.3)))
+
+  /** Bake a transform into the positions as the scan's alignment does. */
+  function bake(geometry: THREE.BufferGeometry, m: THREE.Matrix4): void {
+    const p = geometry.getAttribute('position') as THREE.BufferAttribute
+    const v = new THREE.Vector3()
+    for (let i = 0; i < p.count; i++) p.setXYZ(i, ...v.fromBufferAttribute(p, i).applyMatrix4(m).toArray())
+    p.needsUpdate = true
+  }
+
+  it('is awaited until it lands, then answers as a tree built here does', async () => {
+    const { geometry, land, landed } = pending(1)
+    const drawn = (geometry.getIndex()!.array as Uint32Array).slice()
+    expect(treeAwaited(geometry)).toBe(true)
+    await land()
+    expect(treeAwaited(geometry)).toBe(false)
+    expect(landed).toHaveBeenCalledTimes(1)
+    expect((geometry.boundsTree as unknown as { indirect: boolean }).indirect).toBe(true)
+    const here = renderGeometry(geometry.getAttribute('position').array as Float32Array, drawn)
+    here.computeBoundsTree = computeBoundsTree
+    here.computeBoundsTree()
+    expect(hitsThrough(geometry, 3)).toEqual(hitsThrough(here, 3))
+    expect(geometry.getIndex()!.array).toEqual(drawn)
+  })
+
+  it('is not built again on the main thread for a rigid move made while it is awaited, and is refitted to it when it lands', async () => {
+    const { geometry, land, landed } = pending(2)
+    bake(geometry, rigid)
+    refitAfterRigid(geometry)
+    expect(geometry.boundsTree).toBeUndefined()
+    // The culling bounds follow the move all the same.
+    const fresh = geometry.clone()
+    fresh.computeBoundingBox()
+    expect(geometry.boundingBox!.min.distanceTo(fresh.boundingBox!.min)).toBeLessThan(1e-9)
+    await land()
+    expect(landed).toHaveBeenCalledTimes(1)
+    const here = renderGeometry(geometry.getAttribute('position').array as Float32Array, geometry.getIndex()!.array as Uint32Array)
+    here.computeBoundsTree = computeBoundsTree
+    here.computeBoundsTree()
+    expect(hitsThrough(geometry, 4)).toEqual(hitsThrough(here, 4))
+  })
+
+  it('is turned away from a geometry laid out again before it landed', async () => {
+    const { geometry, land, landed } = pending(3)
+    // A resplit lays a new index on the same geometry and builds its own.
+    geometry.setIndex(new THREE.BufferAttribute((geometry.getIndex()!.array as Uint32Array).slice(), 1))
+    await land()
+    expect(geometry.boundsTree).toBeUndefined()
+    expect(landed).not.toHaveBeenCalled()
+  })
+
+  it('is turned away from a geometry that has a tree of its own by then', async () => {
+    const { geometry, land, landed } = pending(4)
+    const own = new MeshBVH(geometry, { indirect: true } as never)
+    geometry.boundsTree = own
+    await land()
+    expect(geometry.boundsTree).toBe(own)
+    expect(landed).not.toHaveBeenCalled()
+  })
+
+  it('is turned away from a part taken off the stage before it landed', async () => {
+    const { geometry, land, landed } = pending(7)
+    forgetTree(geometry)
+    expect(treeAwaited(geometry)).toBe(false)
+    await land()
+    expect(geometry.boundsTree).toBeUndefined()
+    expect(landed).not.toHaveBeenCalled()
+  })
+
+  it('is built here instead, over the index as it stands, when the worker fails', async () => {
+    const { geometry, land, landed } = pending(5)
+    const drawn = (geometry.getIndex()!.array as Uint32Array).slice()
+    await land(true)
+    expect(landed).toHaveBeenCalledTimes(1)
+    expect(geometry.boundsTree).toBeInstanceOf(MeshBVH)
+    expect(geometry.getIndex()!.array).toEqual(drawn)
+  })
+
+  it('spares a hover the ray through every triangle while it is awaited, and not a click', async () => {
+    const { geometry, land } = pending(6)
+    const mesh = new THREE.Mesh(geometry, new THREE.MeshBasicMaterial({ side: THREE.DoubleSide }))
+    mesh.raycast = clippedRaycast
+    const raycaster = new THREE.Raycaster(new THREE.Vector3(0, 0, 50), new THREE.Vector3(0, 0, -1))
+    // A click still finds the part, the slow way.
+    expect(raycaster.intersectObject(mesh, false).length).toBeGreaterThan(0)
+    // The pointer test a frame makes does not.
+    expect(sparingRays(() => raycaster.intersectObject(mesh, false))).toHaveLength(0)
+    await land()
+    expect(sparingRays(() => raycaster.intersectObject(mesh, false)).length).toBeGreaterThan(0)
+  })
+})

From be68b07f30e7fd680c179550a934b6ad59f048dc Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Thu, 5 Nov 2026 02:03:29 +0000
Subject: [PATCH 31/38] perf(bvh): the reference's tree off the thread too;
 review fixes

The reference is laid out with its tree built in the mesh worker, as the
scan is, and its pending tree is forgotten when it is taken away.

While a part's tree is on its way it hides nothing behind it either: the
hover steps see no cursor and an orbit pivot finds nothing on the stage.
The split picker hears the tree land and looks at its cursor again; the
reverse network's drag step is a frame's test and spares the part too.
Every tree built here as a fallback is indirect, and one from the worker
that cannot be laid over the geometry is built here instead, with a
warning.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 plugins/reverse/viewer/networkLayer.ts |  6 +++-
 src/viewer/PickScene.ts                |  9 ++++++
 src/viewer/SceneManager.ts             | 42 +++++++++++++++++++++++---
 src/viewer/bvh.ts                      | 36 +++++++++++++++++-----
 src/viewer/orthoNav.ts                 |  6 ++--
 src/viewer/sliceCap.ts                 |  6 ++--
 tests/bvhWorker.test.ts                | 27 +++++++++++++++++
 7 files changed, 115 insertions(+), 17 deletions(-)

diff --git a/plugins/reverse/viewer/networkLayer.ts b/plugins/reverse/viewer/networkLayer.ts
index 2dc39ee3..ad8b4174 100644
--- a/plugins/reverse/viewer/networkLayer.ts
+++ b/plugins/reverse/viewer/networkLayer.ts
@@ -48,6 +48,7 @@ import type { Vec3 } from '../../../src/core/types'
 import { SECTION_LINE_DEFAULT } from '../../../src/viewer/lineWidths'
 import { LineWidthRegistry } from '../../../src/viewer/lineWidthRegistry'
 import { pinLabel } from '../../../src/viewer/pinLabel'
+import { sparingRays } from '../../../src/viewer/bvh'
 import { modHeld } from '../../../src/ui/platform'
 import type { SceneManager } from '../../../src/viewer/SceneManager'
 import type { SceneLayer, SceneLayerHost } from '../../../src/viewer/sceneLayers'
@@ -1016,7 +1017,10 @@ export class NetworkLayer {
       const ev = latest
       latest = null
       if (!ev) return
-      const on = this.host.pickScan(ev.clientX, ev.clientY)
+      // A frame's test, like the hover: while the scan's tree is still on
+      // its way it meets nothing, and what is dragged stays where it was —
+      // see bvh.ts sparingRays.
+      const on = sparingRays(() => this.host.pickScan(ev.clientX, ev.clientY))
       if (!on) return
       const at = on.point
       const h = hit
diff --git a/src/viewer/PickScene.ts b/src/viewer/PickScene.ts
index 5a6439a6..ce4d07ca 100644
--- a/src/viewer/PickScene.ts
+++ b/src/viewer/PickScene.ts
@@ -64,6 +64,8 @@ export class PickScene {
    *  footprint is resolved once per frame rather than once per pointermove. */
   private hoverAt: { x: number; y: number } | null = null
   private hoverDirty = false
+  /** Stops hearing the scan's tree land — see armMarking. */
+  private stopHearing: (() => void) | null = null
 
   onPick: ((point: Vec3) => void) | null = null
   /** How many vertices the marking covers, reported when a gesture ends. */
@@ -163,6 +165,12 @@ export class PickScene {
       onPaintChange: (count) => this.onPaintChange?.(count),
     })
     this.marking.setTheme(theme)
+    // The brush footprint skips the scan until its tree lands (see bvh.ts
+    // sparingRays); when it does, the cursor is looked at again here too.
+    this.stopHearing = channel.onTreeLanded?.(() => {
+      this.hoverDirty = true
+      this.viewport.wake()
+    }) ?? null
     const canvas = this.viewport.renderer.domElement
     canvas.addEventListener('pointermove', (e) => {
       this.hoverAt = { x: e.clientX, y: e.clientY }
@@ -265,6 +273,7 @@ export class PickScene {
     // shared mask, and what becomes of it is decided by whoever opened this
     // picker, not by the canvas closing.
     this.marking?.dispose()
+    this.stopHearing?.()
     this.markerGeometry.dispose()
     this.material.dispose()
     this.viewport.dispose()
diff --git a/src/viewer/SceneManager.ts b/src/viewer/SceneManager.ts
index f3e3fa03..552e1ac7 100644
--- a/src/viewer/SceneManager.ts
+++ b/src/viewer/SceneManager.ts
@@ -33,7 +33,7 @@ import type { SectionCut } from '../core/section/slice'
 import type { ControlScheme } from './navSchemes'
 import type { PickMarker } from './PickScene'
 import { computeBoundsTree, disposeBoundsTree } from 'three-mesh-bvh'
-import { forgetTree, refitAfterRigid, sparingRays, treeOffThread } from './bvh'
+import { forgetTree, refitAfterRigid, sparingRays, treeAwaited, treeOffThread } from './bvh'
 import type { SerializedTree } from '../core/workerProtocol'
 import type { FitData, Vec3 } from '../core/types'
 import { rigidApplyToPoints, rigidRotate, rigidRotateVectors, type Rigid } from '../core/deviation/rigid'
@@ -206,6 +206,10 @@ export interface MarkingChannel {
   setPaintColor: (rgb: [number, number, number]) => void
   /** The scan's own vertex behind a render index — see graphVertex. */
   graphVertex: (v: number) => number
+  /** Hear when a part's tree lands from off the thread (see bvh.ts
+   *  treeOffThread): what was under the cursor is to be looked at again.
+   *  The returned function stops it. */
+  onTreeLanded?: (heard: () => void) => () => void
 }
 
 /** A mesh laid out for the scan's place in the viewport: its geometry, the
@@ -377,6 +381,9 @@ export class SceneManager {
    *  bvh.ts treeOffThread. Without it, the tree is built here as the scan is
    *  prepared. */
   boundsTreeFrom: ((positions: Float32Array, indices: Uint32Array) => Promise<SerializedTree>) | null = null
+  /** Who else looks again when a tree lands — the split picker's brush
+   *  footprint; see MarkingChannel.onTreeLanded. */
+  private treeHeard = new Set<() => void>()
   /** Elements lit because something being built refers to them, and
    *  elements lit because a picker's option is hovered — two reasons, one
    *  look; the overlays hear the union. */
@@ -941,15 +948,20 @@ export class SceneManager {
     // region, over what lies behind — and nothing lights under the gizmo
     // corner, which is a button first.
     let covered = axis !== null
+    // While a part's tree is still on its way the frame's rays skip it (see
+    // bvh.ts sparingRays), and it would hide nothing behind it: an element
+    // or a face of a layer's would light through the part. Nothing lights
+    // until the tree lands and the cursor is looked at again.
+    const over = this.partTreeAwaited() ? null : at
     // A step the arrow keys took lights alone: every other layer is covered.
-    const stepped = this.cyclingLayer(at)
+    const stepped = this.cyclingLayer(over)
     for (const step of this.hoverSteps()) {
       const under = stepped ? step.layer !== stepped : covered
       if (step.layer) this.hoverCovered.set(step.layer, under)
-      if (step.hover(at, under) && step.covers) covered = true
+      if (step.hover(over, under) && step.covers) covered = true
     }
     if (!this.hoverEnabled) return
-    const hit = at ? this.pick(at.x, at.y) : null
+    const hit = over ? this.pick(over.x, over.y) : null
     // Silence is worth reporting once, not every frame the cursor spends off
     // the part.
     if (!hit && !this.hoverWasHit) return
@@ -957,6 +969,14 @@ export class SceneManager {
     this.onHover?.(hit)
   }
 
+  /** Whether a part on the stage — the scan, or a reference shown — is
+   *  still waiting for its tree from off the thread. */
+  private partTreeAwaited(): boolean {
+    const scan = this.mesh?.geometry as THREE.BufferGeometry | undefined
+    const reference = this.nominalMesh?.visible ? (this.nominalMesh.geometry as THREE.BufferGeometry) : undefined
+    return Boolean((scan && treeAwaited(scan)) || (reference && treeAwaited(reference)))
+  }
+
   setHoverEnabled(enabled: boolean): void {
     if (this.hoverEnabled === enabled) return
     this.hoverEnabled = enabled
@@ -1067,6 +1087,7 @@ export class SceneManager {
       this.overlays.retestOcclusion()
       this.requestHover()
       this.invalidate()
+      for (const heard of this.treeHeard) heard()
     })
   }
 
@@ -2550,6 +2571,10 @@ export class SceneManager {
         setPaintUniform(this.uPaintColor, rgb)
         this.invalidate()
       },
+      onTreeLanded: (heard) => {
+        this.treeHeard.add(heard)
+        return () => this.treeHeard.delete(heard)
+      },
     }
   }
 
@@ -2618,7 +2643,12 @@ export class SceneManager {
     geometry.setIndex(new THREE.BufferAttribute(indices, 1))
     geometry.computeBoundingBox()
     geometry.computeBoundingSphere()
-    try { geometry.computeBoundsTree() } catch (e) { geometry.dispose(); throw e }
+    // Off the thread once the reference is in place, as a scan's is — see
+    // prepareMesh.
+    const offThread = this.boundsTreeFrom
+    if (!offThread) {
+      try { geometry.computeBoundsTree() } catch (e) { geometry.dispose(); throw e }
+    }
 
     const material = new THREE.MeshStandardMaterial({
       color: this.theme.nominal,
@@ -2639,6 +2669,7 @@ export class SceneManager {
       this.scene.add(this.nominalMesh)
       // Cut with the rest, if the section view is cutting.
       this.applySlice()
+      if (offThread) this.treeFrom(offThread, geometry)
       this.primeClosedShells('nominal', geometry)
       this.warmPrograms()
       this.invalidate()
@@ -3323,6 +3354,7 @@ export class SceneManager {
     if (!this.nominalMesh) return
     this.referenceCap = this.keepCap(this.referenceCap, null)
     const geometry = this.nominalMesh.geometry as THREE.BufferGeometry
+    forgetTree(geometry)
     geometry.disposeBoundsTree?.()
     geometry.dispose()
     ;(this.nominalMesh.material as THREE.Material).dispose()
diff --git a/src/viewer/bvh.ts b/src/viewer/bvh.ts
index b3acc25d..ebd7f58a 100644
--- a/src/viewer/bvh.ts
+++ b/src/viewer/bvh.ts
@@ -35,7 +35,21 @@ export function refitAfterRigid(geometry: THREE.BufferGeometry): void {
   geometry.computeBoundingBox()
   geometry.computeBoundingSphere()
   if (geometry.boundsTree) geometry.boundsTree.refit()
-  else if (!treeAwaited(geometry)) computeBoundsTree.call(geometry)
+  else if (!treeAwaited(geometry)) computeBoundsTree.call(geometry, INDIRECT)
+}
+
+/** A tree that sorts its own list of triangle numbers and never the index:
+ *  the index is drawn and read by triangle — the section caps, the picks —
+ *  so a tree built over a part already shown must leave it as it is. */
+const INDIRECT = { indirect: true } as MeshBVHOptions
+
+/** A tree sent from the worker, laid over the geometry it was built for,
+ *  whose index it reads as it stands. */
+function treeFrom(data: SerializedTree, geometry: THREE.BufferGeometry, index: THREE.BufferAttribute): MeshBVH {
+  // three-mesh-bvh's own type knows nothing of the indirect order; the
+  // index it asks for is the geometry's, and is not laid back (setIndex).
+  const serialized = { roots: data.roots, indirectBuffer: data.indirectBuffer, index: index.array }
+  return MeshBVH.deserialize(serialized, geometry, { setIndex: false })
 }
 
 /** The geometries whose tree is being built off the thread, each with the
@@ -91,15 +105,23 @@ export function treeOffThread(
   new Promise<SerializedTree>((resolve) => resolve(build((position.array as Float32Array).slice(), new Uint32Array(index.array)))).then(
     (tree) => {
       if (!current()) return
-      const bvh = MeshBVH.deserialize(tree as never, geometry, { setIndex: false })
-      // Moved while the tree was out: the same triangles, boxes elsewhere.
-      if (position.version !== version) bvh.refit()
-      geometry.boundsTree = bvh
+      try {
+        const bvh = treeFrom(tree, geometry, index)
+        // Moved while the tree was out: the same triangles, boxes elsewhere.
+        if (position.version !== version) bvh.refit()
+        geometry.boundsTree = bvh
+      } catch (e) {
+        // A tree that does not fit what it landed on: built here instead.
+        console.warn('The bounds tree from the mesh worker could not be used; building it here.', e)
+        geometry.boundsTree = undefined
+        computeBoundsTree.call(geometry, INDIRECT)
+      }
       landed()
     },
-    () => {
+    (e) => {
       if (!current()) return
-      computeBoundsTree.call(geometry, { indirect: true } as MeshBVHOptions)
+      console.warn('The mesh worker could not build the bounds tree; building it here.', e)
+      computeBoundsTree.call(geometry, INDIRECT)
       landed()
     },
   )
diff --git a/src/viewer/orthoNav.ts b/src/viewer/orthoNav.ts
index 1232e1fc..3b2fd7e1 100644
--- a/src/viewer/orthoNav.ts
+++ b/src/viewer/orthoNav.ts
@@ -27,7 +27,7 @@ import {
   type NavAction,
 } from './navSchemes'
 import { spaceMouseBusy, type SpaceMouseMotion } from './spaceMouse'
-import { sparingRays } from './bvh'
+import { sparingRays, treeAwaited } from './bvh'
 
 // SpaceMouse speeds at full deflection, BumpMesh's.
 const PUCK_TURN_RAD_PER_S = 2.4
@@ -549,10 +549,12 @@ export class OrthoNavigator {
   /** The point on the model under a client position, if the model is there.
    *  A pivot has somewhere to fall back to, so a part whose tree is still on
    *  its way is not run through triangle by triangle to find one — see
-   *  bvh.ts sparingRays. */
+   *  bvh.ts sparingRays — and nothing is found at all while it is: skipped,
+   *  it would let the ray through to whatever lies behind it. */
   surfaceAt(clientX: number, clientY: number): THREE.Vector3 | null {
     const targets = this.orbitTargets()
     if (!targets.length) return null
+    if (targets.some((t) => (t as THREE.Mesh).isMesh && treeAwaited((t as THREE.Mesh).geometry))) return null
     this.setPickRay(this.orbitRaycaster, clientX, clientY)
     const hits = sparingRays(() => this.orbitRaycaster.intersectObjects(targets, false))
     return hits.length ? hits[0].point.clone() : null
diff --git a/src/viewer/sliceCap.ts b/src/viewer/sliceCap.ts
index ae9b65be..37ad52dc 100644
--- a/src/viewer/sliceCap.ts
+++ b/src/viewer/sliceCap.ts
@@ -75,8 +75,10 @@ export function closedPartOf(geometry: THREE.BufferGeometry): ClosedPart {
  * Keep closed shells found elsewhere as this geometry's — the mesh worker's,
  * a flag for each vertex (see closedVertices) — so the first cut of a part
  * loaded does not search it on the main thread. A triangle is read off its
- * first corner, through the index as it stands now: a bounds tree built
- * over the geometry reorders its triangles and never its vertices. False,
+ * first corner, through the index as it stands now. A part's tree from the
+ * worker is indirect and leaves the index alone (see bvh.ts treeOffThread),
+ * but one built here as a part is laid out again — a resplit, an edit —
+ * reorders its triangles; neither ever moves a vertex. False,
  * and nothing kept, when the count of flags is not this geometry's count
  * of vertices. That alone does not prove the flags are this geometry's —
  * a replacement can have as many — so the caller also checks that the
diff --git a/tests/bvhWorker.test.ts b/tests/bvhWorker.test.ts
index c2f833d0..310f6f96 100644
--- a/tests/bvhWorker.test.ts
+++ b/tests/bvhWorker.test.ts
@@ -113,6 +113,24 @@ describe('the scan\'s bounds tree built in the worker', () => {
     return replies.at(-1)!
   }
 
+  it('meets on the reference what a tree built on the render thread meets, the index untouched', () => {
+    const buffer = buildBinaryStl(cylinderMesh(10, 30, 96, 24, 0.02).positions, null, null, '')
+    const loaded = send({ type: 'load-nominal', requestId: 1, name: 'reference.stl', buffer })
+    if (loaded.type !== 'nominal-loaded') throw new Error(JSON.stringify(loaded))
+    const geometry = renderGeometry(loaded.positions, loaded.indices)
+    const drawn = (geometry.getIndex()!.array as Uint32Array).slice()
+    const reply = send({ type: 'bounds-tree', requestId: 2, positions: loaded.positions.slice(), indices: loaded.indices.slice() })
+    if (reply.type !== 'bounds-tree-ok') throw new Error(JSON.stringify(reply))
+    adopt(geometry, reply.tree)
+    const here = renderGeometry(loaded.positions, loaded.indices)
+    here.computeBoundsTree = computeBoundsTree
+    here.computeBoundsTree()
+    const want = hitsThrough(here, 11)
+    expect(want.filter((h) => h.length > 0).length).toBeGreaterThan(200)
+    expect(hitsThrough(geometry, 11)).toEqual(want)
+    expect(geometry.getIndex()!.array).toEqual(drawn)
+  })
+
   for (const [name, file] of scans) {
     it(`meets what a tree built on the render thread meets, the index untouched: ${name}`, () => {
       const loaded = send({ type: 'load', requestId: 1, name: 'scan.stl', buffer: file(), crease: { mode: 'on', angleDeg: 30 } })
@@ -224,6 +242,15 @@ describe('a tree built off the thread, landing', () => {
     expect(hitsThrough(geometry, 4)).toEqual(hitsThrough(here, 4))
   })
 
+  it('is turned away from a geometry whose positions were laid anew before it landed', async () => {
+    const { geometry, land, landed } = pending(8)
+    const p = geometry.getAttribute('position') as THREE.BufferAttribute
+    geometry.setAttribute('position', new THREE.BufferAttribute((p.array as Float32Array).slice(), 3))
+    await land()
+    expect(geometry.boundsTree).toBeUndefined()
+    expect(landed).not.toHaveBeenCalled()
+  })
+
   it('is turned away from a geometry laid out again before it landed', async () => {
     const { geometry, land, landed } = pending(3)
     // A resplit lays a new index on the same geometry and builds its own.

From c6994e8c8024c7698e449bccd43ed960feb77dd6 Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Thu, 5 Nov 2026 02:24:59 +0000
Subject: [PATCH 32/38] perf(css): pulse ring animates transform and opacity

The ring keyframes animated border-color and box-shadow, which repaint every
frame while a hint shows. The ring now only changes opacity and the halo is its
own pseudo-element with a static shadow that scales and fades.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 src/styles.css | 60 +++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 47 insertions(+), 13 deletions(-)

diff --git a/src/styles.css b/src/styles.css
index 3fc56c68..ea942d35 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -436,40 +436,69 @@ button.primary:hover:not(:disabled) {
    busy lamp runs at — so the guidance reads as a lamp rather than as another
    piece of the control. It stands off by a couple of pixels rather than hugging
    the control, because that strip of background is what makes it a ring. */
-.pulse::after {
+.pulse::after,
+.pulse::before {
   content: '';
   position: absolute;
   inset: -4px;
-  border: 2px solid #e8a33d;
   border-radius: 6px;
   pointer-events: none;
+}
+
+.pulse::after {
+  border: 2px solid #e8a33d;
   animation: pulsering 1.6s ease-out infinite;
 }
 
-.pulse:disabled::after {
+/* The halo is its own element with a static shadow, so that both layers can
+   be animated on the compositor: a box-shadow or border-color keyframe
+   repaints the control's neighbourhood every frame for as long as the hint is
+   showing, where opacity and scale are only a change of the layer's matrix. */
+.pulse::before {
+  box-shadow: 0 0 0 7px rgba(232, 163, 61, 0.5);
+  opacity: 0;
+  animation: pulsehalo 1.6s ease-out infinite;
+}
+
+.pulse:disabled::after,
+.pulse:disabled::before {
   display: none;
 }
 
 /* An annunciator ping: the ring comes up to full, then throws a halo outward
-   off its own edge as it settles back. Colour and halo are animated rather
-   than opacity, so the two peak together instead of the ring dimming the very
-   halo it is throwing — and the halo is spread on a shadow rather than a
-   second element, so nothing around the control moves. */
+   off its own edge as it settles back. The ring only changes opacity, and the
+   halo swells and fades, so the two peak together instead of the ring dimming
+   the very halo it is throwing — and nothing around the control moves. */
 @keyframes pulsering {
   0%,
   100% {
-    border-color: rgba(232, 163, 61, 0.5);
-    box-shadow: 0 0 0 0 rgba(232, 163, 61, 0);
+    opacity: 0.5;
   }
 
   35% {
-    border-color: rgba(232, 163, 61, 1);
-    box-shadow: 0 0 0 0 rgba(232, 163, 61, 0.5);
+    opacity: 1;
   }
 
   75% {
-    border-color: rgba(232, 163, 61, 0.8);
-    box-shadow: 0 0 0 10px rgba(232, 163, 61, 0);
+    opacity: 0.8;
+  }
+}
+
+@keyframes pulsehalo {
+  0%,
+  35%,
+  100% {
+    opacity: 0;
+    transform: scale(0.92);
+  }
+
+  55% {
+    opacity: 0.6;
+  }
+
+  75% {
+    opacity: 0;
+    transform: scale(1);
   }
 }
 
@@ -2575,6 +2604,11 @@ button.x:disabled {
     animation: none;
     opacity: 1;
   }
+
+  .pulse::before {
+    animation: none;
+    display: none;
+  }
 }
 
 /* ---------------- modals ---------------- */

From 918810b3a0fd18711b42f58a374b5812ca701a61 Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Thu, 5 Nov 2026 02:46:28 +0000
Subject: [PATCH 33/38] fix(mesh): swap the edited copy before the scene paints

SceneSync's effects run ahead of the Workbench's since Task 12, and with
them the paint ran before Mesh Tools swapped its copy in or out: a map
coming back to Deviation or Thickness was laid on the copy and the scan
came back bare. The swap is a layout effect now, ahead of every plain
effect. e2e-mesh-flip checks the round trip for both maps.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 plugins/mesh-tools/app/useMeshWorkspace.ts   | 14 +++-
 plugins/mesh-tools/scripts/e2e-mesh-flip.mjs | 78 +++++++++++++++++++-
 src/app/SceneSync.tsx                        | 11 ++-
 src/app/useSceneSync.ts                      |  4 +-
 4 files changed, 98 insertions(+), 9 deletions(-)

diff --git a/plugins/mesh-tools/app/useMeshWorkspace.ts b/plugins/mesh-tools/app/useMeshWorkspace.ts
index cdb4b7a4..d20a92d2 100644
--- a/plugins/mesh-tools/app/useMeshWorkspace.ts
+++ b/plugins/mesh-tools/app/useMeshWorkspace.ts
@@ -8,7 +8,7 @@
 // the commands share; this hands the panel the session's, and a click on a
 // hole's ring the hole it rings.
 import { meshSceneOf } from '../viewer/meshScene'
-import { useEffect, useRef } from 'react'
+import { useEffect, useLayoutEffect, useRef } from 'react'
 import { meshToolsOf } from '../core/meshClient'
 import { summarizeCopyDeviation } from '../core/edit'
 import { reductionScale } from '../core/reduce'
@@ -425,10 +425,16 @@ export function useMeshWorkspace(session: MeshToolsSession) {
   // ---- The edited copy -------------------------------------------------------------
 
   // Mesh Tools shows the copy in the scan's place; every other workspace the
-  // scan it measures. Before anything is painted on either — the effects of
-  // the scene's own sync run after these.
+  // scan it measures. Before anything is painted on either: the scene's own
+  // sync (app/SceneSync.tsx) is a child of the Workbench this runs in, and a
+  // child's effects run ahead of its parent's, so as a plain effect this
+  // would swap after the paint — the map of the workspace coming laid on the
+  // copy going, and the scan coming back bare. A layout effect runs ahead of
+  // every plain effect in the commit, wherever it sits in the tree. It only
+  // trades a few objects (SceneManager.swapSlots) and reads nothing the
+  // browser lays out or paints.
   const copyTriangles = useMeshTools((s) => s.copyTriangles)
-  useEffect(() => {
+  useLayoutEffect(() => {
     sceneRef.current?.showEdited(workspace === 'mesh' && copyTriangles !== null)
   }, [workspace, copyTriangles, copyVersion, sceneRef])
 
diff --git a/plugins/mesh-tools/scripts/e2e-mesh-flip.mjs b/plugins/mesh-tools/scripts/e2e-mesh-flip.mjs
index dfd12cba..059a9eee 100644
--- a/plugins/mesh-tools/scripts/e2e-mesh-flip.mjs
+++ b/plugins/mesh-tools/scripts/e2e-mesh-flip.mjs
@@ -11,7 +11,7 @@
 // Env: CHROME (chrome.exe path), APP_URL, SHOT_DIR.
 import { mkdirSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
-import { canvasRect, check, drag, finish, launchApp, loadScan, OUT_DIR, shotPath, sleep } from '../../../scripts/e2e-lib.mjs'
+import { canvasRect, check, drag, finish, launchApp, loadScan, OUT_DIR, previewReady, shotPath, sleep } from '../../../scripts/e2e-lib.mjs'
 import { noisyBoxScan } from '../../../scripts/e2e-fixtures.mjs'
 
 mkdirSync(OUT_DIR, { recursive: true })
@@ -106,4 +106,80 @@ console.log('flipped marked', patch)
 check((await text('[data-test=pending-edit]')).includes('marked region'), `the list says so: ${await text('[data-test=pending-edit]')}`)
 check(count(await text('[data-test=mark-count]')) === 0, 'the marking goes with it')
 check(patch.mauve > 2000 && patch.mauve < flipped.mauve * 0.8, 'the patch alone shows its back faces')
+
+// ---- the other workspaces' maps, with the flipped copy waiting -------------
+// Leaving Mesh Tools swaps the copy out for the scan before anything paints,
+// and coming back swaps it in before the paint is taken off: the map of the
+// workspace coming is laid on the scan, not on the copy that was on screen a
+// moment before, and the copy comes back bare.
+/** The surface on screen: which of the two it is, whether a map is laid on
+ *  it, and the scan's own colours — wherever it is — summed. */
+const surface = () =>
+  page.evaluate(() => {
+    const scene = window.__scanruler.scene()
+    const edited = scene.showingEdited()
+    const painted = scene.mapPainted().scan
+    // The scan's vertices and colours, whichever slot it is in: both read
+    // the scan's even while the copy is on screen.
+    const n = scene.scanVertexCount()
+    let sum = 0
+    for (let v = 0; v < n; v++) {
+      const [r, g, b] = scene.scanColorAt(v)
+      sum = (sum * 31 + r * 65536 + g * 256 + b) % 2147483647
+    }
+    return { edited, painted, sum }
+  })
+/** Over to a workspace, and the frames after it settled. */
+const toWorkspace = async (id) => {
+  await page.click(`[data-test=workspace-${id}]`)
+  await sleep(800)
+}
+/** A map measured in a workspace, there and back through Mesh Tools. */
+const roundTrip = async (what, workspace) => {
+  const mapped = await surface()
+  console.log(what, 'measured', mapped)
+  check(!mapped.edited && mapped.painted === 'painted' && mapped.sum !== bare.sum, `the ${what} map is painted on the scan`)
+  await toWorkspace('mesh')
+  const inMesh = await surface()
+  check(inMesh.edited && inMesh.painted === null, `Mesh Tools shows the copy, bare of the ${what} map (${inMesh.painted})`)
+  await toWorkspace(workspace)
+  const back = await surface()
+  console.log(what, 'back', back)
+  check(!back.edited && back.painted === 'painted' && back.sum === mapped.sum, `back on ${workspace}, the scan wears the ${what} map again, byte for byte`)
+  await toWorkspace('mesh')
+  const again = await surface()
+  check(again.edited && again.painted === null, `and the copy is still bare of it (${again.painted})`)
+}
+
+await toWorkspace('thickness')
+// The scan as it is with no map on it, to tell one from.
+const bare = await surface()
+await page.click('[data-test=measure-thickness]')
+await page.waitForSelector('[data-test=thickness-legend]', { timeout: 300_000 })
+await page.waitForFunction(() => !document.querySelector('[data-test=fitting-chip]'), { timeout: 300_000 })
+await sleep(800)
+await roundTrip('thickness', 'thickness')
+
+// The deviation from a plane fitted on the box's top, the same way.
+await toWorkspace('elements')
+await page.click('[data-test=fit-plane]')
+let fitted = false
+for (const [fx, fy] of [[0.5, 0.4], [0.46, 0.36], [0.54, 0.44], [0.5, 0.46], [0.5, 0.32]]) {
+  await page.mouse.click(r.x + (r.w - 190) * fx, r.y + r.h * fy)
+  if (await previewReady(page)) {
+    await page.click('[data-test=create-element]')
+    await sleep(400)
+    fitted = true
+    break
+  }
+}
+check(fitted, 'a plane is fitted on the top of the box')
+await toWorkspace('deviation')
+await page.click('[data-test=source-element]')
+await page.waitForSelector('[data-test=target-select]')
+const target = await page.$eval('[data-test=target-select]', (el) => [...el.options].find((o) => /plane/i.test(o.textContent))?.value ?? '')
+await page.select('[data-test=target-select]', target)
+await page.waitForSelector('[data-test=deviation-legend]', { timeout: 60_000 })
+await sleep(800)
+await roundTrip('deviation', 'deviation')
 await finish(browser, consoleErrors)
diff --git a/src/app/SceneSync.tsx b/src/app/SceneSync.tsx
index 5e54edf0..9b816209 100644
--- a/src/app/SceneSync.tsx
+++ b/src/app/SceneSync.tsx
@@ -9,9 +9,14 @@
 //
 // It is mounted after the viewport, so on the first commit the scene exists by
 // the time these effects first run, exactly as it did when they ran in the
-// Workbench; its effects now run ahead of the Workbench's own in a commit,
-// which nothing there depends on (they act on the stores, the worker and the
-// 2D sheet, not on what the viewport was last told).
+// Workbench. Its effects now run ahead of the Workbench's own in a commit —
+// the plugins' among them, which the Workbench calls. One of those the paint
+// here does depend on: Mesh Tools swapping its edited copy in and out of the
+// scan's place, which has to come first so a map is laid on whichever of the
+// two is on screen. That one is a layout effect (useMeshWorkspace), which runs
+// ahead of every plain effect wherever it sits. The rest act on the stores,
+// the worker, the 2D sheet, or layers and switches of the viewport that
+// nothing here writes as well, or writes to agree with them.
 import { memo } from 'react'
 import { useElementField } from './useElementField'
 import { useSceneSync } from './useSceneSync'
diff --git a/src/app/useSceneSync.ts b/src/app/useSceneSync.ts
index 6fd6f609..76c10a03 100644
--- a/src/app/useSceneSync.ts
+++ b/src/app/useSceneSync.ts
@@ -841,7 +841,9 @@ export function useSceneSync({
     // (a tab taken, the map put away and back): its colours stand, and the
     // scene is told so it does not lay them on or upload them again. This
     // leans on a buffer only ever being handed to the scan state that is
-    // showing: the mesh tools' edited-copy swap runs before this effect.
+    // showing: the mesh tools' edited-copy swap runs before this effect, as
+    // a layout effect, since this one runs in a child of the Workbench that
+    // swaps and so ahead of its plain effects (see SceneSync.tsx).
     const map = colormapById(colormap)
     const key = paintKey(version, scale, map.id)
     const repainted = painted.current.get(rgb) !== key

From bb0071ce863a110531278b3da17fbc8e85a238f9 Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Thu, 5 Nov 2026 02:47:43 +0000
Subject: [PATCH 34/38] fix(commands): session reads answer past the map's wait

session.state and report.get waited strictly for the element map, and a
map queued behind a long job in the mesh worker made a read fail after
30 s. They now answer anyway, the map said to be running; the commands
that act on the map still wait strictly.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/commands/core/common.ts      | 13 +++++++++++
 src/commands/core/session.ts     |  9 ++++----
 tests/commandsMapSettled.test.ts | 39 +++++++++++++++++++++++++++++++-
 3 files changed, 56 insertions(+), 5 deletions(-)

diff --git a/src/commands/core/common.ts b/src/commands/core/common.ts
index 83df5c34..e9d14dd9 100644
--- a/src/commands/core/common.ts
+++ b/src/commands/core/common.ts
@@ -196,3 +196,16 @@ export async function mapSettled(scene?: FrameSource | null): Promise<void> {
   await nextFrame(scene)
   await waitFor(() => useDeviation.getState().elementStatus !== 'running', 'the map against the element', 30_000)
 }
+
+/** As mapSettled, for a command that only reads the session out: past the
+ *  wait with the map still being measured — the mesh worker busy with a long
+ *  job queued ahead of it — the answer is given anyway, and says the map is
+ *  "running" where its figures would be, rather than failing a read for
+ *  being slow. A command that acts on the map waits strictly. */
+export async function mapSettledOrMeasuring(scene?: FrameSource | null): Promise<void> {
+  try {
+    await mapSettled(scene)
+  } catch (e) {
+    if (useDeviation.getState().elementStatus !== 'running') throw e
+  }
+}
diff --git a/src/commands/core/session.ts b/src/commands/core/session.ts
index 83bfe9af..f48a8615 100644
--- a/src/commands/core/session.ts
+++ b/src/commands/core/session.ts
@@ -13,7 +13,7 @@ import { RECENT_KEPT, RECENT_RESULT_CHARS, recentOutcomes } from '../registry'
 import { enumOf, int, obj, str } from '../schema'
 import { internalWorkspace, publicWorkspace, sessionAfterStep, sessionState, workspaceNames } from '../state'
 import { CommandError, type Command } from '../types'
-import { discardSchema, mapSettled, requireDiscardable, waitFor } from './common'
+import { discardSchema, mapSettledOrMeasuring, requireDiscardable, waitFor } from './common'
 
 const state: Command = {
   name: 'state',
@@ -24,7 +24,7 @@ const state: Command = {
   readOnly: true,
   headless: true,
   run: async () => {
-    await mapSettled(sceneOf())
+    await mapSettledOrMeasuring(sceneOf())
     return sessionState()
   },
 }
@@ -78,8 +78,9 @@ const report: Command<{ format?: 'json' | 'text'; workspace?: ReportWorkspace }>
   readOnly: true,
   run: async ({ format = 'json', workspace: w = 'measure' }) => {
     // The report pairs the map's figures with the settings it was measured
-    // under: the one measured, not the one before.
-    await mapSettled(sceneOf())
+    // under: the one measured, not the one before — or, past the wait, none,
+    // with the map said to be running.
+    await mapSettledOrMeasuring(sceneOf())
     return format === 'text' ? { format, workspace: w, text: reportText(w) } : { format, report: reportJson() }
   },
 }
diff --git a/tests/commandsMapSettled.test.ts b/tests/commandsMapSettled.test.ts
index 076ce5d8..e7d41b00 100644
--- a/tests/commandsMapSettled.test.ts
+++ b/tests/commandsMapSettled.test.ts
@@ -4,7 +4,7 @@
 // reads it must wait for that, and not take the status for a refusal ("no
 // map") or hand back the figures of the map before. On a 40 mm box, in the
 // in-process worker — see commandKit.ts.
-import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest'
 import { useDeviation } from '../src/state/deviationStore'
 import { runCommand } from '../src/commands/registry'
 import { boxMesh } from './helpers'
@@ -47,6 +47,43 @@ describe('a command that reads the map against an element', () => {
     expect((await refusal)?.message).toContain('no deviation map')
   })
 
+  // The mesh worker answers in order, so a map queued behind a long job — a
+  // thickness map, a boolean — can be measured for longer than a command
+  // waits. A read of the session says so; a command that acts on the map
+  // gives up, as it waits for a map it needs.
+  describe('past the wait, with the map still being measured', () => {
+    afterEach(() => {
+      vi.useRealTimers()
+      useDeviation.getState().failElementMap()
+    })
+    /** Run a command with the clock run on past the 30 s wait. */
+    const pastTheWait = async <T,>(name: string): Promise<T | Error> => {
+      vi.useFakeTimers({ toFake: ['Date', 'setTimeout', 'clearTimeout'] })
+      useDeviation.setState({ source: 'element', elementStatus: 'running' })
+      const answer = (runCommand(name, {}) as Promise<T>).then((v) => v, (e: Error) => e)
+      await vi.advanceTimersByTimeAsync(31_000)
+      return answer
+    }
+
+    it('session.state answers, the map said to be running', async () => {
+      const read = await pastTheWait<{ deviation: { map: string; stats: unknown } }>('session.state')
+      expect(read).not.toBeInstanceOf(Error)
+      expect((read as { deviation: { map: string } }).deviation.map).toBe('running')
+    })
+
+    it('report.get answers too', async () => {
+      const read = await pastTheWait<{ report: unknown }>('report.get')
+      expect(read).not.toBeInstanceOf(Error)
+      expect((read as { report: unknown }).report).toBeTruthy()
+    })
+
+    it('deviation.hotspots still gives up', async () => {
+      const refusal = await pastTheWait('deviation.hotspots')
+      expect(refusal).toBeInstanceOf(Error)
+      expect((refusal as Error).message).toContain('Gave up waiting for the map against the element')
+    })
+  })
+
   it('goes straight on when nothing is being measured', async () => {
     useDeviation.setState({ source: 'element', elementStatus: 'idle' })
     const started = Date.now()

From c0bdd6d287e2d1467775944b8bf30e7f322783f5 Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Thu, 5 Nov 2026 02:48:40 +0000
Subject: [PATCH 35/38] fix(viewer): let go of warm keepers and trees no longer
 wanted

A warming run now disposes the keepers of kinds the stage no longer has
(a scan closed, a reference cleared), which outlived them before. A scan
laid out again (resplit, replaceScan) forgets a tree still on its way
for the layout it replaces, as disposeMesh does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/viewer/SceneManager.ts | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

diff --git a/src/viewer/SceneManager.ts b/src/viewer/SceneManager.ts
index 552e1ac7..b3f16466 100644
--- a/src/viewer/SceneManager.ts
+++ b/src/viewer/SceneManager.ts
@@ -366,8 +366,9 @@ export class SceneManager {
   private capGeometry = new THREE.PlaneGeometry(1, 1)
   /** The materials the programs were warmed with — see warmPrograms — by
    *  the kind of program, with what each was made from. Kept until this
-   *  viewport goes, or a part of another make warms its kind again: a
-   *  program goes with the last material that used it. */
+   *  viewport goes, a part of another make warms its kind again, or the
+   *  stage no longer has that kind to warm: a program goes with the last
+   *  material that used it. */
   private warmKeepers = new Map<string, { from: object | string; keep: { dispose(): void } }>()
   /** The warming run in hand, and the way to take its next turn back. */
   private warmToken = 0
@@ -1228,6 +1229,9 @@ export class SceneManager {
     }
     const own = geometry.getAttribute('surface')?.array as Uint8Array | undefined
     const surface = own ? own.slice(0, this.scanVertices * 3) : null
+    // A tree still on its way is for the layout going: this one builds its
+    // own below.
+    forgetTree(geometry)
     geometry.disposeBoundsTree?.()
     geometry.dispose()
     const { colors, paint, tint } = this.layOutScan(
@@ -1943,6 +1947,15 @@ export class SceneManager {
       part('reference', nominal, cut, true)
     }
     part('scan', scan, false, false)
+    // A kind the stage no longer has — the reference cleared, the scan
+    // closed — lets its keeper go, and with it a program nothing draws with
+    // any more; a kind still wanted keeps its keeper until a new one is in.
+    const wanted = new Set(jobs.map((job) => job.key))
+    for (const [key, held] of this.warmKeepers) {
+      if (wanted.has(key)) continue
+      this.warmKeepers.delete(key)
+      held.keep.dispose()
+    }
     return jobs.filter((job) => this.warmKeepers.get(job.key)?.from !== job.from)
   }
 
@@ -3105,6 +3118,7 @@ export class SceneManager {
     this.dropDeflection()
     this.releaseDeflect(geometry)
     for (const layer of this.layers) layer.scanReplaced?.()
+    forgetTree(geometry)
     geometry.disposeBoundsTree?.()
     geometry.dispose()
     const { colors, paint, tint } = this.layOutScan(geometry, positions, indices, normals, wireSlots, copyOf, null, true, surface)

From 015d9aabd41292faa9cefa23a24a6ff68092fa8e Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Thu, 5 Nov 2026 02:50:31 +0000
Subject: [PATCH 36/38] fix(marking): hold a stroke laid before the scan's tree
 lands

A brush dab on a scan whose bounds tree was still being built off the
thread was dropped without a word. It is held now, as the ray it was cast
along, and laid when the tree lands (or on the next dab, if the tree came
another way), so a view turned meanwhile does not move it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/viewer/PickScene.ts       |   4 +-
 src/viewer/SceneManager.ts    |   2 +
 src/viewer/marking.ts         |  64 +++++++++++++++-
 tests/markingHeldDabs.test.ts | 138 ++++++++++++++++++++++++++++++++++
 4 files changed, 203 insertions(+), 5 deletions(-)
 create mode 100644 tests/markingHeldDabs.test.ts

diff --git a/src/viewer/PickScene.ts b/src/viewer/PickScene.ts
index ce4d07ca..ac65e281 100644
--- a/src/viewer/PickScene.ts
+++ b/src/viewer/PickScene.ts
@@ -166,8 +166,10 @@ export class PickScene {
     })
     this.marking.setTheme(theme)
     // The brush footprint skips the scan until its tree lands (see bvh.ts
-    // sparingRays); when it does, the cursor is looked at again here too.
+    // sparingRays); when it does, the cursor is looked at again here too,
+    // and a stroke laid here meanwhile is laid on the part.
     this.stopHearing = channel.onTreeLanded?.(() => {
+      this.marking?.treeLanded()
       this.hoverDirty = true
       this.viewport.wake()
     }) ?? null
diff --git a/src/viewer/SceneManager.ts b/src/viewer/SceneManager.ts
index b3f16466..e7e4a7c5 100644
--- a/src/viewer/SceneManager.ts
+++ b/src/viewer/SceneManager.ts
@@ -1087,6 +1087,8 @@ export class SceneManager {
     treeOffThread(geometry, build, () => {
       this.overlays.retestOcclusion()
       this.requestHover()
+      // A stroke laid while it was out is laid now.
+      this.marking.treeLanded()
       this.invalidate()
       for (const heard of this.treeHeard) heard()
     })
diff --git a/src/viewer/marking.ts b/src/viewer/marking.ts
index a0b4f701..1f57a9c2 100644
--- a/src/viewer/marking.ts
+++ b/src/viewer/marking.ts
@@ -168,6 +168,10 @@ export interface MarkingContext {
   onPaintChange(count: number): void
 }
 
+/** How many dabs a stroke may hold for a tree still being built — see
+ *  SurfaceMarking.dab. A couple of seconds of a fast stroke. */
+const HELD_DABS_MAX = 4096
+
 export class SurfaceMarking {
   private paint: PaintBrush | null = null
   /** The scheme's colours for the footprint and the marquee — marks drawn on
@@ -183,6 +187,10 @@ export class SurfaceMarking {
    *  reports up to a thousand moves a second, each dab is a raycast plus a BVH
    *  sweep, and nothing between two frames is ever seen anyway. */
   private strokeQueue: { x: number; y: number; erase: boolean }[] = []
+  /** Dabs laid while the scan's tree was still on its way from off the
+   *  thread, as the rays they were cast along — laid when it lands; see
+   *  dab and treeLanded. */
+  private heldDabs: { ray: THREE.Ray; erase: boolean }[] = []
   private paintSphere = new THREE.Sphere()
   /** Scratch for the per-triangle brush test, which runs thousands of times
    *  per stroke and must not allocate. */
@@ -322,6 +330,7 @@ export class SurfaceMarking {
       this.paintLast = null
       this.pendingDab = null
       this.strokeQueue.length = 0
+      this.heldDabs.length = 0
       this.paintErasing = false
       this.brushRing.visible = false
       this.endMarquee()
@@ -363,6 +372,7 @@ export class SurfaceMarking {
    */
   setPaintedVertices(vertices: Uint32Array, colorHex: string): void {
     if (!this.ctx.mesh()) return
+    this.heldDabs.length = 0
     this.ctx.setPaintColor(colorToRgb(colorHex))
     if (!this.ctx.regions.setPaintedVertices(vertices)) return
     const attr = this.ctx.paintAttr()
@@ -373,6 +383,7 @@ export class SurfaceMarking {
 
   /** Rub out the whole marking. */
   clearPaint(): void {
+    this.heldDabs.length = 0
     if (!this.ctx.regions.clearPaint()) return
     const attr = this.ctx.paintAttr()
     if (attr) attr.needsUpdate = true
@@ -429,16 +440,60 @@ export class SurfaceMarking {
    */
   private dab(clientX: number, clientY: number, erase: boolean): void {
     const mesh = this.ctx.mesh()
-    const brush = this.paint
-    if (!mesh || !brush || !this.ctx.paintAttr()) return
+    if (!mesh || !this.paint || !this.ctx.paintAttr()) return
+    const geometry = mesh.geometry as THREE.BufferGeometry
+    if (!geometry.getIndex()) return
+    this.ctx.setPickRay(clientX, clientY)
     // The sweep needs the tree; without it — still being built off the
-    // thread — the ray would go through every triangle for nothing.
+    // thread — the ray would go through every triangle for nothing. The dab
+    // is held instead, as the ray it is cast along, and laid when the tree
+    // lands (treeLanded): a view turned meanwhile does not move it.
+    if (!geometry.boundsTree) {
+      if (this.heldDabs.length < HELD_DABS_MAX) this.heldDabs.push({ ray: this.ctx.raycaster.ray.clone(), erase })
+      return
+    }
+    // A tree that came by another way than landing — the scan laid out
+    // again over a tree of its own — lays what was held first.
+    if (this.heldDabs.length > 0) this.layHeldDabs()
+    this.dabAlongRay(erase)
+  }
+
+  /** The scan's tree has landed from off the thread: lay the dabs held for
+   *  it, and report them as a gesture's end would if the gesture is over. */
+  treeLanded(): void {
+    if (this.heldDabs.length === 0) return
+    const geometry = this.ctx.mesh()?.geometry as THREE.BufferGeometry | undefined
+    // Another part's tree, the scan's still out.
+    if (!geometry?.boundsTree) return
+    this.layHeldDabs()
+    const attr = this.ctx.paintAttr()
+    if (attr) attr.needsUpdate = true
+    this.ctx.invalidate()
+    if (!this.painting) this.ctx.onPaintChange(this.ctx.regions.paintCount)
+  }
+
+  private layHeldDabs(): void {
+    const held = this.heldDabs
+    this.heldDabs = []
+    const ray = this.ctx.raycaster.ray
+    const was = ray.clone()
+    for (const d of held) {
+      ray.copy(d.ray)
+      this.dabAlongRay(d.erase)
+    }
+    ray.copy(was)
+  }
+
+  /** The dab along the pick ray as it is set — see dab. */
+  private dabAlongRay(erase: boolean): void {
+    const mesh = this.ctx.mesh()
+    const brush = this.paint
+    if (!mesh || !brush) return
     const geometry = mesh.geometry as THREE.BufferGeometry
     const bvh = geometry.boundsTree
     const index = geometry.getIndex()
     if (!bvh || !index) return
 
-    this.ctx.setPickRay(clientX, clientY)
     const hit = this.ctx.raycaster.intersectObject(mesh, false)[0]
     if (!hit || hit.faceIndex === undefined || hit.faceIndex === null) return
     const idx = index.array as ArrayLike<number>
@@ -813,6 +868,7 @@ export class SurfaceMarking {
     this.painting = false
     this.paintLast = null
     this.strokeQueue.length = 0
+    this.heldDabs.length = 0
     this.endMarquee()
   }
 
diff --git a/tests/markingHeldDabs.test.ts b/tests/markingHeldDabs.test.ts
new file mode 100644
index 00000000..f65a15d9
--- /dev/null
+++ b/tests/markingHeldDabs.test.ts
@@ -0,0 +1,138 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// A brush stroke laid on a scan whose bounds tree is still being built off
+// the thread (viewer/bvh.ts treeOffThread) is held, and laid when the tree
+// lands — where the stroke was, not where the cursor's spot lies on a view
+// turned since — rather than dropped without a word.
+import * as THREE from 'three'
+import { MeshBVH } from 'three-mesh-bvh'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { SurfaceMarking } from '../src/viewer/marking'
+import { RegionColors } from '../src/viewer/regionColors'
+
+type Listener = (e: Partial<PointerEvent>) => void
+
+describe('a stroke laid while the tree is out', () => {
+  let on: Record<string, Listener[]>
+  let marking: SurfaceMarking
+  let regions: RegionColors
+  let mesh: THREE.Mesh
+  let reports: number[]
+  /** Where a pixel lands on the part: 100 px to the millimetre about the
+   *  middle of an 800 × 600 view looking down on the XY plane, moved by
+   *  `turn` to stand for the view having been turned. */
+  let turn = 0
+
+  const fire = (type: string, e: Partial<PointerEvent>) => {
+    for (const l of on[type] ?? []) l(e)
+  }
+  const press = (x: number, y: number) =>
+    marking.handlePointerDown({ button: 0, pointerType: 'mouse', clientX: x, clientY: y, shiftKey: false, ctrlKey: false, metaKey: false, altKey: false } as PointerEvent)
+  const release = (x: number, y: number) => fire('pointerup', { button: 0, clientX: x, clientY: y })
+  /** The marked vertices, as points on the part. */
+  const marked = () => {
+    const pos = mesh.geometry.getAttribute('position')
+    return [...regions.paintedVertices()].map((v) => new THREE.Vector3().fromBufferAttribute(pos, v))
+  }
+
+  beforeEach(() => {
+    on = {}
+    turn = 0
+    reports = []
+    const element = () => ({ setAttribute: () => {}, append: () => {}, remove: () => {}, style: { display: '', setProperty: () => {} } })
+    vi.stubGlobal('document', {
+      createElementNS: element,
+      addEventListener: (type: string, l: Listener) => {
+        ;(on[type] ??= []).push(l)
+      },
+      removeEventListener: () => {},
+    })
+    // A 4 × 4 mm sheet in 0.1 mm squares, facing the view.
+    const geometry = new THREE.PlaneGeometry(4, 4, 40, 40)
+    const n = geometry.getAttribute('position').count
+    const paint = new Uint8Array(n)
+    geometry.setAttribute('paint', new THREE.BufferAttribute(paint, 1))
+    mesh = new THREE.Mesh(geometry)
+    mesh.updateMatrixWorld()
+    regions = new RegionColors([200, 200, 200])
+    regions.attach(new Uint8Array(n * 3), paint, new Uint8Array(n), n)
+    const raycaster = new THREE.Raycaster()
+    const partGroup = new THREE.Group()
+    marking = new SurfaceMarking({
+      container: { appendChild: () => {} } as unknown as HTMLDivElement,
+      camera: new THREE.OrthographicCamera(),
+      partGroup,
+      raycaster,
+      regions,
+      setPickRay: (x, y) => raycaster.ray.set(new THREE.Vector3((x - 400) / 100 + turn, (300 - y) / 100, 10), new THREE.Vector3(0, 0, -1)),
+      mesh: () => mesh,
+      paintAttr: () => geometry.getAttribute('paint') as THREE.BufferAttribute,
+      graphVertex: (v) => v,
+      setPaintColor: () => {},
+      invalidate: () => {},
+      wake: () => {},
+      claimDrag: () => {},
+      requestHover: () => {},
+      onPaintChange: (count) => reports.push(count),
+    })
+    marking.setPaintBrush({ color: '#ff8000', diameter: 0.5, erase: false })
+  })
+
+  afterEach(() => {
+    marking.dispose()
+    vi.unstubAllGlobals()
+  })
+
+  it('marks nothing until the tree lands, then marks where it was laid', () => {
+    press(400, 300)
+    release(400, 300)
+    expect(regions.paintCount).toBe(0)
+    expect(reports).toEqual([0])
+    // The view turned before the tree came: the dab is where it was laid.
+    turn = 1.5
+    mesh.geometry.boundsTree = new MeshBVH(mesh.geometry)
+    marking.treeLanded()
+    const points = marked()
+    expect(points.length).toBeGreaterThan(0)
+    expect(points.every((p) => Math.hypot(p.x, p.y) < 0.4)).toBe(true)
+    // Said as a gesture's end says it.
+    expect(reports).toEqual([0, regions.paintCount])
+  })
+
+  it('lays them first on the next dab if the tree came another way', () => {
+    press(400, 300)
+    release(400, 300)
+    mesh.geometry.boundsTree = new MeshBVH(mesh.geometry)
+    press(500, 300)
+    release(500, 300)
+    const points = marked()
+    expect(points.some((p) => Math.hypot(p.x, p.y) < 0.3)).toBe(true)
+    expect(points.some((p) => Math.hypot(p.x - 1, p.y) < 0.3)).toBe(true)
+  })
+
+  it('drops them with the marking rubbed out, or the brush put away', () => {
+    press(400, 300)
+    release(400, 300)
+    marking.clearPaint()
+    mesh.geometry.boundsTree = new MeshBVH(mesh.geometry)
+    marking.treeLanded()
+    expect(regions.paintCount).toBe(0)
+
+    mesh.geometry.boundsTree = undefined
+    press(400, 300)
+    release(400, 300)
+    marking.setPaintBrush(null)
+    mesh.geometry.boundsTree = new MeshBVH(mesh.geometry)
+    marking.treeLanded()
+    expect(regions.paintCount).toBe(0)
+  })
+
+  it('waits on for the scan when another part’s tree lands', () => {
+    press(400, 300)
+    release(400, 300)
+    marking.treeLanded()
+    expect(regions.paintCount).toBe(0)
+    mesh.geometry.boundsTree = new MeshBVH(mesh.geometry)
+    marking.treeLanded()
+    expect(regions.paintCount).toBeGreaterThan(0)
+  })
+})

From 1ea352f810d60add317008c5221ddcabcf944eaf Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Thu, 5 Nov 2026 03:01:07 +0000
Subject: [PATCH 37/38] fix(marking): drop held dabs off the brush, lay them
 after a re-split

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/viewer/SceneManager.ts | 3 +++
 src/viewer/marking.ts      | 7 ++++++-
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/src/viewer/SceneManager.ts b/src/viewer/SceneManager.ts
index e7e4a7c5..20bbada9 100644
--- a/src/viewer/SceneManager.ts
+++ b/src/viewer/SceneManager.ts
@@ -1254,6 +1254,9 @@ export class SceneManager {
     if (this.deflection?.geometry === geometry) this.layOutDeflection()
     else geometry.deleteAttribute('deflect')
     geometry.computeBoundsTree()
+    // The tree is here at once: strokes held for the one that was on its way
+    // are laid on it now rather than at the next dab.
+    this.marking.treeLanded()
     // A cap over the closed shells alone is cut from the old triangles.
     this.applySlice()
     this.invalidate()
diff --git a/src/viewer/marking.ts b/src/viewer/marking.ts
index 1f57a9c2..38eb925f 100644
--- a/src/viewer/marking.ts
+++ b/src/viewer/marking.ts
@@ -339,7 +339,12 @@ export class SurfaceMarking {
     }
     // Switching gesture mid-session leaves the marking alone but takes the
     // footprint of the old one off the part, and abandons anything in flight.
-    if (gesture !== 'brush') this.brushRing.visible = false
+    if (gesture !== 'brush') {
+      this.brushRing.visible = false
+      // Dabs held for a tree still on its way were laid by the brush: another
+      // gesture, or none, does not lay them later at whatever size is set then.
+      this.heldDabs.length = 0
+    }
     if (gesture === null) {
       this.painting = false
       this.paintLast = null

From f9f518d54c4f5d8d29d09331173ff28edb6386d9 Mon Sep 17 00:00:00 2001
From: Jozkah <38704522+Jozkah@users.noreply.github.com>
Date: Thu, 5 Nov 2026 17:35:43 +0000
Subject: [PATCH 38/38] fix(perf): review fixes for map waits, SceneSync memo,
 orbit pivot

- Commands wait for the element map only when it is the map they read:
  with the reference map shown, the element map re-measured behind it no
  longer stalls or times out hotspots, export, heightmap and feature
  patches. set_target still waits, as it asked for that map itself.
- view.render waits for the map only in the deviation workspace, within
  the picture's own time budget, and past it pictures the map as still
  being measured instead of failing the call.
- SceneSync compares the plugin runtime by what scene sync reads of it
  (pluginReads), so Mesh Tools and Reverse no longer re-render it on
  every Workbench render.
- The orbit pivot keeps finding parts that have their bounds tree while
  another part's tree is still being built; it stays off only where that
  part's box could lie in front of the hit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/app/SceneSync.tsx            | 17 ++++++++-
 src/app/useSceneSync.ts          | 26 +++++++++++++
 src/commands/core/common.ts      | 21 ++++++++---
 src/commands/core/deviation.ts   |  2 +-
 src/commands/core/view.ts        | 11 ++++--
 src/viewer/orthoNav.ts           | 27 ++++++++++---
 tests/commandsMapSettled.test.ts | 12 ++++++
 tests/orthoNavPivot.test.ts      | 65 ++++++++++++++++++++++++++++++++
 tests/sceneSyncProps.test.ts     | 34 +++++++++++++++++
 9 files changed, 199 insertions(+), 16 deletions(-)
 create mode 100644 tests/orthoNavPivot.test.ts
 create mode 100644 tests/sceneSyncProps.test.ts

diff --git a/src/app/SceneSync.tsx b/src/app/SceneSync.tsx
index 9b816209..c550bf94 100644
--- a/src/app/SceneSync.tsx
+++ b/src/app/SceneSync.tsx
@@ -19,10 +19,23 @@
 // nothing here writes as well, or writes to agree with them.
 import { memo } from 'react'
 import { useElementField } from './useElementField'
-import { useSceneSync } from './useSceneSync'
+import { pluginReads, useSceneSync } from './useSceneSync'
 
 export type SceneSyncProps = Parameters<typeof useSceneSync>[0] & Parameters<typeof useElementField>[0]
 
+/** The props as this draws them: every one by identity — refs, the session's
+ *  handlers, values held stable by the Workbench — but the plugin's runtime,
+ *  which is new on every render, by what is read of it (pluginReads). */
+export function sameSceneSyncProps(a: SceneSyncProps, b: SceneSyncProps): boolean {
+  for (const key of Object.keys(a) as (keyof SceneSyncProps)[]) {
+    if (key !== 'plugin' && !Object.is(a[key], b[key])) return false
+  }
+  if (Object.keys(a).length !== Object.keys(b).length) return false
+  const x = pluginReads(a.plugin)
+  const y = pluginReads(b.plugin)
+  return x.length === y.length && x.every((v, i) => Object.is(v, y[i]))
+}
+
 export const SceneSync = memo(function SceneSync({
   sceneRef,
   clientRef,
@@ -61,4 +74,4 @@ export const SceneSync = memo(function SceneSync({
     cancelDraft,
   })
   return null
-})
+}, sameSceneSyncProps)
diff --git a/src/app/useSceneSync.ts b/src/app/useSceneSync.ts
index 76c10a03..b00c6a5d 100644
--- a/src/app/useSceneSync.ts
+++ b/src/app/useSceneSync.ts
@@ -61,6 +61,32 @@ import type { PluginRuntime } from '../plugins/api'
  *  its motion is worked out again — see the effect at the end. */
 const DEFLECTION_SETTLE_MS = 150
 
+/**
+ * Everything useSceneSync reads of a plugin's runtime, in a form two renders
+ * can be compared by. A plugin builds its runtime afresh on every render of
+ * the Workbench, so the runtime itself is a new object each time though
+ * nothing in it has moved; SceneSync compares these instead, so a plugin's
+ * workspace does not re-render the scene's follower on every render of the
+ * screen. Its map is read through `fieldVersion`, which changes whenever the
+ * map does — the effects that paint it key on nothing else — and a plugin that
+ * gives none, with a map up, is never taken for unchanged. A new read of
+ * `plugin` in the hook belongs here too.
+ */
+export function pluginReads(plugin: PluginRuntime | null): readonly unknown[] {
+  if (!plugin) return [null]
+  return [
+    plugin.marking?.color ?? null,
+    plugin.marking?.gestures ?? false,
+    Boolean(plugin.scanKey?.seeThrough),
+    Boolean(plugin.scanKey?.shown),
+    Boolean(plugin.showsElements),
+    Boolean(plugin.hideScan),
+    Boolean(plugin.hoverReadout),
+    Boolean(plugin.hovers),
+    plugin.fieldVersion === undefined && plugin.field ? {} : plugin.fieldVersion,
+  ]
+}
+
 export function useSceneSync({
   sceneRef,
   clientRef,
diff --git a/src/commands/core/common.ts b/src/commands/core/common.ts
index e9d14dd9..7be219d2 100644
--- a/src/commands/core/common.ts
+++ b/src/commands/core/common.ts
@@ -191,10 +191,21 @@ export async function nextFrame(scene?: FrameSource | null): Promise<void> {
  *  what it was just told would read the one before, or none. A frame first,
  *  for the stores' change to reach the effect that asks; then the wait, which
  *  is over at once when nothing is being measured. Settled is not measured:
- *  the caller looks at the status for that. */
-export async function mapSettled(scene?: FrameSource | null): Promise<void> {
+ *  the caller looks at the status for that.
+ *
+ *  Only a reader of that map waits: with the reference map the one read, the
+ *  element map is measured again behind it whenever its element changes, and
+ *  a read of the reference map has no business waiting for it — the worker
+ *  may be busy for longer than the wait. `always` is for the command that has
+ *  just asked for the element map itself, whichever map is on screen.
+ *  `timeoutMs` is how long it waits at most. */
+export async function mapSettled(
+  scene?: FrameSource | null,
+  { always = false, timeoutMs = 30_000 }: { always?: boolean; timeoutMs?: number } = {},
+): Promise<void> {
   await nextFrame(scene)
-  await waitFor(() => useDeviation.getState().elementStatus !== 'running', 'the map against the element', 30_000)
+  if (!always && useDeviation.getState().source !== 'element') return
+  await waitFor(() => useDeviation.getState().elementStatus !== 'running', 'the map against the element', timeoutMs)
 }
 
 /** As mapSettled, for a command that only reads the session out: past the
@@ -202,9 +213,9 @@ export async function mapSettled(scene?: FrameSource | null): Promise<void> {
  *  job queued ahead of it — the answer is given anyway, and says the map is
  *  "running" where its figures would be, rather than failing a read for
  *  being slow. A command that acts on the map waits strictly. */
-export async function mapSettledOrMeasuring(scene?: FrameSource | null): Promise<void> {
+export async function mapSettledOrMeasuring(scene?: FrameSource | null, timeoutMs?: number): Promise<void> {
   try {
-    await mapSettled(scene)
+    await mapSettled(scene, { timeoutMs })
   } catch (e) {
     if (useDeviation.getState().elementStatus !== 'running') throw e
   }
diff --git a/src/commands/core/deviation.ts b/src/commands/core/deviation.ts
index ea40d0cf..a423c31d 100644
--- a/src/commands/core/deviation.ts
+++ b/src/commands/core/deviation.ts
@@ -162,7 +162,7 @@ const setTarget: Command<{ element: ElementRef | null; side?: 'outward' | 'inwar
     if (want !== undefined && useDeviation.getState().targetSide !== want) useDeviation.getState().flipTargetSide()
     if (facingDeg !== undefined) useDeviation.getState().setTargetFacing(facingDeg)
     // The map follows the choice on its own (useElementField), once the stores' change has reached it.
-    await mapSettled(scene)
+    await mapSettled(scene, { always: true })
     if (useDeviation.getState().elementStatus !== 'ready') throw new CommandError('failed', 'The map against the element could not be measured.')
     return { deviation: describeDeviation() }
   },
diff --git a/src/commands/core/view.ts b/src/commands/core/view.ts
index db80458f..08f7cb44 100644
--- a/src/commands/core/view.ts
+++ b/src/commands/core/view.ts
@@ -25,7 +25,7 @@ import { arr, bool, enumOf, int, num, obj, oneOf, vec3, type JsonSchema } from '
 import { publicWorkspace } from '../state'
 import { CommandError, type Command } from '../types'
 import { applyShow, settleShown, viewToggles, whyNotShown, type ShowApplied, type ViewToggle } from '../viewToggles'
-import { mapSettled, nextFrame, waitFor } from './common'
+import { mapSettledOrMeasuring, nextFrame, waitFor } from './common'
 
 const VIEWS: readonly StandardView[] = ['iso', 'iso-front-left', 'iso-rear-left', 'iso-rear-right', 'top', 'bottom', 'front', 'rear', 'left', 'right']
 
@@ -314,8 +314,13 @@ const render: Command<{ width?: number; height?: number; view?: StandardView; vi
       }
       await sectioned(scene, section)
       // The map in the picture, and what is said of it, is the one measured
-      // for what the view was just told, not the one before it.
-      await mapSettled(scene)
+      // for what the view was just told, not the one before it. Only the
+      // deviation workspace pictures it, and the wait shares the picture's
+      // budget: past it, the picture is taken with the map said to be still
+      // being measured (describeMapPainted) rather than not taken at all.
+      if (useShell.getState().workspace === 'deviation') {
+        await mapSettledOrMeasuring(scene, Math.max(0, SHOW_WAIT_MS - (Date.now() - started)))
+      }
       const pictured = views ? await sheetOfViews(scene, views, width, height, show) : await picture(scene, width, height, view, show)
       // A sheet of views fits each; otherwise only fit: true does.
       const framed = framing(scaleOf(scene), frame, Boolean(views) || (!frame && fit === true))
diff --git a/src/viewer/orthoNav.ts b/src/viewer/orthoNav.ts
index 3b2fd7e1..c0e1a66f 100644
--- a/src/viewer/orthoNav.ts
+++ b/src/viewer/orthoNav.ts
@@ -114,6 +114,9 @@ export class OrthoNavigator {
   private q2 = new THREE.Quaternion()
   private q3 = new THREE.Quaternion()
   private pickNdc = new THREE.Vector2()
+  /** Scratch for surfaceAt's test of a part still waiting for its tree. */
+  private waitingBox = new THREE.Box3()
+  private waitingHit = new THREE.Vector3()
   /** The canvas rect, asked of the layout engine at most once per frame or
    *  task: getBoundingClientRect can force a layout pass, and setPickRay runs
    *  for every dab of a brush stroke. Cleared in updateClipPlanes, which the
@@ -549,15 +552,29 @@ export class OrthoNavigator {
   /** The point on the model under a client position, if the model is there.
    *  A pivot has somewhere to fall back to, so a part whose tree is still on
    *  its way is not run through triangle by triangle to find one — see
-   *  bvh.ts sparingRays — and nothing is found at all while it is: skipped,
-   *  it would let the ray through to whatever lies behind it. */
+   *  bvh.ts sparingRays. Skipped outright, though, it would let the ray
+   *  through to whatever lies behind it: so the parts with a tree are tested,
+   *  and a hit on them stands only where no waiting part's box comes nearer
+   *  along the ray. */
   surfaceAt(clientX: number, clientY: number): THREE.Vector3 | null {
     const targets = this.orbitTargets()
     if (!targets.length) return null
-    if (targets.some((t) => (t as THREE.Mesh).isMesh && treeAwaited((t as THREE.Mesh).geometry))) return null
+    const waiting = (t: THREE.Object3D) => (t as THREE.Mesh).isMesh === true && treeAwaited((t as THREE.Mesh).geometry)
+    const ready = targets.filter((t) => !waiting(t))
+    if (!ready.length) return null
     this.setPickRay(this.orbitRaycaster, clientX, clientY)
-    const hits = sparingRays(() => this.orbitRaycaster.intersectObjects(targets, false))
-    return hits.length ? hits[0].point.clone() : null
+    const hit = sparingRays(() => this.orbitRaycaster.intersectObjects(ready, false))[0]
+    if (!hit) return null
+    const ray = this.orbitRaycaster.ray
+    for (const t of targets) {
+      if (!waiting(t)) continue
+      const geometry = (t as THREE.Mesh).geometry
+      if (!geometry.boundingBox) geometry.computeBoundingBox()
+      this.waitingBox.copy(geometry.boundingBox!).applyMatrix4(t.matrixWorld)
+      const at = ray.intersectBox(this.waitingBox, this.waitingHit)
+      if (at && ray.origin.distanceTo(at) < hit.distance) return null
+    }
+    return hit.point.clone()
   }
 
   /**
diff --git a/tests/commandsMapSettled.test.ts b/tests/commandsMapSettled.test.ts
index e7d41b00..d0349272 100644
--- a/tests/commandsMapSettled.test.ts
+++ b/tests/commandsMapSettled.test.ts
@@ -47,6 +47,18 @@ describe('a command that reads the map against an element', () => {
     expect((await refusal)?.message).toContain('no deviation map')
   })
 
+  it('is not waited for by a reader of the reference map', async () => {
+    // Measured again behind the reference map whenever its element changes:
+    // nothing that reads the reference map waits on that.
+    useDeviation.setState({ source: 'reference', elementStatus: 'running' })
+    const hotspots = runCommand('deviation.hotspots', {})
+    const refusal = hotspots.then(() => null, (e: Error) => e)
+    expect(await settledAfter(hotspots, 1000)).toBe(true)
+    // Refused at once for the map it reads, of which there is none here.
+    expect((await refusal)?.message).toContain('no deviation map')
+    useDeviation.getState().failElementMap()
+  })
+
   // The mesh worker answers in order, so a map queued behind a long job — a
   // thickness map, a boolean — can be measured for longer than a command
   // waits. A read of the session says so; a command that acts on the map
diff --git a/tests/orthoNavPivot.test.ts b/tests/orthoNavPivot.test.ts
new file mode 100644
index 00000000..0541807a
--- /dev/null
+++ b/tests/orthoNavPivot.test.ts
@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// The orbit's pivot on the surface under the cursor while a part's bounds
+// tree is still being built off the thread: the part waiting is not run
+// through triangle by triangle, but it still hides what lies behind it, and
+// it does not take the pivot off a part beside it that has its tree.
+import * as THREE from 'three'
+import type { OrbitControls } from 'three/addons/controls/OrbitControls.js'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { OrthoNavigator } from '../src/viewer/orthoNav'
+import { treeOffThread } from '../src/viewer/bvh'
+import type { SerializedTree } from '../src/core/workerProtocol'
+
+/** A box of side `size` centred at `at`, its tree on its way and never landing. */
+function waitingBox(size: number, at: [number, number, number]): THREE.Mesh {
+  const mesh = new THREE.Mesh(new THREE.BoxGeometry(size, size, size))
+  mesh.position.set(...at)
+  mesh.updateMatrixWorld()
+  treeOffThread(mesh.geometry, () => new Promise<SerializedTree>(() => {}), () => {})
+  return mesh
+}
+
+function navigatorOver(targets: THREE.Object3D[]): OrthoNavigator {
+  vi.stubGlobal('document', { addEventListener: () => {}, removeEventListener: () => {} })
+  const canvas = {
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    clientHeight: 600,
+    getBoundingClientRect: () => ({ left: 0, top: 0, width: 800, height: 600 }),
+  } as unknown as HTMLCanvasElement
+  const camera = new THREE.OrthographicCamera(-4 / 3, 4 / 3, 1, -1, 0.01, 100)
+  camera.position.set(0, 0, 10)
+  camera.lookAt(0, 0, 0)
+  camera.updateMatrixWorld()
+  return new OrthoNavigator(camera, { target: new THREE.Vector3(), update: () => {} } as unknown as OrbitControls, canvas, () => targets, {
+    center: new THREE.Vector3(),
+    radius: 5,
+  })
+}
+
+describe('the orbit pivot while a tree is on its way', () => {
+  afterEach(() => vi.unstubAllGlobals())
+
+  const ready = () => {
+    const mesh = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1))
+    mesh.updateMatrixWorld()
+    return mesh
+  }
+
+  it('is on the part with a tree when the waiting one is beside it', () => {
+    const nav = navigatorOver([ready(), waitingBox(0.4, [1, 0, 3])])
+    const at = nav.surfaceAt(400, 300)
+    expect(at).not.toBeNull()
+    expect(at!.z).toBeCloseTo(0.5)
+  })
+
+  it('is nowhere when the waiting part may stand in front of it', () => {
+    const nav = navigatorOver([ready(), waitingBox(0.4, [0, 0, 3])])
+    expect(nav.surfaceAt(400, 300)).toBeNull()
+  })
+
+  it('is nowhere when every part is waiting', () => {
+    const nav = navigatorOver([waitingBox(1, [0, 0, 0])])
+    expect(nav.surfaceAt(400, 300)).toBeNull()
+  })
+})
diff --git a/tests/sceneSyncProps.test.ts b/tests/sceneSyncProps.test.ts
new file mode 100644
index 00000000..4c08d8ab
--- /dev/null
+++ b/tests/sceneSyncProps.test.ts
@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// SceneSync is drawn again only when something it reads has moved. A plugin's
+// runtime is a new object on every render of the Workbench, so it is compared
+// by what the scene's follower reads of it, not by identity.
+import { describe, expect, it } from 'vitest'
+import { sameSceneSyncProps, type SceneSyncProps } from '../src/app/SceneSync'
+import type { PluginRuntime } from '../src/plugins/api'
+
+const refs = { current: null }
+const base = { sceneRef: refs, clientRef: refs, cancelDraft: () => {} } as unknown as SceneSyncProps
+const withPlugin = (plugin: PluginRuntime | null): SceneSyncProps => ({ ...base, plugin })
+
+describe('SceneSync props', () => {
+  it('are the same for a plugin runtime built again with the same reads', () => {
+    const make = (): PluginRuntime => ({ marking: { color: '#f00', gestures: true }, hideScan: false, fieldVersion: 'a:1' })
+    expect(sameSceneSyncProps(withPlugin(make()), withPlugin(make()))).toBe(true)
+  })
+
+  it('differ when what is read of the plugin moves', () => {
+    const a = withPlugin({ marking: { color: '#f00', gestures: true }, fieldVersion: 'a:1' })
+    expect(sameSceneSyncProps(a, withPlugin({ marking: { color: '#0f0', gestures: true }, fieldVersion: 'a:1' }))).toBe(false)
+    expect(sameSceneSyncProps(a, withPlugin({ marking: { color: '#f00', gestures: true }, fieldVersion: 'a:2' }))).toBe(false)
+    expect(sameSceneSyncProps(a, withPlugin(null))).toBe(false)
+  })
+
+  it('differ always for a plugin with a map and no version of it', () => {
+    const field = { values: new Float32Array(3), rgb: { current: null }, scale: {} } as unknown as PluginRuntime['field']
+    expect(sameSceneSyncProps(withPlugin({ field }), withPlugin({ field }))).toBe(false)
+  })
+
+  it('differ when any other prop is another object', () => {
+    expect(sameSceneSyncProps(withPlugin(null), { ...withPlugin(null), cancelDraft: () => {} })).toBe(false)
+  })
+})