@pixel-point/toolcraft 0.0.13 → 0.0.15

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

@@ -0,0 +1,86 @@
+# Performance
+
+Read this module before changing renderer technique, animation, canvas, media, export, render scale, heavy controls, or performance tests.
+
+## Verification Triggers
+
+Run a full performance checkpoint only when:
+
+- 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.
+
+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.
+
+## Verification Tiers
+
+- 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.
+
+Record skipped full performance runs and reason in the verification note or worklog.
+
+## Workload Fixtures
+
+- 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.
+
+## Media And Pixel Workloads
+
+- 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
+
+- 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.
+
+## 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.

package/templates/starter/docs/toolcraft/core/reference-study.md

@@ -0,0 +1,115 @@
+# Reference Study
+
+Read this module before porting, auditing, or rebuilding from a reference app, Figma file, video, GIF, screen recording, contact sheet, or extracted frames.
+
+## Reference Runtime Clone
+
+When porting an existing app, use `transferMode: "reference-runtime-clone"` unless the user explicitly asks for redesign.
+
+Preserve the reference runtime as source of truth:
+
+- animation loop and time ownership;
+- refs and mutable renderer state;
+- particles, objects, connections, spawn cadence, and lifetime rules;
+- pause/resume, restart, progress, export, and copy semantics;
+- canvas sizing and media lifecycle;
+- control-to-renderer mapping.
+
+Toolcraft still owns the shell: schema, controls, canvas, panels, toolbar, file upload, sticky footer actions, and `canvasContent`.
+
+Do not iframe the reference, replace the route with copied original UI, or rebuild the app as a different shell.
+
+## Feature Inventory
+
+Before implementation, create `starterTransferMode.referenceFeatureInventory` from inspected reference source/runtime/UI.
+
+Include every user-visible and output-affecting behavior:
+
+- controls;
+- modes;
+- generated objects;
+- renderer state;
+- media import lifecycle;
+- canvas sizing;
+- layers and selection;
+- timeline and transport;
+- export/copy;
+- persistence;
+- randomization;
+- reset behavior.
+
+Each inventory item names the reference feature, cites source evidence, cites feature-level behavior evidence, describes original behavior, describes Toolcraft mapping, and points to an `acceptanceId` that proves the behavior.
+
+Use `status: "ported"` when the behavior is carried over directly and `status: "toolcraft-native"` when Toolcraft owns the same behavior. If behavior is intentionally changed or omitted, mark it `status: "intentionally-changed"` and set `userApprovedChangeReason` with explicit user approval or redesign/change-request evidence.
+
+Do not rely on the user to find missing reference functionality after delivery.
+
+## Reference Study Record
+
+Declare `starterTransferMode.referenceStudy` and record:
+
+- where the reference lives;
+- which source/runtime files, routes, assets, and handlers were inspected;
+- how the original was run or restored locally in the Toolcraft environment;
+- which runtime/browser behaviors were checked.
+
+Use:
+
+- `status: "ran-original"` when the original can run as-is;
+- `status: "restored-local"` when enough of the reference was reconstructed locally to observe behavior;
+- `status: "source-inspection-only"` only when running or restoring is blocked. Set `sourceOnlyReason` to the concrete blocker and compensate with stronger source evidence and acceptance coverage.
+
+Reference clones also declare `referenceTimeline` with mode `none`, `toolcraft-playback`, `toolcraft-keyframes`, or `custom-reference-timeline`. Custom reference transport such as state buttons, trim handles, selected ranges, or range export uses `referenceTimeline.mode: "custom-reference-timeline"` plus browser-backed `referenceTimelineCoverage`.
+
+## Figma Source
+
+When a prompt provides a Figma URL, treat the Figma file as the design source of truth.
+
+Required flow:
+
+- Use Figma MCP/design context before implementation.
+- Inspect the target node, layer tree, component instances, variants, text nodes, variables, styles, and assets.
+- Recreate the design from the Figma structure and Toolcraft runtime/component contracts.
+- Use screenshots only for final visual QA after reading the file structure.
+
+Do not implement a Figma design by eye from an image, screenshot, exported PNG, or rough visual memory.
+
+## Video References
+
+When the prompt provides a video, GIF, screen recording, contact sheet, or extracted-frame sequence, study it as behavior before implementation.
+
+Write a Video Reference Study before coding. Record:
+
+- `referenceLocation`;
+- `extractionEvidence`;
+- `storyboard` with timecoded frames, visible state, and behavior observations;
+- `transitionAnalysis` with frame-to-frame deltas;
+- `behaviorDecomposition`;
+- `acceptanceMapping`.
+
+The transition analysis explains what changes between frames: entities, anchors, state persistence, releases, retargeting, input, timeline state, and copied behavior.
+
+Do not implement video references from a single screenshot, generic visual summary, or a few static style observations.
+
+## Acceptance Mapping
+
+Every reference feature maps to acceptance coverage.
+
+Each `acceptanceMapping` item points to a real acceptance row that proves the copied behavior with automated and browser coverage.
+
+The port is incomplete until inventory and acceptance coverage prove that reference functionality was reviewed and transferred.
+
+## Worklog Evidence
+
+`docs/toolcraft/agent-worklog.md` records:
+
+- explicit reference inputs;
+- source/reference checked;
+- contract rules applied;
+- decisions;
+- alternatives rejected;
+- state/output mapping;
+- verification;
+- risks or follow-ups.
+
+If a worklog cites a video, GIF, screen recording, contact sheet, extracted frames, Figma URL, or reference app, it must include the corresponding study evidence.

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

