@pixel-point/toolcraft 0.0.14 → 0.0.15

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

@@ -0,0 +1,144 @@
+import { control, decisionCatalog } from "./component-contract-builders";
+import type { ToolcraftComponentContract } from "./types";
+export const TOOLCRAFT_MEDIA_CUSTOM_COMPONENT_CONTRACTS = {
+  fileDrop: {
+    ...control("fileDrop", "FileDrop", "standalone", "component-owned"),
+    decisionCatalog: decisionCatalog({
+      strictness: "exact-owner",
+      ownsValueModel: [
+        "source material upload",
+        "file import",
+        "media import",
+        "drop target",
+      ],
+      useWhen: [
+        "Use FileDrop for source material uploads, file import, or drag-and-drop media input.",
+      ],
+      doNotReplaceWith: [
+        "Do not place upload UI on the canvas.",
+        "Do not draw a custom canvas empty-state design, CTA, fake sample output, decorative placeholder, or agent-invented preset source while waiting for uploaded content.",
+        "Do not build custom file buttons for source media import.",
+      ],
+      acceptableAlternatives: [
+        "Use ImagePicker when users choose from built-in visual options rather than uploading a file.",
+      ],
+      layoutConstraints: [
+        "FileDrop lives in the controls panel; single-layer apps use its preview and clear behavior.",
+        "When fileDrop has assetKind: image and one image is present, the runtime renders image transform actions through the built-in actions-control directly below the uploader: 90° Right, Flip horizontal, and Flip vertical.",
+        "FileDrop image previews keep a stable preview frame when rotated or flipped. Rotated preview bitmaps use contain semantics inside that frame so the controls-panel preview never crops the image; canvas/product renderers may still use cover/crop when the uploaded image is source material.",
+        "When fileDrop has multiple: true and more than one image is present, the runtime renders a sortable four-column thumbnail grid with the add-more tile last.",
+        "When fileDrop has multiple: true and more than one image is present, image transform actions render only after the user selects a thumbnail, and they target only that selected image.",
+        "When fileDrop has assetKind: file, the runtime renders a sortable file list with a paperclip icon, filename, remove button, and row separators using --border/5.",
+      ],
+      requiredAcceptance: [
+        "Prove file import changes media state and product output; prove clear, reorder, rotate, flip, and section/global reset update source material.",
+      ],
+    }),
+    aiUsageRules: [
+      "Use fileDrop for source material uploads in the controls panel, not on the canvas.",
+      'Use fileDrop with assetKind: "image" for image-only source media and assetKind: "file" for arbitrary uploaded files.',
+      "If an app ships with predefined source files or background images, declare them as schema media.defaultAssets with sourceTarget matching the fileDrop control. They must render as ordinary attached files in fileDrop, not as hidden renderer constants or canvas placeholder artwork.",
+      "Predefined media files are default runtime state: users can remove them to get an empty source/canvas state, persistence may keep that removal with include: [\"media\"], and global or section Reset restores the default attached files.",
+      "When uploaded/imported content is part of the source-material flow, the canvas must not show agent-invented artwork, CTA text, fake sample output, decorative placeholders, or preset source designs before real content exists; keep the canvas neutral/runtime-backed and put upload affordance in fileDrop.",
+      "Do not add procedural Source Preset modes only to avoid an empty canvas. A default procedural or reference source is allowed only when the prompt/reference explicitly defines it and the worklog records that evidence.",
+      "In single-layer apps, the runtime shows the uploaded image as the fileDrop preview and provides the clear action.",
+      "In image mode, the runtime owns image transform actions: 90° Right, Flip horizontal, and Flip vertical. These actions render through the built-in actions-control in one three-column row with compact visible labels: 90°, Flip H, Flip V; keep a 6px vertical gap between the uploader and action row. Do not create a custom image action button grid. They update runtime mediaAssets transform metadata, and product preview/export must consume that metadata instead of keeping a separate transform state.",
+      "FileDrop panel previews are not product canvas rendering. Keep the preview frame height stable across image rotation/flip, and contain the rotated bitmap inside that frame so horizontal or vertical uploads are not cropped by the control.",
+      "When exactly one uploaded image is present, image transform actions are visible immediately. When multiple images are present, users select a thumbnail first; no transform actions render until a thumbnail is selected, and the action applies only to that selected image.",
+      "In file mode, the runtime shows uploaded files as a sortable list with paperclip icons, file names, remove buttons, and --border/5 separators.",
+      "In single-layer apps, global Reset controls and section reset must restore fileDrop source media to schema media.defaultAssets for that target; when no default asset exists, Reset removes uploaded media and returns the fileDrop target to defaultValue.",
+      "Use fileDrop with multiple: true when the app needs several uploaded images as one source set; do not build a custom thumbnail uploader for this.",
+      "When multiple uploaded images are present, the runtime appends media, shows a sortable four-column preview grid, puts the add-more tile last, and exposes per-image removal.",
+      "Canvas drops route to the first visible matching fileDrop target by asset kind: image files prefer image uploaders, non-image files prefer file uploaders, and file uploaders accept images only when no image uploader matches.",
+      "Dragging thumbnails reorders runtime mediaAssets; preview, export, and renderer mapping must consume that media order instead of maintaining a separate product-only order.",
+      "When uploaded images are used as canvas/background source material, draw them with cover/crop behavior: scale proportionally until the current canvas bounds are fully covered, keep the canvas size/settings unchanged, and crop overflow at the canvas bounds.",
+      "Do not create custom upload buttons, file lists, or file sorting for generic source uploads when fileDrop can represent the source set.",
+      "In multi-layer apps, deletion and visibility belong to the Layers panel; fileDrop remains an upload target.",
+    ],
+    commands: ["media.delete", "media.import", "media.reorder", "media.transform"],
+  },
+  imagePicker: {
+    ...control("imagePicker", "ImagePicker", "standalone", "component-owned"),
+    decisionCatalog: decisionCatalog({
+      strictness: "exact-owner",
+      ownsValueModel: [
+        "visual option choice",
+        "thumbnail selection",
+        "preset image choice",
+      ],
+      useWhen: [
+        "Use ImagePicker when users choose one visual option from a set of thumbnails or images.",
+      ],
+      doNotReplaceWith: [
+        "Do not recreate ImagePicker grids manually.",
+        "Do not show choices that the renderer treats as fallback or no-op.",
+      ],
+      acceptableAlternatives: [
+        "Use Select for non-visual named options.",
+        "Use FileDrop for user-uploaded source material.",
+      ],
+      layoutConstraints: [
+        "Runtime owns tile sizing by option count.",
+      ],
+      requiredAcceptance: [
+        "Prove each visible image choice changes product output or selected visual data.",
+      ],
+    }),
+    aiUsageRules: [
+      "ImagePicker owns thumbnail layout; pass the item list only and do not recreate the grid manually.",
+      "Every visible ImagePicker item must be actionable in the current product context.",
+      "Do not show selectable image choices that the renderer later sanitizes to a fallback or no-op.",
+      "If available choices depend on another control such as template, mode, or selected object, either make every visible item valid for every mode, split the choice into separate semantic controls, or ask the user before implementation.",
+      "A defensive invalid-value fallback is allowed, but it is not acceptance proof for a visible ImagePicker option.",
+      "Tests must choose each visible ImagePicker item and assert the selected image, texture, gradient, or exported pixels change in the product output.",
+      "Do not accept renderer data attributes, runtime target changes, or option existence as final proof that an image choice works.",
+    ],
+  },
+  customControl: {
+    decisionCatalog: decisionCatalog({
+      strictness: "custom-escape-hatch",
+      ownsValueModel: [
+        "product-specific interaction not expressible by built-in controls",
+      ],
+      useWhen: [
+        "Use custom controls only after checking all relevant built-ins and documenting why the closest built-in is insufficient.",
+      ],
+      doNotReplaceWith: [
+        "Do not use custom controls to recreate built-in controls, runtime panels, toolbar, timeline, layers, canvas, or sticky panel actions.",
+      ],
+      acceptableAlternatives: [
+        "Prefer built-in schema controls plus renderer logic whenever the value model fits an existing control.",
+      ],
+      layoutConstraints: [
+        "Custom UI must use Toolcraft primitives and minimal product-specific chrome.",
+      ],
+      requiredAcceptance: [
+        "Document rejected built-ins, prove runtime-state writes, and prove product output or command side effects.",
+      ],
+    }),
+    aiUsageRules: [
+      "Use custom controls only for product interactions that built-in controls cannot express.",
+      "Do not use a custom control to recreate a built-in Slider, RangeSlider, Select, Segmented, Switch, Checkbox, Color, ColorOpacity, Gradient, FontPicker, ImagePicker, FileDrop, TextInput, CodeTextarea, RangeInput, Palette, Actions, CollectionActions, Curves, AnchorGrid, ChannelMixer, Vector, or PanelActions control.",
+      "Every custom-control builtInFitCheck declares typed capabilities. Use collection, reorder, selection, commands, custom-interaction, custom-value-model, and custom-visualization to describe behavior without relying on product nouns.",
+      "When a custom control owns a growable, removable, selectable, or reorderable runtime item set, its builtInFitCheck must explicitly check collectionActions and actions before choosing custom; this is based on the value model and user workflow, not on entity names such as masks or glyphs.",
+      "Do not justify custom controls with icons, layout, styling, compactness, or custom buttons alone. The fit check must name the product interaction or value model that built-ins cannot express.",
+      "Custom controls may use Toolcraft primitives for small app-specific chrome, but must not import or render low-level runtime surfaces or duplicate toolbar, timeline, layers, canvas, panel, or built-in control mechanics.",
+      "Custom controls must render the minimum UI needed to understand the value, context, and available actions; avoid decorative metadata and text that repeats what the section, label, or visible item already explains.",
+      "Every visible custom-control element must justify its space by enabling selection, ordering, preview, removal, upload, editing, or status that affects the product.",
+      "Use Toolcraft primitives and tokens for all custom-control chrome; do not hand-style basic buttons, inputs, selects, sliders, scroll areas, or focus states.",
+      "Custom-control action buttons must be sized for the interaction. Do not shrink destructive, reorder, upload, or primary actions below comfortable kit button/icon-button sizes just to fit more text.",
+      "Choose preview sizes that match the product object scale. A glyph, swatch, chip, or thumbnail can be compact, but its actions and hit targets must stay readable and clickable.",
+      "If a custom item needs explanatory context, prefer concise labels such as Darkest, Mid tone, or Lightest; omit file names, long captions, and duplicated helper text unless they are required to distinguish items.",
+      "Acceptance and browser tests must prove custom-control interactions work through runtime state and product output, not only that custom markup rendered.",
+    ],
+    capabilities: ["controlRenderers", "runtime-state", "minimal-ui"],
+    commands: [],
+    historyPolicy: "patch",
+    id: "customControl",
+    kind: "control",
+    labelPolicy: "required",
+    schemaType: "controlRenderers",
+    stateMode: "controlled",
+    visualComponent: "CustomControlRenderer",
+  },
+} as const satisfies Record<string, ToolcraftComponentContract>;

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

