@pixel-point/toolcraft 0.0.15 → 0.0.16

package/templates/starter/docs/toolcraft/core/runtime-boundary.md

@@ -18,9 +18,11 @@ Use only these app-specific extension points. Shared runtime changes happen upst
 - schema controls;
 - schema `canvas`, `panels`, `toolbar`, `panelActions`, `persistence`, `media`, `assembly`, and transfer-mode metadata;
 - `canvasContent` for product output only;
-- `renderDefaultCanvasMedia={false}` only when a product renderer replaces the default media preview;
+- `renderDefaultCanvasMedia={false}` only when a product renderer replaces generic image/file preview; it does not suppress runtime model layers;
+- typed `modelPresentation`, with `{ mode: "runtime" }` as the default standard preview/export owner or `{ mode: "custom", consumers }` for declared model targets with checked consumers;
 - `controlRenderers` only for true custom controls that pass the built-in fit check;
 - `onPanelAction` for sticky product actions;
+- optional `rendererPipelineRegistration` for one compiled executable custom-renderer pipeline shared by product work, runtime evidence, and performance assessment;
 - runtime commands and hooks.
 
 ## Forbidden Rebuilds
@@ -39,12 +41,22 @@ Use only these app-specific extension points. Shared runtime changes happen upst
 - Product editing handles must be textless overlays, write to runtime state, and stay out of export/copy output.
 - Preserve the runtime canvas backing. Product renderers may draw their own product background, but must not hide, replace, or make the Toolcraft canvas shell/backing transparent.
 
+## Model Presentation Boundary
+
+- Runtime presentation is the default and owns model preview, hit testing, appearance resources, export composition, and cleanup.
+- `renderDefaultCanvasMedia={false}` controls only generic image/file media. It never hides a standard runtime model layer.
+- Custom model presentation is explicit: set `modelPresentation.mode` to `"custom"`, declare one unique consumer id per model `sourceTarget`, and include the matching visible `orientationGizmo` target when the model orbits.
+- A custom canvas consumer calls `useToolcraftModelPresentationConsumer(declaration)` and acquires/releases presentation leases. It does not decode source formats, call `resolveDocument` to build a second Three cache, or reconstruct materials.
+- Runtime reports typed retryable feedback when a declared consumer is missing or cannot acquire the presentation. Successful acquisition clears that feedback without deleting the committed model.
+
 ## State Boundary
 
 - Bind every visible control to runtime schema state or a runtime command side effect.
 - Use `defaultValue` for resettable controls.
 - Use runtime commands such as `controls.reset`, `controls.resetTargets`, `media.import`, `media.delete`, `canvas.center`, `history.undo`, and `history.redo`.
 - Do not keep final product settings in isolated local React state when they need reset, persistence, import/export, keyframes, browser acceptance, or product export.
+- Runtime workspace persistence is enabled by default and owned by `ToolcraftRoot`: values, canvas, and panels are the base slices, with enabled timeline, layers, and media added automatically. Product code does not call localStorage or IndexedDB directly.
+- localStorage is the versioned metadata boundary. Binary media bytes belong to the Toolcraft IndexedDB repository; state, history, settings JSON, and snapshots carry typed resource references instead of durable data URLs.
 
 ## Generated App Source Boundary
 
@@ -56,5 +68,5 @@ Use only these app-specific extension points. Shared runtime changes happen upst
 - Product production modules must form an acyclic dependency graph. The code-health gate resolves relative imports, directory `index.*` modules, configured TypeScript path aliases, and local package exports. Type-only imports, external packages, tests, and copied Toolcraft framework internals do not create product dependency edges. When a cycle exists, the gate prints the complete shortest cycle so the ownership boundary can be corrected directly.
 - Imported product source remains under `src`. Code health and product-boundary analysis consume the same canonical source-inventory semantics instead of maintaining independent recursive walkers. The signed Vitest reporter uses the canonical framework-ownership policy to distinguish product-owned runner results, while acceptance and performance requirements derive from typed app configuration.
 - Do not edit `src/toolcraft` in a generated app. It is an immutable signed copy of the shared runtime. Fix the monorepo runtime and regenerate the app.
