@pixel-point/toolcraft 0.0.13 → 0.0.14

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

@@ -1,48 +1,14 @@
 # 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:
+> Reading route: start with `workflow.md`. Core generated-app rules live in `core/*`; this file is a focused component reference for the topic below.
 
-- 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; if it is last, only the top 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 `collectionActions` for repeatable product entities whose actual item list can grow or shrink, such as colors, glyphs, symbols, points, rules, variants, object entries, or typography style entries. Use it instead of a count slider when the user edits the actual set. The item list must be runtime state that changes preview/export, not panel-only row chrome. The collection control shows the collection `label` on the left and remove/add icon buttons on the right. Homogeneous repeated items do not show visible per-item labels like `Color 1`, `Color 2`, `Item 1`, or `Item 2` when the collection label already names the group. Item controls should use built-ins such as `color`, `colorOpacity`, `text`, `select`, `segmented`, `slider`, `switch`, `checkbox`, `rangeInput`, or `fontPicker` before any custom renderer. Use `fontPicker` as the item control when each item is a text style or typography entity; do not split its owned fields into neighboring collection controls.
-- For a single `actions` button, the control label and the button label must not be identical. Keep the button as the command verb and make the control label a concise one- or two-word context such as `Ink wash`, `Palette action`, or `Current layer`.
-- If an `actions` control has a visible label, the label is always above the buttons. Do not use a side-label layout with buttons on the right.
-- Actions render in 50% cells: one button uses the left half, two buttons fill one row, and larger groups continue in two columns.
-- Do not stretch an odd trailing action full-width or center it; keep it in the left 50% cell.
-- Use `panelActions` for sticky final product actions such as export, copy, generate, apply, or download.
-
-When upload/import is part of the source-material flow, `fileDrop` owns the empty/upload state. Do not put a custom pre-upload design, CTA, helper copy, fake sample output, decorative placeholder, or agent-made source preset on the canvas. A default procedural/reference source is allowed only when the prompt or reference explicitly defines it and the worklog records that evidence. If the default source is a file, image, or background image, declare it in `media.defaultAssets` with `sourceTarget` matching the `fileDrop` control so it renders as an attached file rather than a hidden renderer constant.
-
-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.
+## Control Decision Catalog
 
