@pixel-point/toolcraft 0.0.2

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

@@ -0,0 +1,71 @@
+# Decision Contract
+
+Use this before writing a schema, spec, or implementation plan. It separates hard runtime rules from product decisions.
+
+## Rule Levels
+
+| Level | Meaning | Required Handling |
+| --- | --- | --- |
+| Invariant | Cannot be violated | Follow it; tests should fail if broken |
+| Default | Normal choice | Use it unless the spec proves a reason not to |
+| Heuristic | Product-dependent decision | Decide from product behavior and test the choice |
+| Escape hatch | Allowed exception | Explain why and add stronger coverage |
+| Recommendation | Style guidance | Follow unless product behavior requires otherwise |
+
+## Area Guide
+
+| Area | Decision Type | Summary |
+| --- | --- | --- |
+| Runtime shell | Invariant | Use `defineToolcraft` and `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 |
+| 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 |
+| 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 |
+| Persistence | Default, then invariant | State persistence must be explicit; localStorage apps must prove reload restoration |
+| Workflow | Invariant | Use required skills and 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.
+
+## 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.
+
+| 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 |
+| `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 |
+
+## Enforcement
+
+Hard rules belong in validators and browser gates, not only prose. Heuristics need decision criteria and tests for the chosen behavior.
+
+| Enforcement | Use It For |
+| --- | --- |
+| 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 |
+| 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 |

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