-- Generated integrity protects the copied runtime, signed host/bootstrap, framework validators/tests, `AGENTS.md`, local contract docs under `docs/toolcraft`, `LICENSE.md`, `NOTICE.md`, TypeScript/Vite/Vitest/Playwright root configuration, and the commands of the original package scripts. Alternate root config files in those verification families are rejected instead of silently creating a second test path. `docs/toolcraft/agent-worklog.md` is the explicit editable documentation exception; every other file added under `docs/toolcraft` is rejected as unrecorded contract input. Product dependencies, unrelated product scripts, product source, and the worklog remain editable, but all product production modules are AST-checked for host-surface and built-in-control bypasses. Added `pre*` or `post*` lifecycle hooks for a protected script are rejected because they can execute across a verification boundary. Run the checker directly before the final gate; `pnpm test` must fail when any protected file changes, or when the copied runtime tree or its signed integrity manifest is missing, changed, or contains unrecorded source.
+- Generated integrity protects the copied runtime, signed host/bootstrap, framework validators/tests, `AGENTS.md`, local contract docs under `docs/toolcraft`, `LICENSE.md`, `NOTICE.md`, TypeScript/Vite/Vitest/Playwright root configuration, and the commands of the original package scripts. Alternate root config files in those verification families are rejected instead of silently creating a second test path. `docs/toolcraft/agent-worklog.md` is the required editable product worklog, and `docs/toolcraft/workflow-observation.md` is the optional editable post-delivery observation; every other file added under `docs/toolcraft` is rejected as unrecorded contract input. Product dependencies, unrelated product scripts, product source, the worklog, and the observation remain editable, but all product production modules are AST-checked for host-surface and built-in-control bypasses. The worklog stays inside verification inputs, while the post-delivery observation stays outside `sourceHash` so recording results cannot stale a successful receipt. Added `pre*` or `post*` lifecycle hooks for a protected script are rejected because they can execute across a verification boundary. Run the checker directly before the final gate; `pnpm test` must fail when any protected file changes, or when the copied runtime tree or its signed integrity manifest is missing, changed, or contains unrecorded source.
 - Generated apps must not contain monorepo app/package folders, workspace-protocol dependencies, or workspace package imports.

package/templates/starter/docs/toolcraft/core/setup-export.md

@@ -10,8 +10,13 @@ Read this module before changing Setup, canvas sizing, background, image export,
 - Do not implement settings import/export through `panelActions`, route-local file inputs, or app-authored controls.
 - Do not gate settings import/export by app complexity.
 - Product-output, exportable, shader, procedural, reference-clone, and uploaded-background/source apps use `editable-output`.
-- With `editable-output`, Setup contains `Aspect ratio`, `Canvas width`, and `Canvas height` after settings transfer.
-- App-authored sections must not declare runtime Setup targets: `runtime.settingsTransfer`, `canvas.aspectRatio`, `canvas.size.width`, `canvas.size.height`, `canvas.renderScale`, or `panels.timeline.extended`.
+- Product apps declare the standard background state pair in one authored `Background` source section. Runtime removes that visible section and places a `Background` switch beside `Infinity canvas` immediately after settings transfer, with Background first.
+- Runtime places `Background color` below that row, before finite canvas sizing.
+- When the standard Background pair exists, `Infinity canvas` is available only while Background is on. Turning Background off exits infinite mode; turning it back on restores availability without enabling Infinity automatically.
+- Finite `Aspect ratio`, `Canvas width`, and `Canvas height` follow Color; optional `Resolution scale` follows sizing.
+- When enabled, `Timeline` is the final Setup control.
+- Timeline and Infinity canvas are self-explanatory runtime switches and do not render help icons.
+- App-authored sections must not declare runtime Setup targets: `runtime.settingsTransfer`, `canvas.infinity`, `canvas.aspectRatio`, `canvas.size.width`, `canvas.size.height`, `canvas.renderScale`, or `panels.timeline.extended`.
 
 ## Canvas Size Defaults
 
@@ -21,17 +26,34 @@ Read this module before changing Setup, canvas sizing, background, image export,
 - Fixed/reference/base dimensions are not reasons to hide `Aspect ratio`, `Canvas width`, or `Canvas height`.
 - Manual Canvas width/height edits keep the typed dimension, keep the other dimension unchanged, switch Aspect ratio to Custom, and show the reduced current ratio in the custom ratio inputs.
 
