@pixel-point/toolcraft 0.0.15 → 0.0.17

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,36 @@ 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 for the supplied exact frame state; do not use a registry, DOM measurement, or app-authored time-range envelope.
+- 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 asks the provider for every state in the runtime-owned frame schedule, unions those bounds once, and uses the result for every encoded 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`.
+- Non-vector raster, Canvas 2D, WebGL, and WebGPU previews author `canvas.renderScale` as `true` or `{ step }`. For this control, product code may customize only the slider step; it cannot author `enabled`, `min`, `defaultValue`, or `max`.
+- Runtime resolves the enabled slider to canonical `min: 1`, `defaultValue: 2`, and `max: 2`; the default step is `0.25`.
+- A custom step must be finite, between `0.01` and `1`, and evenly partition the canonical `1..2` range so the `2` maximum remains reachable. Invalid or non-partitioning steps fail schema resolution instead of being clamped.
 - 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 equal `css size × devicePixelRatio × selected scale` within the one-physical-pixel tolerance 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 +63,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.
+- Runtime image export reads Background directly: PNG can be transparent, while JPG remains opaque.
+- Runtime video export keeps the selected background even when Background is off.
 
 ## Image Export
 
@@ -56,31 +82,33 @@ 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`.
+- Typed `export-image` actions are handled by the runtime. It resolves the current scene frame, selected format and resolution, allocates the exact backing, composites background plus visible runtime media/models, awaits `ToolcraftAppComposition.exportRenderer`, encodes the selected artifact, downloads it, and reports typed progress/failures.
+- Product code supplies only the shared deterministic `exportRenderer.renderFrame` callback in scene coordinates. It must not allocate an export canvas, call `toBlob`/`toDataURL`, create object URLs, or download the artifact.
 - 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.
 - Stack the pair only when labels or selected values would clip, and record that fit reason in the worklog.
-- Use `MediaRecorder.isTypeSupported(...)` or an explicit encoder/transcoder capability check before choosing the actual MIME/container.
+- Runtime uses the pinned Mediabunny timestamped encoder to select an actually supported container and codec. It reports the real MIME/extension or a typed visible failure.
 - `MOV` and `ProRes` are not baseline browser outputs; use them only with a custom encoder/transcoder plus acceptance and performance coverage.
 - Use `getToolcraftVideoExportSize` for video dimensions. `current` uses current canvas/output size with even encoder-safe rounding; `4k` fits inside 3840x2160, preserves aspect ratio, and returns even dimensions.
-- Offline rendered-frame video export must write timeline-based timestamps. `canvas.captureStream()` plus `MediaRecorder` records wall-clock time and cannot be the only duration mechanism for heavy renderers.
-- Browser acceptance must load the exported blob as a video, wait for metadata, and compare `video.duration` with the runtime timeline duration.
+- Runtime renders the same shared product frame callback at a fixed 30 FPS offline schedule, evaluates each immutable frame state at its timeline timestamp, and writes explicit packet timestamps/durations. Renderer wall-clock cost changes export latency only, never media cadence or duration.
+- Product code must not instantiate `MediaRecorder` or `VideoEncoder`, call `canvas.captureStream()`, import `mediabunny`, or provide a wall-clock fallback.
+- Protected browser acceptance decodes representative video frames, enumerates actual encoded packet timings, and proves dimensions, duration, cadence, background, and changing product pixels before publishing evidence.
 
 ## 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.
-- Use `reportProgress(0..1)` for determinate progress when available.
+- Runtime export actions own their real Promise and report render/encode/download progress through the sticky footer indicator.
+- Async non-export download/copy/generate/apply handlers return the real Promise from `onPanelAction` and use `reportProgress(0..1)` when determinate progress is available.

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`.
@@ -62,7 +63,7 @@ Use no timeline only when the motion is explicitly autonomous decoration with no
 
 ## Video Export Timing
 
-- Video export uses runtime timeline time.
-- Offline rendered-frame video export must encode frame timestamps from timeline time.
-- Real-time `canvas.captureStream()` plus `MediaRecorder` is not enough when renderer work can be slower than playback.
-- Browser acceptance verifies exported video metadata duration against edited timeline duration.
+- Runtime video export creates a fixed 30 FPS schedule from runtime timeline duration and evaluates one immutable frame state at every scheduled timeline time.
+- The timestamped Mediabunny backend encodes each completed frame with its explicit schedule timestamp and duration; render wall-clock cost does not affect artifact cadence.
+- Product code must not use `canvas.captureStream()`, `MediaRecorder`, `VideoEncoder`, or its own encoder/download fallback.
+- Protected browser acceptance proves edited timeline duration, actual encoded packet count/timings, and distinct decoded product frames.

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 |