@@ -0,0 +1,60 @@
+# Runtime Boundary
+
+Read this module before changing app assembly, routes, runtime surfaces, custom renderers, canvas output, panels, toolbar, timeline, layers, or controls.
+
+## Required Runtime Shell
+
+- Build through `defineToolcraft`.
+- Render through `ToolcraftApp`.
+- Read `appSchema.assembly` before adding custom JSX. It lists the enabled runtime surfaces, capabilities, commands, and assumptions for the current app.
+- Keep app state in the Toolcraft runtime schema and runtime commands.
+- Keep product assembly in typed `src/app/app-composition.tsx`; the signed route only hosts `ToolcraftApp`.
+- Do not replace Toolcraft with copied reference UI, route-local panels, standalone forms, or hand-built editor chrome.
+
+## Allowed Extension Points
+
+Use only these app-specific extension points. Shared runtime changes happen upstream and reach generated apps through regeneration:
+
+- 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;
+- `controlRenderers` only for true custom controls that pass the built-in fit check;
+- `onPanelAction` for sticky product actions;
+- runtime commands and hooks.
+
+## Forbidden Rebuilds
+
+- Do not hand-compose `ToolcraftRoot`, `CanvasShell`, `ControlsPanel`, `LayersPanel`, `TimelinePanel`, `ToolbarPanel`, or panel containers in product routes.
+- Do not render built-in control components such as `SliderControl`, `SelectControl`, `ColorControl`, `GradientControl`, `FontPickerControl`, `FileDropControl`, or `PanelActionsControl` directly in app code.
+- Do not recreate controls, panels, toolbar, timeline, layers, canvas shell, drag handles, section headers, section reset, history, or runtime surfaces by hand.
+- If a shared behavior is wrong, fix the shared runtime/template source and regenerate or sync the copied Toolcraft source instead of patching one exported app.
+
+## Canvas Boundary
+
+- `canvasContent` contains product output only: WebGL, Canvas 2D, SVG, DOM product text, shaders, generated previews, export previews, or product editing handles.
+- App UI, CTAs, upload prompts, helper copy, placeholder instructions, buttons, menus, forms, and settings do not belong in `canvasContent`.
+- If upload/import is part of the source-material flow, the pre-content canvas stays neutral and runtime-backed. Upload affordance belongs in `fileDrop`.
+- DOM product text rendered inside `canvasContent` must be marked with `data-toolcraft-product-output` or `data-toolcraft-product-text` so tests and performance fixtures can target product output instead of app chrome.
+- 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.
+
+## 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.
+
+## Generated App Source Boundary
+
+- Generated applications keep their public entry surface in `src/app/app-composition.tsx` and `src/app/app-schema.ts`. Supporting product modules may live anywhere under `src`; every product production module is discovered by the same source inventory and checked by the same AST boundary.
+- The signed framework bootstrap includes `index.html`, `src/main.tsx`, `src/router.tsx`, `src/routes/index.tsx`, `src/routes/root.tsx`, and `src/styles.css`. Do not edit or replace those host files in a generated app.
+- Product styling is local by construction: use locally imported `*.module.css` files only. Every selector starts with a compound containing a local class. A first-compound `:is()` or `:where()` remains local only when every branch is locally anchored; `:not()` and `:has()` do not create a local anchor. Descendants may style product-owned children, but `:global`, bare/root selectors, host-attribute selectors, sibling escapes, CSS `@import`, package CSS imports, and product-created global `<style>`/`CSSStyleSheet` injection are rejected because they cross the product/runtime boundary.
+- Product `import()` and `require()` specifiers must be statically resolvable from literals, same-file constants, templates, or string concatenation. Production and test source share this rule, so computed module loading cannot hide a runtime/control import or a protected evidence channel.
+- Product production modules must not import product tests, test-support modules, or protected browser-evidence internals, directly or through a product bridge. Runtime evidence is emitted only by the protected public acceptance/performance helpers after their assertions pass; product-owned source must not import, re-export, assemble, or forge the reserved evidence module names and payload identifiers.
+- 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 apps must not contain monorepo app/package folders, workspace-protocol dependencies, or workspace package imports.

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

