[Jozkah]

Closes #91.

Taps that open or change a panel — Deviation, Map, Split, Section view, the element target and facing limit — were slow to show their result, most visibly on phones. This branch removes the main-thread work behind that, on phone and desktop alike. The findings are in docs/superpowers/specs/2026-11-04-mobile-perf-findings.md and the plan in docs/superpowers/plans/2026-11-04-mobile-perf-fixes.md.

What changed

• Measurement: scripts/perf-probe.mjs takes medians over several runs, has a richer test scenario, and checks budgets (PERF_ASSERT=1). It also counts frames drawn while idle.
• Skipping work that changes nothing:
  • The top bar no longer re-fits on every tap.
  • Map colours are not repainted or re-uploaded when they are unchanged.
  • Histograms and stats are cached per map version.
  • Overlays are not rebuilt when their data is unchanged, and their materials are reused.
• Shaders: the Section view and map materials compile while the app is idle, not on the first tap.
• Views kept alive: after first use, the split view and 2D view keep their WebGL contexts, so reopening them costs nothing.
• Moved to the mesh worker:
  • the deformation-animation motion;
  • the deviation map against an element;
  • the scan's and reference's bounds trees (BVH), now indirect so the render index is never reordered.
• React:
  • Panels subscribe only to the store fields they read.
  • The hint ladder is computed once.
  • Scene sync lives in its own leaf component, so store changes no longer re-render the whole workbench.
• Idle:
  • The render loop sleeps after 30 idle frames; input, invalidation, resize and links between views wake it.
  • The canvas size is cached, so per-frame clientWidth reads (forced layout) are gone.
• Misc:
  • Alignment refits the bounds tree instead of rebuilding it.
  • The hint pulse animates only transform and opacity.

Commands that read the element map now wait for it to settle (mapSettled). A command waiting a frame wakes the sleeping viewport first.

Results

4x CPU throttle, 288k-triangle scan, BASE 5763504 vs HEAD. Production build unless marked dev.

What	Before	After
Frames drawn in 3 s idle	~430	0
Open scan, longest task	286 ms	95 ms
Load reference, longest task	308 ms	81 ms
Section view on, shader links	6	0
Split view on, INP	72 ms	32 ms
Deviation animate off, upload	7.6 MB	0
Deviation animate on, longest task (dev, rich)	91 ms	0
Element facing limit, INP (dev, rich)	192 ms	~70 ms
Change element target, longest task (dev, rich)	~180 ms	82–89 ms
Tab to 3D Measure, shader links (dev, rich)	5	0
Volume show / scan key, INP (dev, rich)	76–84 ms	24 ms

The full per-row tables (INP, longest task, links, upload MB, contexts) are in the probe output.

Verification

• npm run build (tsc + vite build): passes.
• npx vitest run --maxWorkers=8: 3223 passed, 24 skipped.
• npm run e2e:ci: all checks pass except the six that need the MCP server's dependencies (npm --prefix mcp ci), which aren't installed on the machine I ran them on (e2e-agent, e2e-agent-warning, e2e-agent-mesh, e2e-agent-reverse, e2e-note-from-file, e2e-reverse-notes). e2e-agent and e2e-agent-warning fail the same way on the base commit. e2e-patch-network skipped (fixture missing).
• New e2e: e2e:sleep checks the view wakes after going idle for wheel, pinch, animation and split view. e2e-mesh-flip gained a check that a map survives switching through Mesh Tools with an edited copy.
• Some e2e scripts need fixtures that weren't on the machine (ballbar.stl, block-marius.stl, side bracket left.stl, fridgeBracket.ply). They were run with a substitute model on both BASE and HEAD, with identical results.
• Perf probe PERF_ASSERT=1 PERF_RUNS=5: bare scenario on the production build passes. The rich scenario on the dev build has two rows over budget; both were already over at BASE:
  • Opening a scan on the dev build takes 172 ms against a 150 ms budget; the rest is shader linking. Production comes in at 95 ms.
  • Switching to Surface Deviation with a map already shown uploads 0.6 MB: one per-vertex float attribute, not the colour buffer. This is left over budget as a follow-up.

Known trade-offs and follow-ups

• Leaving Deviation after using the animation frees its GPU buffer. In three.js that re-uploads the whole mesh once (7.6 MB), where BASE paid that on every "animate off".
• For a moment after a scan opens (~65 ms on desktop), its bounds tree is still being built. Hover ignores the scan until it lands, and brush strokes are held and laid when it arrives.
• Plugin effects that must change the scene before scene sync paints have to be layout effects; the mesh-tools edited-copy swap is one. This is documented in src/app/SceneSync.tsx.
• Not in this PR: switching workspace tabs still re-renders the whole main screen (the panels need wrapping in memo).

Real-device check (not done yet)

On a phone, with Chrome remote debugging (Android) or Safari Web Inspector (iPhone), Performance panel: tap Surface Deviation, Map, Split and Section, and confirm no task runs over 100 ms.

🤖 Generated with Claude Code