-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`.
+Use `core/control-selection.md` for the built-in fit check, exact control owners, compound-control ownership, actions, collection actions, vector ownership, and the custom control gate.
 
 ## 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. If it is the last item, render only its top internal divider and remove the bottom 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.
-- `collectionActions` is a compound control when it shares a section with generated item controls, so it follows the same content-width divider rules. Place it at the start of the controlled section. Generated item controls still follow normal density rules: plain colors use equal 50% columns when they fit, while color+opacity items stay stacked.
+Use `core/layout.md` for section dividers and compound-control divider rules. Component-specific exceptions are documented in the relevant component sections below.
 
 ## Sliders
 
@@ -102,71 +68,21 @@ Standalone `select` controls render stacked and full-width: label above, dropdow
 
 Use a two-column inline row only for related short `select` pairs that tune one workflow or entity, such as export `Format` and `Resolution`. If either label or selected value clips, truncates, or loses internal padding, stack the pair and record the fit reason.
 
-## Sliders
-
-Slider and range slider controls are live canvas controls. Dragging a thumb must update runtime state and product output while the drag is in progress, not only on pointer release, blur, an Apply action, or a final commit. Browser acceptance should drag the real control and prove the canvas/product observable changes during the interaction.
+## Slider Responsiveness
 
-If live slider updates are slow, fix the renderer path first: update uniforms or stable buffers, cache decoded media and expensive derived inputs, coalesce preview work to `requestAnimationFrame`, cancel stale async renders, move heavy work off React renders, or change renderer strategy. Only in an extreme measured performance ceiling may the app use a degraded live preview or delayed heavy refinement; even then, the user must see immediate canvas feedback during drag and the worklog must record the evidence.
+Use `core/performance.md` for live slider responsiveness, renderer optimization, and browser evidence requirements.
 
 ## 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.
-
-Section splitting must preserve dependency cohesion. A selector that chooses a mode, type, source, variant, or include state stays with the controls it gates when they share the same product entity. Prefer internal compound-control dividers, tighter labels, or a more specific section title before moving a gated branch into a separate section.
-
-Every app-authored controls-panel body section must have a short meaningful visible title. Runtime-created `Setup` renders as the first visible headerless controls block with no title, reset action, collapse button, or collapsed state; 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.
-
-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 `Setup` is not collapsible; sticky footer `Export` sections are not collapsible.
-
-Ordinary section headers expose the runtime section reset action before the collapse button. It dispatches `controls.resetTargets` and restores only that section's control targets to their schema `defaultValue`.
-
-Runtime `Setup` and ordinary controls-panel body sections use 8px top spacing and 24px bottom spacing for their control content. Sticky footer action sections keep their dedicated spacing.
+Use `core/layout.md` for section grouping, dependency cohesion, headers, reset, collapse persistence, spacing, dividers, labels, inline rows, and color-row fit. Keep this page focused on component-specific behavior.
 
 ## 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.
-
-Decide color label visibility from the user's point of view and apply that decision to the whole semantic group. Omit per-item labels such as `Color 1`, `Color 2`, or `Color 3` when the colors only add variety to one shared palette/color bank such as `Accent Shades`, `Bead Colors`, or `palette.accent1..5`, even if sibling controls like `Spread`, `Mix`, or `Randomness` tune distribution. Do not mix labeled and unlabeled items inside one semantic color bank. Keep visible labels when each color edits a distinct user-facing entity or role, such as `Fill`, `Stroke`, `Background`, `Connector`, `Object`, or `Highlight`.
-
-Multiple related plain colors stay in the same section and render at most two per row. If the bank has an odd trailing plain `color`, the last color still keeps the same half-width footprint instead of stretching to a full 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 usually require label parity: every field in that row has a visible label. Toggle-plus-parameter rows are the section-owned exception: keep the `switch`/`checkbox` label visible and set the non-toggle parameter to `label: false`; if the parameter label is needed, stack the controls instead. All 50/50 inline rows use the same horizontal column gap as paired `select` controls; do not give toggle-plus-parameter rows a separate wider or narrower gap. The required `Background` section row uses the switch label `Include` beside the background color parameter with `label: false`. Palette variation color banks are the other exception when the group or section label already names the color bank.
-
-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 required `Background` section directly before the first export settings section. With PNG export, that first section is `Image Export`; with video-only export, it is `Video Export`. Use one equal-width inline row with `export.includeBackground` on the left and `appearance.background` on the right when no other fit rule is violated. The switch label is `Include`, not `Include background`; the background color control uses `label: false`. Each control occupies one half of the row; do not shrink the toggle column to intrinsic width. `export.includeBackground` controls PNG alpha and live preview product-background visibility through `shouldIncludeToolcraftPreviewBackground(state)`; it must not make the Toolcraft canvas shell/backing or video output transparent. Do not hardcode a configurable background in CSS, Canvas `fillStyle`, or WebGL clear color.
+Use `core/layout.md` for semantic color grouping, color labels, row fit, and color/opacity layout. Use `core/setup-export.md` for the required output `Background` section and export background behavior.
 
 ## File Upload
 
-Use `fileDrop` for source material uploads in the controls panel. Do not place upload UI on the canvas.
-
-Use `assetKind: "image"` for image-only source uploads and `assetKind: "file"` for arbitrary uploaded files. Image mode accepts images only by default. File mode accepts any file by default unless `accept` narrows the allowed extensions or MIME types.
-
-In single-layer apps, the runtime shows uploaded image preview and clear button in the file control. Clearing removes the attached source from the renderer and canvas. Global Reset controls and section reset restore `media.defaultAssets` for that fileDrop target; when no default asset exists, reset removes uploaded source material and returns the fileDrop target to `defaultValue`. If users can delete/reorder/transform predefined attached files and that state should survive reload, include `"media"` in schema persistence.
-
-In image mode, the runtime owns image transform actions directly below the uploader: `90° Right`, `Flip horizontal`, and `Flip vertical`. They render through the built-in actions-control in one three-column row with compact visible labels: `90°`, `Flip H`, `Flip V`; keep a 6px vertical gap between the uploader and action row. Do not create a custom image action button grid. With exactly one uploaded image, those actions are visible immediately. With multiple uploaded images, the user selects a thumbnail first; until then the actions are hidden, and once shown they apply only to the selected image. Product preview/export must consume `state.mediaAssets[].transform` rather than keeping separate image transform state.
-
-The FileDrop panel preview is not product canvas rendering. It keeps a stable preview frame across rotate/flip actions and contains the transformed bitmap inside that frame, so horizontal or vertical uploads are never cropped by the control preview. Canvas/product renderers may still use cover/crop when the uploaded image is source material.
-
-Use `multiple: true` when the app needs several uploaded images as one source set. The runtime appends media, switches to a sortable four-column thumbnail grid when more than one image is present, puts the add-more tile last, and keeps per-image removal inside the file control. Dragging thumbnails updates runtime media order; preview, export, and renderer mapping must consume that order instead of keeping a separate product-only order.
-
-In file mode, uploaded files render as a sortable list with a paperclip icon, filename, remove button, and `--border/5` separators. Do not build custom file lists, custom upload buttons, or custom sorting for generic source files when `fileDrop` can represent the source set.
-
-When an app contains both image and file uploaders, canvas drops route by asset kind. Image files prefer visible image uploaders; non-image files prefer visible file uploaders; file uploaders may accept images only when no image uploader matches. Product renderers must consume `state.mediaAssets` filtered by `sourceTarget` and runtime media order.
-
-When uploaded images are used as canvas/background source material, use `editable-output`, draw them with cover/crop behavior, scale proportionally until the current canvas bounds are fully covered, leave canvas dimensions and Setup controls unchanged, and crop overflow at the canvas bounds.
-
-In multi-layer apps, deletion and visibility belong to the Layers panel; `fileDrop` stays an upload target.
+Use `core/media-upload.md` for `fileDrop` ownership, image/file modes, multiple uploads, sorting, transform actions, canvas source images, default assets, and layer ownership.
 
 ## Image Picker
 
@@ -256,23 +172,7 @@ Use `code` / `CodeTextarea` as the base multiline content editor for any potenti
 
 ## 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.
-
-Do not add `description` to obvious color clusters. If a section title already names the palette/color context, sequential labels such as `Color 1`, `Color 2`, or simple palette controls such as `Spread` do not need help icons. Keep the whole obvious group clean unless the tooltip explains a non-obvious product behavior.
-
-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 a short contextual label such as `Include` or, only for icon-only visual toggles, `label: false` with 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. This row is always equal-width: each control occupies one half, using the same horizontal column gap as a paired `select` row. The non-toggle parameter uses `label: false`; if that parameter label is needed for clarity, stack the controls instead. Example: `Loop` plus an unlabeled duration field, or `Include` plus unlabeled background color inside the required `Background` section. If the section title already names the toggle context, shorten the toggle label instead of repeating the title.
+Use `core/layout.md` for label naming, help tooltip eligibility, switch/checkbox naming, toggle rows, and label parity. Component pages should add `description` only for non-obvious product behavior that the core layout rules allow.
 
 ## Layers
 
@@ -284,87 +184,11 @@ When Layers are enabled, browser tests must use the real LayersPanel UI: select,
 
 ## 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, export-at-time, or video export.
-- `timeline-keyframes`: editable diamonds, rows, easing, or keyframe evaluation.
-- `autonomous`: decorative or self-running output with no user-facing transport and no video export.
-
-Product output animation uses the top Toolcraft timeline. Use no timeline only for non-product autonomous decorative/self-running motion without video export, and declare `starterTransferMode.animationIntent.mode = "autonomous"` with coverage proving no play/pause, scrub, duration, loop, export-at-time, product animation, or video export behavior.
-
-Use playback timeline for play, pause, scrub, duration, loop, restart, export-at-time, or video export.
-
-When `panels.timeline` is enabled for a new Toolcraft app, `starterTransferMode.animationIntent` must match it: `mode: "timeline-playback"` for playback, or `mode: "timeline-keyframes"` for keyframes.
-
-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.
-
-Product animation loop means a seamless forward-only cycle by default. Motion advances in one direction, the first and last frames stitch without a visible jump, and mirror, yoyo, ping-pong, or reverse loops are allowed only when the user explicitly requests that behavior as a product mode.
-
-When the product has a known loop duration, declare it as `panels.timeline.defaultDurationSeconds`; the runtime timeline starts from that loop duration instead of an unrelated 8s default. Timeline animation intent must also declare `loopDuration` with `source`, `seconds`, and `evidence`. Valid sources are `reference`, `user-request`, and `product-derived`; runtime/template fallback 8s is not a valid source. `panels.timeline.defaultDurationSeconds` must match `animationIntent.loopDuration.seconds` so the initial timeline UI shows the declared product loop. Renderers may compute an initial loop 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 loop duration source of truth and renderer progress must map into it. Use `getToolcraftTimelineLoopTime` or `getToolcraftTimelineLoopProgress` to derive loop phase from `state.timeline.currentTimeSeconds` and `state.timeline.durationSeconds`; do not hand-roll wall-clock, fixed-duration, mirror, yoyo, ping-pong, or reverse phase math. Changing duration must preserve seamless forward-loop semantics: one complete cycle maps from `0` to `state.timeline.durationSeconds`, the first and last frames still stitch, direction does not reverse, and the renderer must not switch to wall-clock time or a fixed local duration.
-
-For reference-runtime-clone apps that map reference transport to the Toolcraft timeline, the same duration proof lives on `starterTransferMode.referenceTimeline.loopDuration`. `referenceTimeline.mode: "toolcraft-playback"` or `"toolcraft-keyframes"` must declare `loopDuration` with source, seconds, and evidence, and `panels.timeline.defaultDurationSeconds` must match it. Do not let a reference clone inherit the runtime/template 8s default unless the reference or user request actually proves an 8s loop.
-
-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.
+Use `core/timeline-animation.md` for animation intent, playback/keyframe timeline choice, forward seamless loop rules, duration mapping, keyframe evaluation, viewport interaction performance, and video export timing.
 
 ## Panel Actions
 
-Use `panelActions` only for sticky footer product actions such as Generate, Apply, Export, Copy, or Download.
-
-Generated apps keep a controls panel so runtime `Setup` is visible from the first run. Settings import/export is mandatory runtime `Setup` behavior there; do not add Import Settings or Export Settings to sticky footer `panelActions`; the runtime inserts them in the first visible headerless `Setup` controls block and imports/exports control values, canvas size, and timeline state.
-
-Do not gate settings import/export by complexity thresholds, app size, or prompt wording. Use schema `settingsTransfer` only to customize exported JSON identity or file name.
-
-When editable-output canvas sizing is enabled, the first `Setup` runtime section contains `Export Settings`, `Import Settings`, `Aspect ratio`, `Canvas width`, `Canvas height`, optional `Resolution scale`, and optional `Timeline` in that order. Do not split these into separate app-authored sections, rename the controls, rebuild the block by hand, or declare runtime Setup targets in product sections. App-authored controls targeting `runtime.settingsTransfer`, `canvas.aspectRatio`, `canvas.size.width`, `canvas.size.height`, `canvas.renderScale`, or `panels.timeline.extended` are invalid and never suppress the mandatory runtime controls.
-
-If only `Export Settings` and `Import Settings` appear in that section, the schema is not using `editable-output` canvas sizing. For product-output apps, fix the canvas sizing decision instead of adding hand-built size fields. A reference, previous app, fixed-format baseline, or user-provided default size does not justify hiding size controls; keep those dimensions as editable `canvas.size` defaults.
-
-Manual `Canvas width` or `Canvas height` edits are exact output-size edits. They keep the other dimension unchanged, switch `Aspect ratio` to `Custom`, and update the custom ratio inputs to the reduced current ratio. Do not recreate the old behavior where typing one size field stays locked to the previous aspect preset.
-
-Enable `canvas.renderScale: true` for non-vector raster previews such as Canvas 2D, WebGL, or WebGPU output. Runtime adds a `Resolution scale` slider after canvas sizing; it defaults to `2` and lets users trade preview quality/performance without changing output size. Adding or enabling this slider requires targeted browser evidence that the canvas stays responsive while dragging sliders or other high-frequency controls at the selected scale. A full browser performance checkpoint is required for the first working product version and explicit performance complaints; use the agent-controlled browser first and `pnpm verify:perf` only as fallback. Performance fixes must preserve the selected scale and keep canvas preview responsive. Diagnose the actual bottleneck before lowering quality; do not silently downsample, stretch a lower-resolution backing canvas, blur output, or clamp `canvas.renderScale` below the user's chosen value. Do not enable it for DOM/SVG/vector-native previews.
-
-When `panels.timeline` is enabled, runtime adds a `Timeline` switch as the last Setup control. It is a runtime presentation preference only: off shows compact Play-only transport, on shows the extended TimelinePanel with scrubber, duration, loop, and keyframe UI. It does not change playback, keyframes, export, product values, settings transfer, or Reset controls. `persistence.include: ["panels"]` may restore it. If `panels.timeline` is omitted, the Timeline switch must not be shown.
-
-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.
-
-Export-labeled footer actions use `icon: "upload-simple"`, matching the runtime `Export Settings` button. Do not use `download`, `download-simple`, or `export` icons for `Export PNG` or `Export Video`.
-
-Every product app with `Export PNG` includes a separate `Image Export` section. That section must contain:
-
-- `export.image.format` as a `select`, with default value `png` and baseline options `png` and `jpg`;
-- `export.image.resolution` as a `select`, with default value `4k` and baseline options `2k`, `4k`, and `8k`.
-
-Place `Image Export` directly above sticky footer export buttons for still-output apps. For animated apps with both PNG and video export, place `Image Export` immediately before `Video Export`. `Format` and `Resolution` are one compact workflow pair: render them in a two-column inline row by default. Do not use `segmented` for this pair; it must visually match the Video Export dropdown structure.
-
-Animated product apps with `Export Video` must enable the top Toolcraft timeline and 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. Video exporters use `getToolcraftVideoExportSize`; do not hand-roll `4096` long-edge sizing for video. The `current` video option uses the current canvas/output size with even encoder-safe rounding. The `4k` video option fits inside 3840x2160, preserves aspect ratio, and returns even encoder-safe dimensions. Recorder/encoder errors must reject the export Promise instead of producing a corrupt blob.
-
-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.
+Use `core/setup-export.md` for mandatory runtime Setup, background, Image Export, Video Export, sticky product actions, export icons, and async progress. Use `core/control-selection.md` for choosing `actions` versus sticky `panelActions`.
 
 ## Canvas Handles
 

package/templates/starter/docs/toolcraft/core/control-selection.md

@@ -0,0 +1,93 @@
+# Control Selection
+
+Read this module before adding, replacing, grouping, or custom-rendering controls.
+
+## Built-In First
+
+- Choose controls by product value model before UI appearance.
+- Use built-in Toolcraft controls before custom controls.
+- If multiple built-ins can work, choose the closest one and record the reason.
+- If a built-in owner is discovered after a custom workaround, replace the workaround with the built-in.
+- Custom controls are allowed only after documenting checked built-ins and why the closest one is insufficient.
+
+## Control Selection Inventory
+
+Before writing schema controls, map every user-visible product setting or action:
+
+```txt
+Product need:
+Value model:
+Candidate built-ins checked:
+Best built-in:
+Why:
+Rejected alternatives:
+Target:
+Renderer/export mapping:
+Acceptance coverage:
+```
+
+This inventory can be in implementation notes, `starterControlSectionInventory`, or `docs/toolcraft/agent-worklog.md`, but the decision must exist before custom UI is introduced.
+
+## Exact Owners
+
+- Use `gradient` for adjustable gradients, color transitions, gradient fills, stops, type, and angle. Do not replace it with two `color` controls.
+- 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` only for stable manually-authored two-axis product parameters such as position, offset, direction, focus, anchor, light direction, white balance, color balance, chroma offset, or tone bias.
+- 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.
+- Use `actions` for local section commands that affect only the nearby entity.
+- Use `collectionActions` for repeatable product entities whose actual item list can grow or shrink.
+- Use `panelActions` for sticky final product actions such as export, copy, generate, apply, or download.
+
+## Compound Controls Are Atomic
+
+- `fontPicker` owns font family, weight, size, text case, text color/opacity, letter spacing, and line height.
+- `gradient` owns gradient type, angle, draggable stop track, and Stops list.
+- RGB `curves`, `channelMixer`, `palette`, and `collectionActions` are also compound controls.
+- Do not split owned fields into neighboring schema controls.
+- If a needed owned field is missing from a built-in, extend the kit instead of composing a parallel control.
+
+## Collection Actions
+
+- Use `collectionActions` when users edit the actual growable/shrinkable set: colors, glyphs, symbols, points, rules, variants, objects, style entries, or similar repeatable entities.
+- Adding/removing items must update runtime state and product preview/export.
+- Do not use a count slider plus hidden fixed item controls when the user needs to add or remove actual entities.
+- The collection control shows the collection label on the left and remove/add icon buttons on the right.
+- Homogeneous repeated items do not show visible per-item labels when the collection label already names the group.
+- Plain color items may use equal 50% columns; color+opacity items stay stacked.
+
+## Actions
+
+- Use schema `actions` for local section commands such as randomize palette, normalize weights, sort glyphs, clear selection, duplicate item, or reset current stop.
+- If there is one `actions` button, the control label and button label must not be identical. Keep the button as the command verb and make the label a concise context.
+- If an `actions` control has a visible label, the label is above the buttons.
+- Actions render in 50% cells: one button uses the left half, two buttons fill one row, and larger groups continue in two columns.
+- Do not stretch an odd trailing action full-width or center it.
+- Keep final product actions in `panelActions`, keep timeline transport in the top timeline, and keep global reset in the controls panel header.
+
+## Vector Ownership
+
+Use Vector only when the user is meant to manually author a stable two-axis product parameter.
+
+Before adding Vector to an animated or interactive product, classify movement ownership:
+
+- `direct-authored`: stable user-authored parameter such as light direction, focus, anchor, or object offset. This can be Vector.
+- `timeline-driven`: movement comes from playback/keyframes. Use timeline, speed, duration, path, step, or amplitude controls instead.
+- `keyboard/pointer-driven`: movement comes from user input on the canvas/app. Keep current position/direction in interaction state and expose only useful tuning controls.
+- `simulation-owned`: movement comes from physics/procedural state. Keep current pose/velocity internal and expose high-level tuning controls.
+
+Do not expose a pad for current animation state, keyboard movement, pointer movement, physics state, timeline phase, velocity, target pose, current pose, or simulated position/direction just because the internal value has `x` and `y`.
+
+## Custom Control Gate
+
+- Custom controls are for product interactions that built-ins cannot represent.
+- Custom controls must use Toolcraft primitives, tokens, spacing, typography, and action affordances.
+- Custom controls must expose the minimum UI needed to understand and operate the product value.
+- Every visible custom-control element must have a job: choose, order, preview, delete, upload, edit, or show useful status.
+- Remove file names, helper text, and captions that do not help distinguish items or explain state.
+- Do not make tiny item-level action buttons below kit comfort sizes.
+- Do not recreate built-in controls, panels, toolbar, timeline, layers, canvas shell, or runtime surfaces.

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