+## Infinity Canvas
+
+- `Infinity canvas` is the one runtime-owned mode switch for an unbounded workspace. Product code does not mirror it in `state.values` or create another canvas-mode control.
+- Turning it on removes the finite artboard boundary and clipping. `Aspect ratio`, `Canvas width`, and `Canvas height` disappear because they do not constrain the workspace.
+- Infinity canvas suppresses the bounded product-rendered preview background so the dormant finite output does not appear as a second canvas. While Background is on, `CanvasShell` fills the complete infinite viewport with the selected `Background color`; product code must not draw a synthetic workspace rectangle.
+- The last finite `canvas.size` remains dormant and immutable while Infinity canvas is on. Turning it off restores that exact size and centers the finite artboard; reset, undo/redo, persistence, and settings transfer preserve the same canonical `canvas.mode` behavior. Fixed proof compares exact artboard pixels and width/height control values before Infinity, after restoration, and after redo.
+- Runtime image and model assets keep explicit center-anchored world frames. Zoom, pan, radar, and model orientation change presentation, not scene geometry or export bounds.
+- Product `canvasContent` and custom renderer output declare one direct `ToolcraftAppComposition.sceneBoundsProvider`. It returns product world-space rectangles and receives `{ state, timeRange? }`; do not use a registry or DOM measurement.
+- Infinite PNG export crops to the outward-rounded union of visible product, image, and model frames. Hidden or unavailable layers, runtime media suppressed by the composition, and editor-only handles or gizmos are excluded.
+- Prove unavailable-image exclusion with `createToolcraftUnavailableImageResourceFixture` and `expectToolcraftInfinityCanvasUnavailableImageExportEvidence`; product tests never mutate storage/state or call the reserved bridge, and evidence publishes only after deterministic cleanup restores the ready resource.
+- Infinite video export resolves one bounds envelope for the requested `timeRange` and uses it for every frame, preventing frame-to-frame output size changes.
+- Finite-mode export remains the full finite canvas and does not call the product bounds provider.
+- Empty scenes, missing/invalid product bounds, and artifacts above `8192px` per edge or `67,108,864` pixels fail before canvas allocation with visible typed feedback: `empty-scene`, `scene-bounds-unavailable`, or `scene-export-too-large`.
+
 ## Resolution Scale
 
 - Non-vector raster, Canvas 2D, WebGL, and WebGPU previews set `canvas.renderScale: true`.
 - Runtime then appends `Resolution scale` after canvas sizing.
 - `Resolution scale` changes backing pixels from `1` to `2` without changing visible CSS size or product output dimensions.
+- The product acceptance matrix adds exactly one browser runtime row targeting `canvas.renderScale` with `renderScaleCoverage: { kind: "selected-backing-pixels", states: ["interaction", "steady"] }`; insert `"playback"` in sorted order when timeline is enabled.
+- The product browser scenario uses `expectToolcraftCanvasRenderScaleEvidence` for every declared state. Only after CSS size remains stable and actual backing dimensions honor `css size × devicePixelRatio × selected scale` does the protected reporter emit `canvas-render-scale-backing`.
+- Any quality clamp or lower-resolution stretch is a functional failure without measured performance.
 - DOM/SVG/vector-native previews should not use render scale.
 - Performance fixes must preserve the user's selected render scale. Do not pass budgets by silently downsampling, stretching a lower-resolution backing canvas, blurring output, or clamping render scale below the chosen value.
 
 ## Timeline Setup Switch
 
-- When `panels.timeline` is enabled, runtime appends a `Timeline` switch as the last Setup control.
+- When `panels.timeline` is enabled, runtime adds the `Timeline` mode switch to Setup.
 - Off shows compact Play-only transport.
 - On shows the extended timeline with scrubber, duration, loop, and keyframe UI.
 - The switch controls runtime presentation only. It does not pause playback, change product values, remove keyframes, alter export, or reset with `Reset controls`.
@@ -39,15 +61,17 @@ Read this module before changing Setup, canvas sizing, background, image export,
 
 ## Background
 
-- Every product app exposes a required `Background` section directly before the first export settings section.
-- The section contains one equal-width inline row:
-  - `export.includeBackground` as a switch labeled `Include`;
-  - the product background color control with `label: false`.
+- Every product app declares one authored `Background` source section containing:
+  - `export.includeBackground` as a switch;
+  - the product background color control.
+- Runtime consumes that pair into Setup, labels the switch `Background`, places it left of `Infinity canvas` in an equal-width row, and labels the full-width color below it `Background color`.
+- Background is a prerequisite for Infinity canvas. Disabling it atomically restores finite mode and disables Infinity; re-enabling it does not change the current finite mode.
+- A separate visible Background section is stale layout and fails acceptance.
 - Use a schema `color` target such as `appearance.background` or `scene.background`.
 - Do not hardcode a configurable background in CSS, Canvas `fillStyle`, or WebGL clear color.
