@pixel-point/toolcraft 0.0.15 → 0.0.16

package/templates/starter/docs/toolcraft/performance.md

@@ -1,209 +1,181 @@
-# Performance
+# Toolcraft Performance Contract
 
-> Reading route: start with `workflow.md`. Core generated-app rules live in `core/*`; this file is a focused performance reference for the topic below.
+<!-- toolcraft-performance-lifecycle: first-delivery=functional; later-delivery=functional-targeted; complaint=one-authority-targeted-performance-iteration; full-audit=explicit-only -->
+<!-- toolcraft-performance-iteration: authority=exact-request-evidence+canonical-path-ids; fixture=reachable-development; after-pass=return-app-to-user+stop -->
+<!-- toolcraft-performance-full-authority: automatic=forbidden; recommendation=two-compatible-iterations-or-broad-unlocalizable-problem; command=pnpm verify:perf; authority=explicit-user-request-or-accepted-offer -->
 
-Every visible non-action control needs a `performanceRole` and `performanceReason`.
+Use this document while authoring `src/app/app-performance.ts`, performance acceptance, and browser evidence. Read `core/performance.md` first. Functional selection and proof ownership are canonical in `workflow.md` and `acceptance-testing.md`; performance metadata does not redefine them.
 
-Performance coverage has two levels:
+## Producer Order
 
-- workload coverage for controls that change render cost;
-- responsiveness coverage for ordinary controls that still must not freeze input or break the viewport.
+The only normative sequence is:
 
-`maxInteractionMs` measures user action start through the first verified product-output/state response for mutating interactions, not merely pointer completion. Generic change measurements first prove a stable pre-action baseline. A live drag may then cross that baseline while the gesture continues: the first changed response sets latency, then the final post-action outcome must remain different through its stability window before evidence is emitted. Autonomous or animated products use a stable semantic `expectedOutcome` or a deterministic fixed playback phase; the next unrelated frame cannot count as response. Settle/stability time after the first response is not charged as first-response latency. The helper uses one runner monotonic clock and restarts frame sampling after document navigation. Non-mutating interactions use action completion.
+```text
+reachable controls and inputs
+-> workload dimensions and enforced boundaries
+-> pass cost, frequency, lifecycle, and invalidation
+-> render-plan assessment and a pending protected benchmark requirement when required
+-> derived paths and combined fixtures
+-> targeted functional/browser development checks
+-> lifecycle-appropriate delivery proof
+```
 
-The preferred runner for targeted browser diagnosis is the current AI agent's controlled browser. The protected `pnpm verify:perf` Playwright checkpoint is the sole final machine authority that can record a passed current-source performance receipt.
+Do not substitute content-type thresholds, key-name matching, or hand-authored stress values for this sequence.
 
-`app-performance.ts` must keep this policy:
+## 1. Reachability
 
-```ts
-browserCheckPolicy: {
-  preferredRunner: "agent-browser",
-  fallbackRunner: "playwright",
-  fallbackWhen: ["agent-browser-unavailable", "ci"],
-}
-```
+Inventory every input that a user or runtime path can reach:
 
-Do not change the preferred runner to Playwright merely to avoid agent-controlled diagnosis; that policy governs targeted investigation. It does not authorize a manual passed receipt: final performance proof comes only from the protected `pnpm verify:perf` checkpoint.
+- visible schema controls and all conditional branches;
+- runtime-owned state read by product output;
+- imported or otherwise external source inputs;
+- derived magnitudes used by renderer cost.
 
-## Workload Coverage
+Every visible non-action control declares `performanceRole: "workload"` or `performanceRole: "responsiveness"`. Workload classification is explicit product modeling. Labels, ids, target strings, units, control types, and option text are not classification evidence.
 
-Use workload coverage for controls that change rendering cost:
+## 2. Workload Envelope
 
-- output size;
-- media resolution;
-- sample count;
-- character or grid density;
-- particle count;
-- blur radius;
-- shader complexity;
-- iterations;
-- quality;
-- timeline playback;
-- keyframe scrubbing.
+Author numeric dimensions for workload magnitude, not one dimension per control. A dimension declares:
 
-Sensitive controls need min/default/max scenarios, `stressFixture`, and real product-output checks.
+- `id`: stable product-owned identifier;
+- `unit`: the numeric quantity represented;
+- `source`: `schema-target`, `runtime-state`, `external-input`, or `derived`;
+- `mapping`: `direct`, `area`, `quadratic`, or `custom`;
+- `defaultValue`;
+- `interactiveMax` when interactive/frame work reaches the dimension;
+- `batchMax` when batch/import/export work reaches the dimension.
 
-`stressFixture` is the machine-checkable value for the scenario itself. For a slider drag, it is the exact slider value to apply. For a text input, it can be the long text value. For preview, zoom, animation, or export stress scenarios, it can be a combined object state.
+These fields name maximum-workload boundaries, not numerical maxima. For a numeric `schema-target`, set `source.workloadBoundary` to `"minimum"` or `"maximum"` and make every declared profile boundary equal that schema endpoint. This supports both count-like controls whose cost rises toward `max` and inverse controls whose cost rises toward `min`. Runtime-state and external-input dimensions declare the actual maximum-workload value directly, even when it is numerically below `defaultValue`.
 
-When the scenario control is not itself the whole heavy source, add `workloadFixture` as the independent heavy baseline that must be applied before measuring. Examples: a large uploaded image before dragging an effect slider, long text before dragging a density slider, many items before dragging spacing, or `renderScale: 2` before checking high-frequency controls. `workloadFixture` must be paired with `stressFixture`: first apply the app baseline, then apply the measured scenario value. Do not encode this as a named-control rule; decide from the renderer pipeline and product workload.
+Declare only the profiles consumed by renderer passes. A schema control can change a batch-only dimension and retain targeted control-change coverage without claiming an interactive workload maximum; numeric batch-only dimensions are not required to manufacture `interactiveMax`.
 
-Both fixture types must include:
+Each explicit workload control maps to exactly one schema-backed dimension. The dimension boundary equals the value the schema or product runtime actually enforces. A scenario or browser test cannot lower that boundary. Interactive boundaries are fully guaranteed.
 
