@pixel-point/toolcraft 0.0.12 → 0.0.14

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.

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

@@ -0,0 +1,83 @@
+# Performance
+
+Read this module before changing renderer technique, animation, canvas, media, export, render scale, heavy controls, or performance tests.
+
+## Verification Triggers
+
+Run a full performance checkpoint only when:
+
+- the first working product app version exists;
+- the user explicitly asks to optimize performance, fix lag, remove jank, speed up animation, stabilize drag/zoom, or otherwise complains about performance.
+
+After the first working version, feature loops do not run the full performance suite by default. Renderer, canvas, animation, export, timeline, layers, `canvas.renderScale`, bug fixes, and performance-sensitive controls still need targeted functional/browser checks first, plus targeted performance scenarios only when they directly exercise the touched workload, viewport, or export path.
+
+## Verification Tiers
+
+- Tier 0-1: targeted docs/typecheck/unit plus focused browser when visual.
+- Tier 2: `pnpm verify:quick` plus relevant browser acceptance.
+- Tier 3: `pnpm verify:quick`, targeted browser acceptance, and targeted performance scenarios for touched workload/viewport/export paths.
+- Tier 4: `pnpm verify:final`; for the first working product version also run and pass a browser performance checkpoint with the current AI agent's controlled browser when available, using `pnpm verify:perf` only as fallback.
+
+Record skipped full performance runs and reason in the verification note or worklog.
+
+## Workload Fixtures
+
+- Performance scenarios declare `stressFixture` for the tested control value.
+- Browser perf tests use `getToolcraftPerformanceStressValue(appPerformance, scenarioId)` so heavy-case tests cannot use toy values.
+- When the tested control is not itself the whole heavy source, declare `workloadFixture` and apply it first.
+- Numeric maximums, density, item counts, canvas/media size, and combined heavy states declare `loadProfile` with `hardLimit`, `smoothTarget`, and `smoothTargetRatio`.
+- Try the hard limit first.
+- Lower the guaranteed smooth target only in 10 percent steps with failed-measurement and optimization evidence.
+- Ranges above `smoothTarget` are experimental, not silently guaranteed.
+
+## Media And Pixel Workloads
+
+- Media import and image-processing workloads use realistic `kind: "media"` fixtures at least `1920x1080`-equivalent.
+- Heavy upload/preview tests must cover realistic source dimensions such as 2K/4K when the app accepts images.
+- Heavy pixel/media Canvas 2D must evaluate WebGL or WebGPU with measured evidence before staying on CPU.
+- Do not stay on CPU for millions of per-pixel operations on the main thread unless measurement proves it remains responsive and alternatives were evaluated.
+
+## Render Scale
+
+- Non-vector raster, Canvas 2D, WebGL, and WebGPU previews set `canvas.renderScale: true`.
+- Runtime `Resolution scale` defaults to `2` and changes backing pixels without changing CSS/output size.
+- Performance fixes must preserve selected render scale and visible output quality.
+- Do not downsample, blur, stretch low-resolution backing pixels, or clamp render scale below the user's chosen value to pass budgets.
+
+## Slider Responsiveness
+
+- Slider and range slider controls are live canvas controls.
+- Dragging a thumb updates runtime state and product output while the drag is in progress.
+- If live updates are slow, fix renderer path first:
+  - update uniforms or stable buffers;
+  - cache decoded media and expensive derived inputs;
+  - coalesce preview work to `requestAnimationFrame`;
+  - cancel stale async renders;
+  - move heavy work off React renders;
+  - change renderer strategy when measured evidence supports it.
+- Only at an extreme measured ceiling may the app use degraded live preview or delayed heavy refinement; even then, immediate canvas feedback is required.
+
+## Renderer Pipeline Inventory
+
+Custom renderer apps declare a typed `rendererPipeline`:
+
+- render passes;
+- cache keys;
+- execution location;
+- preview/export quality;
+- interaction invalidation;
+- control-to-pass mapping.
+
+Every performance-sensitive control maps to the pass it invalidates.
+
+## Optimization Evidence
+
+Optimization worklogs record:
+
+- bottleneck diagnosis;
+- renderer technique evaluated;
+- fixtures used;
+- measurements before and after;
+- rejected alternatives;
+- remaining risks;
+- why quality was preserved.

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

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

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