@@ -0,0 +1,112 @@
+# Performance
+
+Every visible non-action control needs a `performanceRole` and `performanceReason`.
+
+Performance coverage has two levels:
+
+- workload coverage for controls that change render cost;
+- responsiveness coverage for ordinary controls that still must not freeze input or break the viewport.
+
+## Workload Coverage
+
+Use workload coverage for controls that change rendering cost:
+
+- output size;
+- media resolution;
+- sample count;
+- character or grid density;
+- particle count;
+- blur radius;
+- shader complexity;
+- iterations;
+- quality;
+- timeline playback;
+- keyframe scrubbing.
+
+Sensitive controls need min/default/max scenarios, `stressFixture`, and real product-output checks.
+
+`stressFixture` is the machine-checkable heavy case for a workload scenario. It must include:
+
+- `kind`: `large-text`, `large-canvas`, `high-density`, `many-items`, `max-value`, `media`, or `custom`;
+- `reason`: why this value is the heaviest useful product case;
+- `value`: the actual value the browser performance test will apply.
+
+For multiline text, prompt, code, JSON, CSS, shader, script, or template workload controls, use `kind: "large-text"`. The fixture must contain at least `50_000` characters and `1_000` lines unless the product has a stricter real-world maximum.
+
+Choose heavy fixtures from this app's real controls, not from generic examples. Use the largest useful product canvas, longest useful text, highest density, largest media, highest item count, fastest animation, highest export quality, or strongest effect setting that the product exposes.
+
+Browser performance tests for workload scenarios must read the heavy value through:
+
+```ts
+getToolcraftPerformanceStressValue(appPerformance, "scenario-id")
+```
+
+Do not type a separate short value in the Playwright test. If a test uses a toy value while `app-performance.ts` claims a heavy fixture, `pnpm verify:perf` must fail.
+
+## Responsiveness Coverage
+
+Ordinary controls still need lightweight responsiveness checks. They should not cause:
+
+- frozen pointer drag;
+- delayed input;
+- broken slider movement;
+- stale async renders;
+- canvas zoom or offset jumps;
+- panel scroll affecting canvas zoom;
+- timeline or layer interactions destabilizing the viewport.
+
+## Renderer Performance
+
+Custom renderers should:
+
+- initialize contexts, programs, shaders, pipelines, textures, and large buffers once;
+- update uniforms or stable buffers when controls change;
+- cache decoded media;
+- debounce, coalesce, or defer heavy preview work;
+- cancel stale async renders;
+- avoid re-decoding media on every control change;
+- cancel scheduled frames during cleanup.
+
+Pixel-output renderers may use a capped preview pixel budget, but export/copy must render final product output at `state.canvas.size`.
+
+Text-output and vector-output previews must preserve native output fidelity. Do not render low-resolution text/vector output into an offscreen canvas and upscale it.
+
+Renderer strategy is not final until the heavy scenarios pass. When stress preview, animation, drag, zoom, or export tests exceed budget, first decide whether the chosen renderer is wrong for this workload. Move heavy work to WebGL/WebGPU, split semantic foreground from heavy backgrounds, cache atlases/buffers, or change the rendering layer model before reducing product quality or relaxing budgets.
+
+## Required Browser Checks
+
+Use real interactions for:
+
+- `preview-render`;
+- `control-change`;
+- `control-drag`;
+- `media-import` when upload exists;
+- `export-copy` for product export actions and clipboard actions; measure retina output dimensions, not CSS preview size;
+- `timeline-playback` or `timeline-scrub` when timeline exists;
+- `layers-interactions` when layers exist;
+- `viewport-zoom-stress` for detail-heavy or animated custom renderers;
+- `viewport-stability`.
+
+Animated custom renderers also need `animation-viewport-drag`. Animation-only frame sampling and viewport-only stability are not enough: the browser test must sample frames while physically dragging or panning the canvas viewport. If SVG/DOM cannot pass that combined budget, choose a different renderer strategy from evidence instead of loosening the budget.
+
+Detail-heavy or animated custom renderers also need `viewport-zoom-stress`. This test must use the real toolbar zoom controls while sampling frame gaps and long tasks. Do not satisfy it by calling `canvas.zoom`, mutating runtime state directly, or checking only the final zoom value.
+
+Detail-heavy custom renderers also need a stress `preview-render` or `animation-frame` scenario with a `maxLongTaskMs` budget. A high-count Canvas 2D layer must carry that evidence before delivery. If it fails, revise renderer strategy from the measured failure instead of keeping Canvas 2D by default.
+
+During canvas drag, pan, pinch, zoom, and radar/center interactions, animated preview renderers must suspend or coalesce non-essential animation work. This is an interaction-performance throttle, not a user-visible playback command: do not flip the user's Play/Pause state, do not reset timeline time, and do not change export behavior. After the interaction settles, resume from the correct timeline or autonomous time without canvas offset or zoom jumps.
+
+Animation checks should sample enough frames to catch jank. Interaction budgets must match scenario type rather than using one universal number.
+
+Use `app-performance.ts` as the single budget and fixture source. Browser performance tests must call `getToolcraftPerformanceStressValue(appPerformance, scenarioId)` for workload values and `expectToolcraftScenarioPerformanceBudget(..., appPerformance, scenarioId)` for budgets.
+
+Run `pnpm verify:perf` for Tier 3 performance-sensitive edits and inside `pnpm verify:final` before delivery. It runs `e2e/app-performance.spec.ts` and every `browser perf:` scenario with one worker so budget failures are not hidden or created by unrelated parallel browser tests.
+
+Run a full performance checkpoint with `pnpm verify:perf` when:
+
+- the first working version of the app exists;
+- renderer, canvas, animation, export, timeline, or layers change;
+- a bug that previously broke functionality is fixed;
+- a performance optimization lands;
+- the user asks to optimize performance, fix lag, remove jank, speed up animation, or stabilize drag/zoom.
+
+Do not use the full performance suite as the default loop for Tier 0-2 edits. Those edits still need the targeted checks named by the verification tier, but they should not pay for renderer and viewport stress tests unless a checkpoint trigger applies. If a fast feature loop defers full performance, record the deferred check and reason in the worklog.

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