@@ -0,0 +1,86 @@
+# Setup, Background, And Export
+
+Read this module before changing Setup, canvas sizing, background, image export, video export, sticky actions, render scale, or timeline visibility.
+
+## Runtime Setup
+
+- Runtime `Setup` is always the first visible controls block in generated product apps.
+- `Setup` is headerless, not collapsible, and has no section reset action.
+- `Setup` always contains `Export Settings` and `Import Settings`.
+- 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`.
+
+## Canvas Size Defaults
+
+- When no explicit product size is provided, the default canvas size is `16:9` / `1920x1080`.
+- Runtime aspect presets apply canonical canvas sizes; `16:9` is `1920x1080`.
+- A prompt-provided, reference, fixed-format, or base/default size is only the initial `canvas.size`.
+- 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.
+
+## 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.
+- 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.
+- 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`.
+- When `panels.timeline` is omitted, the Timeline switch must not appear.
+
+## 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`.
+- 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.
+
+## Image Export
+
+- Every app with `Export PNG` exposes a separate `Image Export` section.
+- `Image Export` uses two `select` controls in one compact two-column inline row:
+  - `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 })`.
+- 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`.
+- 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`.
+- `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.
+- `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.
+
+## Sticky Product Actions
+
+- Product apps always expose export in sticky `panelActions`.
+- Still products expose `Export PNG`.
+- Animated products expose `Export Video` plus `Export PNG`.
+- 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.

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

