@pixel-point/toolcraft 0.0.14 → 0.0.15

package/templates/runtime/contracts/component-contracts.runtime-shell.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  TOOLCRAFT_COMPONENT_CONTRACTS,
+  getToolcraftComponentContract,
+} from "./component-contracts";
+
+describe("Toolcraft template component contracts: runtime and composition", () => {
+  it("keeps toolbar and controls panels behind PanelHost with their snap defaults", () => {
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.toolbar.requiredWrapper).toBe("PanelHost");
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.toolbar.defaultPlacement).toBe("bottom");
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.toolbar.snapEdges).toEqual(["top", "bottom"]);
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.toolbar.capabilities).toContain(
+      "keyboardShortcuts",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.toolbar.aiUsageRules).toContain(
+      "Toolbar history owns Undo and Redo buttons plus runtime keyboard shortcuts.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.toolbar.aiUsageRules).toContain(
+      "Do not add app-level Cmd/Ctrl+Z, Cmd/Ctrl+Shift+Z, or Ctrl+Y listeners; use toolbar history and runtime commands.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.toolbar.aiUsageRules).toContain(
+      "Undo/redo keyboard shortcuts must not fire while the user is typing into inputs, textareas, selects, or contentEditable value labels.",
+    );
+
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.controlsPanel.requiredWrapper).toBe("PanelHost");
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.controlsPanel.defaultPlacement).toBe("right");
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.controlsPanel.snapEdges).toEqual(["left", "right"]);
+  });
+
+  it("preserves canvas runtime commands and patch history", () => {
+    const contract = getToolcraftComponentContract("canvas");
+
+    expect(contract.kind).toBe("canvas");
+    expect(contract.stateMode).toBe("runtime-owned");
+    expect(contract.historyPolicy).toBe("patch");
+    expect(contract.visualComponent).toBe("CanvasShell");
+    expect(contract.commands).toContain("canvas.setSize");
+    expect(contract.commands).toContain("canvas.panBy");
+    expect(contract.commands).toContain("canvas.setOffset");
+    expect(contract.commands).toContain("media.import");
+    expect(contract.commands).toContain("media.transform");
+    expect(contract.capabilities).toContain("editable-size");
+    expect(contract.aiUsageRules).toContain(
+      "Do not let canvas.upload choose intrinsic-media by default. Upload without explicit sizing resolves to editable-output so source/background images do not own product output size.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Use intrinsic-media only for true media-viewer or source-native apps where the natural uploaded/generated media size is the product output; record the reason and prove it with intrinsic-media-size acceptance.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Use editable-output for generated, exportable, shader, poster, badge, wall, banner, thumbnail, procedural, reference-clone, and product-output apps so users always see Aspect ratio, Canvas width, and Canvas height.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "When an uploaded image is a background/source inside the product canvas, keep the current canvas.size, keep Setup/canvas controls visible, and render the image as cover/crop inside the current canvas bounds without letterbox or aspect distortion.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "A user-provided, reference, fixed-format, or base/default size is not a reason to remove size controls; model it as canvas.size plus editable-output so the size is an initial value, not a hidden lock.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Do not use fixed-output for generated product/output apps with export actions. Reserve fixed-output for non-product internal fixtures where width and height truly must never be user-editable, and prove that lock with canvasSizingCoverage fixed-output-size acceptance.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "A reference or previous app lacking a size editor, or defining a fixed-size baseline, is not a fixed-output reason for a generated product app; product-output clones still use editable-output.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Resolved canvas.size exists for every canvas app, but visible Canvas width and Canvas height controls are mandatory only for editable-output sizing and live in the mandatory runtime Setup section.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "If canvas.size is provided without an explicit sizing mode, defineToolcraft treats it as editable-output and adds Canvas width and Canvas height controls.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "The runtime Canvas width and Canvas height block uses the mandatory headerless Setup controls block; do not add a separate Canvas section label above these fields.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "When the user manually edits Canvas width or Canvas height, the runtime keeps the typed dimension, keeps the other dimension unchanged, switches Aspect ratio to Custom, and shows the reduced current ratio in the custom ratio inputs.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Aspect ratio presets are the only interaction that may resize both canvas dimensions from a preset; manual size inputs are exact output dimensions.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "For non-vector raster, Canvas 2D, WebGL, and WebGPU previews, set canvas.renderScale: true so the runtime adds Resolution scale after canvas sizing. The scale changes backing pixels from 1 to 2 without changing visible canvas size, and adding/enabling it requires targeted browser evidence that the canvas stays responsive at the selected scale.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "After enabling canvas.renderScale, verify that canvas preview stays responsive while dragging sliders and other high-frequency controls at the selected scale.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Performance fixes for canvas.renderScale must preserve the selected visual quality; do not silently downsample, stretch a lower-resolution backing canvas, blur output, or clamp canvas.renderScale below the user's chosen value to pass budgets.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Do not enable canvas.renderScale for DOM/SVG/vector-native previews; preserve vector fidelity through native vector rendering instead of raster supersampling.",
+    );
+  });
+
+  it("documents persistence as a runtime-owned policy instead of ad hoc localStorage", () => {
+    const contract = getToolcraftComponentContract("persistence");
+
+    expect(contract.kind).toBe("persistence");
+    expect(contract.stateMode).toBe("runtime-owned");
+    expect(contract.historyPolicy).toBe("never");
+    expect(contract.aiUsageRules).toContain("Do not write app state to localStorage directly.");
+    expect(contract.aiUsageRules).toContain(
+      "Use schema persistence policy for app state that should survive reload.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Persistence may include values, canvas, panels, timeline, layers, and media; history is not persisted.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Use persistence include: [\"media\"] only when runtime media state must survive reload, such as predefined attached files that users can delete, reorder, or transform. Do not use ad hoc storage for media state.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      'Apps with visible runtime panels and localStorage persistence must include "panels" so dragged panel positions survive reload.',
+    );
+    expect(contract.aiUsageRules).toContain(
+      'Apps with localStorage persistence must include acceptance coverage for changing a user setting, reloading the browser page, and seeing the restored value or product output.',
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Settings import/export is a mandatory runtime preset transfer feature; it must not be used to hide or replace broken persistence reload behavior.",
+    );
+  });
+
+  it("documents settings transfer as a mandatory runtime-owned feature", () => {
+    const contract = getToolcraftComponentContract("settingsTransfer");
+
+    expect(contract.kind).toBe("settings");
+    expect(contract.stateMode).toBe("runtime-owned");
+    expect(contract.aiUsageRules).toContain(
+      "Generated apps keep a controls panel so runtime Setup is visible from the first run; product controls are added after that mandatory runtime section.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Do not gate Export Settings / Import Settings behind complexity thresholds, app size, or prompt wording.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Do not hand-roll settings import/export through app routes, hidden file inputs, or panelActions.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Settings transfer appears in the first visible headerless Setup controls-panel block; it imports and exports control values, canvas size, and timeline state.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "App-authored sections must not declare runtime Setup targets such as runtime.settingsTransfer, canvas.aspectRatio, canvas.size.width, canvas.size.height, canvas.renderScale, or panels.timeline.extended; those controls never suppress the mandatory runtime Setup controls.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "When editable-output canvas sizing is enabled, the first visible Setup runtime section contains Export Settings, Import Settings, Aspect ratio, Canvas width, Canvas height, and optional Resolution scale in that order.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "When panels.timeline is enabled, Setup appends the Timeline switch as the last control; when panels.timeline is omitted, the Timeline switch must not appear.",
+    );
+  });
+});