@@ -0,0 +1,48 @@
+# Renderer Technique
+
+Choose render technology per product layer. Do not choose a renderer because it is convenient; choose it from product output semantics, reference behavior, fidelity, and workload.
+
+The initial renderer choice is provisional. It becomes accepted only after the app passes performance checks with the largest useful product canvas and the heaviest useful values for its own controls. If those checks show frame gaps, long tasks, viewport shaking, slow export, or interaction jank, revise the renderer strategy from that evidence before delivery.
+
+## Strategy Guide
+
+- DOM: native product text, editable text, accessible product labels, low-count structured markup.
+- SVG: crisp vector shapes, lines, icons, product foreground geometry, handles, and hit targets.
+- Canvas 2D: medium raster compositing, text-to-canvas export, simple procedural previews, export passes.
+- WebGL or WebGPU: dense pixels, shaders, image processing, high-resolution procedural output, large particle fields, heavy animated backgrounds.
+- Mixed: use separate layers when background, product foreground, editing handles, and export composite have different semantics.
+
+Dense backgrounds may use Canvas 2D, WebGL, or WebGPU when the spec names primitive count and performance reason. A dense raster background does not justify rasterizing low-count foreground geometry or text.
+
+Do not force WebGL only because an app is visually rich, and do not keep Canvas 2D only because the primitive is text or vector. Use the stress results. High-count text, vectors, particles, grids, media, or procedural layers can stay on Canvas/SVG/DOM only when worst-case preview or animation tests prove they remain responsive. If they do not, split layers or move the heavy product renderer to WebGL/WebGPU.
+
+## Required Matrix
+
+Custom renderer specs and `src/app/app-performance.ts` must mirror the decision:
+
+- `sourceRepresentation`;
+- `productRepresentation`;
+- `previewRenderer`;
+- `exportRenderer`;
+- `rendererWorkload`;
+- `rendererStrategy`;
+- `whyNotAlternativeStrategies`;
+- `fidelityRisks`;
+- `performanceRisks`.
+
+If text or vector output is intentionally rasterized, include `intentionalRasterizationReason`. If preview and export renderers differ, include `previewExportDifferenceReason`. If a reference runtime renderer changes, include `referenceRendererChangeReason`.
+
+For heavy custom renderers, specs and `app-performance.ts` must also include stress preview or animation evidence using real maximum values from the app: max density, max text length, max item count, max canvas size, max animation speed, max export quality, max media size, or the nearest real heavy fixture for the product.
+
+## Layer Inventory
+
+Custom renderer specs must classify product layers when they exist:
+
+- `background`;
+- `product-foreground`;
+- `editing-handles`;
+- `export-composite`.
+
+Mirror these in `rendererTechnique.layers` with visible `uiSelector` values for browser verification.
+
+Editing handles should be DOM/SVG overlays, must not appear in export/copy output, and must write through runtime state.

package/templates/starter/docs/toolcraft/schema-reference.md