@@ -0,0 +1,104 @@
+# Controls Layout
+
+Read this module before changing sections, labels, helper icons, inline rows, dividers, action layouts, or panel density.
+
+## Sections
+
+- Build controls-panel sections from product entities and workflow stages, not component types.
+- Before writing controls, export `starterControlSectionInventory`. Each product section declares title, product entity or workflow stage, targets, and grouping reason.
+- Keep sections discrete. Two to seven product controls is the normal size.
+- Split sections that grow past seven controls or mix several meanings.
+- Do not reuse the same section title for multiple sections.
+- Bad titles: `Controls`, `Settings`, `Options`, `Sliders`, `Inputs`, `Buttons`, `Color`, `Colors`.
+- Good titles name the edited thing: `Background`, `Object`, `Token Pattern`, `Motion`, `Tone Mapping`, `Export`.
+- Every app-authored controls-panel body section has a short meaningful visible title.
+- Runtime `Setup` is the first visible headerless controls block. Sticky footer export actions render without a visible heading.
+
+## Dependency Cohesion
+
+- A selector that controls mode, type, source, variant, or include state stays with the controls it gates when they share the same product entity.
+- Use `visibleWhen` for inactive product branches so the panel shows only usable controls.
+- Do not create a separate section that merely mirrors one selector option unless that branch is a genuinely separate product entity with its own workflow evidence.
+- A section with no visible controls is hidden automatically.
+- Do not use `disabled: true` or `disabledWhen` for generated product controls.
+
+## Section Headers And Reset
+
+- Every visible section title renders through the standard 36px collapsible header row.
+- Do not hand-build section headers in generated apps.
+- Section expand/collapse uses the standard runtime height/opacity animation.
+- Collapsed/expanded state persists as per-app runtime UI preference.
+- Collapsed/expanded state is not undo/redo state, settings import/export state, or Reset controls state.
+- Ordinary section headers expose the runtime section reset action before the collapse button.
+- Section reset dispatches `controls.resetTargets` and restores only that section's targets to schema `defaultValue`.
+- Runtime `Setup` is not collapsible and has no reset action. Sticky footer export sections are not collapsible.
+
+## Section Spacing
+
+- Runtime `Setup` and ordinary body sections use 8px top spacing and 24px bottom spacing for control content.
+- Sticky footer action sections keep their dedicated spacing.
+- Do not add custom padding in generated apps to compensate for a local section issue. Fix the shared layout rule.
+
+## 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 compound-control content.
+- If the compound control is the first item in that section, render only its bottom internal divider and remove top internal padding.
+- If the compound control is the last item, render only its top internal divider and remove bottom internal padding.
+- If a section contains exactly one control, simple or compound, render only the parent section dividers.
+- Do not add full-width borders inside a compound control.
+- 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.
+
+## Labels And Help
+
+- Keep labels short but semantically sufficient with the nearest visible section/group context.
+- Put product-specific behavior help in schema `description`.
+- Runtime shows the help icon only when `description` adds meaning beyond the label.
+- Do not use descriptions that recap the label, such as `Adjusts Opacity`.
+- Do not add helper icons to obvious homogeneous groups when the section title and label already explain the control.
+- In toggle components, do not prefix labels with `Enable`; the switch already communicates on/off.
+- When a section title supplies the context, remove repeated nouns from nearby labels. For example, in `Background`, the switch label is `Include`, not `Include background`.
+
+## Inline Rows
+
+- Inline rows are allowed only when the controls are related, short, and preserve internal padding.
+- Every 50/50 inline row uses the same horizontal column gap as paired select controls.
+- Controls in a 50/50 row each occupy half the available content width.
+- If any label or value clips, truncates, or loses internal padding, stack the controls and record the fit reason.
+- Toggle-plus-parameter rows are allowed when the toggle enables/includes the same entity and the parameter is short. Keep the toggle label visible and set the non-toggle parameter `label: false`.
+- If the non-toggle parameter label is necessary, stack the controls instead.
+- Sliders and range sliders are full-width and do not sit in inline rows.
+- Segmented controls are full-width and do not sit beside Switch, Color, Select, or another control.
+- Standalone selects are full-width with label above dropdown. Use two-column select rows only for related short pairs such as export `Format` and `Resolution`.
+
+## Actions Layout
+
+- If an `actions` control has a visible label, the label is above the buttons.
+- One action button occupies the left 50% cell.
+- Two action buttons fill one row.
+- Larger groups continue in two columns.
+- Odd trailing actions stay in the left 50% cell.
+- Sticky footer `panelActions` use the sticky footer action layout, where a final odd action can span the full row.
+
+## Colors In Rows
+
+- First identify the semantic entity the color belongs to: background, object, connector, glow, tone mapping, brand, export, or named product object.
+- Keep color inside the entity 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 create a section titled `Color` or `Colors`.
+- Omit per-item labels such as `Color 1`, `Color 2`, or `Color 3` when colors only add variety to one shared palette/color bank.
+- Keep visible labels when each color edits a distinct user-facing entity or role.
+- Apply label visibility to the whole semantic color group; do not mix labeled and unlabeled items inside one bank.
+- Multiple related plain colors render at most two per row.
+- An odd trailing plain `color` keeps the same half-width footprint instead of stretching to full width.
+- If any color has opacity, keep it stacked instead of placing it in a two-column row.
+- `colorOpacity` owns color plus opacity for one entity and must not be split into color plus opacity slider/input.
+
+## Select And Segmented Fit
+
+- Standalone `select` controls render stacked and full-width.
+- Use compact two-column select layout only for related short pairs that tune one workflow or entity.
+- Segmented controls are full-width compact choices with at most four options, no option label longer than nine characters, and no more than twenty-four total option-label characters.
+- If segmented cells clip, collide, lose padding, or force labels into adjacent cells, shorten labels first. If compact labels still fail, use `select`.

