@pixel-point/toolcraft 0.0.2

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

@@ -0,0 +1,206 @@
+# Assembly Workflow
+
+Build the app from the local Toolcraft runtime copy. Do not recreate controls, panels, toolbar, canvas behavior, timeline, layers, or app chrome by hand.
+
+Use:
+
+- `@/toolcraft/runtime` for schema, contracts, state, commands, history, canvas, panels, timeline, layers, toolbar, and tests.
+- `@/toolcraft/runtime/react` for `ToolcraftApp` and hooks.
+- `@/toolcraft/runtime/styles.css` for runtime styles.
+- `@/toolcraft/ui` for visual components.
+
+Declare the product with `defineToolcraft`. Render through `ToolcraftApp`.
+
+```tsx
+import { defineToolcraft } from "@/toolcraft/runtime";
+import { ToolcraftApp } from "@/toolcraft/runtime/react";
+
+const appSchema = defineToolcraft({
+  canvas: { enabled: true, sizing: { mode: "intrinsic-media" }, upload: true },
+  panels: {},
+  toolbar: { history: true, radar: true, theme: true, zoom: true },
+});
+
+export function AppHome() {
+  return <ToolcraftApp schema={appSchema} />;
+}
+```
+
+Routes must render `ToolcraftApp` directly. Do not compose `ToolcraftRoot`, `CanvasShell`, `ControlsPanel`, `LayersPanel`, `TimelinePanel`, or `ToolbarPanel` by hand in product routes. If a runtime surface has a performance or behavior issue, fix the shared runtime contract instead of replacing the surface with app-level UI.
+
+App-specific source may use only runtime extension points: schema controls, `canvasContent` for product output, `controlRenderers` for true custom controls, `onPanelAction` for sticky footer actions, and runtime commands/hooks. Do not render built-in control components such as `SliderControl`, `SelectControl`, `ColorControl`, `GradientControl`, `FontPickerControl`, `FileDropControl`, or `PanelActionsControl` directly in app code. Declare them in schema so layout, reset, history, disabled states, keyframes, labels, and tests stay runtime-owned.
+
+Read `appSchema.assembly` before adding custom JSX. It lists enabled surfaces, capabilities, commands, and runtime assumptions.
+
+Toolbar history owns undo/redo buttons and keyboard shortcuts. When `toolbar.history` is enabled, the runtime handles `Cmd/Ctrl+Z`, `Cmd/Ctrl+Shift+Z`, and `Ctrl+Y`, while ignoring shortcuts inside inputs, textareas, selects, and editable value labels. Do not add route-local undo/redo keyboard listeners.
+
+The starter baseline is deliberately neutral. It must not include demo controls, prompt fields, timeline, or layers until the product behavior requires them. Use tests and docs fixtures to exercise component coverage; do not expose those fixtures in the starting product schema.
+
+Once the folder is a real product, switch `src/app/app-acceptance.ts` from neutral readiness to:
+
+```ts
+export const appProductReadiness = {
+  mode: "product",
+  productName: "Product name",
+  productSummary: "What the app creates or edits.",
+  requestedBehavior: "The user-facing behavior this app must implement.",
+} as const;
+```
+
+Do not leave `mode: "starter"` in a renamed product folder or after adding product controls, `canvasContent`, timeline, layers, or acceptance rows.
+
+## Control Sections
+
+Before writing the schema, make a Control Section Inventory. Each section needs a product entity or workflow stage, included targets, and a reason for grouping. Do not group by control type.
+
+Bad section titles: `Controls`, `Settings`, `Options`, `Sliders`, `Inputs`, `Buttons`, `Color`, `Colors`.
+
+Good section titles name the thing being edited: `Background`, `Object`, `Square 1 (Right)`, `Token Pattern`, `Motion`, `Tone Mapping`, `Export`.
+
+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 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.
+
+If a color, slider, input, or selector edits the same entity as nearby controls, keep it in that entity section. Split only when the product has a real workflow split and cover that decision in acceptance.
+
+Before choosing the concrete control type for each target, check `component-rules.md` and `schema-reference.md`. Built-in compound controls must stay compound: for example, typography with font choice, weight, size, color/opacity, and text rhythm uses `fontPicker`, not a plain `select` plus separate inputs/sliders. The product renderer and acceptance rows must cover every semantic value part of the chosen component.
+
+## Figma Source
+
+When the 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. If the Figma URL is not node-specific, inspect the file/page metadata and choose the relevant node only when it is unambiguous; otherwise ask for a node-specific link.
+
+## Product Output
+
+Use `canvasContent` only for product output: WebGL, Canvas 2D, SVG, DOM product text, shader previews, generated previews, export previews, or product editing handles.
+
+```tsx
+<ToolcraftApp
+  canvasContent={<ProductRenderer />}
+  renderDefaultCanvasMedia={false}
+  schema={appSchema}
+/>
+```
+
+`canvasContent` must not contain app UI: buttons, forms, CTAs, upload prompts, helper text, settings, menus, labels, placeholder copy, or empty-state instructions.
+
+Product text rendered as DOM must be marked with `data-toolcraft-product-output` or `data-toolcraft-product-text`. Product editing handles must be textless overlays, write to runtime state, and stay out of export/copy output.
+
+Preserve the runtime canvas surface. Product renderers may draw their own output background, but must not hide, replace, or make the Toolcraft canvas backing transparent.
+
+## 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.
+
+## Animation Intent
+
+Before adding animation controls, write an Animation Intent Inventory. Classify the animation as playback timeline, keyframes timeline, custom reference timeline, or autonomous decorative output.
+
+If the user asks for product animation, use the top playback timeline by default. Use no timeline only when the animation is self-running output with no user-facing play/pause, scrub, duration, loop, restart, progress, or export-at-time behavior. In that case, declare `starterTransferMode.animationIntent.mode = "autonomous"` and list the absent transport behavior in `behaviorCoverage`.
+
+Do not replace `TimelinePanel` with an app-level playback, transport, or timeline panel to work around performance. Playback/keyframe timeline UI is runtime-owned. Custom timeline UI is allowed only when a reference app has non-Toolcraft timeline behavior and `starterTransferMode.referenceTimeline.mode` is `"custom-reference-timeline"` with browser-backed `referenceTimelineCoverage`.
+
+Animated preview renderers must prioritize viewport interactions. During canvas drag, pan, pinch, zoom, and radar/center, suspend or coalesce non-essential animation work, then resume from the correct timeline or autonomous time without changing the user's play/pause state.
+
+## Canvas Sizing And Background
+
+A base/default size in the prompt is the initial output size. It does not remove user-facing size controls. Use `editable-output` unless the reference or product explicitly locks dimensions, and cover any `fixed-output` choice with `canvasSizingCoverage: "fixed-output-size"`.
+
+Every product app exposes output background controls:
+
+- `appearance.background` or `scene.background` as a schema `color` control;
+- `export.includeBackground` as a `switch`, `checkbox`, `select`, or `segmented` control.
+
+Preview, PNG export, and video export read the background color runtime value. PNG export passes the include-background runtime value to the export helper. Turning `export.includeBackground` off makes only PNG output transparent; live preview, workspace canvas backing, and video output keep the background.
+
+Keep those controls together in one `Background` section. When the section title supplies the full context, prefer an inline row with hidden-label `export.includeBackground` on the left and the background color parameter on the right; do not repeat `Background` as both the section title and switch label.
+
+Every product app needs output delivery in sticky footer `panelActions`. Still-output apps expose `Export PNG`. Animated apps expose `Export Video` and `Export PNG`. Clipboard copy is optional and 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.
+
+Async product actions such as Export, Download, Copy, Generate, or Apply must return the real Promise from `ToolcraftApp onPanelAction`. The controls panel uses that Promise to show the sticky footer top accent indicator while the operation is pending. Use the `reportProgress(0..1)` callback from `onPanelAction` for determinate progress; video export reports frame-based render/encode progress, and PNG export reports phase progress for render, blob, and handoff when those phases are asynchronous. Do not fire-and-forget long export work from `onPanelAction`, and do not add custom loading strips or canvas UI for export progress.
+
+For complex apps, use schema `settingsTransfer: "auto"` or `true` for settings import/export. Recalculate settings-transfer eligibility after adding, removing, or reorganizing controls, sections, timeline, or layers. The runtime threshold is 12 product controls, 5 product sections, or weighted score 18. Do not put Import Settings or Export Settings in sticky footer `panelActions`; runtime inserts the technical `Setup` settings-transfer section first without a visible section heading.
+
+If the app also uses `editable-output` canvas sizing, that first technical `Setup` runtime section is mandatory and contains `Export Settings`, `Import Settings`, `Canvas width`, and `Canvas height` in that order. Do not split the canvas size fields and settings-transfer actions into app-authored sections.
+
+If a controls panel shows only `Export Settings` and `Import Settings` in the first runtime section, check the canvas sizing decision. Product-output apps usually need `editable-output`; intrinsic media and explicitly fixed output are the cases where visible canvas size inputs are absent.
+
+For user-edited settings that should survive reload, use schema `persistence` with a stable app-specific key. When localStorage persistence is enabled, acceptance must prove a user setting restores after a real browser reload. Do not use settings import/export as a workaround for broken persistence.
+
+Animated apps with `Export Video` must include a separate `Video Export` controls section with at least:
+
+- `export.video.format` as `select`, defaulting to `mp4`, with `mp4` and `webm` baseline options;
+- `export.video.resolution` as `select`, defaulting to `current`, with options such as `current` and `4k`.
+
+Place `Video Export` as the final authored controls section directly above sticky footer export buttons. Treat `Format` and `Resolution` as a compact semantic pair and put them in one two-column inline row by default. Use vertical rows only when the compact row would clip labels or selected values, and record that fallback reason in the worklog.
+
+Use standard export helpers. `createToolcraftPngExportCanvas` applies retina sizing and accepts `includeBackground` for runtime PNG transparency. Do not rely on static `export.png.background` alone when the UI exposes background controls. Video export keeps background and still uses `getToolcraftRetinaExportSize`.
+
+Video export must choose the actual MIME/container with `MediaRecorder.isTypeSupported(...)` or an explicit encoder/transcoder capability check. `MOV` and `ProRes` are allowed only when the app provides a custom encoder/transcoder and proves it with acceptance plus performance coverage. Treat `4K` as an export resolution target, not a hardcoded canvas lock. Offline rendered-frame export must encode or mux frame timestamps from runtime timeline time; real-time `canvas.captureStream()` plus `MediaRecorder` records wall-clock export time and is not enough when renderer work can be slower than playback. Browser acceptance must load the exported blob as a video, wait for metadata, and compare `video.duration` with the edited timeline duration; `blobSize > 0`, `blobType`, parser fallback, or assigning the expected duration in `catch` is not enough.
+
+## Verification Tiers
+
+Before every edit, classify the change by blast radius and write the planned checks in the implementation note or plan:
+
+```md
+Verification tier: Tier N
+Reason: <changed surface and expected blast radius>
+Run: <commands and browser checks>
+Skip: <checks not needed for this pass and why>
+```
+
+Use these tiers:
+
+| Tier | Use When | Required Checks |
+| --- | --- | --- |
+| Tier 0 — docs/copy | Documentation, comments, copy, labels, or titles change without schema targets, values, runtime behavior, renderer output, or layout mechanics. | Targeted docs/typecheck or targeted app test. Browser is not required unless visual text fitting is the risk. |
+| Tier 1 — local control presentation | One control or panel visual state changes: spacing, hover, focus, disabled, marker visibility, label fit, or component variant display. Runtime state shape and product renderer are unchanged. | Targeted unit/component test plus one focused browser check for the affected control or panel. |
+| Tier 2 — schema/product behavior | Controls, sections, defaults, persistence, panel actions, export actions, acceptance rows, or product behavior mapping changes. | `pnpm verify:quick` plus relevant browser acceptance. Run perf only when the changed control affects renderer workload or responsiveness. |
+| Tier 3 — renderer/canvas/runtime feature | Custom renderer, animation loop, canvas sizing, upload/media, timeline, layers, toolbar, export bytes, WebGL/Canvas/SVG output, zoom, radar, history, heavy control behavior changes, or a post-generation iteration that touches renderer workload or viewport stability. | `pnpm verify:quick`, targeted browser acceptance, and relevant `pnpm verify:perf` scenarios for touched workload/viewport/export paths. |
+| Tier 4 — final delivery/template architecture | Fresh generated app completion, folder export, commit-ready delivery, dependency changes, runtime/template/contract/CLI changes, broad refactors, or major post-generation iterations that rewrite renderer, canvas, animation, timeline/keyframes, layers, media, export, or control mapping. | Fresh folders run `pnpm install` once, then `pnpm verify:final`, then start `pnpm dev` to provide the local URL. |
+
+Choose the tier by blast radius, not by line count. If uncertain, move one tier higher, not automatically to Tier 4.
+
+Do not rerun `pnpm install` after every edit. Run it after fresh export, dependency changes, lockfile changes, or a missing package error.
+
+Use `pnpm verify:ui` when a tier calls for the browser acceptance suite without the performance suite. Use a focused named Playwright test instead when only one entity changed and the relevant test is already known.
+
+Run a full performance checkpoint with `pnpm verify:perf` when the first working version of the app exists, when renderer/canvas/animation/export/timeline/layers change, after fixing a bug that previously broke functionality, after any performance optimization, or when 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 the checkpoint triggers apply. Record the deferred check and reason in the worklog.
+
+For final delivery, run:
+
+```bash
+pnpm verify:final
+pnpm dev
+```
+
+Browser verification must use the real Toolcraft shell plus renderer output. `pnpm verify:final` runs the full static, build, browser, and browser performance gate. `pnpm dev` is intentionally separate because it keeps the local server running.
+
+Do not stop existing local servers to free `3002`. `pnpm dev`, `pnpm preview`, and browser verification prefer `3002`, then automatically use the next free port when it is occupied.

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