@@ -0,0 +1,265 @@
+# Schema Reference
+
+Edit `src/app/app-schema.ts` as the public product surface.
+
+## Runtime Shape
+
+- Use `defineToolcraft`.
+- Configure `canvas`, `panels`, `toolbar`, and `panelActions` through the schema instead of composing those surfaces by hand.
+- Use `settingsTransfer: "auto"` for complex apps that should let users import/export control settings.
+- Bind every control to a schema `target`.
+- Use `defaultValue` for reset behavior.
+- Use `description` for product-specific help beside a visible label. Keep `label` short. Omit `description` instead of writing label recaps like `Adjusts Opacity`; compound controls such as `fontPicker` must not use `description` to list their own fields.
+- Use `disabled: true` only when the control is intentionally unavailable; the runtime renders the disabled visual and interaction state.
+- Use `visibleWhen` when a control or section exists only for a specific template, type, mode, variant, or count. Hidden values are preserved. A section with no visible controls is hidden automatically.
+- Use `disabledWhen` when a control belongs to the current entity but is temporarily unavailable in the selected state. The value is preserved while disabled.
+- Conditions support `equals`, `notEquals`, `oneOf`, `notOneOf`, `greaterThan`, `greaterThanOrEqual`, `lessThan`, and `lessThanOrEqual`.
+- Use `orderRole` to make control order testable.
+- Use `performanceRole` and `performanceReason` on every visible non-action control so performance coverage can be derived from the schema.
+- Use built-in controls before custom renderers.
+- Use `panelActions` only for sticky footer product actions.
+- Do not use `panelActions` for settings import/export; `settingsTransfer` owns that body section.
+- Do not use `panelActions` for reset. The controls panel header owns reset, and footer actions with `label`, `value`, or `command` containing reset fail acceptance.
+- Still-output product apps expose `Export PNG`.
+- Animated product apps expose `Export Video` and `Export PNG`.
+- `Copy PNG` can be secondary, but it never replaces export.
+- If an odd number of footer actions leaves one action alone in the final row, that final action spans the full row.
+- Use `ToolcraftApp onPanelAction` for product-specific actions.
+- Async export/download/copy/generate/apply handlers return the real Promise from `onPanelAction`; the runtime shows the sticky footer top accent indicator only while that Promise is pending and fills it from `reportProgress(0..1)` when determinate progress is available.
+- Do not duplicate runtime-owned canvas, toolbar, panel, layer, or timeline internals.
+
+## Export
+
+Use the standard export helpers from `@/toolcraft/runtime`.
+
+```ts
+export: {
+  png: {
+    background: "include",
+  },
+}
+```
+
+`export.png.background` defaults to `"include"`. Product apps still expose runtime controls for the actual user choice:
+
+- `appearance.background` or `scene.background` as a `color` control;
+- `export.includeBackground` as a boolean/options control.
+
+PNG exporters should call `createToolcraftPngExportCanvas({ background, includeBackground, state, render })`, where `background` and `includeBackground` come from runtime state. `includeBackground` controls only PNG alpha; live preview, workspace canvas backing, and video export keep the product background. Video export always includes the product background, uses `getToolcraftRetinaExportSize`, and must prove exported metadata duration matches the runtime timeline duration.
+
+Animated apps with `Export Video` also expose a separate `Video Export` controls section. Do not mix video export settings into renderer/effect sections. Place this section as the final authored controls section directly above sticky footer export buttons. `Format` and `Resolution` are a compact semantic pair, so use an inline two-column layout by default; stack them only when labels or selected values would clip.
+
+```ts
+{
+  title: "Video Export",
+  controls: {
+    videoFormat: {
+      defaultValue: "mp4",
+      label: "Format",
+      options: [
+        { label: "MP4", value: "mp4" },
+        { label: "WebM", value: "webm" },
+      ],
+      target: "export.video.format",
+      type: "select",
+    },
+    videoResolution: {
+      defaultValue: "current",
+      label: "Resolution",
+      options: [
+        { label: "Current", value: "current" },
+        { label: "4K", value: "4k" },
+      ],
+      target: "export.video.resolution",
+      type: "select",
+    },
+  },
+  layoutGroups: [
+    {
+      columns: 2,
+      controls: ["videoFormat", "videoResolution"],
+      layout: "inline",
+    },
+  ],
+}
+```
+
+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 and dedicated acceptance plus performance coverage. `4K` is an export resolution target, not a reason to lock `canvas.size`. 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.
+
+## Canvas Sizing
+
+Choose sizing from product context:
+
+- `intrinsic-media`: a single uploaded or generated source defines `canvas.size`.
+- `editable-output`: exportable output where users should edit width and height.
+- `fixed-output`: product-defined output size that users must not edit.
+
+For product output, export, copy, download, shader rendering, procedural rendering, or no single intrinsic source image, use `editable-output` unless the product explicitly needs `fixed-output`.
+
+A prompt-provided base/default size is only the initial `canvas.size`. It must not remove the runtime Canvas width and Canvas height controls. Use `fixed-output` only when the reference or product explicitly locks dimensions, and add runtime acceptance with `canvasSizingCoverage: "fixed-output-size"`.
+
+Resolved `canvas.size` exists for every canvas app, but visible `Canvas width` and `Canvas height` inputs are mandatory only for `editable-output` sizing. They do not depend on `settingsTransfer`: when settings transfer is off, the runtime prepends a technical `Setup` canvas size section without a visible heading; when settings transfer is on, the controls merge into the first technical `Setup` runtime settings section without a visible heading. Do not hand-build a duplicate size selector.
+
+## Panels
+
+- Use `panels: {}` for the neutral starter or for products that have no user-facing panels yet.
+- Controls panel is the primary editing panel once the product has schema controls.
+- Layers are optional. Enable only for multiple editable objects, media objects, groups, visibility, selection, reorder, or selected-layer controls.
+- Do not use `selectedLayer.*` targets when layers are disabled.
+- Timeline is optional. Use no timeline, playback, keyframes, or custom reference timeline from product transport behavior.
+- Do not add right-panel Play, Pause, Animate, or Restart controls for app-wide transport. Use the top timeline.
+
+## Built-In Control Types
+
+Use built-ins before custom controls. Unknown `type` values render nothing unless the app passes a matching `controlRenderers` entry.
+
+| `type` | Renders | Key fields |
+| --- | --- | --- |
+| `actions` | Inline local action buttons for the current section or nearby entity | `actions`, `target`, `label` |
+| `anchorGrid` | Anchor picker | `defaultValue`, `target` |
+| `channelMixer` | RGB-only channel matrix mixer with R/G/B tabs and Red/Green/Blue source sliders | `defaultValue`, `target`, `label` |
+| `checkbox` | Checkbox field | `defaultValue`, `target`, `label` |
+| `code` | Multiline textarea | `defaultValue`, `target`, `label` |
+| `color` | Hex color picker | `defaultValue: { hex }`, `target`, `label` |
+| `colorOpacity` | Hex color picker plus opacity percent input | `defaultValue: { hex, opacity }`, `target`, `label` |
+| `curves` | RGB or single curve editor | `defaultValue`, `target`, `variant: "single"`, `interpolation: "smooth" \| "monotone"` |
+| `fileDrop` | Upload/drop input | `accept`, `target` |
+| `fontPicker` | Font preview select with popup, category search, weight, size, text case, text color/opacity, letter spacing, and line height; product text must consume `fontId`, `fontWeight`, `fontSize`, `letterSpacing`, `lineHeight`, `textCase`, `color`, and `opacity` | `defaultValue: { fontId, fontWeight, fontSize, letterSpacing, lineHeight, textCase, color, opacity }`, `target` |
+| `gradient` | Gradient editor | `defaultValue: { angle, gradientType, stops }`, `target` |
+| `imagePicker` | Image choice grid | `items`, `defaultValue`, `target` |
+| `palette` | Constrained design-token palette picker for family + shade | `defaultValue: { family, shade }`, `target` |
+| `panelActions` | Sticky footer product actions | `actions`, `target`, `variant` |
+| `rangeInput` | Two compact text values | `defaultValue: { start, end }`, `target` |
+| `rangeSlider` | Two-thumb slider | `defaultValue`, `min`, `max`, `step`, `variant` |
+| `segmented` | Segmented control | `options`, `defaultValue`, `variant` |
+| `select` | Select dropdown | `options`, `defaultValue` |
+| `slider` | Single-value slider | `defaultValue`, `min`, `max`, `step`, `unit`, `variant` |
+| `switch` | Binary switch | `defaultValue`, `target`, `label` |
+| `text` | Single-line input | `defaultValue`, `target`, `label`, `commitMode` |
+| `vector` | X/Y vector pad and fields | `defaultValue: { x, y }`, `xLabel`, `yLabel`, `variant` |
+
+`text` defaults to `commitMode: "content"` and applies while typing for real content such as prompts, names, titles, tokens, and short text. Use `commitMode: "setting"` for text inputs that edit settings such as font size, numeric-like style values, dimensions, ids, or configuration fields; setting text commits on blur or Enter. Canvas width and Canvas height always commit on blur or Enter. `code` / `CodeTextarea` is a content editor, applies while typing, and is capped at 12 visible lines. Long content scrolls inside the textarea instead of making the controls panel taller.
+
+## Control Selection Inventory
+
+Before writing schema controls, map product needs to built-ins by value model, not visual similarity.
+
+For every user-visible product setting or action, write:
+
+```txt
+Product need:
+Value model:
+Candidate built-ins checked:
+Best built-in:
+Rejected alternatives:
+Target:
+Required acceptance:
+```
+
+If a built-in exact owner matches the value model, use that built-in. If several controls fit, choose the best fit and record why. If no built-in fits, use the custom escape hatch from `component-rules.md`.
+
+For `curves`, choose the variant explicitly. Use `variant: "single"` for acceleration, bend, easing, response, depth, mask, opacity, threshold, or remap curves. Omit it only for RGB/color-correction or channel-specific curves that intentionally need RGB/R/G/B tabs.
+
+## Animation Intent
+
+Before adding animation controls, decide the animation owner:
+
+- `timeline-playback`: product time controlled by the top timeline.
+- `timeline-keyframes`: property animation controlled by keyframe diamonds and rows.
+- `autonomous`: decorative/self-running output with no user-facing transport.
+
+In keyframes mode, renderer code reads evaluated values from the runtime keyframe evaluator. Do not parse timeline labels and do not use raw `state.values` for targets with keyframes.
+
+If the user asks for product animation and does not explicitly say it is decorative autoplay, use `panels.timeline: { mode: "playback" }`. If no timeline is used while animation controls remain visible, `starterTransferMode.animationIntent` must declare `mode: "autonomous"`, include a concrete reason, and include behavior coverage for no transport, no play/pause, no scrub, no duration control, no loop control, and no export-at-time.
+
+## Control Section Inventory
+
+Before editing `panels.controls.sections`, write a short inventory in the spec or plan:
+
+- section title;
+- product entity or workflow stage;
+- included schema targets;
+- reason these controls belong together or reason for a real workflow split.
+
+Group controls by product meaning, not by component type. Do not create sections named `Controls`, `Settings`, `Options`, `Sliders`, `Inputs`, `Buttons`, `Color`, or `Colors`.
+
+Every app-authored controls-panel body section must have a short meaningful visible title. Runtime-created setup/settings sections use the technical title `Setup` but render without a visible heading; sticky footer action sections use the technical title `Export` but render without a visible heading.
+
+Every visible section title renders through the standard 36px collapsible header row with vertically centered text and the runtime collapse icon. Do not hand-build section headers in generated apps.
+
+Section expand/collapse uses the standard runtime height/opacity animation. Do not replace it with instant custom section visibility.
+
+Ordinary section collapsed/expanded state persists as a per-app runtime UI preference. It is not undo/redo state, not settings import/export state, and `Reset controls` must not clear it. Runtime technical `Setup` / settings sections and sticky footer `Export` sections are not collapsible.
+
+Ordinary controls-panel body sections use 8px top spacing and 24px bottom spacing for their control content. Runtime technical `Setup` / settings sections use 12px top and bottom spacing to match side padding. Sticky footer action sections keep their dedicated spacing.
+
+Large built-in compound controls inside mixed sections render content-width internal dividers with 18px between each rendered divider and the control content. If a compound control is the first item in that section, render only its bottom internal divider and remove the top internal padding. If a section contains exactly one control, whether simple or compound, only the parent section dividers render. Single `curves` are not compound for dividers; RGB `curves` are compound.
+
+Controls for the same product entity stay in the same section. For example, `squares.right.connections`, `squares.right.hoverRadius`, and `squares.right.color` belong in `Square 1 (Right)` with `Color` as the field label. A standalone color section is only valid when the color is the whole product entity, such as `Background`, `Accent`, `Connector`, or `Brand`.
+
+Keep sections discrete. A section usually has two to seven product controls. If a section grows past seven controls, split it by the next product sub-entity or workflow stage instead of keeping a broad bucket. Broad titles such as `Flow`, `Icon`, `Shapes`, `Scene`, `Text`, `Typography`, or `Motion` are valid only for small cohesive groups; larger groups need specific titles such as `Flow Motion`, `Flow Geometry`, `Letter Burst`, `Shape Colors`, `Logo Glow`, `Logo Plate`, or `Text Block`. Section titles must be unique in the same panel.
+
+Control labels are judged with their nearest visible context. Short property labels such as `Speed`, `Color`, `Size`, or `Opacity` are allowed when the section or group clearly names the edited product entity. If the section is generic, mixed, missing, or otherwise weak context, include the affected entity or role in the label, such as `Pattern color`, `Background opacity`, `Wave speed`, or `Stroke width`. Acceptance suggests a semantic replacement label; fix the schema label instead of relying on runtime fallback rewriting.
+
+If a target prefix has to be split across sections, the spec must name the workflow reason. Otherwise the acceptance validator treats the split as a sectioning error.
+
+Switch and checkbox labels name the setting context only. Do not prefix them with `Enable` or `Disable`; use `CRT`, `Glow`, `Loop`, or `Guides` instead. If the nearest section title already names the context, do not duplicate it as the visible toggle label. Use `label: false` for a visual-only toggle and keep the product meaning in `target` and `description`.
+
+Inline two-column groups are preferred when controls tune one close product meaning and labels/values fit. Short numeric text pairs can be inline. Related short `select` pairs can be inline, especially workflow pairs such as `Format` + `Resolution`, `Codec` + `Profile`, or `Width unit` + `Height unit`. Use stacked one-control rows only as a fit fallback when a label, selected value, or option text would clip, truncate, or lose padding; record that fallback reason in the spec or worklog. A short numeric/text field may also pair with one related plain `color` field when both configure the same entity, such as `Mask size` and `Color` inside `Mask`. `colorOpacity` never renders in inline two-column groups; if either color control has opacity, keep the controls stacked. Color controls show visible field labels in mixed sections that contain any non-color control. Omit visible color labels only in color-only sections or in a section-title-owned toggle + parameter row, such as hidden `export.includeBackground` plus `appearance.background` inside `Background`. Mixed inline rows require visible labels on every field except this hidden-label toggle + parameter pattern. Color fields in other mixed rows must not be unlabeled. Two adjacent `switch` or `checkbox` controls for the same product entity must share one inline row when both visible labels fit without truncation; the runtime auto-pairs safe adjacent toggles by target entity, and schemas should stack them only when either label is too long. A single `switch` or `checkbox` may share an inline row with one related parameter control when the toggle label fits and both controls edit the same entity; hide the toggle label when the section title already supplies the context. Schema `slider` and `rangeSlider` controls always stay stacked at full width; the only built-in exception is the paired letter-spacing and line-height footer sliders inside `fontPicker`. Do not place sibling controls for case, color, opacity, size, weight, letter spacing, or line height when the same text entity already uses `fontPicker`.
+
+`rangeSlider` is always a full-width two-thumb control. Do not include it in `layoutGroups`. Its `defaultValue` must start with different lower and upper values, such as `[20, 80]`, so the two handles do not collapse into one apparent slider. Manual range labels accept built-in separators such as slash, hyphen, spaces, and dashes.
+
+## Control Order
+
+Order controls by decision flow inside each section:
+
+- `input`: upload, source, and canvas-size controls;
+- `mode`: mode, type, filter, blend, style, and preset selectors;
+- `primary`, `spatial`, `color`: core product parameters;
+- `strength`: intensity, opacity, scale, depth;
+- `detail`: grain, noise, blur, density, radius, quality;
+- `advanced`: secondary tuning;
+- `action`: footer actions.
+
+A selector that changes how later controls are interpreted must use `orderRole: "mode"` and sit above dependent parameters.
+
+Use `visibleWhen` for mode-, type-, variant-, or count-exclusive controls and sections. Example: `Partner` is visible when `coBrand.identityMode` is `text`; `Partner logo` is visible when it is `logo`. Count-controlled banks use numeric conditions: `Shade 4` is visible when `shapes.shadeCount` is `greaterThanOrEqual: 4`. When every control in a section is hidden by `visibleWhen`, the whole section is hidden automatically. Use `disabledWhen` only when the control remains part of the current entity but temporarily has no effect.
+
+If a selector says “use the first N”, “number of colors”, “number of stops”, “active slots”, or similar, dependent sibling controls must be hidden with `visibleWhen` when they are outside the current count. Do not leave all possible controls visible while making the renderer ignore the inactive ones.
+
+App schema tests must assert visible control order with `getToolcraftControlOrderTargets(appSchema)` or an equivalent exact target-order check.
+
+## Persistence
+
+State persistence is a product policy, not a hidden side effect.
+
+Use `persistence: { storage: "localStorage", key, version, include }` when user-edited app settings should survive reload. Typical product editors persist `values`, `canvas`, and `panels`. If localStorage persistence is enabled and any runtime panel is visible, `include` must contain `"panels"` so dragged panel positions survive reload in that specific app. Add `timeline` when playback position, duration, loop, expansion, or keyframes should survive reload. Add `layers` only when the app has a real layer model.
+
+Do not persist media blobs, files, generated images, or history stacks. Theme preference is runtime-owned separately. Do not write runtime state to `localStorage` directly from app code.
+
+If `storage` is `"localStorage"`, add a runtime acceptance row with `persistenceCoverage: "reload"` and a browser test that changes a user-facing setting, reloads the page, and verifies the restored value or product output. Settings import/export is for preset transfer in complex apps; it is not proof that persistence works.
+
+## Settings Transfer
+
+Use `settingsTransfer` when users should move a complex app setup between sessions or machines.
+
+```ts
+settingsTransfer: "auto"
+```
+
+Allowed values:
+
+- `"auto"`: default. Runtime enables the first settings-transfer section when the app reaches the complexity threshold: 12 product controls, 5 product sections, or weighted score 18. Compound controls, layers, and timeline increase the weighted score.
+- `true`: force the section on.
+- `false`: force the section off.
+- `{ enabled, appId, fileName }`: customize the exported JSON identity and file name.
+
+When enabled, the runtime inserts a technical `Setup` settings-transfer section as the first controls-panel section. It renders without a visible section heading, exports and imports control values, `canvas.size`, and timeline state, ignores unknown targets on import, and pauses playback after importing.
+
+After adding, removing, or reorganizing controls, sections, timeline, or layers, recalculate settings-transfer eligibility. If the threshold is reached, use `"auto"` / `true` or add an explicit `runtime.settingsTransfer` opt-out acceptance row with product evidence.
+
+When settings transfer is enabled and the canvas uses `editable-output` sizing, the first technical `Setup` runtime section is mandatory and contains `Export Settings`, `Import Settings`, `Canvas width`, and `Canvas height` in that order. Do not split these into separate sections or recreate them manually.
+
+A settings-transfer section with only `Export Settings` and `Import Settings` means the canvas is not `editable-output` or the app already declares its own `canvas.size.width` / `canvas.size.height` controls. For product-output apps, treat that as a schema decision to review.
+
+Do not hand-write `settings-transfer.ts`, hidden file inputs, route handlers, or `panelActions` for settings import/export. Sticky footer `panelActions` remain product delivery only.

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

