@pixel-point/toolcraft 0.0.15 → 0.0.16

package/templates/starter/docs/toolcraft/assembly-workflow.md

@@ -25,7 +25,7 @@ export const appComposition = {
 } satisfies ToolcraftAppComposition;
 ```
 
-Edit `src/app/app-composition.tsx`, not the signed route. Product composition may provide only `schema`, `canvasContent`, `controlRenderers`, `onPanelAction`, and `renderDefaultCanvasMedia`; the protected route owns `className` and other host layout. Do not compose `ToolcraftRoot`, `CanvasShell`, `ControlsPanel`, `LayersPanel`, `TimelinePanel`, or `ToolbarPanel` by hand. If a runtime surface has a performance or behavior issue, fix the shared runtime instead of replacing the surface locally.
+Edit `src/app/app-composition.tsx`, not the signed route. Product composition may provide only `schema`, `canvasContent`, `controlRenderers`, `modelPresentation`, `onPanelAction`, `renderDefaultCanvasMedia`, and optional `rendererPipelineRegistration`; the protected route owns `className` and other host layout. Model products default to `modelPresentation: { mode: "runtime" }`. Custom presentation declares checked consumers and suppresses only their model targets; `renderDefaultCanvasMedia={false}` affects generic image/file preview, not runtime models. Do not compose `ToolcraftRoot`, `CanvasShell`, `ControlsPanel`, `LayersPanel`, `TimelinePanel`, or `ToolbarPanel` by hand. If a runtime surface has a performance or behavior issue, fix the shared runtime instead of replacing the surface locally.
 
 Supporting product modules may be organized anywhere under `src`; there is no folder allowlist. The product boundary follows all product production files and rejects host/runtime surface imports, built-in control imports/re-exports, dynamic bypasses, and production dependencies on test/spec modules.
 
@@ -37,6 +37,7 @@ Allowed app extension points:
 | `canvasContent` | Product output only. |
 | `controlRenderers` | True custom controls only after the built-in fit check. |
 | `onPanelAction` | Sticky footer product actions. |
+| `rendererPipelineRegistration` | One compiled executable pipeline shared by render work, actions, evidence, and new-envelope assessment. |
 | Runtime commands/hooks | History, media, canvas, timeline, layers, and controlled app behavior. |
 
 Do not render built-in controls such as `SliderControl`, `SelectControl`, `ColorControl`, `GradientControl`, `FontPickerControl`, `FileDropControl`, or `PanelActionsControl` directly in app code. Declare them in schema so layout, reset, history, visibility, keyframes, labels, and tests stay runtime-owned.
@@ -49,13 +50,28 @@ Once the folder is a real product, switch `src/app/app-acceptance-data.ts` from
 
 ```ts
 export const appProductReadiness = {
+  interactionOwnership: [],
   mode: "product",
   productName: "Product name",
   productSummary: "What the app creates or edits.",
   requestedBehavior: "The user-facing behavior this app must implement.",
+  viewInteraction: {
+    mode: "non-spatial",
+    reason: "This product has no visible three-dimensional scene or model.",
+  },
 } as const;
 ```
 
+Populate `interactionOwnership` before adding canvas handles or custom
+interactions. One operation has one primary `canvas` or `panel` surface chosen
+from user request, inspected reference, or product usability evidence. Different
+operations may share related state across surfaces; mirrored operations may not.
+
+Use `viewInteraction.mode: "orbit"` for a visible editable spatial scene and
+list its `orientationGizmo` targets. `fixed-camera` or `timeline-camera` require
+explicit request/reference evidence; do not infer fixed framing merely because
+the prompt did not separately request rotation.
+
 ## Controls
 
 Before writing product sections, export `starterControlSectionInventory`. Each product section declares its title, targets, product entity or workflow stage, and grouping reason.
@@ -88,26 +104,26 @@ Use `core/timeline-animation.md` for timeline mode, compact/extended timeline, s
 
 ## Renderer Work
 
-For custom renderers, write the Renderer Technique Decision Matrix and Render Pipeline Inventory before code. The implementation plan maps every performance-sensitive control to the render pass it invalidates.
+For custom renderers, write the Renderer Technique Decision Matrix and typed performance model before code. Follow one sequence: reachable controls and inputs; workload dimensions and enforced boundaries; pass cost, frequency, lifecycle, and invalidation; render-plan assessment and protected kernel benchmark when required; derived paths and combined fixtures; impact-derived functional/browser development checks; lifecycle-appropriate delivery proof. Only exact request authority may add measured targeted performance.
 
-Use `renderer-technique.md` and `core/performance.md` for renderer strategy, cache keys, workload fixtures, render scale, and optimization evidence.
+Compile one lightweight renderer pipeline registration outside test modules. Supply that exact registration as `rendererPipelineRegistration` in the composition and as `rendererPipeline` to new-envelope performance assessment. Run `assessToolcraftRenderPlan` before implementing the renderer. Derive path ids from the assessed registration and compile workload fixtures from those paths; do not classify workload by target names or author scenario-specific maxima. Renderer work uses `useToolcraftPipelinePass`; retained resources are available only from its generation-bound pass execution context. Product code never receives runtime disposal ownership.
 
-## Verification Tiers
+Use `renderer-technique.md`, `core/performance.md`, and `performance.md` for renderer strategy, envelope dimensions, pass metadata, adapters, derived paths, render scale, and optimization evidence.
 
-Before every edit, classify blast radius and record the planned checks:
+## Automatic Delivery Lifecycle
 
-```md
-Verification tier: Tier N
-Reason: <changed surface and expected blast radius>
-Run: <commands and browser checks>
-Skip: <checks not needed for this pass and why>
-```
+Use one normal sequence: assemble or change the product, gather focused functional feedback, finish the coherent delivery batch, run protected functional delivery once, and return the app for user evaluation. Focused checks while implementation is changing do not mint delivery evidence.
+
+1. First product delivery uses bare `pnpm verify:delivery` for complete product contracts, one production build, full functional acceptance, and no measured performance.
+2. Later `functional-targeted` delivery uses the same bare command for exact ownership-derived functional proof relative to the immediately previous successful delivery.
+3. A performance complaint records its exact request quote and canonical affected path IDs in the worklog, then one bare delivery runs one targeted iteration and returns the app for evaluation.
+4. A full audit requires an explicit operator request or accepted offer; only then run `pnpm verify:perf` for one fresh build and the complete maximum-fixture performance matrix.
 
-Use `pnpm verify:ui` when browser acceptance is required without the performance suite. Run `pnpm verify:final` for first working product delivery, folder export, runtime/template/contract/CLI changes, broad refactors, and final gates. Full performance checkpoints run only for the first working product version or explicit performance complaints; otherwise run targeted performance checks only for touched paths.
+Protected receipts own changed files, the derived plan, executed checks, reports, measurements, and pass/fail evidence. The worklog keeps product intent and decisions.
 
 For final delivery, run:
 
 ```bash