-- Live preview calls `shouldIncludeToolcraftPreviewBackground(state)` and hides only the product-rendered background when Include is off.
-- PNG export passes the Include value to the standard PNG export helper.
-- Video export keeps the background even when Include is off.
+- Live preview calls `shouldIncludeToolcraftPreviewBackground(state)` and hides only the bounded product-rendered background when Background is off or Infinity canvas is on. In Infinity mode, the runtime viewport—not the product renderer—uses the selected Background color.
+- PNG export passes the Background value to the standard PNG export helper.
+- Video export keeps the background even when Background is off.
 
 ## Image Export
 
@@ -56,15 +80,15 @@ Read this module before changing Setup, canvas sizing, background, image export,
   - `export.image.format`, default `png`, with baseline `PNG` and `JPG` options;
   - `export.image.resolution`, default `4k`, with baseline `2K`, `4K`, and `8K` options.
 - Still-output apps place `Image Export` directly above sticky footer actions.
-- Animated apps with both image and video export place `Image Export` immediately before `Video Export`.
-- PNG export calls `createToolcraftPngExportCanvas({ includeBackground, resolution, state, render })`.
+- Apps with both image and video export place `Image Export` immediately before `Video Export`.
+- PNG export resolves the concrete scene frame through the panel action context, then calls `createToolcraftPngExportCanvas({ frame, includeBackground, resolution, state, render })` and `renderRuntimeSceneToCanvas(canvas, frame)` before drawing product pixels.
 - The selected `export.image.resolution` must produce real 2048/4096/8192px long-edge PNG output for 2K/4K/8K. Retina sizing is only the fallback for current/omitted resolution.
 
 ## Video Export
 
-- Animated product apps expose `Export Video` and `Export PNG`.
+- Product apps whose requested delivery includes animation expose `Export Video` and `Export PNG`; timeline playback alone does not require video delivery.
 - Any app with `Export Video` must enable the top Toolcraft timeline.
-- Animated apps expose a separate `Video Export` section directly above sticky footer export buttons, after `Image Export`.
+- Apps with `Export Video` expose a separate `Video Export` section directly above sticky footer export buttons, after `Image Export`.
 - `Video Export` uses two `select` controls in one compact two-column inline row by default:
   - `export.video.format`, default `mp4`, with baseline `MP4` and `WebM` options;
   - `export.video.resolution`, default `current`, with baseline `Current` and `4K` options.
@@ -78,8 +102,8 @@ Read this module before changing Setup, canvas sizing, background, image export,
 ## Sticky Product Actions
 
 - Product apps always expose export in sticky `panelActions`.
-- Still products expose `Export PNG`.
-- Animated products expose `Export Video` plus `Export PNG`.
+- Every product exposes `Export PNG`.
+- Products whose requested delivery includes animation also expose `Export Video`.
 - Clipboard copy is optional and never replaces export.
 - Export PNG and Export Video use `icon: "upload-simple"` to match the runtime `Export Settings` action.
 - Async export/download/copy/generate/apply handlers return the real Promise from `onPanelAction`. The runtime shows the sticky footer top accent indicator while the Promise is pending.

package/templates/starter/docs/toolcraft/core/timeline-animation.md

@@ -23,7 +23,8 @@ Use no timeline only when the motion is explicitly autonomous decoration with no
 
 ## Compact And Extended Timeline
 
-- When `panels.timeline` is enabled, runtime Setup appends a `Timeline` switch.
+- Setup places the standard Background switch beside Infinity canvas immediately after settings transfer, then Background color and finite sizing. Timeline is the final Setup control.
+- Timeline and Infinity canvas are self-explanatory runtime mode switches and do not render help icons.
 - Off shows compact Play-only transport.
 - On shows the extended timeline with scrubber, duration, loop, and keyframe UI.
 - The switch is runtime UI state only. It does not pause playback, change keyframes, alter export, write product values, or reset with `Reset controls`.

package/templates/starter/docs/toolcraft/custom-controls.md

@@ -81,4 +81,10 @@ Choose element sizes from interaction need, not from how much content you want t
 
 When a custom list item needs context, prefer concise semantic labels such as `Darkest`, `Mid tone`, or `Lightest`. Omit file names, long captions, and duplicate helper text unless they are required to distinguish items.
 