@@ -0,0 +1,87 @@
+# Toolcraft Workflow
+
+This file is the app-local routing layer for Toolcraft work. It does not replace the detailed contracts; it tells an agent which contract to read and which verification path to use before editing.
+
+## Required Preflight
+
+Before planning or editing app code, runtime code, controls, canvas, panels, renderer, timeline, layers, export, or tests:
+
+1. Confirm the nearest `AGENTS.md` is the active project contract.
+2. Classify the project type:
+   - **Generated app**: use local `docs/toolcraft/*`.
+   - **Starter source**: use `starter/AGENTS.md`, local starter docs, and runtime contracts.
+   - **Runtime/template source**: use root `AGENTS.md` and runtime contracts.
+3. Classify the task type.
+4. Read the task-specific docs below.
+5. Choose and record a verification tier before implementation.
+
+Do not edit implementation files until this preflight is complete.
+
+## Task Routing
+
+Use the smallest reading set that covers the changed surface.
+
+| Task type | Read before editing |
+| --- | --- |
+| App assembly, route structure, generated app porting | `assembly-workflow.md`, `decision-contract.md` |
+| Schema, controls, defaults, persistence, actions | `schema-reference.md`, `component-rules.md`, `acceptance-testing.md` |
+| Custom controls | `custom-controls.md`, `component-rules.md`, `acceptance-testing.md` |
+| Renderer, canvas output, visual technique | `renderer-technique.md`, `performance.md`, `acceptance-testing.md` |
+| Timeline, keyframes, animation transport | `decision-contract.md`, `component-rules.md`, `acceptance-testing.md`, `performance.md` |
+| Layers | `decision-contract.md`, `component-rules.md`, `acceptance-testing.md` |
+| Export, copy, media, background | `schema-reference.md`, `component-rules.md`, `acceptance-testing.md` |
+| Broken control, visual mismatch, failed build, export bug, performance issue | `decision-contract.md`, the relevant component/runtime doc, and the failing test/log first |
+| Figma implementation | Use Figma MCP/design context, then `assembly-workflow.md` and the relevant component docs |
+
+## Worklog Gate
+
+For product app work, update `docs/toolcraft/agent-worklog.md` before reporting completion. Record:
+
+- `Decision Trail` entries for each significant implementation pass, including:
+  - request;
+  - task type;
+  - user-visible result;
+  - source/reference checked;
+  - docs/contracts read;
+  - contract rules applied;
+  - decision;
+  - alternatives rejected;
+  - state/output mapping from controls, commands, timeline, layers, media, or renderer to the visible product;
+  - files changed;
+  - verification;
+  - skipped checks with reason;
+  - risks or follow-ups.
+- updated high-level decisions for renderer, timeline, layers, controls, export, and performance when those choices change.
+
+If the folder is still the neutral starter, do not invent product decisions. Once it becomes a product, switch the worklog to product mode and keep it concrete.
+
+## Runtime Boundary
+
+Use the runtime extension points described in the current contracts:
+
+- schema controls;
+- `canvasContent` for product output only;
+- `controlRenderers` only for true custom controls;
+- `onPanelAction` for sticky product actions;
+- runtime commands and hooks.
+
+Do not recreate controls, panels, toolbar, timeline, layers, canvas shell, or runtime surfaces by hand. If a shared behavior is wrong, fix the shared runtime/template source and regenerate when needed.
+
+## Verification Gate
+
+Choose the tier from `AGENTS.md` before editing. Use the tier to decide checks.
+
+- 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 relevant `pnpm verify:perf` scenarios.
+- Tier 4: `pnpm verify:final`, then start `pnpm dev` for the local URL.
+
+Run a full performance checkpoint with `pnpm verify:perf` when:
+
+- the first working version of the app exists;
+- renderer, canvas, animation, export, timeline, or layers change;
+- a bug that previously broke functionality is fixed;
+- a performance optimization lands;
+- the user asks to optimize performance, fix lag, remove jank, speed up animation, or stabilize drag/zoom.
+
+Fast feature loops may defer full performance only when none of these checkpoint triggers apply. Record the deferred check and reason in the worklog.