-- `kind`: `large-text`, `large-canvas`, `high-density`, `many-items`, `max-value`, `media`, or `custom`;
-- `reason`: why this value is the heaviest useful product case;
-- `value`: the actual value the browser performance check will apply.
+Numeric capability is structural. Sliders and range sliders use their effective numeric bounds. Any other control participates as a numeric schema source only when it declares finite `min`, `max`, and numeric `defaultValue`; a partial domain, inverted bounds, or a default outside the bounds is invalid. Control names and kinds do not manufacture numeric limits.
 
-Fixtures that represent numeric maximums, density, item counts, canvas/media size, or custom combined heavy states also declare `loadProfile`. This separates the product `hardLimit` from the `smoothTarget` that the browser performance checkpoint guarantees. For bounded numeric controls, min/default/max and the hard limit are derived from schema; omit duplicated scenario `values`, or use `requireToolcraftSchemaPerformanceValues` when another fixture needs the same range. Supplied values must match schema exactly, and `metric: "custom"` cannot replace a numeric boundary. `smoothTarget` is the value the browser performance check applies and must match `stressFixture.value` or `workloadFixture.value`. A `many-items` fixture must apply at least 10 real items; an authored `minCount` cannot redefine a token fixture as heavy.
+The empty starter uses:
 
-Default to `smoothTargetRatio: 1`, which means the full hard limit must pass budgets. If the hard limit cannot pass after reasonable renderer and pipeline optimizations, lower the smooth target only in 10 percent steps (`0.9`, then `0.8`, and so on). Every skipped higher step has exactly one `loadProfile.evidence` entry with the exact `attemptedRatio`, schema-reachable `attemptedTarget`, matching scenario id and target, measured result, optimization attempted, and decision. When `smoothTargetRatio < 1`, set `userFacingRange: "experimental-above-smooth"` so the range above the smooth target is not silently presented as guaranteed.
+```ts
+workloadEnvelope: { dimensions: [] }
+```
 
-For multiline text, prompt, code, JSON, CSS, shader, script, or template workload controls, use `kind: "large-text"`. The fixture must contain at least `50_000` characters and `1_000` lines unless the product has a stricter real-world maximum.
+It omits `fixtureAdapters` because there are no dimensions to apply.
 
-For uploaded images, videos, source media, and image-processing workloads, use `kind: "media"` with a `value` object containing numeric `width` and `height`. The fixture must be at least `1920x1080`-equivalent, and products that claim high-resolution media or export quality should test a 4K-class source when that is the realistic heavy case. Do not satisfy media import, preview, effect-slider, or image-processing performance with `640x480`, thumbnails, or toy fixtures.
+## 3. Render Pipeline
 
-Choose heavy fixtures from this app's real controls, not from generic examples. Derive the workload from four app-specific sources: schema controls and `performanceRole`, `rendererTechnique`, `rendererPipeline`, and real product stress values such as large text, source media dimensions, `canvas.renderScale`, canvas size, export resolution, animation speed, viewport interactions, and effect strength. Try the product hard limit first, then use a documented smooth target only when measured evidence shows the hard limit cannot be made smooth without changing product scope.
+Custom renderers declare a stable `rendererPipeline.runtimeId`. Every pass declares `cost` and `lifecycle` in addition to its existing inputs, invalidators, cache key, kind, output, quality, and execution location.
 
-Every `automatedTestName` and `browserTestName` must match exactly one product-owned test selected by the real Vitest or Playwright runner, and that test must finish passed. Comments, strings, local fake runners, focused/skipped tests, runtime skip/fixme/fail annotations, conditional declarations, and uncalled registration functions are not performance evidence.
+`cost` names the dimensions that affect a pass, their relationship, and execution frequency. `lifecycle` says whether resources are uncached, memoized, or retained and whether their scope is a call, interaction, renderer, or source. A constant-cost pass uses an empty dimension list. A workload dimension appears only on passes whose cost changes with that magnitude.
 
-Browser slider stress tests apply the declared value through the protected helper:
+`interactionInvalidation` includes `initial-render` and every exact reachable interaction. Targets that produce the same invalidation path remain together. High-frequency viewport or playback paths declare work they must not invalidate when that work is retained upstream.
 
-```ts
-await dragToolcraftSliderToPerformanceStressValue(
-  page,
-  "Control label",
-  appPerformance,
-  "scenario-id",
-)
-```
+## 4. Assessment And Benchmarks
 
-For non-slider scalar values, use `applyToolcraftPerformanceStressValue` with `{ applyValue, observeValue }`. The helper reads the exact scenario value and emits stress evidence only after `observeValue` equals that declared value. Agent-browser checks must apply the same value from `app-performance.ts`. Do not divide a stress value by the slider max, type a separate short value, hardcode a runner-local ratio, or claim application without observing the resulting UI/runtime state.
+Call `assessToolcraftRenderPlan(appSchema, model)` before implementing renderer code. Resolve all structural errors first. A returned benchmark requirement remains visible and pending during ordinary functional development and delivery.
 
-Slider and range slider performance scenarios must preserve live product feedback. The browser test should drag the real thumb and verify the canvas/product output changes during drag. If that drag misses budget, keep the live control semantics and optimize the renderer path first: cache expensive inputs, update uniforms or stable buffers, coalesce preview work to `requestAnimationFrame`, cancel stale async renders, move work off React renders, reuse GPU resources, or change renderer strategy. Do not pass performance by making the slider update only after pointer release or Apply.
+When assessment returns a kernel benchmark requirement, add its `kernelBenchmarkDecisions` entry and executable candidates in `e2e/app-kernel-benchmarks.ts` only inside an exact request-authorized performance iteration or explicit full audit. Then run `pnpm verify:kernel`; its protected Playwright runner owns timing, verifies equal deterministic output at the exact required workload, and writes a source-bound receipt. `app-performance.ts`, the harness, tests, and worklog must not contain authored timing evidence. High-frequency variable-cost `pixel-transform`, `rasterize`, and `composite` passes compare Canvas 2D and WebGL even when the proposed pass already declares GPU execution; WebGPU is added only when selected. Do not add a decision or harness when assessment does not require one.
 