@@ -0,0 +1,229 @@
+import { describe, expect, it } from "vitest";
+
+import { getToolcraftComponentContract } from "./component-contracts";
+
+describe("Toolcraft template component contracts: runtime and composition", () => {
+  it("documents app entity acceptance as product-output verification", () => {
+    const contract = getToolcraftComponentContract("appEntityAcceptance");
+
+    expect(contract.kind).toBe("composition");
+    expect(contract.stateMode).toBe("runtime-owned");
+    expect(contract.capabilities).toContain("product-output-verification");
+    expect(contract.aiUsageRules).toContain(
+      "Every app entity introduced by the AI must have an acceptance test that proves its product responsibility.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Compound control browser tests must explicitly exercise each required value part, not only one visible sub-control.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Acceptance tests must fail when an entity is disconnected from runtime state, renderer output, export output, or command side effects.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Do not accept typecheck, component existence, registered commands, runtime state mutation, renderer input objects, shader uniform presence, or signature strings as final proof.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "A generic canvas hash difference is not enough for workload or semantic controls; assert the intended direction of the effect.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Conditional entities require fixtures that make the condition observable.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Use visibleWhen for mode-, type-, source-, include-, variant-, or count-exclusive sections or controls that do not belong to the current selected state.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "If a switch/select/segmented/imagePicker/checkbox chooses a branch for the same product entity, controls outside the current branch use visibleWhen, not disabledWhen.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Do not leave inactive conditional controls visible while making the renderer ignore them.",
+    );
+  });
+
+  it("documents performance acceptance for custom renderer workload controls", () => {
+    const contract = getToolcraftComponentContract("performanceAcceptance");
+
+    expect(contract.kind).toBe("composition");
+    expect(contract.stateMode).toBe("runtime-owned");
+    expect(contract.capabilities).toContain("performance-budgets");
+    expect(contract.capabilities).toContain("workload-control-tests");
+    expect(contract.aiUsageRules).toContain(
+      "Custom renderers must define performance budgets for media import, preview updates, control drags, and export/copy before implementation.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      '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.',
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Performance matrices must declare rendererWorkload as none, simple-composition, text-output, vector-output, or pixel-output.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Renderer specs must include a Renderer Technique Decision Matrix with sourceRepresentation, productRepresentation, previewRenderer, exportRenderer, rendererWorkload, rendererStrategy, whyNotAlternativeStrategies, fidelityRisks, and performanceRisks.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Custom renderer apps must mirror the Renderer Technique Decision Matrix in typed rendererTechnique config so validation can reject contradictory renderer choices.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Editing handles must be DOM/SVG overlays, excluded from export, and written through runtime state instead of being drawn into the product raster layer.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Product foreground and editing handle renderer layers must declare uiSelector so browser tests can verify the visible layer exists.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      'productRepresentation "mixed" is valid only when rendererTechnique.layers proves at least two different content families.',
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Custom renderer apps must declare rendererPipeline with render passes, cache keys, execution location, preview/export quality, and interaction invalidation before implementation.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules.join("\n")).toMatch(/rendererTechnique/);
+    expect(contract.aiUsageRules.join("\n")).toMatch(/rendererTechnique\.layers/);
+    expect(contract.aiUsageRules.join("\n")).toMatch(/rendererPipeline/);
+    expect(contract.aiUsageRules.join("\n")).toMatch(/Render Pipeline Inventory/);
+    expect(contract.aiUsageRules.join("\n")).toMatch(/sourceRepresentation/);
+    expect(contract.aiUsageRules.join("\n")).toMatch(/productRepresentation/);
+    expect(contract.aiUsageRules.join("\n")).toMatch(/previewRenderer/);
+    expect(contract.aiUsageRules.join("\n")).toMatch(/exportRenderer/);
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "WebGL and WebGPU renderers must initialize contexts, programs, shaders, pipelines, textures, and large buffers once, then update uniforms or stable buffers when controls change.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Do not create WebGL/WebGPU contexts, shader programs, textures, or requestAnimationFrame loops directly in the React render path.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Animation loops must cancel scheduled frames during cleanup.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Performance matrices must declare rendererStrategy so tests can distinguish none, dom, svg, canvas-2d, webgl, and webgpu renderer paths.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+  });
+
+  it("documents reference runtime clone mode as a tested composition contract", () => {
+    const contract = getToolcraftComponentContract("referenceRuntimeClone");
+
+    expect(contract.kind).toBe("composition");
+    expect(contract.schemaType).toBe("transferMode");
+    expect(contract.visualComponent).toBe("canvasContent");
+    expect(contract.capabilities).toContain("reference-runtime-clone");
+    expect(contract.capabilities).toContain("reference-timeline-inventory");
+    expect(contract.aiUsageRules).toContain(
+      'Use transferMode: "reference-runtime-clone" when the user asks to port, clone, copy, or reproduce an existing app exactly.',
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Preserve the reference runtime as the source of truth instead of replacing it with a new renderer or timeline model.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Reference clone timeline choice is based on timeline behavior, not only on whether the reference draws a timeline-shaped UI.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      'Use referenceTimeline.mode "toolcraft-playback" for plain transport behavior such as play/pause, restart, duration/progress, loop, scrub, or export at time.',
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      '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.',
+    );
+    expect(contract.aiUsageRules).toContain(
+      "panels.timeline.defaultDurationSeconds must match referenceTimeline.loopDuration.seconds for referenceTimeline.mode toolcraft-playback/toolcraft-keyframes.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      '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.',
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+  });
+});

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

@@ -0,0 +1,76 @@
+import { describe, expect, it } from "vitest";
+
+import { getToolcraftComponentContract } from "./component-contracts";
+
+describe("Toolcraft template component contracts: runtime and composition", () => {
+  it("documents concise control label rules", () => {
+    const contract = getToolcraftComponentContract("controlLabels");
+
+    expect(contract.kind).toBe("composition");
+    expect(contract.visualComponent).toBe("ControlFieldLabel");
+    expect(contract.aiUsageRules).toContain(
+      "Control labels must be short UI names, usually one to three words.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Do not put explanations, formulas, units, parenthetical hints, or usage instructions in control labels.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Acceptance validators suggest semantic replacement labels for weak generic labels; fix the schema label instead of relying on runtime fallback rewriting.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Controls-panel section expand and collapse uses the standard runtime height/opacity animation; generated apps must not replace it with instant custom section visibility.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Section titles in one controls panel must be unique.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Bad: Grid Density (every Nth). Good: Grid Density, with Every 6th as the select option label.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Do not write label-recap descriptions such as Adjusts Opacity, Controls Speed, or Sets Background.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "If there is no useful product-specific explanation, omit control.description; the runtime should not show a help tooltip for that label.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.capabilities).toContain("control-description-tooltip");
+  });
+});

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

@@ -0,0 +1,135 @@
+import { describe, expect, it } from "vitest";
+
+import { TOOLCRAFT_COMPONENT_CONTRACTS } from "./component-contracts";
+
+describe("Toolcraft template component contracts: runtime and composition", () => {
+  it("preserves runtime panel commands for optional layers and timeline panels", () => {
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.layersPanel.commands).toContain("layers.reorder");
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.layersPanel.capabilities).toContain("selection");
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.layersPanel.aiUsageRules).toContain(
+      "Do not enable the layers panel for single-layer apps.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.layersPanel.aiUsageRules).toContain(
+      "When layers are enabled, layer-specific controls should target selectedLayer.* and apply to the currently selected runtime layer.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.layersPanel.aiUsageRules).toContain(
+      "Do not use selectedLayer.* targets when panels.layers is disabled; single-layer apps use app-specific targets.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.layersPanel.aiUsageRules).toContain(
+      "Layer-enabled apps need layerCoverage acceptance for selection, visibility, reorder, and grouping.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.layersPanel.aiUsageRules).toContain(
+      "Every selectedLayer.* control needs selected-layer-controls acceptance proving it edits the currently selected layer output.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.layersPanel.aiUsageRules).toContain(
+      "Layer browser coverage must use real LayersPanel rows and buttons, not direct layers.* command dispatch.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.layersPanel.aiUsageRules).toContain(
+      "Layer-enabled custom renderers need layers.interactions viewport-stability coverage around real selection, visibility, reorder or grouping, and selected-layer output checks.",
+    );
+
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.commands).toContain(
+      "timeline.setCurrentTime",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.commands).toContain(
+      "timeline.togglePlayback",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.commands).toContain(
+      "panels.setHidden",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.capabilities).toContain("keyframes");
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      "Any product output animation must enable the top Toolcraft timeline; do not ship animated product output with only local requestAnimationFrame playback.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      '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.',
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      '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.',
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      '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.',
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      '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.',
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      "When non-looping playback reaches the end, pressing Play again restarts playback from time 0.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      "Intrinsic-media upload timelines must stay paused at time 0 until source media exists; clearing the last media asset must pause and reset playback.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      "Do not put Pause or Resume in panelActions; playback belongs to TimelinePanel transport controls.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      "In keyframes mode, Toolcraft infers keyframe diamonds from control type; AI must not manually pick a smaller subset of slider/vector/color-style controls.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      "Keyframe state stores typed control values; valueLabel is display-only and must never be parsed by renderers or tests as the source of truth.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      "Custom renderers with keyframes must consume evaluateToolcraftTimelineValues or useToolcraftEvaluatedValues for keyframed settings instead of raw state.values for those targets.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      "Keyframe custom renderers must prove zoom, radar, and canvas viewport stability while expanding the timeline, creating keyframes, and scrubbing or playing the timeline.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      "Keyframe renderers must not re-decode media or re-upload source textures on timeline ticks, scrubs, playback, or evaluated setting changes.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      'Custom timeline UI is allowed only for explicit referenceTimeline.mode "custom-reference-timeline" transfers with browser-backed referenceTimelineCoverage.',
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      'When panels.timeline is enabled, runtime inserts a Setup switch labeled "Timeline" as the last runtime setup control after Resolution scale.',
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      "If timeline verification fails, wire the renderer to runtime timeline state or remove panels.timeline.",
+    );
+  });
+});