-If a custom control is really direct manipulation of the product output, prefer a product editing handle in `canvasContent` plus a schema-backed target.
+### Bounded Image And Thumbnail Lists
+
+When an image or thumbnail grid has its own bounded scroll viewport inside the controls panel, render that viewport through `ScrollFade` with `scrollBoundaryBehavior="chain"`. The grid scrolls internally first; at its top or bottom boundary, native wheel and trackpad momentum continues through the owning controls panel.
+
+This rule is independent of thumbnail dimensions, source-image aspect ratio, column count, fade preset, and viewport height. Keep the default contained behavior for independent selects, font lists, popovers, timeline lists, and other scroll surfaces that must not move the parent panel. Do not inspect descendants for `<img>` elements and do not forward wheel events manually.
+
+Before choosing a custom interaction, declare its typed `interactionOwnership` and compare both surfaces. User request, inspected reference, or product usability selects one primary owner. A custom panel control must not mirror a canvas operation, and a canvas handle must not mirror a panel operation. Different operations may remain complementary: direct manipulation or selection on canvas can coexist with any useful property, mode, constraint, collection, command, or exact-value editing in the panel.

package/templates/starter/docs/toolcraft/decision-contract.md

@@ -21,12 +21,12 @@ Use this before writing a schema, spec, or implementation plan. It separates har
 | Panels | Mixed | Panel mechanics are hard; panel presence is product-dependent |
 | Layers | Heuristic, then invariant | Enable only for real layer behavior; fully test when enabled |
 | Timeline | Heuristic, then invariant | Choose from Animation Intent Inventory and transport behavior |
-| Controls | Mixed | Bind every visible control and prove product output behavior |
-| Renderer | Default with escape hatches | Choose technique from fidelity, reference behavior, and workload |
+| Controls | Mixed | Bind every visible control, choose one evidence-backed surface per operation, and prove product output behavior |
+| Renderer | Default plus invariant | Choose technique from fidelity/workload and declare spatial view interaction before renderer code |
 | Reference analysis | Invariant | Study video references as frame-to-frame behavior before implementation |
 | Reference clone | Invariant | Preserve reference behavior unless redesign is explicit |
 | Acceptance | Invariant | Prove product observables, not only runtime mutation |
-| Performance | Mixed | Workload controls need workload budgets; ordinary controls need responsiveness coverage; animated previews yield to viewport interactions |
+| Performance | Mixed | Workload controls need enforced envelope boundaries; derived paths receive central profiles; animated previews yield to viewport interactions |
 | Persistence | Default, then invariant | State persistence must be explicit; localStorage apps must prove reload restoration |
 | Workflow | Invariant | Follow signed local workflow, use available skills, and run browser verification |
 
@@ -42,7 +42,9 @@ This catalog mirrors `TOOLCRAFT_DECISION_CONTRACT`. If runtime adds or renames a
 | `runtime-shell-required` | invariant | runtime-shell |
 | `canvas-no-app-ui` | invariant | canvas |
 | `canvas-surface-preserved` | invariant | canvas |
+| `infinity-canvas-scene-bounds` | invariant | canvas |
 | `canvas-handle-placement` | heuristic | canvas |
+| `interaction-surface-ownership` | invariant | controls |
 | `panel-host-behavior` | invariant | panels |
 | `layers-enable-only-when-needed` | heuristic | layers |
 | `layers-enabled-behavior` | invariant | layers |
@@ -54,6 +56,8 @@ This catalog mirrors `TOOLCRAFT_DECISION_CONTRACT`. If runtime adds or renames a
 | `controls-component-layout-invariants` | invariant | controls |
 | `controls-layout-heuristics` | heuristic | controls |
 | `renderer-technique-inventory` | default | renderer |
+| `renderer-view-interaction` | invariant | renderer |
+| `model-appearance-presentation` | invariant | renderer |
 | `reference-clone-source-of-truth` | invariant | reference-clone |
 | `video-reference-analysis` | invariant | reference-analysis |
 | `acceptance-product-observable` | invariant | acceptance |
@@ -71,7 +75,7 @@ Hard rules belong in validators and browser gates, not only prose. Heuristics ne
 | Runtime behavior | Mechanics owned by the shared runtime |
 | Schema normalization | Repeated layout and density decisions |
 | Acceptance validator | Product behavior and control coverage |
-| Performance validator | Workload and responsiveness budgets |
+| Performance validator | Workload envelopes, canonical paths, and central profiles |
 | Browser helper | Real UI interaction and visual breakage |
 | CLI integrity check | Generated-app source boundaries |
 | Local docs and `AGENTS.md` | Decision criteria and workflow instructions |