-When a scenario declares `workloadFixture`, apply it first with `applyToolcraftPerformanceWorkloadValue` or `applyToolcraftPerformanceWorkloadFixture`, then apply `stressFixture`, then measure. A control-drag scenario that only sets its own slider value while leaving the source media, text, item count, render scale, or dense scene at defaults is invalid.
+Renderer source guards remain mandatory. Typed assessment does not permit resources to be created in React render, source-bound resources to be rebuilt by unrelated state, or scheduled animation work to escape cleanup.
 
-For combined worst cases, put every relevant independent baseline value in `workloadFixture.value` for control scenarios, such as `{ sourceMedia: { width: 3840, height: 2160 }, renderScale: 2 }`, and put the tested control value in `stressFixture.value`. For preview, zoom, drag, animation, or export scenarios that stress the entire state instead of one control, use `stressFixture.value`, such as `{ detail: 96, scale: 0.6, renderScale: 2 }`. Testing workload controls one-by-one is not enough when the product exposes combinations that multiply render cost.
+## 5. Canonical Paths
 
-Use `kind: "custom"` only for combined object fixtures. Single numeric/string heavy values should use a semantic kind such as `max-value`, `high-density`, `large-canvas`, `many-items`, or `large-text`. Custom object fixtures are still semantically validated: keys such as `content`, `text`, `prompt`, `code`, `script`, `shader`, `template`, `json`, and `css` must hold real `large-text` values; keys for media/image/video must hold realistic `width`/`height`; and `renderScale` / `canvas.renderScale` / `resolutionScale` must be numeric values greater than `1`. Do not hide a short text string, thumbnail media, or a non-applied render scale inside `kind: "custom"`. Browser tests for custom object fixtures must call:
+Call `deriveToolcraftPerformancePaths(appSchema, model)` after the pipeline is declared. Path ids are deterministic products of profile, interaction, invalidated passes, execution locations, and workload dimensions. Target membership is exact scenario coverage but does not churn the id when another equivalent control joins the path.
 
-```ts
-await applyToolcraftPerformanceStressFixture(page, appPerformance, "scenario-id", {
-  detail: {
-    applyValue: async (value) => {
-      await dragToolcraftSliderToValue(page, "Detail", Number(value));
-    },
-    observeValue: async () =>
-      Number(await page.getByRole("slider", { name: "Detail" }).getAttribute("aria-valuenow")),
-  },
-  scale: {
-    applyValue: async (value) => {
-      await dragToolcraftSliderToValue(page, "Scale", Number(value));
-    },
-    observeValue: async () =>
-      Number(await page.getByRole("slider", { name: "Scale" }).getAttribute("aria-valuenow")),
-  },
-});
-```
+Declare exactly one scenario for every derived path. Each scenario declares:
+
+- `pathId` from the derived path;
+- `coversTargets` exactly equal to that path's targets;
+- a browser test and automated test;
+- a real browser adapter while the budget comes from the path's centrally derived profile;
+- a real expected product observable.
+
+Do not use an umbrella viewport scenario when a concrete viewport path exists. Export remains a batch path and retains download or clipboard completion proof.
+
+Scenario interaction is the canonical pipeline interaction from its derived path, such as `control-drag`, `viewport-drag`, `viewport-zoom`, `initial-render`, or `export`. Do not introduce scenario-only aliases or umbrella interaction names.
+
+`src/app/app-verification-impact.json` maps every current product production module to `presentation`, `functional`, or `performance` impact and names its nearest acceptance ids. A performance entry is reserved for a module that can change a named pass's execution, invalidation, workload, resource lifecycle, or measured output, and names only those exact pass ids. The inventory contains no stale or missing module paths; blanket every-module acceptance or pass ownership is invalid. This mapping is the authority for verification scope after first delivery.
+
+## 6. Fixture Adapters And Plans
 
-The applier object contains exactly one entry for each key in `stressFixture.value`, and each entry provides both `applyValue` and `observeValue`. Missing keys, stale extra keys, or an observed value that differs from the declared fixture are test failures, so every heavy-state part is proved through the real UI before measurement.
+`fixtureAdapters.dimensions` contains exactly one adapter per workload dimension. An adapter:
 
-For `workloadFixture.value` object fixtures, use `applyToolcraftPerformanceWorkloadFixture` with the same exact-key rule. `workloadFixture` is the app baseline; `stressFixture` is the action under test.
+- owns the same `dimensionId` as its registry key;
+- converts a compiled numeric value into the product value used by the UI;
+- observes that product value back into the same number;
+- applies and observes every compiled checkpoint exactly;
+- uses an `exhaustive-discrete` entries domain when the product input is finite, binding each numeric workload value to the value actually applied to the product.
 
-## Responsiveness Coverage
+For schema `select` and `segmented` controls, the discrete domain matches every option one-to-one: omissions, extras, duplicate product values, and duplicate numeric values are invalid. Finite runtime-state, external-input, and derived domains carry exhaustive provenance aligned with the dimension source. Continuous adapters do not need a discrete domain.
 
-Ordinary controls still need lightweight responsiveness checks. They should not cause:
+The compiler moves every continuous dimension from `defaultValue` toward its declared maximum-workload boundary, including numerically downward ranges. It accepts a development vector only when the combined normalized pressure is exactly `0.8` within the runtime tolerance. Discrete values must additionally be present in their exhaustive domain. If no reachable vector meets those invariants, development is unavailable; the maximum checkpoint remains independently available. Execution applies and observes available checkpoints exactly, never an interpolated or rounded discrete value. Measured inverse vectors for custom mappings or benchmark relationships must pass the same domain check before execution.
 
-- frozen pointer drag;
-- delayed input;
-- broken slider movement;
-- stale async renders;
-- canvas zoom or offset jumps;
-- panel scroll affecting canvas zoom;
-- timeline or layer interactions destabilizing the viewport.
+Discrete combination search is deterministic and lazy. The runtime-owned `toolcraftDiscreteDimensionBudget` allows at most 256 dimensions in a searched path, and `toolcraftDiscreteCombinationBudget` allows at most 4096 path-level combinations. Dimension count and cardinality are checked before search; overflow or a path above either budget is an actionable planning error distinct from an exhaustive domain that simply has no exact development vector. A valid exact inverse checkpoint for a custom or benchmark development path bypasses these search budgets because no combination search runs; its full vector must still belong to the exhaustive domains and produce exact normalized pressure `0.8` within tolerance.
 
