design-editor-performance

# Design Editor Performance The general rules (closure chains, cache budgets, view swaps, measuring after GC) are in the root `performance` skill, §11. This is what they mean on the board, where one user session holds dozens of multi-megabyte screens. ## What a screen costs | Shown as | Runs in | Costs | Bounded by | | --- | --- | --- | --- | | Live editor | same-origin iframe, main thread | ~20 MB and ~380 ms of main thread to boot | 32 in the pool, 4 booting at once, 3 kept warm through a zoom-out | | Static preview | sandboxed `srcdoc` iframe, preview process | its ~2 MB `srcdoc` string in the main heap; the preview process renders one at a time | 64, nearest first, then screens already seen | | Placeholder | nothing | nothing | everything else | A screen gets an editor at ≥240 px on screen and loses it below 180 px, only once the camera has rested 250 ms; hovering promotes after 300 ms. The pool sizes and thresholds live in `multi-screen/culling.ts`; the timings and the warm count are constants at the top of `MultiScreenCanvas.tsx`. ## Rules for changes here - **Decide in `multi-screen/culling.ts`, wire in `MultiScreenCanvas.tsx`.** The selection functions are pure; prove a policy change in `MultiScreenCanvas.culling.test.ts` or the boot-budget component test, not in a browser. - **Swaps hand off; they never blank.** `staticPreviewHandoffById` keeps a painted preview over an editor until that editor's own ready signal (the 8-second boot timeout frees a boot slot but proves nothing was drawn), and a demoted editor until its preview has painted. The preview slot stays ahead of `{screenContent}` in the DOM: that order puts it under a running editor and keeps the iframe from being re-inserted, which would reload it. - **A screen already seen keeps its preview** (`retainedIds`). Unmounting one rebuilds it from blank when the camera returns, which users read as the board "rebuilding itself". - **Previews are parsed off the main thread before they mount.** The canvas hands the workers the screens it is about to mount with `wantPreviewParses`, which replaces its last list, and admission waits for each result. Workers take one job at a time, so a pan never buries the screens now in view. Don't parse a screen on mount. - **In the editor's hooks (`design-editor/domains/use-editor-*.ts`), never capture a heavy value.** A `useCallback` or `useMemo` that closes over a projection, tree, layer model or file content pins that render, and every render chained behind it. Take trees and node maps from `cachedCodeLayerTree` / `cachedCodeLayerNodeById` (`shared/code-layer.ts`), and read the latest value through a ref. - **Layer models are built on demand** (`derive/layer-model-coverage.ts`). Don't add an `isNeeded` condition that keeps a screen's model for the rest of the session; that is how the board's heap passed a gigabyte. - **A command that knows its result before the server answers starts the work during the round trip.** `duplicate-screen.ts` annotates and parses the copy while `create-file` is in flight. - **Drag isolation lasts only for the drag.** `isolateMovingPreviewIframes` gives a moving screen's iframes their own layer and removes it on drop. ## Proving a change 1. **A count in a unit or component test**, in the fast lanes. The existing ones show the shapes that work: `code-layer.recent-documents.test.ts` (documents retained), `memoize-by-content` (characters cached), the culling tests (previews retained, warm editors), and the boot-budget tests (preview survives a promotion, demoted editor waits for paint). 2. **`pnpm perf:runtime-budget`**, against a production build started with `AUTH_DISABLED=1`. It seeds the 48-screen stress board, runs four rounds of select, text edit, fill color, duplicate, a zoom cycle and screen visits, and compares with `scripts/runtime-budget.json`. It exits 0 within budget, 1 over budget, and 2 when a step did not take effect. It runs as the `Runtime budget` check of the Design E2E workflow, on the same pull requests that workflow already runs for. The gates (heap, blanked screens, live editors) each carry their reason in the JSON; editor churn and frame times are reported only, because shared runners are too noisy for a fixed limit. When a change improves a gated number, lower its `max` in the same PR. 3. **When the budget fails or a report comes in**, read `references/measuring.md` for the local setup, the traps that faked results, and how to find what holds memory.