-pnpm verify:final
+pnpm verify:delivery
 pnpm dev
 ```

package/templates/starter/docs/toolcraft/component-rules.md

@@ -56,14 +56,20 @@ Use segmented controls only for compact mode choices that preserve every cell's
 
 Segmented controls are full-width. Do not place `segmented` beside Switch, Color, Select, or another control in a two-column inline row; use `select` when a finite choice must occupy a half-width column.
 
-Limits:
+Text segmented controls allow at most 4 options, no option label longer than 9 characters, and no more than 24 total option-label characters.
 
-- at most four options;
-- no option label longer than nine characters;
-- no more than twenty-four total option-label characters.
+`defineToolcraft` rejects over-budget text segmented schemas before controls render. Shorten labels or use `select`; there is no silent conversion.
 
 If cells clip, collide, lose padding, or force labels into adjacent cells, shorten labels first. If compact labels still fail, use `select`.
 
+## Tabs Controls
+
+Use `tabs` when one finite choice replaces the content or workflow view shown below the control. Use `segmented` instead for a compact mode setting that leaves the surrounding view unchanged.
+
+Tabs are full-width and never render a separate visible field label. The schema `label` supplies the accessible tab-list name; the nearest section title supplies visible context. Do not place `tabs` in a two-column inline row.
+
+Tabs preserve the same controlled value while adapting to available width. When every tab cell cannot keep its text and internal padding on one row, the runtime renders the choices through `Select`; when the width returns, it restores the tab row without changing the selected value.
+
 ## Select Controls
 
 Standalone `select` controls render stacked and full-width: label above, dropdown below. Do not use the old compact side-label form with label on the left and dropdown on the right.
@@ -80,7 +86,7 @@ Use `core/layout.md` for section grouping, dependency cohesion, headers, reset,
 
 ## Colors
 
-Use `core/layout.md` for semantic color grouping, color labels, row fit, and color/opacity layout. Use `core/setup-export.md` for the required output `Background` section and export background behavior.
+Use `core/layout.md` for semantic color grouping, color labels, row fit, and color/opacity layout. Use `core/setup-export.md` for the authored background source pair, its runtime Setup placement, and export background behavior.
 
 ## File Upload
 
@@ -145,6 +151,36 @@ Holding Shift while dragging a vector pad locks movement to the dominant axis an
 
 Do not add custom vector sizing props. Choose the right number, variant, and section grouping, then let runtime sizing handle the pad.
 
+Do not use Vector for camera orbit, object orbit, or a visually flat object that users rotate through 3D space. Use Orientation Gizmo.
+
+## Orientation Gizmo
+
+`orientationGizmo` is runtime-owned canvas chrome for a visible model that users can rotate in three dimensions. It is not a panel pad and it must not be recreated in product code.
+
+Declare `starterProductReadiness.viewInteraction` first. A visible editable
+spatial scene defaults to `orbit`; the fact that rotation was not separately
+requested does not justify a fixed camera. `fixed-camera` and `timeline-camera`
+are evidence-backed modes for explicit user/reference behavior, not agent design
+shortcuts.
+
+Declare one control for the active model mode in its semantic model/view section:
+
+```ts
+orientation: {
+  defaultValue: { position: [0, 0, 5], up: [0, 1, 0] },
+  keyframeable: false,
+  label: false,
+  target: "view.orbit",
+  type: "orientationGizmo",
+}
+```
+
+Use `useToolcraftModelOrbitInteraction` on the product renderer and provide a hit test against actual visible geometry. A plain primary drag starting on the model rotates the shared pose; a drag starting outside the model bubbles to `CanvasShell` and pans. The owner is locked at pointer-down. Preview, raycasting, reset/history, PNG, and video consume the same pose target.
+
+Multiple `orientationGizmo` declarations are allowed only for model modes whose combined section/control visibility conditions are statically provable as mutually exclusive. Runtime renders at most one active canvas handle and rejects an ambiguous state instead of selecting the first declaration.
+
+Click a signed axis endpoint to return to that view. Drag anywhere inside the circular gizmo to orbit with Blender-style Turntable behavior: horizontal movement rotates around world up, vertical movement rotates around the screen-horizontal axis, and sensitivity is 0.4 degrees per CSS pixel. Direct model drag uses the same rotation kernel. Axis snaps use angle-scaled Blender Smooth View timing with a 200ms maximum. Gizmo drag, snap, and direct model drag share target-scoped ownership, so a newer gesture, reset, undo/redo, or external target write cancels stale work. A background click is inert; pointer cancel and lost capture end the gesture. The runtime handle is fixed under canvas pan/zoom, uses one history group per completed gesture, and is excluded from export. Product code selects it through schema and must not import or render the visual gizmo directly.
+
 ## Curves
 
 Use `curves` for editable remapping curves. First decide the curve variant by product meaning; do not rely on the runtime default.
@@ -199,3 +235,5 @@ Use `core/setup-export.md` for mandatory runtime Setup, background, Image Export
 Use product editing handles only when direct manipulation is better than panel-only editing: gradient stops, focus points, light vectors, crop bounds, mask points, transforms, bezier anchors, or perspective corners.
 
 Handles are visual overlays, not app UI. They must be textless, tokenized, bound to runtime state, and excluded from export/copy output.
+
+Three-dimensional view rotation is the built-in Orientation Gizmo case. Use generic product handles only for geometry/value interactions the gizmo does not own.

package/templates/starter/docs/toolcraft/core/control-selection.md

@@ -28,6 +28,47 @@ Acceptance coverage:
 
 This inventory can be in implementation notes, `starterControlSectionInventory`, or `docs/toolcraft/agent-worklog.md`, but the decision must exist before custom UI is introduced.
 
+## Spatial View Intent Before Controls
+
+Before choosing a gizmo, Vector, camera controls, or renderer interaction, declare
+`starterProductReadiness.viewInteraction`:
+
+- `non-spatial`: no visible three-dimensional scene/model; include a concrete reason.
+- `orbit`: the default for a visible editable spatial scene; list every mutually exclusive `orientationGizmo` target.
+- `fixed-camera`: only when an explicit user request or inspected reference requires fixed framing; record source and evidence.
+- `timeline-camera`: only when an explicit user request or inspected reference owns an authored camera path driven by Toolcraft timeline intent.
+
+The absence of an explicit rotation request is not evidence for `fixed-camera`.
+Do not first make a 3D scene non-rotatable and then use that implementation
+choice to omit Orientation Gizmo. Renderer technology is not the classifier:
+WebGL, WebGPU, Canvas2D, and DOM/SVG may each render spatial or non-spatial
+output.
+
+## Interaction Surface Ownership
+
+Before implementing controls or canvas editing, declare
+`starterProductReadiness.interactionOwnership` for every operation that could
+plausibly live on either surface. Each entry records the runtime target,
+operation capability, selected `canvas` or `panel` surface, evidence, the
+selection reason, and why the other surface does not own the same operation.
+
+Choose from evidence in this order:
+
+- an explicit user request owns the location when it states one;
+- an inspected reference is direct evidence for the interaction it demonstrates;
+- otherwise compare spatial correspondence, feedback, precision, discoverability,
+  output clutter, accessibility, off-screen use, and collection/configuration needs.
+
+One user operation has one primary surface. Do not recreate a canvas drag,
+selection, spatial map, property edit, collection edit, or command in the panel
+with different chrome, and do not recreate a panel operation as canvas UI.
+
+Related state may expose genuinely different operations on both surfaces. A
+canvas can select or directly manipulate an entity while the panel edits any
+useful properties, modes, constraints, colors, collections, commands, or exact
+values. These are complementary only when their typed capabilities differ; a
+renamed copy of the same capability is still duplication.
+
 ## Exact Owners
 
 - Use `gradient` for adjustable gradients, color transitions, gradient fills, stops, type, and angle. Do not replace it with two `color` controls.
@@ -36,9 +77,12 @@ This inventory can be in implementation notes, `starterControlSectionInventory`,
 - Use `rangeSlider` or `rangeInput` for lower/upper bounds or from/to ranges.
 - Use `curves` for editable tone, response, easing, remapping, opacity, depth, mask, or channel curves.
 - Use `vector` only for stable manually-authored two-axis product parameters such as position, offset, direction, focus, anchor, light direction, white balance, color balance, chroma offset, or tone bias.
+- Use `orientationGizmo` whenever users can rotate a visible canvas model through 3D space, including a visually flat object presented with 3D rotation.
 - Use `fileDrop` for source material uploads.
 - Use `imagePicker` for choosing one visual option from a set.
 - Use `palette` only for constrained design-token color choices with both family and shade.
+- Use `tabs` for finite choices that replace the content or workflow view below the control; the runtime changes overflowing tabs to Select without changing the value.
+- Use `segmented` for compact finite mode settings that leave the surrounding view unchanged.
 - Use `actions` for local section commands that affect only the nearby entity.
 - Use `collectionActions` for repeatable product entities whose actual item list can grow or shrink.
 - Use `panelActions` for sticky final product actions such as export, copy, generate, apply, or download.
@@ -82,6 +126,27 @@ Before adding Vector to an animated or interactive product, classify movement ow
 
 Do not expose a pad for current animation state, keyboard movement, pointer movement, physics state, timeline phase, velocity, target pose, current pose, or simulated position/direction just because the internal value has `x` and `y`.
 
+Do not use Vector for camera orbit, object orbit, or a three-dimensional view orientation. Those interactions belong to Orientation Gizmo.
+
+## Orientation Gizmo Ownership
+
+Use schema `orientationGizmo` whenever a visible model can be rotated through three-dimensional space. This is the exact owner for both volumetric 3D models and visually flat planes/cards that expose a 3D orbit.
+
+For a visible editable spatial scene, `viewInteraction.mode: "orbit"` is the
+default and every `orientationTargets` entry must match a schema gizmo target.
+Fixed framing is not a default alternative; it is accepted only through the
+typed evidence-backed `fixed-camera` escape hatch.
+
+- Declare one shared pose target for the active model mode with `{ position: [x, y, z], up: [x, y, z] }`, `label: false`, and `keyframeable: false`.
+- At most one orientation gizmo may be visible at a time. Multiple declarations are valid only when their combined section/control visibility conditions are statically provable as mutually exclusive; runtime rejects ambiguous active states.
+- Keep the hidden control in the semantic section that owns the model or view so section/global reset owns its target; do not create an empty panel section only for the gizmo.
+- Product preview, geometry hit testing, gizmo drag, direct model drag, history/reset, image export, and video export all consume that same target.
+- Bind the rendered model with `useToolcraftModelOrbitInteraction` and supply a product-owned `hitTest` based on actual visible geometry.
+- Pointer ownership is decided on pointer-down: higher-priority product editing may claim first; a plain primary hit on the visible model rotates it; a miss remains untouched so `CanvasShell` pans. Modified primary and non-primary presses are not claimed by model orbit.
+- Gizmo drag, snap, and direct model orbit share target-scoped ownership. Starting newer work or writing reset/undo/redo to the target cancels stale in-flight interaction before it can overwrite current state.
+- The runtime gizmo stays fixed 16px from the canvas viewport's left and bottom edges, does not scale or move with canvas pan/zoom, and never appears in export.
+- Do not use Vector, paired angle sliders, segmented axis buttons, or custom canvas chrome as a substitute.
+
 ## Custom Control Gate
 
 - Custom controls are for product interactions that built-ins cannot represent.
@@ -91,3 +156,4 @@ Do not expose a pad for current animation state, keyboard movement, pointer move
 - Remove file names, helper text, and captions that do not help distinguish items or explain state.
 - Do not make tiny item-level action buttons below kit comfort sizes.
 - Do not recreate built-in controls, panels, toolbar, timeline, layers, canvas shell, or runtime surfaces.
+- A custom control with `custom-interaction` must reference its typed interaction owner. Its built-in fit check does not justify panel UI when the same operation is already owned by a canvas interaction.

package/templates/starter/docs/toolcraft/core/layout.md

@@ -36,7 +36,7 @@ Read this module before changing sections, labels, helper icons, inline rows, di
 
 ## Section Spacing
 
-- Runtime `Setup` and ordinary body sections use 8px top spacing and 24px bottom spacing for control content.
+- Runtime `Setup` uses 12px top spacing so its first control row has equal top, left, and right insets. Ordinary body sections keep 8px top spacing. Both use 24px bottom spacing.
 - Sticky footer action sections keep their dedicated spacing.
 - Do not add custom padding in generated apps to compensate for a local section issue. Fix the shared layout rule.
 
@@ -60,7 +60,7 @@ Read this module before changing sections, labels, helper icons, inline rows, di
 - Do not use descriptions that recap the label, such as `Adjusts Opacity`.
 - Do not add helper icons to obvious homogeneous groups when the section title and label already explain the control.
 - In toggle components, do not prefix labels with `Enable`; the switch already communicates on/off.
-- When a section title supplies the context, remove repeated nouns from nearby labels. For example, in `Background`, the switch label is `Include`, not `Include background`.
+- When a section title supplies the context, remove repeated nouns from nearby labels. Runtime Setup is the exception for its normalized output pair: the switch is `Background` and the color below it is `Background color`.
 
 ## Inline Rows
 
@@ -101,5 +101,7 @@ Read this module before changing sections, labels, helper icons, inline rows, di
 
 - Standalone `select` controls render stacked and full-width.
 - Use compact two-column select layout only for related short pairs that tune one workflow or entity.
-- Segmented controls are full-width compact choices with at most four options, no option label longer than nine characters, and no more than twenty-four total option-label characters.
+- Text segmented controls allow at most 4 options, no option label longer than 9 characters, and no more than 24 total option-label characters.
+- The static segmented option/label budget rejects over-budget schemas before render; there is no silent conversion to `select`.
+- Browser geometry verification remains required for actual font metrics, localization, zoom, and panel width.
 - If segmented cells clip, collide, lose padding, or force labels into adjacent cells, shorten labels first. If compact labels still fail, use `select`.

package/templates/starter/docs/toolcraft/core/media-upload.md

@@ -9,6 +9,7 @@ Read this module before changing image upload, file upload, source material impo
 - Do not build custom file lists, custom upload buttons, or custom sorting when `fileDrop` can represent the source set.
 - Use `assetKind: "image"` for image-only source uploads.
 - Use `assetKind: "file"` for arbitrary uploaded files.
+- Use `assetKind: "model"` for one 3D model package whose supported authored appearance should survive import.
 - Image mode accepts images only by default.
 - File mode accepts any file by default unless `accept` narrows extensions or MIME types.
 
@@ -43,6 +44,10 @@ Read this module before changing image upload, file upload, source material impo
 ## Multiple Uploads And Sorting
 
 - Use `multiple: true` when the app needs several uploaded images or files as one source set.
+- `recommendedMaxItems` is advisory and never rejects an import.
+- Use `hardMaxItems` only for a real product or technical boundary. It must be a finite nonnegative safe integer and is enforced as an upload admission limit.
+- Additive imports count existing assets for the same `sourceTarget` plus the incoming logical batch. Replacement imports count only the replacement batch. Assets for other targets do not consume this capacity, and deleting an item frees capacity.
+- A batch above `hardMaxItems` is rejected with typed resource-limit feedback before media decode, worker preparation, or binary repository allocation.
 - Multiple image uploads render as a sortable four-column thumbnail grid.
 - The add-more tile is last.
 - Per-image removal stays inside the file control.
@@ -61,6 +66,44 @@ Read this module before changing image upload, file upload, source material impo
   - file uploaders may accept images only when no image uploader matches.
 - Product renderers filter `state.mediaAssets` by `sourceTarget`.
 
+## 3D Model Uploads
+
+- A model `fileDrop` is a runtime-owned compound control. Product code declares the target, optional `modelFormats`, optional narrowed `modelLimits`, and `topologyProfile`; it does not build loaders, topology UI, repair buttons, workers, or a parallel model state.
+- Production formats are `glb`, `gltf`, `fbx`, `obj`, `stl`, and `ply`. The normalized default advertises every production format. Narrow the list only when product semantics require it; never advertise an adapter that is absent from the production worker registry.
+- Import consumes a standalone root, the complete selected folder `File[]` batch, or one bounded ZIP archive. ZIP extraction runs in the model worker with path, entry-count, byte, compression-ratio, encryption, and source limits. Remote resources and path traversal are never fetched.
+- Supported root paths are normalized and sorted; the first root is selected deterministically. Folder and equivalent ZIP inputs therefore resolve the same root and dependencies.
+- The model pipeline preserves static authored materials, PBR factors, supported textures/samplers, alpha/double-sided flags, vertex colors, and supported static transforms. Lights, cameras, animation clips, rigs, skins, morph animation, unsupported extensions, and remote resources do not become renderer authority.
+- If no authored material exists, preview and export use the Blender-compatible fallback: linear base color `[0.8, 0.8, 0.8]`, metallic `0`, roughness `0.5`, emissive `[0, 0, 0]`, opacity `1`. Missing appearance dependencies produce typed warnings and retain renderable geometry; they do not silently fabricate a texture.
+- One accepted package becomes one model item and one model layer. The original selected files or ZIP archive remain immutable durable source. Canonical geometry/appearance version 2, repair plans, decoded bitmaps, and Three/GPU resources are derived artifacts outside Toolcraft state, history, and localStorage; serializable state stores validated resource references and analysis summaries.
+
+### Analysis And Repair
+
+- Import decodes and structurally validates in the runtime module worker before topology analysis or canvas presentation.
+- Lifecycle is `clean`, `repairable`, `fixed`, `restoring`, or `unavailable`. Fatal input is rejected atomically and must not replace the last committed model.
+- Runtime shows `Fix model` only when it has already compiled a deterministic safe repair plan. The action uses the built-in actions control and its canonical button loader; duplicate repair is disabled while the worker runs.
+- Safe repair may remove invalid or duplicate triangles, compact unused vertices, regenerate normals, repair locally provable winding, and recalculate bounds. It must not weld, remesh, fill holes, smooth, merge shells, guess indices, or mutate authored transforms.
+- Appearance diagnostics never expose `Fix model`. Repair changes only canonical geometry/topology and reattaches the validated appearance references; it does not recolor, replace materials, invent textures, or rewrite the durable source package.
+- Repair commits only after the derived canonical document is structurally validated and topology is reanalyzed. Failure keeps the original committed model and exposes typed feedback.
+
+### Preview, Orientation, And Export
+
+- `ToolcraftAppComposition.modelPresentation` selects exactly one visible owner. `{ mode: "runtime" }` is the standard lazy Three preview/export path. `{ mode: "custom", consumers }` suppresses standard layers only for declared model targets and requires each checked consumer to acquire/release a runtime presentation lease.
+- `renderDefaultCanvasMedia={false}` hides generic image/file preview only. It does not hide standard runtime model layers.
+- A structurally valid staged draft may preview during analysis without replacing committed state.
+- Analyzing and repairing preview opacity is `40%`; committed preview and export opacity is `100%`.
+- Rotatable model products use `orientationGizmo`. Direct drag on model geometry and the gizmo write the same orientation target against the same presentation lease; a canvas miss remains viewport pan. Preview, undo/reset, and export read that shared pose, canonical document reference, and appearance cache key.
+- Product image export creates its normal target canvas, renders product-owned pixels, then awaits `renderModelsToCanvas(exportCanvas)` from `onPanelAction` before encoding or downloading. This composites visible committed model layers at the current canvas size, target pixel ratio, and shared orientation. Do not enumerate model assets or call Three loaders in product export code.
+- Video export must render the same visible models and shared pose through the runtime model binding for every exported frame; it cannot substitute the panel preview or omit model layers.
+
+### Persistence And Proof
+
+- Apps with image, file, or model media automatically resolve `"media"` into the default persistence plan. Serializable state and localStorage snapshots contain metadata plus durable resource references; binary bytes live in the Toolcraft IndexedDB repository and never enter runtime state, history, or snapshots as data URLs.
+- Image, file, and model records restore asynchronously through the shared source-asset coordinator. Missing, corrupt, forged, stale, or unavailable resources mark only the affected asset `unavailable` rather than publishing a partial migration, losing other persisted slices, or crashing.
+- Legacy data-URL snapshots migrate through a repository lease before a new snapshot is published. Failed migration preserves the original recoverable snapshot and reports persistence as unavailable.
+- Reset restores default model attachments through the same async import pipeline. Delete, replacement, undo, redo, reset, hydration, and active jobs participate in repository reachability and cleanup.
+- Model acceptance uses complete `modelImportCoverage` and protected browser recipes. Required proof covers every advertised format, package extraction, deterministic root selection, authored appearance, exact fallback, checked presentation readiness, nontransparent RGBA output, staged/committed output, repair diagnosis/action/progress/result, fatal preservation, persistence/unavailable restoration, preview/export parity, and history/reset.
+- Model workload and responsiveness checks derive from normalized model limits and run as targeted model paths. Package extraction and canonical decode are worker passes; presentation, orbit, export, and cleanup are main-thread/GPU passes with frame and completion budgets. The combined geometry-plus-texture envelope, cache reuse, and disposal lifecycle are measured without refreshing the full checkpoint during later functional feature work.
+
 ## Canvas Source Images
 
 - Uploaded background/source images inside product canvases use `editable-output`.
@@ -75,7 +118,7 @@ Read this module before changing image upload, file upload, source material impo
 - Use `media.defaultAssets` when an app starts with predefined files, source images, masks, symbol sets, or background images.
 - Each default asset sets `sourceTarget` to the matching `fileDrop` target.
 - Runtime treats these as attached files: users see them in the uploader, can remove them, and Reset restores them.
-- If removal, reorder, or transforms of predefined media should survive reload, add `"media"` to `persistence.include`.
+- Removal, reorder, and transforms of predefined media survive reload through the capability-derived `"media"` slice unless the whole app explicitly opts out with `{ storage: "none" }`.
 - Do not mirror the file list into product `values`.
 - Do not hard-code default source files inside `canvasContent` or the renderer.
 

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

@@ -1,86 +1,119 @@
 # Performance
 
-Read this module before changing renderer technique, animation, canvas, media, export, render scale, heavy controls, or performance tests.
+<!-- 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 -->
+
+Read this module before changing renderer technique, animation, canvas, media, export, render scale, workload controls, or performance tests.
+
+## Normative Sequence
+
+Use this order for every product:
+
+1. Reachable controls and inputs.
+2. Workload dimensions and enforced boundaries.
+3. Pass cost, frequency, lifecycle, and invalidation.
+4. Render-plan assessment and capture of any protected kernel benchmark requirement.
+5. Derived paths and combined fixtures.
+6. Targeted functional and browser development checks.
+7. Lifecycle-appropriate delivery proof: first-delivery functional proof with no measured performance, later `functional-targeted` proof, or one authority-backed targeted performance iteration. Full certification is a separate explicit operator/CI action.
+
+Do not begin renderer implementation before steps 1-4 are represented in typed configuration and the render-plan assessment has no structural errors. An unresolved kernel benchmark requirement remains explicit pending work; first and later functional delivery defer it without weakening envelope, pipeline, path, fixture, or adapter validation.
+
+## Envelope
+
+- Inventory every reachable schema control, runtime-state input, and external input.
+- Mark workload controls explicitly with `performanceRole: "workload"`; never infer workload from labels, target names, units, option text, or keywords.
+- Map every workload role to exactly one numeric `workloadEnvelope` dimension.
+- Each dimension declares a stable id, unit, source, mapping, `defaultValue`, and every applicable `interactiveMax` or `batchMax`.
+- `interactiveMax` and `batchMax` mean maximum workload for that profile, not the numerically largest value. A numeric `schema-target` source declares `workloadBoundary: "minimum" | "maximum"`; every declared profile boundary equals that selected schema endpoint. A lower endpoint is valid when smaller values create more work.
+- Declare only boundaries consumed by passes of that profile. A control may change a batch-only dimension without claiming an `interactiveMax` when interactive passes do not consume it.
+- Schema-backed limits equal schema limits. Other limits equal enforced runtime or input boundaries.
+- Slider and range controls use their effective numeric domain. Any other schema control is numeric only when it declares a complete finite `min`, `max`, and numeric `defaultValue`; partial, inverted, or out-of-range domains fail validation instead of being guessed from the control type.
+- The neutral starter declares `workloadEnvelope: { dimensions: [] }` and omits `fixtureAdapters`.
+
+## Render Plan
+
+Custom renderers declare `rendererPipeline.runtimeId`, passes, and exact interaction invalidation before renderer code. Every pass declares:
+
+- workload dimensions and cost relationship;
+- execution frequency;
+- lifecycle and resource scope;
+- execution location and output quality;
+- concrete inputs, invalidators, and cache keys where applicable.
+
+Include `initial-render` and every reachable interaction that executes or intentionally avoids renderer work. Run `assessToolcraftRenderPlan` and resolve every structural error. If it returns a benchmark requirement, keep that requirement pending during functional work and delivery. Declare `kernelBenchmarkDecisions`, implement only their executable candidates in `e2e/app-kernel-benchmarks.ts`, and run protected `pnpm verify:kernel` only inside an exact request-authorized performance iteration or explicit full audit. The protected runner measures the exact workload, verifies equal deterministic full-quality output, and records a current-source receipt; authored timing values are invalid. High-frequency variable-cost pixel-transform, rasterize, and composite passes compare a Canvas 2D baseline with WebGL, independent of the already-selected execution location; WebGPU joins the comparison only when it is the selected implementation.
+
+## Compiled Fixtures And Paths
+
+- Derive paths with `deriveToolcraftPerformancePaths`; never author path ids by hand.
+- Declare exactly one scenario for each canonical path. The scenario uses that path's `pathId` and exact `coversTargets`; do not create one scenario per equivalent control.
+- Equivalent controls share a path when interaction, invalidated passes, execution locations, workload dimensions, and profile are equal.
+- Register one `fixtureAdapters.dimensions` adapter per envelope dimension. Each adapter only applies and observes exact numeric values; envelope boundaries and central path profiles remain the sole sources of load and budget policy.
+- Finite inputs use an `exhaustive-discrete` entries domain that binds each numeric workload value to the product value actually applied. Schema `select` and `segmented` domains match all schema options one-to-one; other finite sources carry exhaustive provenance aligned with the dimension source.
+- A development checkpoint moves from each `defaultValue` toward its declared maximum-workload boundary, including numerically downward ranges. It is available only when the combined vector has exact normalized development pressure `0.8` within the runtime tolerance. For discrete dimensions every value must also belong to the exhaustive domain; otherwise development is unavailable. Maximum remains independently available and execution observes every applied value exactly. Inverse checkpoints use the same domain.
+- Discrete path search is deterministic and lazy. The runtime-owned `toolcraftDiscreteDimensionBudget` is 256 searched dimensions and `toolcraftDiscreteCombinationBudget` is 4096 combinations. Dimension overflow, cardinality overflow, or a path above either budget is an actionable planning error, not an unavailable exact vector. A valid exact inverse checkpoint for a custom or benchmark development path bypasses search budgets because no search runs, while its full vector still requires exhaustive-domain membership and exact normalized pressure `0.8` within tolerance.
+- Compile development and maximum vectors with `compileToolcraftPerformanceFixturePlan`.
+- Combined fixtures include every dimension on the path.
+- Add measured inverse full-vector evidence only when a dimension mapping is `custom` or a pass relationship is `benchmark`.
+- Performance profile names and budgets come from the runtime-owned profile manifest shared by runtime validation and generated runners. Product scenarios and copied scripts do not redefine those thresholds.
+
+Browser checks apply compiled values through the real UI, observe every dimension, exercise the real preview or export path, assert the product result, and then check the budget. Export scenarios keep exact `actionValue`, visible `controlLabel`, and `completionEvidence` proof.
 
 ## Verification Triggers
 
-Run a full performance checkpoint only when:
+Keep `src/app/app-verification-impact.json` complete: every product production module is `presentation`, `functional`, or `performance`, every owner names its nearest acceptance ids, and performance owners name their exact renderer pass ids. `performance` means the module can change a named pass's execution, invalidation, workload, resource lifecycle, or measured output. Shared modules name only the acceptance and pass coverage they can actually change; blanket every-module ownership is invalid. The protected delivery runner compares the inventory with the immediately previous successful delivery and requires ownership-derived functional proof for changed implementation. Performance ownership constrains which passes and paths an exact request may authorize; it does not authorize measurements by itself. A durable full-performance baseline, when one exists, remains historical evidence rather than the functional change anchor. Missing modules, stale paths, unknown acceptance or pass ids, and blanket ownership fail before a receipt can be written.
+
+Run targeted functional and browser checks during development. Only exact request authority can create a measured targeted performance iteration; a changed pipeline, workload boundary, adapter, interaction, measured output, owner, pass, path, filename, tier, or subsystem cannot. During an authorized iteration, the targeted Playwright reporter binds passed test names, pass ids, canonical path ids, nonce, and current source hash; product code and prose cannot mint that evidence.
+
+Functional performance coverage uses the runtime-owned deferred validation policy: all structural envelope, renderer pipeline, path, fixture, and adapter errors still fail, while unresolved kernel benchmark decisions remain visible as pending assessment requirements and require no kernel receipt. Strict/default validation and every authorized performance run continue to require the decision and protected current-source evidence.
+
+Targeted performance iteration verification requests the compiled development fixture at exact normalized pressure `0.8`. Each selected path must have its exact reachable development fixture or verification fails with a configuration error; it never falls back to maximum. The separate operator/CI certification command uses compiled maximum fixtures across the complete current matrix.
 
-- the first working product app version exists;
-- the user explicitly asks to optimize performance, fix lag, remove jank, speed up animation, stabilize drag/zoom, or otherwise complains about performance.
+The protected conversational lifecycle is automatic:
 
-After the first working version, feature loops do not run the full performance suite by default. Renderer, canvas, animation, export, timeline, layers, `canvas.renderScale`, bug fixes, and performance-sensitive controls still need targeted functional/browser checks first, plus targeted performance scenarios only when they directly exercise the touched workload, viewport, or export path.
+- **First product delivery:** bare `pnpm verify:delivery` runs complete product contracts, one production build, and full functional acceptance with no measured performance. It preserves any independent full-performance baseline and cannot claim targeted or full performance evidence.
+- **Later functional-targeted delivery:** the same bare command runs exact ownership-derived functional checks for the changed implementation. It preserves any existing baseline and cannot silently invoke measured performance.
+- **Performance complaint:** record only domain authority in the latest Decision Trail—an exact request quote and canonical affected path IDs—then one bare `pnpm verify:delivery` runs one targeted iteration against the reachable development fixture. The same authority cannot produce a second successful iteration. Deliver the verified app, then stop and wait for user evaluation. A later complaint creates a new Decision Trail authority and starts another bounded iteration from the immediately previous successful delivery.
 
-## Verification Tiers
+Request classification is tri-state. High-confidence performance language selects `performance-iteration`; high-confidence ordinary product work remains ordinary; ambiguous or unrecognized language becomes `needs-agent-judgment`, and the AI decides from the complete request. Local negation and product commands are interpreted in their own clause rather than through a global phrase list. Before a performance iteration, the worklog must contain a nontrivial exact raw substring of Request as evidence. Whitespace and Unicode code units must match exactly; invented, whitespace-collapsed, NFKC-equivalent, or otherwise mismatched text is rejected. Complaint wording, repetition, filename, diagnostic classification, and touched subsystem never launch the complete matrix automatically.
 
-- Tier 0-1: targeted docs/typecheck/unit plus focused browser when visual.
-- Tier 2: `pnpm verify:quick` plus relevant browser acceptance.
-- Tier 3: `pnpm verify:quick`, targeted browser acceptance, and targeted performance scenarios for touched workload/viewport/export paths.
-- Tier 4: for the first working product version, run and receipt the browser performance checkpoint first, then run `pnpm verify:final` against the current receipt.
+Every protected targeted performance report stores the independently validated `cold`, `warm`, and `sustained` numeric observations for each selected canonical path. When the immediately previous successful delivery contains compatible targeted measurements, the next complaint records metric deltas against that report; otherwise it records an explicit non-comparable result. Deltas are diagnostic evidence, not a noisy strict-improvement gate: the current iteration must pass its absolute profile budgets, then return to the user without launching another optimization pass.
 
-Record skipped full performance runs and reason in the verification note or worklog.
+The preferred conversational delivery boundary is `pnpm verify:delivery`. A targeted failure starts targeted diagnosis and architecture repair; it does not automatically expand into the full suite. After the selected evidence passes, return the app to the user instead of continuing speculative optimization. When two consecutive compatible protected performance iterations have passed, the runner emits an evidence-backed recommendation and the agent must offer the user a slower complete audit if performance remains unacceptable. A demonstrably broad or unlocalizable cross-system problem may justify the same offer earlier through agent judgment; a path-count threshold is not authority.
 
-## Workload Fixtures
+`pnpm verify:perf` is the single protected operator/CI full-audit command: it performs one fresh production build, runs maximum fixtures across every canonical path, writes `full-performance` evidence, and creates or refreshes the durable baseline without advancing the delivery anchor. It runs only after an explicit natural-language request for the complete audit or explicit acceptance of the agent's offer; the user does not need to know the command name. A complaint, repeated complaint, filename, diagnostic classification, or changed subsystem alone never authorizes it. The full audit is diagnostic and certification evidence, not an automatic optimization loop: repair failed paths with focused checks, then run the complete matrix once at the requested certification boundary.
 
-- Performance scenarios declare `stressFixture` for the tested control value.
-- `export-copy` scenarios declare the exact `panelActions` `actionValue`, visible `controlLabel`, and `completionEvidence` (`download` or `clipboard`). Their browser test uses the matching protected output-action helper with `scenarioId`; the helper owns the click and real download/clipboard completion. The signed reporter rejects missing completion evidence, skipped/failed tests, and evidence from failed retries.
-- Browser perf tests apply scalar values with `applyToolcraftPerformanceStressValue` / `applyToolcraftPerformanceWorkloadValue` and object fixtures with `applyToolcraftPerformanceStressFixture` / `applyToolcraftPerformanceWorkloadFixture`. Every fixture mapping supplies `applyValue` plus `observeValue`; evidence attaches only after the observed UI/runtime value exactly matches the declared fixture.
-- Mutating measurements pass a structured-cloneable `observeOutcome`. Generic change evidence first proves that its baseline stays stable before the action, timestamps the first live changed response, then requires the final post-action outcome to remain changed through the stability window. Autonomous or animated output uses `expectedOutcome` with a stable semantic observation, or the test fixes playback to a deterministic phase; an incidental next frame cannot satisfy the interaction. The immutable result stays bound to the same `scenarioId` as its budget. `durationMs` uses a runner monotonic clock from interaction start to the first changed or expected response; required frame sampling survives document navigation, and settle/stability checks still finish before evidence is emitted without replacing product-response latency with action completion or inflating it with the post-change window. Non-mutating measurements end at action completion.
-- When the tested control is not itself the whole heavy source, declare `workloadFixture` and apply it first.
-- Numeric control ranges and hard limits come from schema; scenarios may omit duplicated `values`, and any supplied values must match schema exactly. A bounded numeric control cannot switch to `metric: "custom"` to avoid its min/max.
-- Numeric maximums, density, item counts, canvas/media size, and combined heavy states declare `loadProfile` with `hardLimit`, `smoothTarget`, and `smoothTargetRatio`. `many-items` applies at least 10 real items; lowering an authored `minCount` is not evidence.
-- Try the hard limit first.
-- Lower the guaranteed smooth target only in 10 percent steps with failed-measurement and optimization evidence. Every entry names the exact `attemptedRatio`, schema-reachable `attemptedTarget`, scenario id, and target for that step.
-- Ranges above `smoothTarget` are experimental, not silently guaranteed.
+`TOOLCRAFT_PERFORMANCE_VERIFICATION_LIFECYCLE` is runtime-owned: protected Playwright owns functional, performance-iteration, and operator full-certification receipts. Product config cannot override this lifecycle.
 
-## Media And Pixel Workloads
+Completion wording must name the evidence level. Functional delivery reports functional proof only and states that measured performance was not run. A performance iteration reports only its exact targeted proof and asks the user to evaluate the verified app. After the second consecutive compatible iteration it also offers the slower complete audit without launching it. Never describe targeted iteration evidence as a complete audit, baseline, maximum-workload proof, or full certification. Only the separate explicitly authorized operator command may report certification after `full-performance` evidence and its durable baseline pass.
 
-- Media import and image-processing workloads use realistic `kind: "media"` fixtures at least `1920x1080`-equivalent.
-- Heavy upload/preview tests must cover realistic source dimensions such as 2K/4K when the app accepts images.
-- Heavy pixel/media Canvas 2D must evaluate WebGL or WebGPU with measured evidence before staying on CPU.
-- Do not stay on CPU for millions of per-pixel operations on the main thread unless measurement proves it remains responsive and alternatives were evaluated.
+## Render Scale And Quality
 
-## Render Scale
+Render Scale preserves selected backing resolution and visible quality. A raster product with `canvas.renderScale` declares typed `renderScaleCoverage: { kind: "selected-backing-pixels", states }` on one browser runtime row targeting `canvas.renderScale`. Exact sorted states are `["interaction", "steady"]`, plus `"playback"` when timeline is enabled.
 
-- Non-vector raster, Canvas 2D, WebGL, and WebGPU previews set `canvas.renderScale: true`.
-- Runtime `Resolution scale` defaults to `2` and changes backing pixels without changing CSS/output size.
-- Performance fixes must preserve selected render scale and visible output quality.
-- Do not downsample, blur, stretch low-resolution backing pixels, or clamp render scale below the user's chosen value to pass budgets.
+The product browser scenario supplies real state transitions to `expectToolcraftCanvasRenderScaleEvidence`. The protected helper keeps CSS size stable, checks actual canvas backing pixels against `css size × devicePixelRatio × selected scale` in every state, and only then emits `canvas-render-scale-backing` for each `<acceptance-id>#<state>`. A clamp or downsample is a functional failure without measured performance. In an explicitly authorized render-scale performance path, `performance-render-scale` may be emitted only after the same real backing assertion passes.
+
+Do not pass budgets by silently reducing selected quality, backing resolution, product range, source fidelity, export fidelity, or live interaction semantics. Diagnose pass cost, invalidation, cache lifetime, scheduling, and execution location first.
 
 ## Slider Responsiveness
 