-When `canvas.renderScale` / `Resolution scale` is enabled, responsiveness coverage must include slider or other high-frequency control drags at the selected scale. Browser performance tests for scenarios that include `renderScale`, `canvas.renderScale`, or the Resolution scale control must assert backing canvas pixels with `expectToolcraftCanvasBackingPixelsForRenderScale`; state-only checks, labels, or visual CSS stretching do not prove the selected scale was applied. If the canvas lags, diagnose the source before changing quality: renderer technique, React update frequency, decoded media, shader/program setup, buffer uploads, layout work, stale async renders, or animation scheduling.
+Compile each workload-bearing path with `compileToolcraftPerformanceFixturePlan`. Use the compiled development checkpoint for targeted iteration and the compiled maximum checkpoint for boundary proof. The plan includes every path dimension exactly once.
 
-## Renderer Performance
+Performance profiles are loaded from the runtime-owned shared profile manifest. Runtime validation, starter scripts, and generated standalone runners consume that same versioned manifest; product scenarios cannot copy or override budgets.
 
-Custom renderers should:
+Generic direct, area, quadratic, and product cost models derive a development vector without authored full-vector evidence. `fixtureAdapters.inverseCheckpoints` are present only when a custom mapping or benchmark relationship makes generic inversion impossible; each required pass receives one measured checkpoint for the same complete vector.
 
-- initialize contexts, programs, shaders, pipelines, textures, and large buffers once;
-- update uniforms or stable buffers when controls change;
-- cache decoded media;
-- coalesce high-frequency preview work and split lightweight live feedback from heavier refinement when needed;
-- cancel stale async renders;
-- avoid re-decoding media on every control change;
-- cancel scheduled frames during cleanup.
+## 7. Browser Evidence
 
-Coalescing may reduce redundant renders during high-frequency slider drags, but it must not make the slider feel deferred or leave the canvas unchanged until release.
+Browser tests execute compiled values, apply adapter results through the real UI, and re-observe every dimension before measurement. The action then exercises the derived path and asserts its product-level result.
 
-Custom renderers must declare `rendererPipeline` in `src/app/app-performance.ts`. This is the machine-checkable Render Pipeline Inventory:
+Mutating measurements prove a stable baseline, record the first persistent changed response, and keep the immutable result bound to the same `pathId` as its centrally derived budget. Autonomous output uses a deterministic semantic expectation. Non-mutating batch work ends only after real completion.
 
-- every render pass has an `id`, `kind`, `runsOn`, `output`, `quality`, `inputs`, and `invalidatedBy`;
-- cache-sensitive passes such as `decode`, `preprocess`, `pixel-transform`, `text-layout`, `rasterize`, and `composite` include `cacheKey`;
-- `interactionInvalidation` maps controls and high-frequency interactions to the passes they invalidate;
-- animation frames, drag, pan, zoom, timeline playback, timeline scrub, and mask movement must not invalidate upstream decode/preprocess/pixel-transform work unless that runtime target truly changes the upstream result;
-- each `workloadTargets` entry appears in `interactionInvalidation.targets` so tests can prove which control changes renderer cost.
+`export` scenarios declare exact `actionValue`, visible `controlLabel`, and `completionEvidence`. They may declare a `completionDeadlineMs` only when the product needs a stricter deadline than the central batch profile; scenarios do not author responsiveness budgets. The protected helper owns the click and completion event. Export evidence still inspects the delivered artifact and verifies that it is non-empty and matches selected output semantics.
 
-Write this inventory before custom renderer code. If the inventory says a slider only updates a shader uniform, the implementation should update a uniform or stable buffer, not rebuild media decode, glyph layout, or raster caches. If the inventory says media import invalidates source decode, browser performance must include a realistic `media-import` scenario.
+## 8. Demand-Only Performance Lifecycle
 
-Pixel-output renderers may use a capped preview pixel budget, but export/copy must render final product output at `state.canvas.size`.
+During implementation, run targeted unit and functional browser checks for feedback without minting delivery evidence. At the coherent delivery boundary, the protected delivery runner diffs current sources against the immediately previous successful delivery and resolves changed modules through `app-verification-impact.json`. Every functional delivery requires only its ownership-derived functional proof, including changes to performance-owned modules. Performance ownership constrains an exact request-authorized iteration; it does not authorize measurements. A durable full-performance baseline, when one exists, remains historical evidence and is not reused as the functional-delivery diff anchor. Reports remain bound to their executed plan, nonce, and current source hash; product-authored JSON is not evidence.
 
-Text-output and vector-output previews must preserve native output fidelity. Do not render low-resolution text/vector output into an offscreen canvas and upscale it.
+First and later functional gates validate every structural envelope, pipeline, path, fixture, and adapter invariant with the runtime-owned deferred coverage policy. They may expose unresolved benchmark requirements but do not require `kernelBenchmarkDecisions`, run `verify:kernel`, or read a kernel receipt. Default strict coverage and authorized performance execution retain those requirements.
 
-For heavy bitmap-media, shader-like, noise/texture, filters, halftone, mesh, and per-pixel image-processing paths, WebGL/WebGPU is a required candidate before choosing CPU Canvas 2D. Canvas 2D is allowed only when `rendererTechnique.measuredAlternativeEvidence` records a structured WebGL/WebGPU comparison with `alternativeStrategy`, `scenarioId`, `fixture`, `measuredResult`, and `decision`. Prose in `whyNotAlternativeStrategies` or `performanceRisks` is not enough. A worker can protect the UI thread, but it is not a substitute for GPU acceleration when the workload is fundamentally per-pixel or when the pipeline has main-thread rasterize/composite preview pressure.
+Ordinary changes and performance metadata cannot authorize measured performance. Only exact complaint/request authority can create one measured targeted performance iteration. Changed files, tier, ownership, passes, paths, pipeline, boundary, adapter, interaction, output, or subsystem never authorize it. Once authorized, run only the exact `browser perf:` paths named by the request authority; unrelated paths and the full suite remain outside the iteration.
 