package/templates/starter/docs/toolcraft/core/media-upload.md

@@ -0,0 +1,85 @@
+# Media Upload
+
+Read this module before changing image upload, file upload, source material import, media defaults, source images, sorting, or image transform actions.
+
+## FileDrop Ownership
+
+- Use `fileDrop` for source material uploads in the controls panel.
+- Do not place upload UI on the canvas.
+- Do not build custom file lists, custom upload buttons, or custom sorting when `fileDrop` can represent the source set.
+- Use `assetKind: "image"` for image-only source uploads.
+- Use `assetKind: "file"` for arbitrary uploaded files.
+- Image mode accepts images only by default.
+- File mode accepts any file by default unless `accept` narrows extensions or MIME types.
+
+## Empty Source State
+
+- When upload/import is part of the source-material flow, the empty product canvas stays neutral.
+- Do not invent canvas placeholder artwork, CTA copy, helper text, fake sample output, decorative placeholder, or agent-made source preset before real content exists.
+- A default procedural/reference source is allowed only when the prompt or reference explicitly defines it and the worklog records the evidence.
+
+## Image Uploads
+
+- In single-layer apps, the runtime shows uploaded image preview and clear button in the file control.
+- Clearing removes the attached source from the renderer and canvas.
+- With exactly one uploaded image, image transform actions are visible immediately.
+- With multiple uploaded images, users select a thumbnail first; until then transform actions are hidden.
+- Once selected, transform actions apply only to that selected image.
+- The FileDrop panel preview is not product canvas rendering. It keeps a stable preview frame across rotate/flip actions and contains the transformed bitmap inside that frame.
+- Horizontal or vertical uploads must not be cropped by the control preview.
+
+## Image Transform Actions
+
+- Runtime owns image transform actions directly below image uploaders.
+- Actions render through the built-in `actions` control, not through a custom image action grid.
+- Use one row of three compact action buttons:
+  - `90°` for rotate right;
+  - `Flip H`;
+  - `Flip V`.
+- Keep a 6px vertical gap between uploader and action row.
+- Product preview/export consumes `state.mediaAssets[].transform`.
+- Do not keep separate product-only image transform state.
+
+## Multiple Uploads And Sorting
+
+- Use `multiple: true` when the app needs several uploaded images or files as one source set.
+- Multiple image uploads render as a sortable four-column thumbnail grid.
+- The add-more tile is last.
+- Per-image removal stays inside the file control.
+- Dragging thumbnails updates runtime media order.
+- Product renderers and exports consume runtime media order instead of keeping a separate product-only order.
+
+## File Uploads
+
+- In file mode, uploaded files render as a sortable list with a paperclip icon, filename, remove button, and `--border/5` separators.
+- Long filenames fade/truncate at the end instead of hard-clipping.
+- The last item has no bottom separator.
+- The add row is part of the file control and uses the same width and hover behavior as list rows.
+- When an app contains both image and file uploaders, canvas drops route by asset kind:
+  - image files prefer visible image uploaders;
+  - non-image files prefer visible file uploaders;
+  - file uploaders may accept images only when no image uploader matches.
+- Product renderers filter `state.mediaAssets` by `sourceTarget`.
+
+## Canvas Source Images
+
+- Uploaded background/source images inside product canvases use `editable-output`.
+- Uploaded source images do not change `canvas.size`.
+- Setup canvas controls remain visible.
+- Draw source/background images as cover/crop inside current canvas bounds without letterbox or aspect distortion.
+- Scale proportionally until the current canvas bounds are fully covered, then crop overflow at canvas bounds.
+- Reserve `intrinsic-media` for true media-viewer/source-native products where imported media natural dimensions intentionally own `canvas.size`, and prove that with acceptance coverage.
+
+## Default Assets
+
+- Use `media.defaultAssets` when an app starts with predefined files, source images, masks, symbol sets, or background images.
+- Each default asset sets `sourceTarget` to the matching `fileDrop` target.
+- Runtime treats these as attached files: users see them in the uploader, can remove them, and Reset restores them.
+- If removal, reorder, or transforms of predefined media should survive reload, add `"media"` to `persistence.include`.
+- Do not mirror the file list into product `values`.
+- Do not hard-code default source files inside `canvasContent` or the renderer.
+
+## Layers
+
+- In multi-layer apps, deletion and visibility belong to the Layers panel.
+- `fileDrop` stays an upload target.