-- Slider and range slider controls are live canvas controls.
-- Dragging a thumb updates runtime state and product output while the drag is in progress.
-- If live updates are slow, fix renderer path first:
-  - update uniforms or stable buffers;
-  - cache decoded media and expensive derived inputs;
-  - coalesce preview work to `requestAnimationFrame`;
-  - cancel stale async renders;
-  - move heavy work off React renders;
-  - change renderer strategy when measured evidence supports it.
-- Only at an extreme measured ceiling may the app use degraded live preview or delayed heavy refinement; even then, immediate canvas feedback is required.
-
-## Renderer Pipeline Inventory
-
-Custom renderer apps declare a typed `rendererPipeline`:
-
-- render passes;
-- cache keys;
-- execution location;
-- preview/export quality;
-- interaction invalidation;
-- control-to-pass mapping.
-
-Every performance-sensitive control maps to the pass it invalidates.
-
-## Optimization Evidence
-
-Optimization worklogs record:
-
-- bottleneck diagnosis;
-- renderer technique evaluated;
-- fixtures used;
-- measurements before and after;
-- rejected alternatives;
-- remaining risks;
-- why quality was preserved.
+Slider Responsiveness means the real product response remains live through the gesture. Model the slider's reachable interaction and invalidated passes, then measure its derived path; a label, target name, or control kind never classifies workload by itself.
+
+Source lifecycle guards remain mandatory: resources are created outside React render, retained according to the declared lifecycle, reused across unrelated interactions, and released during cleanup. Animation frames are cancelled during cleanup, and timeline-only updates do not recreate source-bound resources.
+
+## Non-Normative Examples
+
+These examples illustrate the model; they do not define product categories or minimum fixture sizes:
+
+- An export selector can adapt an option value to a numeric output-width dimension.
+- A collection editor can adapt runtime items to a numeric item-count dimension.
+- A source importer can expose numeric source dimensions as external-input dimensions.
+
+Choose dimensions from the real product cost model and enforced boundaries, not from these examples.
+
+## Model Appearance Paths
+
+Model `fileDrop` performance proof names six affected passes: `package-extraction`, `canonical-decode`, `model-presentation`, `canvas-orbit`, `export`, and `resource-cleanup`. Extraction and canonical decode execute in the worker; presentation, orbit, export, and cleanup execute on the main thread/GPU boundary.
+
+Use fixtures for authored textures/materials, vertex colors, fallback-only models, equivalent folder/ZIP packages, missing dependencies, multiple roots, and hostile archives. Derive a combined geometry-plus-texture envelope from normalized `modelLimits`; source bytes alone are insufficient because decoded RGBA pixels and GPU resources coexist with canonical geometry. Measure visible completion and frame gaps, cache reuse across preview/export or replacement, and zero active presentation leases after remove/reset/failure/unmount. Do not pass by dropping textures, changing the selected root, replacing authored appearance with fallback, or rendering only metadata.