-Renderer strategy is not final until the heavy scenarios pass. When stress preview, animation, drag, zoom, or export tests exceed budget, first decide whether the chosen renderer is wrong for this workload. Move heavy work to WebGL/WebGPU, split semantic foreground from heavy backgrounds, cache atlases/buffers, coalesce high-frequency preview updates, or change the rendering layer model before reducing product quality or relaxing budgets.
+The protected performance-iteration runner requests each path's compiled development fixture at exact normalized pressure `0.8`. Every selected path must have the exact reachable development fixture, or verification fails with a configuration error; it never falls back to maximum. The separate operator/CI certification command selects compiled maximum fixtures for the complete matrix.
 
-Do not pass performance by lowering output quality, render scale, canvas backing pixels, export resolution, media fidelity, maximum detail, item count, or animation fidelity. If all reasonable optimizations are exhausted and the app still cannot meet the budget at the hard limit, document the measured ceiling with `loadProfile`: exact hard limit, smooth target, ratio, failed higher measurements, attempted optimizations, why further changes would harm product quality or require a different product scope, and whether the range above the smooth target remains experimental. Lowering the smooth target does not relax frame, interaction, preview, render, export, or long-task budgets.
+The conversational lifecycle is automatic:
 
-## Required Browser Checks
+1. **First product delivery.** Bare `pnpm verify:delivery` proves complete product contracts, performs one production build, and runs full functional acceptance with no measured performance. The receipt preserves any independent full-performance baseline and cannot claim targeted or full performance evidence.
+2. **Later functional-targeted delivery.** The same bare command derives exact ownership-required functional checks from the current inputs and immediately previous successful delivery. It preserves a baseline when present and cannot silently run measured performance or create one.
+3. **Performance complaint.** The latest Decision Trail records only an exact request quote and canonical affected path IDs. One bare `pnpm verify:delivery` then runs one targeted iteration against the reachable development fixture. The protected report stores independently validated `cold`, `warm`, and `sustained` measurements; compatible prior evidence produces diagnostic deltas, while absent or incompatible evidence records a non-comparable result. Current absolute budgets remain the pass/fail authority. Deliver the verified app, then stop and wait for user evaluation. A later complaint creates a new Decision Trail authority for another bounded iteration.
+4. **Full audit.** Only an explicit operator request or accepted offer authorizes `pnpm verify:perf`. It performs one fresh production build and the complete maximum-fixture performance matrix, updates only the performance checkpoints, and preserves the delivery anchor.
 
-Use real interactions for:
+Use the runtime request classifier as a guard, not as a substitute for understanding the user. It returns high-confidence `performance-iteration`, high-confidence ordinary product work, or `needs-agent-judgment`. High-confidence ordinary product instructions stay ordinary. For ambiguous language, the AI reads the actual request and decides. Iteration mode requires `Performance intent: performance-iteration — Request evidence: "<verbatim exact Request quote>"` in the worklog before the command runs. The quote must be a nontrivial exact raw substring of the current Request, including identical whitespace and Unicode code units; invented, whitespace-collapsed, or NFKC-equivalent evidence is invalid.
 
-- `preview-render`;
-- `control-change`;
-- `control-drag`;
-- `mask-drag` when canvas handles, masks, pins, or on-canvas anchors affect output;
-- `media-import` when upload exists;
-- `export-copy` for product export actions and clipboard actions; measure the selected output dimensions, not CSS preview size;
-- `timeline-playback` or `timeline-scrub` when timeline exists;
-- `layers-interactions` when layers exist;
-- `viewport-zoom-stress` for detail-heavy or animated custom renderers;
-- `viewport-stability`.
+Canonical classification examples:
 
-Every `export-copy` scenario declares `actionValue` with the exact `panelActions`
-value, `controlLabel` for its visible button, and `completionEvidence` set to
-`download` or `clipboard`. Its browser test uses the corresponding protected
-`measureToolcraftDownloadActionByLabel` or
-`measureToolcraftClipboardActionByLabel` helper with `scenarioId`. The helper
-owns the real click and completion event; the signed runtime-evidence reporter
-rejects missing completion, skipped/failed tests, and evidence from failed
-retries.
+- direct reports that the app lags, the editor is slow, dragging has latency, frames stutter, or CPU/GPU/memory use is excessive select one performance iteration;
+- product commands such as increasing animation speed, freezing a camera at a frame, renaming a mode to “Performance”, or stating that the app does not lag are high-confidence ordinary product work;
+- wording such as “the controls feel sticky” or “something feels off” needs agent judgment from the full request;
+- classification is clause-local: an independent complaint still selects an iteration even when another clause negates a different complaint or requests a product speed change.
 
-For `slider` and `rangeSlider`, the required performance scenario is `control-drag`. A `control-change` scenario can cover selects, inputs, toggles, and other non-drag controls, but it does not prove live canvas feedback or drag smoothness for sliders.
+Use bare `pnpm verify:delivery` once for the coherent delivery batch. Complaint wording, repetition, filename, diagnostic classification, and touched subsystem never launch the complete matrix automatically. A targeted failure triggers targeted diagnosis, not an automatic full-suite run, and a passing iteration stops after returning the verified app for user evaluation.
 
-Animated custom renderers also need `animation-viewport-drag`. Animation-only frame sampling and viewport-only stability are not enough: the browser test must sample frames while physically dragging or panning the canvas viewport. If SVG/DOM cannot pass that combined budget, choose a different renderer strategy from evidence instead of loosening the budget.
+After two consecutive compatible protected performance iterations, the runner emits a recommendation and the agent must offer a slower complete audit if the user remains unsatisfied. A demonstrably broad or unlocalizable cross-system problem may justify offering it earlier through semantic agent judgment; do not reduce that decision to the number of selected paths.
 
