@pixel-point/toolcraft 0.0.13 → 0.0.14

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.

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

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

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

@@ -1,5 +1,7 @@
 # Custom Controls
 
+> Reading route: start with `workflow.md`. Core generated-app rules live in `core/*`; this file is a focused custom-control reference for the topic below.
+
 Use a custom control only when no built-in Toolcraft control represents the product interaction.
 
 Built-ins come first: `slider`, `rangeSlider`, `select`, `segmented`, `switch`, `checkbox`, `color`, `colorOpacity`, `vector`, `gradient`, `curves`, `fontPicker`, `imagePicker`, `fileDrop`, `text`, `code`, `rangeInput`, `palette`, `actions`, `collectionActions`, and `panelActions`.

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

@@ -1,5 +1,7 @@
 # Performance
 
+> Reading route: start with `workflow.md`. Core generated-app rules live in `core/*`; this file is a focused performance reference for the topic below.
+
 Every visible non-action control needs a `performanceRole` and `performanceReason`.
 
 Performance coverage has two levels:

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

@@ -1,5 +1,7 @@
 # Renderer Technique
 
+> Reading route: start with `workflow.md`. Core generated-app rules live in `core/*`; this file is a focused renderer reference for the topic below.
+
 Choose render technology per product layer. Do not choose a renderer because it is convenient; choose it from product output semantics, reference behavior, fidelity, and workload.
 
 The initial renderer choice is provisional. It becomes accepted only after the app passes performance checks with the largest useful product canvas and the heaviest useful values for its own controls. If those checks show frame gaps, long tasks, viewport shaking, slow export, or interaction jank, revise the renderer strategy from that evidence before delivery. Do not make a renderer look fast by silently reducing the selected preview scale, backing pixels, source media quality, or export fidelity.