@@ -0,0 +1,299 @@
+# Component Rules
+
+## Control Decision Catalog
+
+Choose controls by product value model before UI appearance.
+
+- Exact owner: if the value model belongs to a built-in, use that built-in.
+- Best fit: if multiple built-ins can work, choose one and record the reason.
+- Custom escape hatch: use custom controls only after documenting checked built-ins and why the closest one is insufficient.
+
+If a built-in owner is discovered after a custom workaround, replace the workaround with the built-in.
+
+Common exact-owner choices:
+
+- Use `gradient` for adjustable gradients, color transitions, gradient fills, stops, type, and angle. Do not replace it with two `color` controls. The built-in Gradient owns type/angle, the draggable stop track, and the Stops list; the full Gradient control uses content-width internal dividers only when it shares a section with sibling controls, with 18px between each divider and the control content. If Gradient is the first control in that section, only the bottom internal divider renders.
+- Use `fontPicker` for typography that includes font family, weight, size, text case, text color/opacity, letter spacing, or line height.
+- Use `colorOpacity` when one product entity owns both color and opacity.
+- Use `rangeSlider` or `rangeInput` for lower/upper bounds or from/to ranges.
+- Use `curves` for editable tone, response, easing, remapping, opacity, depth, mask, or channel curves.
+- Use `vector` for position, offset, direction, focus, anchor, light direction, or color-balance pads.
+- Use `fileDrop` for source material uploads.
+- Use `imagePicker` for choosing one visual option from a set.
+- Use `palette` only for constrained design-token color choices with both family and shade: brand palette, Tailwind-like token color, style-guide color scale, semantic palette family, or theme accent token.
+- Use `actions` for local section commands that affect only the nearby entity, such as randomize palette, normalize weights, sort glyphs, clear selection, duplicate item, or reset current stop.
+- Use `panelActions` for sticky final product actions such as export, copy, generate, apply, or download.
+
+Small action buttons inside custom controls are for item-level actions such as remove, reorder, add stop, or delete stop. Use schema `actions` for section-level local commands. Keep final product actions in `panelActions`, keep timeline transport in the top timeline, and keep global reset in the controls panel header.
+
+For local reset-like `actions`, use product-specific values such as `reset-current-layer`, `reset-palette`, or `reset-current-stop` and handle them through `ToolcraftApp onPanelAction`. Do not use a bare `reset` value unless the action intentionally runs global `controls.reset`.
+
+## Dividers
+
+- Full-width dividers belong only to panel sections.
+- Large built-in compound controls inside a section render content-width internal dividers only when their parent section contains more than one visible control item. Keep 18px between each rendered internal divider and the compound control content. If the compound control is the first item in that section, render only its bottom internal divider and remove the top internal padding. This applies to `gradient`, `fontPicker`, RGB `curves`, `channelMixer`, and `palette`. Single `curves` are one labeled control and do not render internal dividers.
+- If a section contains exactly one control, whether simple or compound, render only the parent section dividers.
+- Do not add full-width borders inside a compound control, and do not put dividers only around an internal subsection such as Gradient Stops.
+- Small compound fields such as `colorOpacity` and `rangeInput` stay inline fields without section dividers.
+
+## Sliders
+
+Slider `step` means numeric snapping only. It does not make a slider visually discrete by itself.
+
+Classify every stepped slider as either `stepped continuous` or `visual discrete` in the spec and schema tests.
+
+Use `variant: "discrete"` for semantic integer domains where markers help choose positions: counts, rows, columns, levels, bands, passes, points, tiles, segments, finite position choices, and finite animation-step controls such as flip depth, character count, glyph steps, or frame steps.
+
+Keep large or precision stepped ranges visually continuous, even with `step`: speed, FPS, rate, duration, seconds, milliseconds, density, size, intensity, quality, and other ranges with many positions.
+
+Visual discrete sliders must declare `step`; the runtime derives one marker per value position from `min`, `max`, and `step`. Visual discrete sliders with too many positions are invalid because they produce marker noise.
+
+Schema sliders always render stacked at full width. Do not put `slider` or `rangeSlider` controls in two-column inline rows. The only built-in exception is `fontPicker`, whose letter-spacing and line-height footer sliders stay paired inside that component.
+
+Range sliders are always full-width two-thumb controls. Do not put a `rangeSlider` in an inline row. Its `defaultValue` must start with different lower and upper values, such as `[20, 80]`, so the control does not collapse into a single-value slider.
+
+Range slider value editing accepts common range separators such as `20/80`, `20-80`, `20 - 80`, `20 80`, and en-dash ranges. Use the built-in parser instead of adding custom label parsing.
+
+Discrete sliders must still drag smoothly. Heavy preview work must be debounced, coalesced, or deferred.
+
+When a slider or range slider is intentionally unavailable, use schema `disabled: true`. Do not draw custom disabled-looking slider rows or disable only the renderer response while leaving the control active.
+
+When a slider is meaningful only in some mode values, keep it visible and use `disabledWhen`:
+
+```ts
+fillAmount: {
+  type: "slider",
+  label: "Fill level",
+  target: "distribution.fillAmount",
+  disabledWhen: {
+    target: "distribution.fillMode",
+    equals: "full",
+  },
+}
+```
+
+The disabled value is preserved. When the user switches back to a mode where the control is meaningful, the slider becomes active with its previous value.
+
+Use `visibleWhen` instead of `disabledWhen` when a control or section belongs only to another template, type, mode, variant, or count. Example: in a co-brand lockup, `Partner` belongs to text identity mode and `Partner logo` belongs to logo identity mode. For count-controlled banks, hide inactive siblings: if `Shades` is `2`, `Shade 3`, `Shade 4`, and `Shade 5` are not visible. Do not keep inactive controls visible and enabled while making the renderer ignore them.
+
+## Palette
+
+Use `palette` only when the product needs a constrained token palette: family plus shade. It is for design-system color tokens, not for arbitrary color entry.
+
+Use `color` for free hex colors, `colorOpacity` when opacity belongs to the same color entity, `gradient` for color transitions, and `fontPicker` when the color belongs to typography. Browser acceptance must change both `palette.family` and `palette.shade` and prove the rendered/exported output consumes both parts.
+
+## Segmented Controls
+
+Use segmented controls only for compact mode choices that preserve every cell's internal padding.
+
+Limits:
+
+- at most four options;
+- no option label longer than nine characters;
+- no more than twenty-four total option-label characters.
+
+If cells clip, collide, lose padding, or force labels into adjacent cells, shorten labels first. If compact labels still fail, use `select`.
+
+## Sections
+
+Build controls-panel sections from product entities and workflow stages, not component types. Keep sections discrete: two to seven product controls is the normal size. When a section grows past seven controls or mixes several meanings, split it into specific sections such as `Flow Motion`, `Flow Geometry`, `Letter Burst`, `Shape Colors`, `Logo Glow`, `Logo Plate`, or `Text Block`. Do not reuse the same section title for multiple sections.
+
+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. Do not omit a title on app-authored body sections to avoid naming decisions; choose the nearest honest product context instead.
+
+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.
+
+## Colors
+
+First identify the semantic entity the color belongs to: background, object, connector, glow, tone mapping, brand, export, or a named product object.
+
+Keep color inside a section when it configures the same entity as nearby controls. Use a standalone color section only when color is the whole semantic section.
+
+Standalone color section titles must describe product role. Never generate a section titled `Color` or `Colors`. If no meaningful role exists, use a neutral title such as `Appearance` instead of omitting the title.
+
+Show visible field labels for `color` and `colorOpacity` controls when the section also contains any non-color controls. Omit visible color labels only when the whole section is made of color controls.
+
+Multiple related plain colors stay in the same section and render at most two per row. If any color control has opacity, keep it stacked instead of placing it in a two-column row.
+
+Use `colorOpacity` when one product entity owns both color and opacity, such as text color, shadow color, glow color, overlay color, or stroke color. Do not split that into a separate `color` plus opacity slider/input.
+
+When one short numeric/text field and one plain `color` field configure the same entity, they can share a two-column inline row. Example: `Mask size` and `Color` belong in the same `Mask` row instead of two stacked rows. Do not put `colorOpacity` in inline rows.
+
+Mixed inline rows require label parity: every field in that row has a visible label. The exception is a section-title-owned toggle + parameter row: a hidden-label `switch` or `checkbox` may sit beside one related parameter when the section title supplies the visible context. Color fields in other mixed rows must not be unlabeled.
+
+Renderer-owned output background is a base product control. Use a schema `color` target such as `appearance.background` or `scene.background`, add an `export.includeBackground` control for PNG transparency, and make preview/export read those runtime values. Keep them in one `Background` section. Prefer one inline row with hidden-label `export.includeBackground` on the left and `appearance.background` on the right when no other fit rule is violated. `export.includeBackground` controls only PNG alpha; it must not make live preview, workspace canvas backing, or video output transparent. Do not hardcode a configurable background in CSS, Canvas `fillStyle`, or WebGL clear color.
+
+## File Upload
+
+Use `fileDrop` for source material uploads in the controls panel. Do not place upload UI on the canvas.
+
+In single-layer apps, the runtime shows uploaded image preview and clear button in the file control. Clearing removes source material from the renderer and canvas.
+
+In multi-layer apps, deletion and visibility belong to the Layers panel; `fileDrop` stays an upload target.
+
+## Image Picker
+
+Every visible `ImagePicker` item must be actionable in the current product context. Do not show choices that sanitize to fallback or no-op behavior.
+
+Sizing:
+
+- two options: large tiles;
+- three or six options: medium tiles;
+- larger sets: small tiles.
+
+Filter or split choices by template, mode, or selected object when only some choices are valid.
+
+## Font Picker
+
+Use `fontPicker` for typography choices that need font preview plus weight, size, text-case, text color/opacity, letter-spacing, and line-height controls. Do not recreate it with a plain `select`, custom font list, or separate typography inputs.
+
+The value is one object: `{ fontId, fontWeight, fontSize, letterSpacing, lineHeight, textCase, color, opacity }`. Typography renderers and exports must consume all eight parts.
+
+If `fontPicker` controls product text, the preview renderer and export renderer must apply the selected `fontId`, `fontWeight`, `fontSize`, `letterSpacing`, `lineHeight`, `textCase`, `color`, and `opacity` to that actual text. Do not stop at updating runtime state, the select label, or the popup preview.
+
+The component owns search, category filters, virtualized scrolling, font preview loading, selected-row behavior, the font-weight select, the font-size input, the text-case select, the color/opacity control, and the two footer sliders. Browser acceptance must choose a different font, change weight, change size, change text case, change color/opacity, move Letter spacing, and move Line height.
+
+`fontPicker` is an atomic typography block. Do not place sibling schema controls for `Case`, `Weight`, `Size`, `Letter spacing`, `Line height`, `Color`, or `Opacity` when they affect the same product text entity. If a typography part is missing from the built-in value model, extend `fontPicker` in the kit instead of composing a neighboring control.
+
+Do not add `description` to `fontPicker` just to list these owned fields. If the section title and visible field labels already make the text target clear, omit `description`; use it only for non-obvious product scope.
+
+## Vector
+
+One vector control in the controls panel uses the square X/Y pad. Multiple vector controls use compact pads so the sidebar does not become too tall.
+
+Use variants by product meaning:
+
+- default: position, offset, direction, focus, anchor, light direction;
+- `whiteBalance`: temperature and tint;
+- `colorBalance`: paired color-balance axes;
+- `chromaOffset`: RGB or chromatic offset;
+- `toneBias`: split-tone, duotone, or color-grading bias.
+
+Do not add custom vector sizing props. Choose the right number, variant, and section grouping, then let runtime sizing handle the pad.
+
+## Curves
+
+Use `curves` for editable remapping curves. First decide the curve variant by product meaning; do not rely on the runtime default.
+
+Use `variant: "single"` for one standalone curve without channel tabs, such as acceleration, bend, easing, opacity response, depth response, mask response, threshold response, tone response, or another single mapping curve. Do not create a custom curve UI just to remove RGB tabs.
+
+RGB Curves is the color-correction or channel-specific case. Use RGB/R/G/B tabs only when the product edits RGB channels, color correction, color grading, or channel curves. Do not force RGB/R/G/B tabs onto products that need only one response, bend, depth, or easing curve.
+
+Single Curves is one labeled control and does not use internal dividers. RGB Curves is the compound variant because it contains channel tabs plus curve points, so it follows the compound divider rules when mixed with sibling controls.
+
+Choose interpolation by product meaning:
+
+- `interpolation: "smooth"` for photo/editor-like visual tone, color, and RGB curves where the curve should feel like a creative spline;
+- `interpolation: "monotone"` for depth, response, mask, opacity, threshold, and data-mapping curves where order must be preserved and overshoot is unsafe.
+
+Single curves default to monotone. If a single curve is still a creative visual tone curve, set `interpolation: "smooth"` explicitly.
+
+Acceptance for curves should include an off-center control point near an edge so smooth-vs-monotone interpolation mistakes are visible in the actual product output, not only in the curve UI.
+
+## Text And Code
+
+Use `text` for short single-line strings: names, small values, compact prompts, titles, and tokens.
+
+For `text`, separate content from settings. `commitMode` defaults to `"content"`: content strings such as prompts, names, titles, tokens, and short text update while the user types. 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 are runtime-owned editable-size fields and always commit on blur or Enter.
+
+Use `code` / `CodeTextarea` as the base multiline content editor for any potentially long value: prompts, instructions, JSON, CSS, shader code, scripts, templates, or other structured text. It applies while typing, is capped at 12 visible lines, and long content scrolls inside the textarea instead of making the controls panel taller. Do not name a section `Code` unless the product value is actually code.
+
+## Labels
+
+Visible control labels should be short UI names, usually one to three words. Do not put explanations, formulas, units, parenthetical hints, or usage instructions in field labels.
+
+Short labels must still be semantically sufficient with nearby context. `Animation` / `Speed` is fine because the section names the entity; `Settings` / `Speed` should become `Animation speed`, and mixed visual buckets should use labels such as `Symbol color` or `Background opacity`.
+
+Visible control labels can get a runtime-owned filled Phosphor question tooltip icon. Put a concise product-specific explanation in `description` only when it adds meaning beyond the label. Do not write recaps like `Adjusts Opacity`, and do not build custom help icons beside built-in labels.
+
+For compound controls such as `fontPicker`, `description` must not enumerate owned fields like font, weight, size, case, color, opacity, letter spacing, or line height. The component already labels those fields.
+
+If a source label is unavoidably long, keep the visible label concise and rely on native `title` for the full text.
+
+Switch and checkbox labels name the setting context, not the action. Do not prefix them with `Enable` or `Disable`; use `CRT`, `Glow`, `Loop`, or `Guides` instead of `Enable CRT` or `Disable guides`. If the section title already names the setting context, do not repeat that title as the visible toggle label; use `label: false` and keep the meaning in `target` and `description`.
+
+Two adjacent `switch` or `checkbox` controls for the same product entity must share one inline row when every visible label fits without truncation. Use short one- or two-word labels such as `Snap X` and `Snap Y`, or `Glow` and `Loop`. The runtime auto-pairs safe adjacent toggles by target entity; use explicit layout groups only when pairing a toggle with a non-toggle parameter. If either label would truncate in half-width, remove the inline group and let the toggles stack.
+
+A single `switch` or `checkbox` may share an inline row with one related parameter control when the toggle label fits and the controls edit the same entity. Example: `Loop` plus `Duration`, or hidden-label `export.includeBackground` plus `appearance.background` inside `Background`. If the section title already names the toggle context, hide the toggle label instead of repeating the title.
+
+## Layers
+
+Enable layers only when the app has multiple editable objects, media objects, groups, visibility, selection, reorder, or selected-layer controls.
+
+Do not show Layers for a single-layer app. Do not use `selectedLayer.*` targets when Layers are disabled.
+
+When Layers are enabled, browser tests must use the real LayersPanel UI: select, visibility, reorder, grouping, and media lifecycle when uploads/deletes create or remove layers.
+
+## Timeline
+
+Before choosing timeline mode for an animated product, write an Animation Intent Inventory:
+
+- `timeline-playback`: user-facing play, pause, scrub, duration, loop, restart, progress, or export-at-time.
+- `timeline-keyframes`: editable diamonds, rows, easing, or keyframe evaluation.
+- `autonomous`: decorative or self-running output with no user-facing transport.
+
+User-requested product animation defaults to playback timeline. Use no timeline only for autonomous decorative/self-running animation, and declare `starterTransferMode.animationIntent.mode = "autonomous"` with coverage proving no play/pause, scrub, duration, loop, or export-at-time behavior.
+
+Use playback timeline for play, pause, scrub, duration, loop, restart, or export-at-time.
+
+Playback renderers must read `state.timeline.currentTimeSeconds`, `state.timeline.durationSeconds`, `state.timeline.isPlaying`, and loop state from the runtime. The full animation cycle must span `state.timeline.durationSeconds`; do not hard-code a separate local animation duration such as 3s or 8s inside the renderer.
+
+Renderers may compute an initial duration default during app initialization or reset, but they must not watch `state.timeline.durationSeconds` and dispatch `timeline.setDuration` back to a computed local value. Once the user edits the timeline duration, that runtime value is the source of truth and renderer progress must map into it.
+
+Use keyframes timeline for diamonds, editable rows, easing, or keyframe evaluation. In keyframes mode, Toolcraft infers capable controls; do not manually hide diamonds on controls that can be keyframed.
+
+Keyframe state stores typed control values. `valueLabel` is display-only for the timeline UI; renderers and tests must never parse it as the source of truth. Custom renderers must read keyframed settings through `evaluateToolcraftTimelineValues`, `evaluateToolcraftTimelineValue`, `useToolcraftEvaluatedValues`, or `useToolcraftEvaluatedValue` instead of reading raw `state.values` for keyframed targets.
+
+Playback-only timelines stay collapsed and must not show control diamonds or expanded keyframe rows.
+
+When non-looping playback reaches the end, pressing Play again must restart from time 0. Do not require users to scrub back manually before replaying.
+
+App-wide Play, Pause, Animate, and Restart controls do not belong in the right panel.
+
+Right-panel animation controls may tune renderer parameters such as mode, intensity, speed, or stagger only after the animation intent is declared. They must not replace top timeline transport.
+
+Do not replace `TimelinePanel` with an app-level playback, transport, or timeline panel to avoid runtime performance issues. Keep the runtime panel design and fix the Toolcraft runtime clock/state path. Use custom timeline UI only for explicit `custom-reference-timeline` transfers with browser-backed reference timeline coverage.
+
+## Panel Actions
+
+Use `panelActions` only for sticky footer product actions such as Generate, Apply, Export, Copy, or Download.
+
+Use schema `settingsTransfer` for settings import/export. Do not add Import Settings or Export Settings to sticky footer `panelActions`; when enabled, the runtime inserts a first technical `Setup` settings-transfer section without a visible heading and imports/exports control values, canvas size, and timeline state.
+
+Recalculate settings-transfer eligibility after adding, removing, or reorganizing controls, sections, timeline, or layers. The runtime threshold is 12 product controls, 5 product sections, or weighted score 18. If the threshold is reached, use `settingsTransfer: "auto"` / `true` or document a product-specific opt-out through `runtime.settingsTransfer` acceptance evidence.
+
+When settings transfer and editable-output canvas sizing are both enabled, 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 app-authored sections, rename the controls, or rebuild the block by hand.
+
+If only `Export Settings` and `Import Settings` appear in that section, the schema is not using `editable-output` canvas sizing or already owns `canvas.size.width` / `canvas.size.height` controls. For product-output apps, prefer fixing the canvas sizing decision over adding hand-built size fields.
+
+Reset belongs to the controls panel header reset button. Do not add a footer action with `label`, `value`, or `command` containing reset; acceptance treats that as a duplicate Reset.
+
+Still-output product apps include one primary `Export PNG` action.
+
+Animated product apps include `Export Video` as the primary action and `Export PNG` as the secondary action.
+
+Animated product apps with `Export Video` include a separate `Video Export` section. That section must contain:
+
+- `export.video.format` as a `select`, with default value `mp4` and baseline options `mp4` and `webm`;
+- `export.video.resolution` as a `select`, with default value `current` and options such as `current` and `4k`.
+
+Place `Video Export` as the final authored controls section directly above sticky footer export buttons. `Format` and `Resolution` are one compact workflow pair: render them in a two-column inline row by default. Use stacked rows only when a label or selected value would clip, truncate, or lose internal padding, and record that fallback reason in the spec or worklog. Do not use `segmented` for this pair unless the product has a deliberately tiny fixed output menu and browser tests prove every cell keeps padding.
+
+Do not put video export format/resolution controls inside effect, renderer, animation, or output-background sections. `MOV` and `ProRes` are not baseline browser outputs; use them only with an explicit encoder/transcoder and dedicated acceptance plus performance coverage.
+
+Add `Copy PNG` only when clipboard output is part of the product. Copy never replaces export. If two footer actions are needed, secondary/outline goes left and primary goes right. Footer actions must be one compact horizontal group, not stacked full-width rows. If an odd number of actions leaves one action alone in the final row, that final action spans the full row.
+
+Async footer actions return the real Promise from `ToolcraftApp onPanelAction`. Export, download, copy, generate, and apply must not run as fire-and-forget work; the runtime uses the returned Promise to show the sticky footer top accent indicator only while the operation is pending. Use `reportProgress(0..1)` from `onPanelAction` for determinate progress. Video export reports frame-based render/encode progress, and PNG export reports phase progress when render/blob/handoff are asynchronous.
+
+Do not place product action buttons on the canvas or in the renderer.
+
+## Canvas Handles
+
+Use product editing handles only when direct manipulation is better than panel-only editing: gradient stops, focus points, light vectors, crop bounds, mask points, transforms, bezier anchors, or perspective corners.
+
+Handles are visual overlays, not app UI. They must be textless, tokenized, bound to runtime state, and excluded from export/copy output.

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