-Detail-heavy or animated custom renderers also need `viewport-zoom-stress`. This test must apply the combined worst-case stress fixture first, then use the real toolbar zoom controls while sampling frame gaps and long tasks. Do not satisfy it by calling `canvas.zoom`, mutating runtime state directly, checking only the final zoom value, or zooming a default/lightweight output.
+`pnpm verify:perf` is the separate protected operator/CI full-audit command. It performs one fresh build, runs maximum fixtures for the complete matrix, records `full-performance`, and creates or refreshes the durable baseline while preserving delivery evidence. An explicit natural-language request for a complete audit or explicit acceptance of the agent's offer authorizes the agent acting as operator to run it; the user does not need to know the command name. A complaint, repeated complaint, worklog iteration evidence, filename, diagnostic classification, or changed subsystem alone never authorizes it. Treat the audit as diagnosis and certification: fix failed paths with focused checks, then run the complete matrix once at the requested certification boundary.
 
-Detail-heavy custom renderers also need a stress `preview-render` or `animation-frame` scenario with a `maxLongTaskMs` budget. A high-count Canvas 2D layer must carry that evidence before delivery. If it fails, revise renderer strategy from the measured failure instead of keeping Canvas 2D by default.
+`TOOLCRAFT_PERFORMANCE_VERIFICATION_LIFECYCLE` owns this split centrally: agent-browser is limited to diagnosis and targeted visual investigation, while protected Playwright owns functional, performance-iteration, and operator full-certification receipts. Product config cannot override it.
 
-During canvas drag, pan, pinch, zoom, and radar/center interactions, animated preview renderers must suspend or coalesce non-essential animation work. This is an interaction-performance throttle, not a user-visible playback command: do not flip the user's Play/Pause state, do not reset timeline time, and do not change export behavior. After the interaction settles, resume from the correct timeline or autonomous time without canvas offset or zoom jumps.
+Agent-browser observations help diagnosis and visual verification, but they do not mint receipts or a durable baseline. Worklog prose is context, not execution proof.
 
-Animation checks should sample enough frames to catch jank. Interaction budgets must match scenario type rather than using one universal number.
+User-facing completion text must distinguish the levels. Functional delivery reports exact functional proof and states that measured performance was not run. A performance iteration reports the selected tests, returns the verified app, and waits for user evaluation; after a second consecutive compatible iteration it also offers the slower complete audit. Only an explicitly authorized and passed operator-run `full-performance` matrix may be described as full performance certification.
 
-Use `app-performance.ts` as the single budget and fixture source. Mutating measurements pass `scenarioId` and a structured-cloneable `observeOutcome`; generic change mode proves a stable baseline before the action, its first changed response sets latency, and its final post-action outcome must remain different through the stability window. For autonomous output, pass `expectedOutcome` and observe a stable semantic state, or fix playback to a deterministic phase; latency is measured to that expected result. Scalar fixtures are applied and observed through `applyToolcraftPerformanceStressValue` / `applyToolcraftPerformanceWorkloadValue`; object fixtures use `applyToolcraftPerformanceStressFixture` / `applyToolcraftPerformanceWorkloadFixture`, apply every declared key, then re-observe the complete final state before evidence can attach. Budget checks await `expectToolcraftScenarioPerformanceBudget`. Completed measurements are frozen and branded for one scenario, so a mutable literal or another scenario's result cannot satisfy the gate.
+## Performance Quality
 
-Run targeted performance scenarios for Tier 3 performance-sensitive edits when they directly exercise the touched workload, viewport, or export path. The default `pnpm test:browser` / `pnpm verify:ui` gate excludes every Playwright test whose name contains `browser perf:`, including the performance audit and budget scenarios. Use the current AI agent's controlled browser for targeted diagnosis. `pnpm verify:perf` is the protected final Playwright checkpoint; it builds the current production bundle, serves it through Vite preview, and runs every `browser perf:` scenario with one worker so budgets measure shipped runtime work instead of dev-server transformation and are not distorted by unrelated parallel browser tests.
+Preserve selected output quality, preview fidelity, backing resolution, source fidelity, product boundaries, and live interaction behavior. Raster products with Resolution scale declare functional `renderScaleCoverage` using `kind: "selected-backing-pixels"` and exact `interaction`/`steady` states, plus `playback` when timeline is enabled. Their product browser scenario uses `expectToolcraftCanvasRenderScaleEvidence`; `canvas-render-scale-backing` is emitted only after real backing dimensions satisfy the selected scale without changing visible CSS size.
 
-Run a full performance checkpoint only when:
+A renderer that caps 2x output during interaction, playback, or steady state fails functional acceptance without measured performance. `performance-render-scale` remains limited to an explicitly authorized performance path and follows the same backing-pixel assertion; path metadata alone is not evidence. When a budget fails, inspect assessed pass cost, invalidation, resource lifecycle, scheduling, cancellation, and execution location before changing product scope.
 
-- the first working version of the app exists;
-- the user explicitly asks to optimize performance, fix lag, remove jank, speed up animation, stabilize drag/zoom, or otherwise complains about performance.
+## Non-Normative Domain Examples
 
-For the first working product app, this checkpoint is mandatory and runs before `pnpm verify:final`. Run `pnpm verify:perf`; its protected Playwright runner records the current-source machine receipt automatically. Agent-controlled browser checks remain preferred for quick diagnosis and visual investigation, but they cannot mint or replace the final receipt. The final gate rejects a missing or stale receipt. Worklog prose remains decision context and cannot substitute for the structured receipt. A post-first-working non-performance exemption must use `pnpm verify:perf:record-exemption -- --tier=<0|1|2>` and requires a prior passed receipt.
+The following examples are illustrative only and establish no universal fixture minimum, product category, or naming rule:
 
-Performance fixes must preserve selected output and preview quality. Do not pass budgets by lowering image quality, selected `canvas.renderScale`, export resolution, source media fidelity, or canvas backing pixels unless the user explicitly chooses that lower-quality value through a visible control. Prefer coalescing slider updates, caching expensive inputs, moving work off the React render path, reusing GPU resources, or changing renderer strategy over reducing visual fidelity.
+- An image export app may use output width as a schema-backed dimension and treat export as quadratic batch work.
+- A list compositor may use item count from runtime state and combine it with a second independently enforced magnitude.
+- A source-driven renderer may model source width and height separately or derive area when that matches measured cost.
+- A model source path includes package extraction, canonical decode, model presentation, canvas orbit, export, and resource cleanup. Its protected fixtures combine geometry with authored texture/material bytes, assign worker versus main-thread execution explicitly, verify cache reuse, and require disposal after replace/remove/reset/failure/unmount.
 