@@ -0,0 +1,53 @@
+# Runtime Boundary
+
+Read this module before changing app assembly, routes, runtime surfaces, custom renderers, canvas output, panels, toolbar, timeline, layers, or controls.
+
+## Required Runtime Shell
+
+- Build through `defineToolcraft`.
+- Render through `ToolcraftApp`.
+- Read `appSchema.assembly` before adding custom JSX. It lists the enabled runtime surfaces, capabilities, commands, and assumptions for the current app.
+- Keep app state in the Toolcraft runtime schema and runtime commands.
+- Keep route files thin: routes compose the schema-backed Toolcraft app and product renderers.
+- Do not replace Toolcraft with copied reference UI, route-local panels, standalone forms, or hand-built editor chrome.
+
+## Allowed Extension Points
+
+Use only these app-specific extension points unless you are intentionally changing the shared Toolcraft runtime:
+
+- schema controls;
+- schema `canvas`, `panels`, `toolbar`, `panelActions`, `persistence`, `media`, `assembly`, and transfer-mode metadata;
+- `canvasContent` for product output only;
+- `renderDefaultCanvasMedia={false}` only when a product renderer replaces the default media preview;
+- `controlRenderers` only for true custom controls that pass the built-in fit check;
+- `onPanelAction` for sticky product actions;
+- runtime commands and hooks.
+
+## Forbidden Rebuilds
+
+- Do not hand-compose `ToolcraftRoot`, `CanvasShell`, `ControlsPanel`, `LayersPanel`, `TimelinePanel`, `ToolbarPanel`, or panel containers in product routes.
+- Do not render built-in control components such as `SliderControl`, `SelectControl`, `ColorControl`, `GradientControl`, `FontPickerControl`, `FileDropControl`, or `PanelActionsControl` directly in app code.
+- Do not recreate controls, panels, toolbar, timeline, layers, canvas shell, drag handles, section headers, section reset, history, or runtime surfaces by hand.
+- If a shared behavior is wrong, fix the shared runtime/template source and regenerate or sync the copied Toolcraft source instead of patching one exported app.
+
+## Canvas Boundary
+
+- `canvasContent` contains product output only: WebGL, Canvas 2D, SVG, DOM product text, shaders, generated previews, export previews, or product editing handles.
+- App UI, CTAs, upload prompts, helper copy, placeholder instructions, buttons, menus, forms, and settings do not belong in `canvasContent`.
+- If upload/import is part of the source-material flow, the pre-content canvas stays neutral and runtime-backed. Upload affordance belongs in `fileDrop`.
+- DOM product text rendered inside `canvasContent` must be marked with `data-toolcraft-product-output` or `data-toolcraft-product-text` so tests and performance fixtures can target product output instead of app chrome.
+- Product editing handles must be textless overlays, write to runtime state, and stay out of export/copy output.
+- Preserve the runtime canvas backing. Product renderers may draw their own product background, but must not hide, replace, or make the Toolcraft canvas shell/backing transparent.
+
+## State Boundary
+
+- Bind every visible control to runtime schema state or a runtime command side effect.
+- Use `defaultValue` for resettable controls.
+- Use runtime commands such as `controls.reset`, `controls.resetTargets`, `media.import`, `media.delete`, `canvas.center`, `history.undo`, and `history.redo`.
+- Do not keep final product settings in isolated local React state when they need reset, persistence, import/export, keyframes, browser acceptance, or product export.
+
+## Generated App Source Boundary
+
+- Generated applications keep their public editing surface in `src/app/app-schema.ts` and app-specific files under `src/app` and `src/routes`.
+- Do not edit `src/toolcraft` in one generated app unless the task is intentionally changing the local copied runtime. Prefer fixing the monorepo runtime and regenerating or syncing.
+- Generated apps must not contain monorepo app/package folders, workspace-protocol dependencies, or workspace package imports.

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