@@ -0,0 +1,71 @@
+# Custom Controls
+
+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`, and `panelActions`.
+
+Register custom renderers through `ToolcraftApp controlRenderers`.
+
+Do not use `controlRenderers` to recreate a built-in control. If the product needs a slider, select, segmented mode picker, color input, gradient editor, font picker, upload, textarea, local action group, or footer action, declare the matching schema control instead of rendering the component manually.
+
+Do not edit `ControlsPanel`, copied `src/toolcraft`, or Toolcraft internals inside a generated app.
+
+Import custom renderer types from `@/toolcraft/runtime/react`.
+
+## Required Schema
+
+Custom control schemas still need:
+
+- `type`;
+- `target`;
+- `defaultValue`;
+- `label`;
+- `orderRole`;
+- acceptance coverage;
+- `customControlCoverage`;
+- `builtInFitCheck`;
+- browser coverage;
+- performance coverage when they can trigger product work.
+
+`builtInFitCheck` is required for every custom control acceptance row:
+
+```ts
+builtInFitCheck: {
+  checkedBuiltIns: ["fileDrop", "imagePicker", "select"],
+  closestBuiltIn: "fileDrop",
+  whyInsufficient:
+    "FileDrop imports source files, but it does not provide ordering, preview, remove, and density mapping in one runtime value.",
+  productObservable:
+    "Ordering uploaded glyphs changes the rendered glyph ramp output.",
+}
+```
+
+`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.
+
+## State Rules
+
+Custom renderers must write through the provided `setValue(nextValue, meta)` callback or existing runtime commands.
+
+Local-only custom control state is invalid unless it is transient draft, hover, focus, or drag state. Final product state belongs to the Toolcraft runtime.
+
+## Keyframes
+
+If a custom value is keyframe-capable, the renderer must work with runtime keyframes instead of local animation state. Store typed values in keyframes through runtime commands and consume `useToolcraftEvaluatedValues`, `useToolcraftEvaluatedValue`, `evaluateToolcraftTimelineValues`, or `evaluateToolcraftTimelineValue`.
+
+## Visual Rules
+
+Custom controls should use Toolcraft tokens, spacing, focus states, disabled opacity, and interaction patterns. A custom control should look like it belongs in the controls panel.
+
+Custom controls must render the minimum UI needed to understand the value, context, and available actions. Do not add decorative metadata or text that repeats the section title, control label, or obvious item state.
+
+Every visible custom-control element must justify its space by enabling selection, ordering, preview, removal, upload, editing, or a product-affecting status. If text is only nice-to-have, remove it.
+
+Use Toolcraft primitives for all custom-control chrome. Do not hand-style basic buttons, inputs, selects, sliders, scroll areas, or focus states.
+
+Custom controls may use primitives for app-specific chrome, but they must not duplicate toolbar, timeline, layers, canvas, panel, or built-in control mechanics.
+
+Choose element sizes from interaction need, not from how much content you want to fit. Glyphs, swatches, chips, and thumbnails can be compact, but destructive, reorder, upload, and primary actions must keep comfortable kit button or icon-button sizes.
+
+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.