-Do not use the full performance suite as the default loop for feature work after the first working version. Those edits still need the targeted checks named by the verification tier, but they should not pay for every renderer and viewport stress test unless one of the two full-performance triggers applies. If a feature loop skips full performance, record the reason in the worklog.
+Use the smallest set of numeric dimensions that explains the real renderer workload.

package/templates/starter/docs/toolcraft/renderer-technique.md

@@ -1,54 +1,119 @@
 # Renderer Technique
 
-> Reading route: start with `workflow.md`. Core generated-app rules live in `core/*`; this file is a focused renderer reference for the topic below.
+> Reading route: start with `workflow.md`. Core generated-app rules live in `core/*`; this file is the focused renderer-selection reference.
 
-Choose render technology per product layer. Do not choose a renderer because it is convenient; choose it from product output semantics, reference behavior, fidelity, and workload.
+Choose renderer technology from product output semantics, reference behavior, fidelity requirements, and the assessed render plan. Names, keywords, control types, source formats, and visual richness do not select a renderer.
 
-The initial renderer choice is provisional. It becomes accepted only after the app passes performance checks with the largest useful product canvas and the heaviest useful values for its own controls. If those checks show frame gaps, long tasks, viewport shaking, slow export, or interaction jank, revise the renderer strategy from that evidence before delivery. Do not make a renderer look fast by silently reducing the selected preview scale, backing pixels, source media quality, or export fidelity.
+## Normative Sequence
 
-## Strategy Guide
+Use the same producer order for every custom renderer:
 
-- DOM: native product text, editable text, accessible product labels, low-count structured markup.
-- SVG: crisp vector shapes, lines, icons, product foreground geometry, handles, and hit targets.
-- Canvas 2D: medium raster compositing, text-to-canvas export, simple procedural previews, export passes.
-- WebGL or WebGPU: dense pixels, shaders, image processing, high-resolution procedural output, large particle fields, heavy animated backgrounds.
-- Mixed: use separate layers when background, product foreground, editing handles, and export composite have different semantics.
+1. Inventory reachable controls, runtime-state inputs, and external inputs.
+2. Model workload dimensions with schema or product-enforced boundaries.
+3. Declare each candidate pass's cost, frequency, lifecycle, execution location, quality, cache keys, and exact interaction invalidation.
+4. Run `assessToolcraftRenderPlan`; resolve errors and run protected `pnpm verify:kernel` only when the assessment requires candidate evidence.
+5. Derive canonical paths and compile combined fixtures through their adapters.
+6. Implement the selected renderer and run targeted checks for the paths being developed.
+7. Run lifecycle-appropriate delivery proof: full functional acceptance with no measured performance for first product delivery, exact ownership-derived functional checks for later work, or one targeted iteration for a performance complaint. Full certification is a separate operator/CI command.
 
-Dense backgrounds may use Canvas 2D, WebGL, or WebGPU when the spec names primitive count and performance reason. A dense raster background does not justify rasterizing low-count foreground geometry or text.
+Do not write renderer code before the envelope, `rendererTechnique`, pipeline, and assessment exist.
 
-Heavy bitmap-media, shader-like, noise/texture, filter, halftone, mesh, and per-pixel image-processing layers must evaluate WebGL/WebGPU before delivery. Keeping the pixel work on Canvas 2D requires measured worst-case evidence in `whyNotAlternativeStrategies` or `performanceRisks`, using the real media/canvas stress fixture. Do not keep CPU Canvas 2D by default and then pass budgets by downsampling, lowering render scale, or testing a small upload.
+## Selection Principles
 
-Do not force WebGL only because an app is visually rich, and do not keep Canvas 2D only because the primitive is text or vector. Use the stress results. High-count text, vectors, particles, grids, media, or procedural layers can stay on Canvas/SVG/DOM only when worst-case preview or animation tests prove they remain responsive. If they do not, split layers or move the heavy product renderer to WebGL/WebGPU.
+- Preserve the reference renderer in reference-runtime-clone mode unless a concrete blocker, replacement reason, and acceptance mapping are recorded.
+- Keep semantic output in a representation that preserves its required fidelity, editing behavior, accessibility, and export meaning.
+- Select execution location and renderer API from assessed pass cost and update frequency. Do not infer them from a product category or target name.
+- Preview and export may use different renderers when `previewExportDifferenceReason` explains the boundary and tests prove equivalent product semantics.
+- Prefer retained resources and stable cache keys. Source-bound resources live outside React render, survive unrelated interactions according to pass lifecycle, and release during cleanup.
+- Separate layers when they have different semantics, invalidation, lifecycle, interaction, or export treatment. A costly layer does not force unrelated output into the same renderer.
+- Preserve selected quality, product boundaries, backing resolution, and source fidelity. A renderer is not accepted by silently reducing them.
 
-## Required Matrix
+When assessment requires a benchmark, declare `kernelBenchmarkDecisions`, implement only the named executable candidates in `e2e/app-kernel-benchmarks.ts`, and let protected `pnpm verify:kernel` measure them at the exact combined workload vector. Candidate outputs must be deterministic and equal at full quality. Do not author timing values or add speculative benchmark metadata when generic assessment resolves the choice.
 
-Custom renderer specs and `src/app/app-performance.ts` must mirror the decision:
+## Required Inventory
+
+Custom renderer specs and `src/app/app-performance.ts` mirror:
 
 - `sourceRepresentation`;
 - `productRepresentation`;
 - `previewRenderer`;
 - `exportRenderer`;
-- `rendererWorkload`;
 - `rendererStrategy`;
 - `whyNotAlternativeStrategies`;
 - `fidelityRisks`;
 - `performanceRisks`.
 