@@ -0,0 +1,86 @@
+# Setup, Background, And Export
+
+Read this module before changing Setup, canvas sizing, background, image export, video export, sticky actions, render scale, or timeline visibility.
+
+## Runtime Setup
+
+- Runtime `Setup` is always the first visible controls block in generated product apps.
+- `Setup` is headerless, not collapsible, and has no section reset action.
+- `Setup` always contains `Export Settings` and `Import Settings`.
+- Do not implement settings import/export through `panelActions`, route-local file inputs, or app-authored controls.
+- Do not gate settings import/export by app complexity.
+- Product-output, exportable, shader, procedural, reference-clone, and uploaded-background/source apps use `editable-output`.
+- With `editable-output`, Setup contains `Aspect ratio`, `Canvas width`, and `Canvas height` after settings transfer.
+- App-authored sections must not declare runtime Setup targets: `runtime.settingsTransfer`, `canvas.aspectRatio`, `canvas.size.width`, `canvas.size.height`, `canvas.renderScale`, or `panels.timeline.extended`.
+
+## Canvas Size Defaults
+
+- When no explicit product size is provided, the default canvas size is `16:9` / `1920x1080`.
+- Runtime aspect presets apply canonical canvas sizes; `16:9` is `1920x1080`.
+- A prompt-provided, reference, fixed-format, or base/default size is only the initial `canvas.size`.
+- Fixed/reference/base dimensions are not reasons to hide `Aspect ratio`, `Canvas width`, or `Canvas height`.
+- Manual Canvas width/height edits keep the typed dimension, keep the other dimension unchanged, switch Aspect ratio to Custom, and show the reduced current ratio in the custom ratio inputs.
+
+## Resolution Scale
+
+- Non-vector raster, Canvas 2D, WebGL, and WebGPU previews set `canvas.renderScale: true`.
+- Runtime then appends `Resolution scale` after canvas sizing.
+- `Resolution scale` changes backing pixels from `1` to `2` without changing visible CSS size or product output dimensions.
+- DOM/SVG/vector-native previews should not use render scale.
+- Performance fixes must preserve the user's selected render scale. Do not pass budgets by silently downsampling, stretching a lower-resolution backing canvas, blurring output, or clamping render scale below the chosen value.
+
+## Timeline Setup Switch
+
+- When `panels.timeline` is enabled, runtime appends a `Timeline` switch as the last Setup control.
+- Off shows compact Play-only transport.
+- On shows the extended timeline with scrubber, duration, loop, and keyframe UI.
+- The switch controls runtime presentation only. It does not pause playback, change product values, remove keyframes, alter export, or reset with `Reset controls`.
+- When `panels.timeline` is omitted, the Timeline switch must not appear.
+
+## Background
+
+- Every product app exposes a required `Background` section directly before the first export settings section.
+- The section contains one equal-width inline row:
+  - `export.includeBackground` as a switch labeled `Include`;
+  - the product background color control with `label: false`.
+- Use a schema `color` target such as `appearance.background` or `scene.background`.
+- Do not hardcode a configurable background in CSS, Canvas `fillStyle`, or WebGL clear color.
+- Live preview calls `shouldIncludeToolcraftPreviewBackground(state)` and hides only the product-rendered background when Include is off.
+- PNG export passes the Include value to the standard PNG export helper.
+- Video export keeps the background even when Include is off.
+
+## Image Export
+
+- Every app with `Export PNG` exposes a separate `Image Export` section.
+- `Image Export` uses two `select` controls in one compact two-column inline row:
+  - `export.image.format`, default `png`, with baseline `PNG` and `JPG` options;
+  - `export.image.resolution`, default `4k`, with baseline `2K`, `4K`, and `8K` options.
+- Still-output apps place `Image Export` directly above sticky footer actions.
+- Animated apps with both image and video export place `Image Export` immediately before `Video Export`.
+- PNG export calls `createToolcraftPngExportCanvas({ includeBackground, resolution, state, render })`.
+- The selected `export.image.resolution` must produce real 2048/4096/8192px long-edge PNG output for 2K/4K/8K. Retina sizing is only the fallback for current/omitted resolution.
+
+## Video Export
+
+- Animated product apps expose `Export Video` and `Export PNG`.
+- Any app with `Export Video` must enable the top Toolcraft timeline.
+- Animated apps expose a separate `Video Export` section directly above sticky footer export buttons, after `Image Export`.
+- `Video Export` uses two `select` controls in one compact two-column inline row by default:
+  - `export.video.format`, default `mp4`, with baseline `MP4` and `WebM` options;
+  - `export.video.resolution`, default `current`, with baseline `Current` and `4K` options.
+- Stack the pair only when labels or selected values would clip, and record that fit reason in the worklog.
+- Use `MediaRecorder.isTypeSupported(...)` or an explicit encoder/transcoder capability check before choosing the actual MIME/container.
+- `MOV` and `ProRes` are not baseline browser outputs; use them only with a custom encoder/transcoder plus acceptance and performance coverage.
+- Use `getToolcraftVideoExportSize` for video dimensions. `current` uses current canvas/output size with even encoder-safe rounding; `4k` fits inside 3840x2160, preserves aspect ratio, and returns even dimensions.
+- Offline rendered-frame video export must write timeline-based timestamps. `canvas.captureStream()` plus `MediaRecorder` records wall-clock time and cannot be the only duration mechanism for heavy renderers.
+- Browser acceptance must load the exported blob as a video, wait for metadata, and compare `video.duration` with the runtime timeline duration.
+
+## Sticky Product Actions
+
+- Product apps always expose export in sticky `panelActions`.
+- Still products expose `Export PNG`.
+- Animated products expose `Export Video` plus `Export PNG`.
+- Clipboard copy is optional and never replaces export.
+- Export PNG and Export Video use `icon: "upload-simple"` to match the runtime `Export Settings` action.
+- Async export/download/copy/generate/apply handlers return the real Promise from `onPanelAction`. The runtime shows the sticky footer top accent indicator while the Promise is pending.
+- Use `reportProgress(0..1)` for determinate progress when available.