package/templates/runtime/contracts/component-contracts.runtime.ts

@@ -0,0 +1,361 @@
+import { panel } from "./component-contract-builders";
+import type { ToolcraftComponentContract } from "./types";
+export const TOOLCRAFT_RUNTIME_COMPONENT_CONTRACTS = {
+  canvas: {
+    aiUsageRules: [
+      "Choose canvas.sizing.mode from product context instead of copying a universal 1024px artboard.",
+      "Do not let canvas.upload choose intrinsic-media by default. Upload without explicit sizing resolves to editable-output so source/background images do not own product output size.",
+      "Use intrinsic-media only for true media-viewer or source-native apps where the natural uploaded/generated media size is the product output; record the reason and prove it with intrinsic-media-size acceptance.",
+      "Use editable-output for generated, exportable, shader, poster, badge, wall, banner, thumbnail, procedural, reference-clone, and product-output apps so users always see Aspect ratio, Canvas width, and Canvas height.",
+      "When an uploaded image is a background/source inside the product canvas, keep the current canvas.size, keep Setup/canvas controls visible, and render the image as cover/crop inside the current canvas bounds without letterbox or aspect distortion.",
+      "When no explicit product size is provided, the runtime default canvas is 16:9 at 1920x1080; do not reset a new product-output app to 1:1 unless the product meaning requires it.",
+      "A user-provided, reference, fixed-format, or base/default size is not a reason to remove size controls; model it as canvas.size plus editable-output so the size is an initial value, not a hidden lock.",
+      "Do not use fixed-output for generated product/output apps with export actions. Reserve fixed-output for non-product internal fixtures where width and height truly must never be user-editable, and prove that lock with canvasSizingCoverage fixed-output-size acceptance.",
+      "A reference or previous app lacking a size editor, or defining a fixed-size baseline, is not a fixed-output reason for a generated product app; product-output clones still use editable-output.",
+      "Resolved canvas.size exists for every canvas app, but visible Canvas width and Canvas height controls are mandatory only for editable-output sizing and live in the mandatory runtime Setup section.",
+      "If canvas.size is provided without an explicit sizing mode, defineToolcraft treats it as editable-output and adds Canvas width and Canvas height controls.",
+      "The runtime Canvas width and Canvas height block uses the mandatory headerless Setup controls block; do not add a separate Canvas section label above these fields.",
+      "When the user manually edits Canvas width or Canvas height, the runtime keeps the typed dimension, keeps the other dimension unchanged, switches Aspect ratio to Custom, and shows the reduced current ratio in the custom ratio inputs.",
+      "Aspect ratio presets are the only interaction that may resize both canvas dimensions from a preset; manual size inputs are exact output dimensions.",
+      "For non-vector raster, Canvas 2D, WebGL, and WebGPU previews, set canvas.renderScale: true so the runtime adds Resolution scale after canvas sizing. The scale changes backing pixels from 1 to 2 without changing visible canvas size, and adding/enabling it requires targeted browser evidence that the canvas stays responsive at the selected scale.",
+      "After enabling canvas.renderScale, verify that canvas preview stays responsive while dragging sliders and other high-frequency controls at the selected scale.",
+      "Performance fixes for canvas.renderScale must preserve the selected visual quality; do not silently downsample, stretch a lower-resolution backing canvas, blur output, or clamp canvas.renderScale below the user's chosen value to pass budgets.",
+      "Do not enable canvas.renderScale for DOM/SVG/vector-native previews; preserve vector fidelity through native vector rendering instead of raster supersampling.",
+    ],
+    capabilities: ["drag", "zoom", "radar", "upload", "editable-size"],
+    commands: [
+      "canvas.setSize",
+      "canvas.panBy",
+      "canvas.setOffset",
+      "canvas.center",
+      "canvas.zoomIn",
+      "canvas.zoomOut",
+      "canvas.zoomReset",
+      "media.delete",
+      "media.import",
+      "media.reorder",
+      "media.transform",
+    ],
+    historyPolicy: "patch",
+    id: "canvas",
+    kind: "canvas",
+    schemaType: "canvas",
+    stateMode: "runtime-owned",
+    visualComponent: "CanvasShell",
+  },
+  persistence: {
+    aiUsageRules: [
+      "Do not write app state to localStorage directly.",
+      "Use schema persistence policy for app state that should survive reload.",
+      "Persistence may include values, canvas, panels, timeline, layers, and media; history is not persisted.",
+      "Use persistence include: [\"media\"] only when runtime media state must survive reload, such as predefined attached files that users can delete, reorder, or transform. Do not use ad hoc storage for media state.",
+      'Apps with visible runtime panels and localStorage persistence must include "panels" so dragged panel positions survive reload.',
+      'Apps with localStorage persistence must include acceptance coverage for changing a user setting, reloading the browser page, and seeing the restored value or product output.',
+      "Settings import/export is a mandatory runtime preset transfer feature; it must not be used to hide or replace broken persistence reload behavior.",
+      "Do not store media blobs, files, or large generated images in localStorage.",
+    ],
+    capabilities: ["themePreference", "appStatePolicy"],
+    commands: [],
+    historyPolicy: "never",
+    id: "persistence",
+    kind: "persistence",
+    schemaType: "persistence",
+    stateMode: "runtime-owned",
+    visualComponent: "none",
+  },
+  settingsTransfer: {
+    aiUsageRules: [
+      "Generated apps keep a controls panel so runtime Setup is visible from the first run; product controls are added after that mandatory runtime section.",
+      "Do not gate Export Settings / Import Settings behind complexity thresholds, app size, or prompt wording.",
+      "Do not hand-roll settings import/export through app routes, hidden file inputs, or panelActions.",
+      "Settings transfer appears in the first visible headerless Setup controls-panel block; it imports and exports control values, canvas size, and timeline state.",
+      "App-authored sections must not declare runtime Setup targets such as runtime.settingsTransfer, canvas.aspectRatio, canvas.size.width, canvas.size.height, canvas.renderScale, or panels.timeline.extended; those controls never suppress the mandatory runtime Setup controls.",
+      "When editable-output canvas sizing is enabled, the first visible Setup runtime section contains Export Settings, Import Settings, Aspect ratio, Canvas width, Canvas height, and optional Resolution scale in that order.",
+      "When panels.timeline is enabled, Setup appends the Timeline switch as the last control; when panels.timeline is omitted, the Timeline switch must not appear.",
+      "Keep sticky footer panelActions for product delivery actions only, such as Export PNG, Export Video, Copy, Generate, Apply, or Download.",
+    ],
+    capabilities: ["settings-import-export"],
+    commands: ["controls.setValue", "timeline.setCurrentTime", "timeline.setDuration"],
+    historyPolicy: "patch",
+    id: "settingsTransfer",
+    kind: "settings",
+    schemaType: "settingsTransfer",
+    stateMode: "runtime-owned",
+    visualComponent: "SettingsTransfer",
+  },
+  appEntityAcceptance: {
+    aiUsageRules: [
+      "Every app entity introduced by the AI must have an acceptance test that proves its product responsibility.",
+      "Compound controls must declare controlPartCoverage for every semantic value part required by their control type.",
+      "Compound control browser tests must explicitly exercise each required value part, not only one visible sub-control.",
+      "Acceptance tests must fail when an entity is disconnected from runtime state, renderer output, export output, or command side effects.",
+      "Do not accept typecheck, component existence, registered commands, runtime state mutation, renderer input objects, shader uniform presence, or signature strings as final proof.",
+      "Use product-level observables such as rendered pixels, exported image bytes, canvas hash, clipboard payload, cleared media preview, selected layer result, changed viewport, or timeline-rendered frame.",
+      "Any supplied video, GIF, screen-recording, contact-sheet, or extracted-frame reference requires a Video Reference Study before implementation: storyboard frames, frame-to-frame transition analysis, behavior decomposition, and acceptance mapping. Do not implement video references from a single screenshot or high-level summary.",
+      "A generic canvas hash difference is not enough for workload or semantic controls; assert the intended direction of the effect.",
+      "Component variants are accepted entities too; tests should fail if a non-default Toolcraft control variant falls back to the default variant or custom markup.",
+      "Conditional entities require fixtures that make the condition observable.",
+      "Use visibleWhen for mode-, type-, source-, include-, variant-, or count-exclusive sections or controls that do not belong to the current selected state.",
+      "When visibleWhen references a selector for the same product entity or selected branch, keep the selector and its dependent controls in one semantic section. A section that exists only because one selector option is active is not a separate product section just because the branch uses a standalone control.",
+      "When a count/quantity control determines how many sibling controls are available, hide unavailable siblings with visibleWhen; do not render all possible controls while the renderer reads only the first N.",
+      "If a switch/select/segmented/imagePicker/checkbox chooses a branch for the same product entity, controls outside the current branch use visibleWhen, not disabledWhen.",
+      "Do not use schema disabled: true or disabledWhen for generated product controls; the panel should show only controls usable in the current state. Runtime primitives may still have disabled styling internally, but app schemas should model product availability with visibleWhen.",
+      "Do not leave inactive conditional controls visible while making the renderer ignore them.",
+      "If an entity cannot be tested against a product-level observable, remove it from the app schema or ask whether it is required.",
+    ],
+    capabilities: ["acceptance-tests", "product-output-verification"],
+    commands: [],
+    historyPolicy: "never",
+    id: "appEntityAcceptance",
+    kind: "composition",
+    schemaType: "appEntityAcceptance",
+    stateMode: "runtime-owned",
+    visualComponent: "none",
+  },
+  performanceAcceptance: {
+    aiUsageRules: [
+      "Custom renderers must define performance budgets for media import, preview updates, control drags, and export/copy before implementation.",
+      "Controls that change renderer workload by changing output dimensions, element count, density, sample count, iteration count, blur/filter radius, shader branch cost, media processing, text layout, or export quality must be tested at min, default, and max values.",
+      "For workload control scenarios, stressFixture is the tested control value. If the app has an independent heavy baseline such as large media, long text, many items, high render scale, or dense source state, declare workloadFixture and apply it before the measured control interaction.",
+      "Hash differs is not enough for workload controls; tests must assert semantic direction, such as density increasing item count or size changes reducing/increasing rendered cells.",
+      "Performance tests must use representative fixtures and the same renderer/export path as the running app, not only tiny 32px fixtures or isolated helper state.",
+      "Every export-copy performance scenario must declare the exact panelActions actionValue, visible controlLabel, and completionEvidence it exercises; selectors, unrelated export actions, and injectable completion callbacks are not output evidence. The named browser scenario must resolve to test or it imported from @playwright/test, be statically registered at module scope or inside an executable test.describe, test.describe.serial, or test.describe.parallel suite, and directly await the matching unshadowed protected output-action helper in its root callback block without focus, skip, condition, or nesting; local test runners, uncalled or conditional test declarations, skipped/fixme suites, and runtime skip/fixme/fail annotations are invalid, and generated integrity protects the focused-test Playwright config.",
+      "Media-import workload fixtures and media workload baselines must use fixture kind \"media\" with numeric width and height at least 1920x1080-equivalent; 640x480 preview fixtures cannot satisfy upload, effect-control, or image-processing performance coverage.",
+      "Expensive renderers must cache decoded media, source pixels, glyph atlases, gradients, and other reusable inputs by media id, canvas size, and stable control keys.",
+      "Slider drags and high-frequency controls must debounce or coalesce preview work, cancel stale async renders, and avoid re-decoding media on every control change.",
+      "Performance matrices must declare rendererWorkload as none, simple-composition, text-output, vector-output, or pixel-output.",
+      "A full performance checkpoint must run only when the first working app version exists or the user requests performance, lag, jank, animation speed, drag/zoom stabilization work, or otherwise complains about performance; use the agent-controlled browser first and this app's verify:perf script only as the Playwright fallback.",
+      "Renderer, canvas, animation, export, timeline, layers, canvas.renderScale, bug fixes, and performance-sensitive control changes use targeted functional/browser checks first and targeted performance scenarios only for touched workload, viewport, or export paths.",
+      "Performance fixes must preserve selected output and preview quality; do not reduce image quality, selected renderScale, export resolution, source media fidelity, or canvas backing pixels as the hidden way to pass budgets.",
+      "When canvas or slider interactions lag, diagnose where the slowdown comes from before changing output quality: renderer technique, React update frequency, decoded media, shader/program setup, buffer uploads, layout work, async render cancellation, or animation scheduling.",
+      "Renderer specs must include a Renderer Technique Decision Matrix with sourceRepresentation, productRepresentation, previewRenderer, exportRenderer, rendererWorkload, rendererStrategy, whyNotAlternativeStrategies, fidelityRisks, and performanceRisks.",
+      "Custom renderer apps must mirror the Renderer Technique Decision Matrix in typed rendererTechnique config so validation can reject contradictory renderer choices.",
+      "Custom renderer specs must include a Renderer Layer Inventory and mirror it in typed rendererTechnique.layers so dense raster backgrounds cannot silently rasterize semantic foreground output.",
+      "Custom renderer apps must declare rendererPipeline with render passes, cache keys, execution location, preview/export quality, and interaction invalidation before implementation.",
+      "Render Pipeline Inventory must explain which runtime targets invalidate each expensive pass; high-frequency interactions such as animation frames, drag, zoom, pan, timeline playback, and mask movement must not invalidate upstream decode/preprocess/pixel-transform work unless that target truly changes the upstream result.",
+      "Cache-sensitive render passes such as decode, preprocess, pixel-transform, text-layout, rasterize, and composite must declare cache keys so tests can reject full recomputation on every control change.",
+      "Semantic foreground output such as product lines, shapes, icons, text, object bounds, and meaningful markers should use DOM or SVG by default; dense raster backgrounds do not justify rasterizing low-count foreground geometry or text.",
+      "Editing handles must be DOM/SVG overlays, excluded from export, and written through runtime state instead of being drawn into the product raster layer.",
+      "Product foreground and editing handle renderer layers must declare uiSelector so browser tests can verify the visible layer exists.",
+      'productRepresentation "mixed" is valid only when rendererTechnique.layers proves at least two different content families.',
+      "Choose renderer technique from product context, not convenience or novelty. Preserve reference renderer technology in reference-runtime-clone mode unless a concrete blocker and replacement acceptance tests are named.",
+      "Do not switch renderer technology just because it seems more modern or faster. Preview and export may use different renderers only when the decision matrix explains why and export/copy remains product-quality.",
+      "Choose renderer workload by product fidelity before choosing rendering technology: ASCII, glyph grids, code art, subtitles, typography, or monospace text products are text-output unless the product intentionally rasterizes them into per-pixel effects.",
+      "Text-output and vector-output visible previews must preserve native output fidelity. Do not render a low-resolution offscreen canvas or texture and upscale it to the product size.",
+      "Pixel-output renderers must treat WebGL/WebGPU as the default candidate even when the scene is static; Canvas 2D is allowed only when measured worst-case evidence shows the CPU path preserves quality and remains responsive.",
+      "Procedural pixel renderers, shader-like effects, animated mesh gradients, and large exportable previews should use WebGL or WebGPU for pixel work instead of main-thread ImageData loops.",
+      "Detail-heavy Canvas 2D pixel/media renderers may stay on CPU only when rendererTechnique records measured stress evidence for rejecting WebGL/WebGPU; if the heavy media stress fails, move pixel work to GPU instead of lowering quality.",
+      "WebGL and WebGPU renderers must initialize contexts, programs, shaders, pipelines, textures, and large buffers once, then update uniforms or stable buffers when controls change.",
+      "For keyframe or playback renderers, texture upload and media decode must be keyed to source media/resource changes, not to timeline time or evaluated settings. Timeline-only updates must reuse decoded media and existing GPU resources.",
+      "Do not create WebGL/WebGPU contexts, shader programs, textures, or requestAnimationFrame loops directly in the React render path.",
+      "Animation loops must cancel scheduled frames during cleanup.",
+      "Animated preview renderers must suspend or coalesce non-essential animation work while the user drags, pans, pinches, zooms, or centers the canvas viewport, then resume from the correct timeline or autonomous time without changing the user's play/pause state.",
+      "If a generated app uses ImageData, getImageData, or putImageData for procedural output, performance validation must fail unless rendererTechnique records measured WebGL/WebGPU comparison evidence that the CPU path preserves quality and responsiveness, or the renderer is moved to GPU.",
+      "Performance matrices must declare rendererStrategy so tests can distinguish none, dom, svg, canvas-2d, webgl, and webgpu renderer paths.",
+      "Browser verification must interact with the actual UI, exercise worst-case control values, and fail if the app freezes, creates runaway render loops, drops canvas zoom/offset, or misses the performance budget.",
+      "If a renderer cannot meet the budget, first optimize renderer technique, caching, invalidation, scheduling, and critical-path work. Only change exposed product ranges, work units, or controls after recording measured evidence that the requested quality ceiling is impossible; do not silently reduce product quality to pass budgets.",
+    ],
+    capabilities: ["performance-budgets", "workload-control-tests"],
+    commands: [],
+    historyPolicy: "never",
+    id: "performanceAcceptance",
+    kind: "composition",
+    schemaType: "performanceAcceptance",
+    stateMode: "runtime-owned",
+    visualComponent: "none",
+  },
+  referenceRuntimeClone: {
+    aiUsageRules: [
+      'Use transferMode: "reference-runtime-clone" when the user asks to port, clone, copy, or reproduce an existing app exactly.',
+      "Preserve the reference runtime as the source of truth instead of replacing it with a new renderer or timeline model.",
+      "Port requestAnimationFrame loops, refs, mutable particle/object state, connection state, spawn/update cadence, lifetime rules, pause/resume, export/copy, canvas sizing, and media lifecycle when the reference depends on them.",
+      "Keep Toolcraft as the shell: defineToolcraft, ToolcraftApp, schema controls, canvasContent, fileDrop, panelActions, and runtime commands.",
+      "Reference clone timeline choice is based on timeline behavior, not only on whether the reference draws a timeline-shaped UI.",
+      "If the reference has Play/Pause, Restart from beginning, current time/progress, duration, loop, scrub, selected range, trim handles, or video export timing, write a Reference Timeline Inventory before choosing a timeline mode.",
+      'Use referenceTimeline.mode "toolcraft-playback" for plain transport behavior such as play/pause, restart, duration/progress, loop, scrub, or export at time.',
+      'Use referenceTimeline.mode "toolcraft-keyframes" when controls need keyframe diamonds, expanded keyframe rows, easing, or editable keyframes.',
+      'Use referenceTimeline.mode "none" only when the reference has no user-facing transport behavior at all.',
+      "Reference clone specs must list every detected transport behavior explicitly, including pause-resume, restart, time-progress, export-at-time, playback, scrub, duration, loop, and keyframes when present.",
+      'Toolcraft reference timelines must declare referenceTimeline.loopDuration with source "reference", "user-request", or "product-derived", plus seconds and evidence; runtime/template fallback 8s is not a valid source.',
+      "panels.timeline.defaultDurationSeconds must match referenceTimeline.loopDuration.seconds for referenceTimeline.mode toolcraft-playback/toolcraft-keyframes.",
+      "Do not create right-panel controls named or targeted as Play, Pause, Paused, Animate, Restart animation, or equivalent app-wide transport toggles.",
+      'Do not downgrade custom reference timelines to panels.timeline mode "playback". State buttons, trim handles, selected-range playback, or range export require referenceTimeline.mode "custom-reference-timeline" and dedicated acceptance.',
+      "Generated reference clone apps must declare starterTransferMode.referenceTimeline with mode none, toolcraft-playback, toolcraft-keyframes, or custom-reference-timeline.",
+      "Custom reference timeline behavior needs referenceTimelineCoverage entries such as state-jump, trim-range, range-playback, all-range, jump-to-trim-start, and export-range.",
+      "Reference clone acceptance must include referenceCoverage rows for canvas sizing, control mapping, renderer state, and any renderer loop, spawn/update cadence, pause/resume, export/copy, or media lifecycle behavior in the reference.",
+      "Video reference assets used in a reference clone also require starterTransferMode.videoReferenceStudy with storyboard frames, frame-to-frame transition analysis, behavior decomposition, and acceptance mapping.",
+      "Browser tests must compare reference behavior or a reference-derived baseline, not only Toolcraft state mutation.",
+    ],
+    capabilities: [
+      "reference-runtime-clone",
+      "reference-behavior-acceptance",
+      "reference-timeline-inventory",
+      "canvasContent-renderer",
+    ],
+    commands: [],
+    historyPolicy: "never",
+    id: "referenceRuntimeClone",
+    kind: "composition",
+    schemaType: "transferMode",
+    stateMode: "runtime-owned",
+    visualComponent: "canvasContent",
+  },
+  controlLabels: {
+    aiUsageRules: [
+      "Control labels must be short UI names, usually one to three words.",
+      "Do not put explanations, formulas, units, parenthetical hints, or usage instructions in control labels.",
+      "A concise property label such as Speed, Color, Size, or Opacity is allowed when the nearest visible section or group clearly names the affected product entity.",
+      "When the section is generic, mixed, missing, or otherwise weak context, include the affected entity or role in the label: Pattern color, Background opacity, Wave speed, Stroke width.",
+      "Acceptance validators suggest semantic replacement labels for weak generic labels; fix the schema label instead of relying on runtime fallback rewriting.",
+      "Controls-panel sections should stay discrete: two to seven product controls is the normal size, and larger sections must split by product sub-entity or workflow stage.",
+      "Generated product apps must export starterControlSectionInventory beside acceptance. Every product controls section declares title, exact targets, groupingReason, and entity or workflowStage; intentional splits of one target entity require workflowStage and splitReason on every split section.",
+      "Section splitting must preserve dependency cohesion: a selector stays with the visibleWhen controls it gates when they share the same target entity or selected branch. Use internal spacing/dividers or a more specific section title before splitting dependent branch controls away.",
+      "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.",
+      "Every visible app-authored controls-panel section title renders through the standard 36px collapsible header row with vertically centered text and the runtime collapse icon; generated apps must not hand-build section headers.",
+      "Controls-panel section expand and collapse uses the standard runtime height/opacity animation; generated apps must not replace it with instant custom section visibility.",
+      "Controls-panel section collapsed/expanded state persists as a runtime UI preference per app. 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 controls-panel 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.",
+      "Broad section titles such as Flow, Icon, Shapes, Scene, Text, Typography, or Motion are only valid for small cohesive groups; use specific titles such as Flow Motion, Flow Geometry, Letter Burst, Shape Colors, Logo Glow, Logo Plate, or Text Block for larger groups.",
+      "Section titles in one controls panel must be unique.",
+      "Use section titles, option labels, tests, or renderer/spec prose for details instead of long field labels.",
+      "Bad: Grid Density (every Nth). Good: Grid Density, with Every 6th as the select option label.",
+      "Use control.description for the short help tooltip shown beside visible labels. It must describe the product behavior or output affected by the control, not restate the label.",
+      "Do not write label-recap descriptions such as Adjusts Opacity, Controls Speed, or Sets Background.",
+      "If there is no useful product-specific explanation, omit control.description; the runtime should not show a help tooltip for that label.",
+      "Do not add control.description to sequential colors such as Color 1, Color 2, or simple palette controls such as Spread when the section title already names the color or palette context.",
+      "For compound controls such as FontPicker, do not use control.description to enumerate the control's owned fields. FontPicker descriptions must not recap font family, weight, size, case, color, opacity, letter spacing, or line height; use description only for non-obvious product scope or omit it.",
+      "The runtime renders a filled Phosphor question icon beside each visible ControlFieldLabel; generated apps must not hand-build their own help icon beside built-in labels.",
+      "If a source label is unavoidably long, keep the visible label concise and rely on the native title tooltip for the full text.",
+    ],
+    capabilities: ["short-labels", "control-description-tooltip", "native-title-tooltip"],
+    commands: [],
+    historyPolicy: "never",
+    id: "controlLabels",
+    kind: "composition",
+    schemaType: "controlLabels",
+    stateMode: "runtime-owned",
+    visualComponent: "ControlFieldLabel",
+  },
+  controlsPanel: panel("controlsPanel", "ControlsPanel", "right", ["left", "right"], "handle"),
+  layersPanel: {
+    ...panel("layersPanel", "LayersPanel", "left", ["left", "right"], "handle"),
+    aiUsageRules: [
+      "Enable panels.layers only when the app needs editable layer selection, ordering, grouping, visibility, or multi-object media management.",
+      "Do not enable the layers panel for single-layer apps.",
+      "If the user intent is ambiguous, ask whether layer management is required before enabling panels.layers.",
+      "When layers are enabled, layer-specific controls should target selectedLayer.* and apply to the currently selected runtime layer.",
+      "Do not use selectedLayer.* targets when panels.layers is disabled; single-layer apps use app-specific targets.",
+      "Layer-enabled apps need layerCoverage acceptance for selection, visibility, reorder, and grouping.",
+      "Every selectedLayer.* control needs selected-layer-controls acceptance proving it edits the currently selected layer output.",
+      "Layer browser coverage must use real LayersPanel rows and buttons, not direct layers.* command dispatch.",
+      "Layer-enabled custom renderers need layers.interactions viewport-stability coverage around real selection, visibility, reorder or grouping, and selected-layer output checks.",
+    ],
+    capabilities: [
+      "draggable",
+      "snap",
+      "doubleClickReset",
+      "dragMode:handle",
+      "groups",
+      "selection",
+      "visibility",
+    ],
+    commands: [
+      "layers.add",
+      "layers.delete",
+      "layers.moveToGroup",
+      "layers.rename",
+      "layers.reorder",
+      "layers.select",
+      "layers.toggleCollapsed",
+      "layers.toggleVisibility",
+    ],
+  },
+  timelinePanel: {
+    ...panel("timelinePanel", "TimelinePanel", "top", ["top", "bottom"], "panel"),
+    aiUsageRules: [
+      "Any product output animation must enable the top Toolcraft timeline; do not ship animated product output with only local requestAnimationFrame playback.",
+      "Before choosing no timeline for any animated product, write an Animation Intent Inventory: product transport, editable keyframes, or autonomous decorative output, plus the user-facing time behaviors present or intentionally absent.",
+      'User-requested product animation defaults to panels.timeline mode "playback" unless the spec explicitly declares autonomous decorative/self-running output with no play, pause, scrub, duration, loop, export-at-time behavior, or video export.',
+      'Any product app with Export Video must enable the top Toolcraft timeline: use panels.timeline mode "playback" for product animation transport, or mode "keyframes" when exported animation is driven by keyframes.',
+      'Use panels.timeline: { mode: "playback" } when the product needs user-facing play, pause, scrubbing, duration, loop, restart, time progress, export-at-time controls, or video export.',
+      'When panels.timeline is enabled for a new Toolcraft app, appTransferMode.animationIntent must match it: mode "timeline-playback" for playback, or mode "timeline-keyframes" for keyframes.',
+      "Playback renderers must consume runtime timeline state; pause freezes output, scrubbing renders a deterministic frame, and the full animation cycle maps to state.timeline.durationSeconds instead of a local fixed duration.",
+      "When the product has a known loop duration, declare it as panels.timeline.defaultDurationSeconds; the runtime timeline duration starts from that loop duration instead of an unrelated 8s default.",
+      'Timeline animation intent must declare loopDuration with source "reference", "user-request", or "product-derived", plus seconds and evidence; runtime/template fallback 8s is not a valid source.',
+      "panels.timeline.defaultDurationSeconds must match animationIntent.loopDuration.seconds for playback/keyframe animation, so the initial timeline UI shows the declared product loop instead of a generic default.",
+      "Video export renderers must render deterministic frames from runtime timeline timestamps and duration; do not treat autonomous wall-clock time or captureStream recording time as the source of product duration.",
+      "Playback renderers may compute an initial loop duration default during app initialization or reset, but must not watch state.timeline.durationSeconds and dispatch timeline.setDuration back to a computed local duration. User-edited timeline duration becomes the loop duration source of truth after initialization or reset.",
+      "Playback renderers should use getToolcraftTimelineLoopTime or getToolcraftTimelineLoopProgress to derive product 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.",
+      "Product animation loop means a seamless forward-only cycle by default: motion advances in one direction, first and last frames stitch without a visible jump, and mirror/yoyo/ping-pong/reverse loops require explicit user request.",
+      "Changing timeline duration must preserve seamless forward-loop semantics: one full product animation cycle maps from 0 to state.timeline.durationSeconds, first and last frames still stitch, direction does not reverse, and changing duration must not switch the renderer to wall-clock or fixed local speed.",
+      "When non-looping playback reaches the end, pressing Play again restarts playback from time 0.",
+      "Intrinsic-media upload timelines must stay paused at time 0 until source media exists; clearing the last media asset must pause and reset playback.",
+      'Use panels.timeline: { mode: "keyframes" } or panels.timeline: true only when controls need keyframe diamonds, expanded timeline rows, easing, or keyframe editing.',
+      "In keyframes mode, Toolcraft infers keyframe diamonds from control type; AI must not manually pick a smaller subset of slider/vector/color-style controls.",
+      "Keyframe state stores typed control values; valueLabel is display-only and must never be parsed by renderers or tests as the source of truth.",
+      "Custom renderers with keyframes must consume evaluateToolcraftTimelineValues or useToolcraftEvaluatedValues for keyframed settings instead of raw state.values for those targets.",
+      "Every inferred keyframe-capable control must be evaluated from runtime timeline keyframes and needs acceptance proving diamond creation, row creation, keyframe updates, scrub/playback evaluation, and product output change.",
+      "Keyframe custom renderers must prove zoom, radar, and canvas viewport stability while expanding the timeline, creating keyframes, and scrubbing or playing the timeline.",
+      "Keyframe renderers must not re-decode media or re-upload source textures on timeline ticks, scrubs, playback, or evaluated setting changes.",
+      "Timeline-driven preview renderers must suspend or coalesce non-essential animation work during canvas drag, pan, pinch, zoom, and radar/center interactions without mutating the user's timeline play/pause state.",
+      "Use keyframeable: false only on controls that are structurally unsupported by the shared keyframe capability helper; capable controls cannot opt out to hide broken animation wiring.",
+      "Right-panel animation controls may tune renderer parameters such as mode, intensity, speed, or stagger only after animation intent is declared; they must not replace top timeline transport.",
+      "Do not put Pause or Resume in panelActions; playback belongs to TimelinePanel transport controls.",
+      "Do not replace TimelinePanel with an app-level playback, transport, or timeline panel to avoid runtime performance issues; fix the Toolcraft runtime clock/state path instead.",
+      'Custom timeline UI is allowed only for explicit referenceTimeline.mode "custom-reference-timeline" transfers with browser-backed referenceTimelineCoverage.',
+      'When panels.timeline is enabled, runtime inserts a Setup switch labeled "Timeline" as the last runtime setup control after Resolution scale.',
+      "The Timeline Setup switch controls only compact versus extended runtime presentation: off shows the compact Play-only transport, on shows the extended timeline with scrubber, duration, loop, and keyframe UI. It must not stop playback, change keyframes, affect export, enter product values, or be reset by Reset controls/settings transfer.",
+      "Playback-only timelines stay collapsed and do not show keyframe diamonds or expanded keyframe rows.",
+      "If timeline verification fails, wire the renderer to runtime timeline state or remove panels.timeline.",
+    ],
+    capabilities: [
+      "draggable",
+      "snap",
+      "doubleClickReset",
+      "dragMode:panel",
+      "duration",
+      "keyframes",
+      "playback",
+    ],
+    commands: [
+      "timeline.changeKeyframeEasing",
+      "timeline.deleteControlKeyframes",
+      "timeline.deleteKeyframe",
+      "timeline.moveKeyframe",
+      "timeline.selectKeyframe",
+      "panels.setHidden",
+      "timeline.setCurrentTime",
+      "timeline.setDuration",
+      "timeline.setPlaying",
+      "timeline.toggleLoop",
+      "timeline.togglePlayback",
+    ],
+  },
+  toolbar: {
+    ...panel("toolbar", "ToolbarPanel", "bottom", ["top", "bottom"], "panel"),
+    aiUsageRules: [
+      "Toolbar history owns Undo and Redo buttons plus runtime keyboard shortcuts.",
+      "Do not add app-level Cmd/Ctrl+Z, Cmd/Ctrl+Shift+Z, or Ctrl+Y listeners; use toolbar history and runtime commands.",
+      "Undo/redo keyboard shortcuts must not fire while the user is typing into inputs, textareas, selects, or contentEditable value labels.",
+    ],
+    capabilities: [
+      "draggable",
+      "snap",
+      "doubleClickReset",
+      "history",
+      "keyboardShortcuts",
+      "zoom",
+      "radar",
+    ],
+    commands: [
+      "history.undo",
+      "history.redo",
+      "canvas.center",
+      "canvas.zoomIn",
+      "canvas.zoomOut",
+      "canvas.zoomReset",
+    ],
+    kind: "toolbar",
+  },
+} as const satisfies Record<string, ToolcraftComponentContract>;