@@ -0,0 +1,68 @@
+# Timeline And Animation
+
+Read this module before changing animation, timeline, keyframes, playback, loop duration, video export, or animated renderer timing.
+
+## Animation Intent Inventory
+
+Before adding animation controls, write an Animation Intent Inventory. Classify the animation as one of:
+
+- playback timeline;
+- keyframes timeline;
+- custom reference timeline;
+- autonomous decorative output.
+
+Use no timeline only when the motion is explicitly autonomous decoration with no user-facing play/pause, scrub, duration, loop, restart, progress, export-at-time behavior, product animation, or video export.
+
+## Timeline Requirement
+
+- Product animation uses the top playback timeline by default.
+- Any app with `Export Video` must enable the top Toolcraft timeline.
+- Do not add right-panel Play, Pause, Animate, Restart, or app-wide transport controls. Use the top timeline.
+- Do not replace `TimelinePanel` with app-level playback, transport, or timeline UI to work around performance.
+- Custom timeline UI is allowed only when a reference app has non-Toolcraft timeline behavior and the reference timeline inventory proves it.
+
+## Compact And Extended Timeline
+
+- When `panels.timeline` is enabled, runtime Setup appends a `Timeline` switch.
+- 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`.
+
+## Seamless Forward Loops
+
+- Product loops are seamless forward-only cycles by default.
+- First and last frames stitch.
+- Direction does not reverse.
+- Mirror, yoyo, ping-pong, or back-and-forth behavior requires explicit user intent.
+- Use `getToolcraftTimelineLoopTime` or `getToolcraftTimelineLoopProgress` in playback renderers instead of local wall-clock or fixed-duration phase math.
+- When the loop period is known or product-derived, set `panels.timeline.defaultDurationSeconds` to that period and record the evidence in animation or reference timeline metadata.
+- Runtime/template fallback `8s` is not evidence for loop duration.
+- Playback acceptance with loop coverage declares typed `timelineLoopProof`: forward-only direction, reverse playback forbidden, first/last frame seam match, and reproof after a duration edit. This declaration never replaces browser sampling of the real renderer.
+
+## Duration Changes
+
+- Editing timeline duration changes the loop length, not the scene design.
+- The app must keep animation settings stable when duration changes.
+- The loop remains seamless and forward-only after duration changes.
+- Export duration follows runtime timeline duration.
+
+## Keyframes
+
+- Use keyframes timeline when users edit property animation over time.
+- Keyframe renderers consume Toolcraft evaluated-value helpers/hooks.
+- Do not parse timeline `valueLabel` strings.
+- Do not read raw `state.values` for keyframed targets when evaluated keyframe helpers are available.
+- When a keyframe point is selected and a parameter is edited, update the selected point instead of creating a new point unless the user explicitly adds one.
+
+## Viewport Interaction Performance
+
+- Animated preview renderers suspend or coalesce non-essential animation work during canvas drag, pan, pinch, zoom, and radar/center interactions.
+- Resume from the correct timeline or autonomous time without changing play/pause state.
+- Do not sacrifice selected render scale or visible quality to pass performance budgets without measured evidence.
+
+## 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.

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

@@ -1,5 +1,7 @@
 # Custom Controls
 
+> Reading route: start with `workflow.md`. Core generated-app rules live in `core/*`; this file is a focused custom-control reference for the topic below.
+
 Use a custom control only when no built-in Toolcraft control represents the product interaction.
 
 Built-ins come first: `slider`, `rangeSlider`, `select`, `segmented`, `switch`, `checkbox`, `color`, `colorOpacity`, `vector`, `gradient`, `curves`, `fontPicker`, `imagePicker`, `fileDrop`, `text`, `code`, `rangeInput`, `palette`, `actions`, `collectionActions`, and `panelActions`.
@@ -31,6 +33,13 @@ Custom control schemas still need:
 
 ```ts
 builtInFitCheck: {
+  capabilities: [
+    "collection",
+    "reorder",
+    "selection",
+    "commands",
+    "custom-value-model",
+  ],
   checkedBuiltIns: ["fileDrop", "collectionActions", "imagePicker"],
   closestBuiltIn: "fileDrop",
   whyInsufficient:
@@ -40,7 +49,7 @@ builtInFitCheck: {
 }
 ```
 
-`checkedBuiltIns` must name real Toolcraft built-in controls. `closestBuiltIn` must be one of those checked controls or `"none"` when no built-in is meaningfully close. `whyInsufficient` explains the missing interaction. `productObservable` names the output or side effect that proves the custom control is necessary.
+`capabilities` is required and uses broad behavior facts: `collection`, `reorder`, `selection`, `commands`, `custom-interaction`, `custom-value-model`, or `custom-visualization`. At least one of the three `custom-*` capabilities must explain why built-ins cannot own the interaction. `checkedBuiltIns` must name real Toolcraft built-in controls. `closestBuiltIn` must be one of those checked controls or `"none"` when no built-in is meaningfully close. `whyInsufficient` explains the missing interaction. `productObservable` names the output or side effect that proves the custom control is necessary.
 
 If the custom control owns a growable, removable, selectable, or reorderable runtime item set, `checkedBuiltIns` must include both `collectionActions` and `actions`. Decide this from the value model and workflow, such as arrays, `{ items: [...] }` objects, selected-item state, or add/remove/reorder behavior, not from entity names like masks or glyphs. This applies even when the empty state visually looks like a few icon buttons: the fit check must prove why `collectionActions` cannot own the runtime list and why `actions` alone cannot represent the collection state.
 

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

@@ -16,7 +16,7 @@ Use this before writing a schema, spec, or implementation plan. It separates har
 
 | Area | Decision Type | Summary |
 | --- | --- | --- |
-| Runtime shell | Invariant | Use `defineToolcraft` and `ToolcraftApp` |
+| Runtime shell | Invariant | Use `defineToolcraft` and `ToolcraftAppComposition`; the signed host renders `ToolcraftApp` |
 | Canvas | Mixed | No app UI in `canvasContent`; handles are product-dependent |
 | 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 |
@@ -28,35 +28,39 @@ Use this before writing a schema, spec, or implementation plan. It separates har
 | 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 |
 | Persistence | Default, then invariant | State persistence must be explicit; localStorage apps must prove reload restoration |
-| Workflow | Invariant | Use required skills and browser verification |
+| Workflow | Invariant | Follow signed local workflow, use available skills, and run browser verification |
 
-The runtime shell invariant means product routes render `ToolcraftApp` directly. Do not hand-compose `ToolcraftRoot`, `CanvasShell`, `ControlsPanel`, `TimelinePanel`, `LayersPanel`, or `ToolbarPanel`; those surfaces are shared runtime design, not app-specific implementation details. App-specific source also must not render built-in control components directly; schema controls and `controlRenderers` are the allowed control extension points.
+The runtime shell invariant means product code exports the typed composition and does not edit the signed route. The host renders `ToolcraftApp`; product modules must not hand-compose `ToolcraftRoot`, `CanvasShell`, `ControlsPanel`, `TimelinePanel`, `LayersPanel`, or `ToolbarPanel`. App-specific source also must not render built-in control components directly; schema controls and `controlRenderers` are the allowed control extension points.
 
 ## Rule Catalog
 
 This catalog mirrors `TOOLCRAFT_DECISION_CONTRACT`. If runtime adds or renames a rule id, this page and `AGENTS.md` must list the same id.
 
+[//]: # (toolcraft-contract:decision-rule-table:start)
 | Rule ID | Level | Area |
 | --- | --- | --- |
-| `runtime-shell-required` | Invariant | Runtime shell |
-| `canvas-no-app-ui` | Invariant | Canvas |
-| `canvas-surface-preserved` | Invariant | Canvas |
-| `canvas-handle-placement` | Heuristic | Canvas |
-| `panel-host-behavior` | Invariant | Panels |
-| `layers-enable-only-when-needed` | Heuristic | Layers |
-| `layers-enabled-behavior` | Invariant | Layers |
-| `timeline-mode-choice` | Heuristic | Timeline |
-| `timeline-enabled-behavior` | Invariant | Timeline |
-| `controls-product-coverage` | Invariant | Controls |
-| `output-export-required` | Invariant | Controls |
-| `controls-layout-heuristics` | Heuristic | Controls |
-| `renderer-technique-inventory` | Default | Renderer |
-| `video-reference-analysis` | Invariant | Reference analysis |
-| `reference-clone-source-of-truth` | Invariant | Reference clone |
-| `acceptance-product-observable` | Invariant | Acceptance |
-| `performance-coverage-levels` | Invariant | Performance |
-| `persistence-policy-explicit` | Default | Persistence |
-| `workflow-required` | Invariant | Workflow |
+| `runtime-shell-required` | invariant | runtime-shell |
+| `canvas-no-app-ui` | invariant | canvas |
+| `canvas-surface-preserved` | invariant | canvas |
+| `canvas-handle-placement` | heuristic | canvas |
+| `panel-host-behavior` | invariant | panels |
+| `layers-enable-only-when-needed` | heuristic | layers |
+| `layers-enabled-behavior` | invariant | layers |
+| `timeline-mode-choice` | heuristic | timeline |
+| `timeline-enabled-behavior` | invariant | timeline |
+| `controls-product-coverage` | invariant | controls |
+| `output-export-required` | invariant | controls |
+| `controls-section-inventory-required` | invariant | controls |
+| `controls-component-layout-invariants` | invariant | controls |
+| `controls-layout-heuristics` | heuristic | controls |
+| `renderer-technique-inventory` | default | renderer |
+| `reference-clone-source-of-truth` | invariant | reference-clone |
+| `video-reference-analysis` | invariant | reference-analysis |
+| `acceptance-product-observable` | invariant | acceptance |
+| `performance-coverage-levels` | invariant | performance |
+| `persistence-policy-explicit` | default | persistence |
+| `workflow-required` | invariant | workflow |
+[//]: # (toolcraft-contract:decision-rule-table:end)
 
 ## Enforcement