-If text or vector output is intentionally rasterized, include `intentionalRasterizationReason`. If preview and export renderers differ, include `previewExportDifferenceReason`. If a reference runtime renderer changes, include `referenceRendererChangeReason`.
+Workload pressure and renderer candidates are derived from envelope dimensions and assessed renderer-pass cost/lifecycle. Do not author a parallel coarse workload category or separate renderer-comparison metadata. `kernelBenchmarkDecisions` records product intent; only its protected current-source receipt is measurement evidence.
+
+If output is intentionally rasterized, include `intentionalRasterizationReason`. If preview and export renderers differ, include `previewExportDifferenceReason`. If a reference runtime renderer changes, include `referenceRendererChangeReason`.
 
-`rendererTechnique` chooses the technology. `rendererPipeline` proves the architecture. Do not start a custom renderer until both are written: technology without pass invalidation still lets an app recompute too much work.
+`rendererTechnique` records the selected technology. `rendererPipeline` records why and when its passes execute. Both must agree with the implementation.
 
-For heavy custom renderers, specs and `app-performance.ts` must also include stress preview or animation evidence using real maximum values from the app: max density, max text length, max item count, max canvas size, max animation speed, max export quality, max media size, or the nearest real heavy fixture for the product.
+Renderer technology does not decide camera ownership. Before renderer code,
+product readiness separately declares `viewInteraction`: editable spatial scenes
+default to `orbit`; fixed or timeline-owned cameras require explicit
+user/reference evidence. WebGL/Three.js alone does not imply orbit, and a fixed
+camera chosen by the implementation is not evidence for omitting it.
 
 ## Layer Inventory
 
-Custom renderer specs must classify product layers when they exist:
+Declare each meaningful product, overlay, and export layer in `rendererTechnique.layers`. Give visible product and editing layers a stable `uiSelector` for browser proof. For every layer, record content semantics, renderer, primitive magnitude, and export mode.
+
+Editing handles remain interaction overlays, stay out of exported product output, and write through runtime state. Tests verify visible layers and export inclusion independently.
+
+## Three-Dimensional Model Interaction
+
+Standard model apps use `modelPresentation: { mode: "runtime" }` and the runtime's lazy Three binding/canvas layer. It renders canonical geometry plus the supported authored material/texture/vertex-color appearance, or the exact Blender-compatible fallback when appearance is absent. Product `canvasContent` must not import format loaders, enumerate repository records, create a second Three cache, reconstruct materials, or render a duplicate model over the runtime layer. `renderDefaultCanvasMedia={false}` affects generic image/file preview only and never disables model presentation.
+
+Custom model output is an explicit presentation mode, not a loader escape hatch. Declare unique consumers in `modelPresentation: { mode: "custom", consumers }`, mount `useToolcraftModelPresentationConsumer(declaration)`, then acquire and release the supplied presentation lease. Runtime suppresses its standard layer only for those declared source targets and reports retryable feedback when the checked consumer is missing or acquisition fails.
+
+```tsx
+const declaration = {
+  id: "product-model",
+  sourceTarget: "source.model",
+  orientationTarget: "view.orbit",
+} as const;
+
+function ProductModel({ activeDocumentRef }: { activeDocumentRef: string }) {
+  const presentation = useToolcraftModelPresentationConsumer(declaration);
+
+  React.useEffect(() => {
+    const controller = new AbortController();
+    let release: (() => void) | undefined;
+
+    void presentation
+      .acquirePresentation(activeDocumentRef, {
+        purpose: "preview",
+        signal: controller.signal,
+      })
+      .then((lease) => {
+        if (controller.signal.aborted) return lease.release();
+        release = lease.release;
+        mountProductSceneRoot(lease.root, lease.document, lease.bounds);
+      })
+      .catch((error: unknown) => {
+        if (!controller.signal.aborted) handleProductPresentationError(error);
+      });
+
+    return () => {
+      controller.abort();
+      unmountProductSceneRoot();
+      release?.();
+    };
+  }, [activeDocumentRef, presentation]);
+
+  return <canvas data-toolcraft-product-output />;
+}
+```
+
+The `mount*` and error functions above stand for product renderer integration only. The consumer receives the ready canonical root and metadata; it does not import GLTF/OBJ/FBX loaders or rebuild materials.
+
+The presentation lease is keyed by canonical document reference and shares immutable geometry/material/texture GPU resources across preview and export while cloning only scene roots. Replacement, delete/reset, failed creation, release, and provider unmount dispose ownership deterministically. The original uploaded folder/ZIP remains immutable durable source; display fit and camera pose live outside the leased root.
+
+The runtime presents structurally valid analyzing or repairing geometry at `0.4` opacity and committed clean/fixed geometry at `1`. Export is always `1`. Product image export renders its own pixels first, then awaits the `renderModelsToCanvas(exportCanvas)` helper supplied to `onPanelAction`. The public `renderToolcraftModelsToCanvas` API is the host-level implementation behind that helper; product apps should not bypass the action context to assemble their own host. Video export uses the same binding, visible layers, pose, current canvas dimensions, and target pixel ratio for every frame.
 
-- `background`;
-- `product-foreground`;
-- `editing-handles`;
-- `export-composite`.
+When `viewInteraction.mode` is `orbit`, schema `orientationGizmo`, direct model drag, preview rendering, hit testing, reset/history, and export share every declared orientation pose target. The product renderer supplies geometry-aware `hitTest`; Toolcraft owns gesture scheduling and history through `useToolcraftModelOrbitInteraction`.
 
-Mirror these in `rendererTechnique.layers` with visible `uiSelector` values for browser verification.
+Pointer ownership is selected on pointer-down. A visible-model hit rotates; a miss is left untouched so `CanvasShell` pans. Target-scoped runtime ownership serializes gizmo drag, snap, and direct orbit, and cancels stale work on a newer gesture or external state write. Do not infer model geometry in runtime, keep a second local camera/Euler state, or let orientation invalidate passes that do not consume the pose. Measure the orientation target's canonical live interaction path at the declared workload without reducing preview quality.
 
-Editing handles should be DOM/SVG overlays, must not appear in export/copy output, and must write through runtime state.
+Layer boundaries follow semantics and invalidation, not a fixed list of product domains. Their workload proof comes from derived paths and combined fixtures.