@pixel-point/toolcraft 0.0.8 → 0.0.11

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

@@ -82,12 +82,24 @@ describe("Toolcraft template component contracts", () => {
 
     expect(segmented?.strictness).toBe("best-fit");
     expect(segmented?.acceptableAlternatives?.join(" ")).toMatch(/Select/i);
+    expect(segmented?.layoutConstraints).toContain(
+      "Segmented controls are full-width controls and must not be placed in two-column inline or half-width layout groups.",
+    );
+    expect(getToolcraftComponentContract("segmented").aiUsageRules).toContain(
+      "Do not place Segmented beside Switch, Color, Select, or another control in an inline row; use Select when a finite choice must occupy a half-width column.",
+    );
     expect(select?.useWhen.join(" ")).toMatch(/long labels|many options/i);
+    expect(select?.useWhen).toContain(
+      "Use Select when a dropdown choice is more readable than a row of segmented cells.",
+    );
+    expect(select?.layoutConstraints).toContain(
+      "Standalone Select controls render stacked full-width with the label above the dropdown; do not use the compact side-label row with label left and dropdown right.",
+    );
     expect(select?.layoutConstraints).toContain(
-      "Prefer compact two-column inline layout for related short Select pairs that tune one workflow or entity.",
+      "Prefer compact two-column inline layout only for related short Select pairs that tune one workflow or entity.",
     );
     expect(select?.layoutConstraints).toContain(
-      "Use vertical one-select-per-row layout only as a fallback when a label, selected value, or option text would clip, truncate, or lose internal padding in the compact row.",
+      "Use vertical one-select-per-row layout for single Select controls and as the fallback when a Select pair label, selected value, or option text would clip, truncate, or lose internal padding in the compact row.",
     );
     expect(select?.layoutConstraints).toContain(
       "If a compact Select pair falls back to vertical layout, record the fit reason in the spec or worklog.",
@@ -150,6 +162,21 @@ describe("Toolcraft template component contracts", () => {
     expect(contract.aiUsageRules).toContain(
       'Use the default vector variant for spatial values such as position, offset, direction, focus, anchor, and light direction.',
     );
+    expect(contract.aiUsageRules).toContain(
+      'Default spatial vector pads use coordinateMode: "screen": dragging left/up makes vector.x and vector.y smaller so canvas objects move left/up without renderer-side Y inversion.',
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Vector pad value labels render compact rounded coordinates. Do not expose raw floating-point strings such as -0.07070312499999998 in the controls panel.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Double-clicking a vector pad resets both axes to the control default through the normal runtime value update, matching section header reset semantics; if no default is defined, the fallback is 0,0. Do not add a separate custom reset UI for this basic pad reset behavior.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Holding Shift while dragging a vector pad locks movement to the dominant axis and must not select text or page content; do not build a custom pad just to support axis-constrained movement.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      'Use coordinateMode: "cartesian" only when the product intentionally exposes mathematical Y-up coordinates instead of canvas/screen movement.',
+    );
     expect(contract.aiUsageRules).toContain(
       "Vector is a compound control; acceptance must prove vector.x and vector.y both affect the product output.",
     );
@@ -192,7 +219,7 @@ describe("Toolcraft template component contracts", () => {
       "When the nearest section title already names the switch context, do not duplicate that title as the visible switch label. Use label false for a visual-only toggle and keep the meaning in target/description.",
     );
     expect(switchContract.aiUsageRules).toContain(
-      'A Switch may share an inline row with one related parameter control when the visible switch label is short enough to fit. That row uses equal-width columns; never shrink the switch column to intrinsic width. In section-owned rows, use a short visible label such as "Include" instead of repeating the section title, such as "Include background" inside Background.',
+      'A Switch may share an inline row with one related parameter control when the visible switch label is short enough to fit. That row uses equal-width columns and the same horizontal column gap as paired Select controls; never shrink the switch column to intrinsic width. The non-switch parameter uses label false in that row; if its label is needed, stack the controls instead. In section-owned rows, use a short visible switch label such as "Include" instead of repeating the section title, such as "Include background" inside Background.',
     );
     expect(checkboxContract.aiUsageRules).toContain(
       'Checkbox labels name the setting context only; do not prefix labels with "Enable" or "Disable" because the checkbox already communicates enabled/selected state.',
@@ -207,7 +234,7 @@ describe("Toolcraft template component contracts", () => {
       "Two adjacent Checkbox controls for the same product entity must share one inline row when every visible label fits without truncation. Keep paired labels to short one- or two-word names; the runtime auto-pairs safe adjacent checkboxes by target entity, and generated schemas should stack checkboxes only when any label would truncate.",
     );
     expect(checkboxContract.aiUsageRules).toContain(
-      "A Checkbox may share an inline row with one related parameter control when the visible checkbox label is short enough to fit. That row uses equal-width columns; never shrink the checkbox column to intrinsic width. Hide the checkbox label when the section title provides the visible context.",
+      "A Checkbox may share an inline row with one related parameter control when the visible checkbox label is short enough to fit. That row uses equal-width columns and the same horizontal column gap as paired Select controls; never shrink the checkbox column to intrinsic width. The non-checkbox parameter uses label false in that row; if its label is needed, stack the controls instead. Hide the checkbox label when the section title provides the visible context.",
     );
   });
 
@@ -261,10 +288,28 @@ describe("Toolcraft template component contracts", () => {
       "Do not use Actions for animation transport; Play, Pause, Resume, Restart, and Scrub belong to the top timeline when timeline behavior exists.",
     );
     expect(contract.decisionCatalog?.layoutConstraints).toContain(
-      "When an Actions button group wraps below its label, the wrapped button row starts at the left edge of the control content instead of centering or staying right-aligned.",
+      "Do not set an Actions control label to the exact same visible text as its only button; use a short one- or two-word context label such as Ink wash, Palette action, or Current layer while the button keeps the command verb.",
+    );
+    expect(contract.decisionCatalog?.layoutConstraints).toContain(
+      "Actions never use a side-label layout. If a visible label exists, it sits above the buttons.",
+    );
+    expect(contract.decisionCatalog?.layoutConstraints).toContain(
+      "Actions buttons render as a two-column grid. One visible button occupies the left half of the section; two buttons occupy one half each; more than two buttons wrap into additional 50% cells.",
+    );
+    expect(contract.decisionCatalog?.layoutConstraints).toContain(
+      "Do not center or right-align a partial final Actions row; an odd trailing button stays in the left 50% cell.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "For a single visible Actions button, the control label and button label must not be identical; make the control label a concise context and the button label the command.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Render the Actions label above the buttons; do not put the label on the left with buttons on the right.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Render Actions buttons in 50% cells: one button uses the left half, two buttons fill one row, and larger groups continue in two columns.",
     );
     expect(contract.aiUsageRules).toContain(
-      "When an Actions button group no longer fits beside its label and wraps to a second row, align the wrapped button row to the left.",
+      "Do not stretch an odd trailing Actions button full-width.",
     );
     expect(contract.aiUsageRules).toContain(
       'For local reset-like actions, use product-specific values such as "reset-current-layer" or "reset-palette" and handle them through ToolcraftApp onPanelAction; do not use a bare "reset" value unless the action intentionally runs controls.reset.',
@@ -328,6 +373,12 @@ describe("Toolcraft template component contracts", () => {
     expect(contract.aiUsageRules).toContain(
       "Do not use Palette when opacity belongs to the same color entity; use ColorOpacity instead.",
     );
+    expect(contract.decisionCatalog?.requiredAcceptance).toContain(
+      "Prove Palette family and shade selections update runtime state immediately, before delayed persistence/commit settles.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Palette is a live control like Color and Slider: family and shade changes must update runtime state immediately so the next canvas interaction uses the selected token without waiting for delayed commit or persistence timers.",
+    );
     expect(contract.aiUsageRules).toContain(
       "Do not use Palette for gradients or color transitions; use Gradient instead.",
     );
@@ -369,27 +420,37 @@ describe("Toolcraft template component contracts", () => {
     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(
-      "Use intrinsic-media for single-layer upload/generation apps so imported media natural size becomes canvas.size.",
+      "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 by default for generated, exportable, shader, poster, badge, wall, banner, thumbnail, and product-output apps where users should see or edit width and height.",
+      "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(
-      "A user-provided base/default size is not a reason to remove size controls; model it as canvas.size plus editable-output unless the prompt or reference explicitly locks output dimensions.",
+      "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(
-      "Use fixed-output only when the product output size must not be user-editable, and prove that lock with canvasSizingCoverage fixed-output-size acceptance.",
+      "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(
-      "Resolved canvas.size exists for every canvas app, but visible Canvas width and Canvas height controls are mandatory only for editable-output sizing and do not depend on settingsTransfer.",
+      "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 technical Setup section and renders without a visible section heading; do not add a separate Canvas section label above these fields.",
+      "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.",
@@ -398,7 +459,7 @@ describe("Toolcraft template component contracts", () => {
       "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 1x to 2x without changing visible canvas size, and adding/enabling it requires targeted browser evidence that the canvas stays responsive at the selected scale.",
+      "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.",
@@ -422,7 +483,10 @@ describe("Toolcraft template component contracts", () => {
       "Use schema persistence policy for app state that should survive reload.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Persistence may include values, canvas, panels, timeline, and layers; history and media blobs are not persisted.",
+      "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.',
@@ -431,32 +495,35 @@ describe("Toolcraft template component contracts", () => {
       '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 preset transfer feature for complex apps; it must not be used to hide or replace broken persistence reload behavior.",
+      "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 runtime-owned complex-app feature", () => {
+  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(
-      'Use schema settingsTransfer: "auto" for complex apps unless the prompt explicitly disables settings import/export.',
+      "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(
-      "After adding, removing, or reorganizing controls, sections, timeline, or layers, recalculate settings-transfer eligibility. The runtime threshold is 12 product controls, 5 product sections, or weighted score 18.",
+      "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 as the first technical Setup controls-panel section when enabled and renders without a visible section heading; it imports and exports control values, canvas size, and timeline state.",
+      "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(
-      "A settings-transfer section with only Export Settings and Import Settings means canvas sizing is not editable-output or canvas size controls already exist elsewhere.",
+      "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 settings transfer and editable-output canvas sizing are both enabled, the first technical Setup runtime section contains Export Settings, Import Settings, Aspect ratio, Canvas width, Canvas height, and optional Resolution scale in that order and renders without a visible section heading.",
+      "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.",
     );
   });
 
@@ -464,6 +531,24 @@ describe("Toolcraft template component contracts", () => {
     const slider = getToolcraftComponentContract("slider");
     const rangeSlider = getToolcraftComponentContract("rangeSlider");
 
+    expect(slider.decisionCatalog.requiredAcceptance).toContain(
+      "Prove dragging the slider changes product output or the intended runtime side effect while the drag is in progress, not only after pointer release, blur, Apply, or a final commit.",
+    );
+    expect(slider.aiUsageRules).toContain(
+      "Sliders are live canvas controls: dragging must update runtime state and product output in real time by default.",
+    );
+    expect(slider.aiUsageRules).toContain(
+      "Do not implement slider values as deferred local drafts, Apply-only updates, pointer-up-only commits, or renderer changes that appear only after the user asks again.",
+    );
+    expect(slider.aiUsageRules).toContain(
+      "Slider performance coverage must use a real control-drag scenario; control-change coverage is not enough to prove live canvas feedback or drag smoothness.",
+    );
+    expect(slider.aiUsageRules).toContain(
+      "If a live slider causes jank, optimize the renderer path first: update uniforms or stable buffers, cache expensive inputs, coalesce preview work to requestAnimationFrame, cancel stale async renders, move heavy work off React, or switch renderer strategy.",
+    );
+    expect(slider.aiUsageRules).toContain(
+      "Only in an extreme documented performance ceiling may a slider use a degraded live preview or delayed heavy refinement; the user must still see immediate canvas feedback while dragging and the worklog must record the measured reason.",
+    );
     expect(slider.aiUsageRules).toContain(
       "Slider step means numeric snapping only; it does not make the slider visually discrete by itself.",
     );
@@ -480,16 +565,19 @@ describe("Toolcraft template component contracts", () => {
       "Large or precision stepped ranges such as speed, FPS, rate, duration, density, size, and intensity stay visually continuous even when they declare step.",
     );
     expect(slider.aiUsageRules).toContain(
-      "Use slider unit only for measurement or scale suffixes such as %, px, °, x, s, ms, fps, rows/cols, or similar domain units.",
+      "Use slider unit only for real measurement suffixes such as %, px, °, s, ms, fps, rows/cols, or similar domain units.",
     );
     expect(slider.aiUsageRules).toContain(
       "Do not use unit for repeated entity nouns already named by the section or label, such as Letters + letters, Shape Density / Count + shapes, Words + words, Symbols + symbols, Items + items, Particles + particles, or Layers + layers.",
     );
+    expect(slider.aiUsageRules).toContain(
+      'Do not use unit: "x"; scale, multiplier, intensity, opacity, strength, depth, and shader amount sliders display plain numbers unless a real measurement unit applies.',
+    );
     expect(slider.aiUsageRules).toContain(
       "When the value needs an entity noun to make sense, improve the label or section title instead of appending that noun as the value unit.",
     );
     expect(slider.aiUsageRules).toContain(
-      "Compact symbol/CSS units render tight, such as 70%, 24px, 1.2x, and 8s; word units render with a space, such as 5 cols, when they are truly needed.",
+      "Compact symbol/CSS units render tight, such as 70%, 24px, and 8s; word units render with a space, such as 5 cols, when they are truly needed.",
     );
     expect(slider.aiUsageRules).toContain(
       "Slider valueLabel is editable only when it contains a numeric value; textual state labels such as Normal are display-only and must not expose hover or click editing affordances.",
@@ -507,13 +595,31 @@ describe("Toolcraft template component contracts", () => {
       "Visual discrete sliders must still drag smoothly; browser performance tests should use expectToolcraftDiscreteSliderDragSmoothness for real pointer drag.",
     );
     expect(slider.aiUsageRules).toContain(
-      "Use schema disabled: true for unavailable sliders; do not recreate a disabled-looking slider with custom markup.",
+      "Use visibleWhen for sliders that are meaningful only in some mode/type/source/include/count states; inactive branches should disappear so the panel shows only controls usable in the current state.",
     );
     expect(slider.aiUsageRules).toContain(
-      "Use disabledWhen for sliders that are only meaningful in some mode values, such as Fill level and Islands being disabled when Fill mode is Full.",
+      "Do not use schema disabled: true or disabledWhen for product sliders; product panels should show only controls usable in the current state. Use visibleWhen for unavailable product states instead of rendering disabled controls.",
     );
     expect(slider.aiUsageRules).toContain(
-      "Do not leave a mode-dependent slider active while making the renderer ignore it; the UI must expose the unavailable state.",
+      "Do not leave an inactive conditional slider visible while making the renderer ignore it; hide it with visibleWhen.",
+    );
+    expect(rangeSlider.decisionCatalog.requiredAcceptance).toContain(
+      "Prove dragging rangeSlider.lower and rangeSlider.upper both affect product output while the drag is in progress, not only after pointer release, blur, Apply, or a final commit.",
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      "Range sliders are live canvas controls: dragging either thumb must update runtime state and product output in real time by default.",
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      "Do not implement range slider values as deferred local drafts, Apply-only updates, pointer-up-only commits, or renderer changes that appear only after the user asks again.",
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      "Range slider performance coverage must use a real control-drag scenario; control-change coverage is not enough to prove live canvas feedback or drag smoothness.",
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      "If a live range slider causes jank, optimize the renderer path first: update uniforms or stable buffers, cache expensive inputs, coalesce preview work to requestAnimationFrame, cancel stale async renders, move heavy work off React, or switch renderer strategy.",
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      "Only in an extreme documented performance ceiling may a range slider use a degraded live preview or delayed heavy refinement; the user must still see immediate canvas feedback while dragging and the worklog must record the measured reason.",
     );
     expect(rangeSlider.aiUsageRules).toContain(
       "Range slider step means numeric snapping only; it does not make the range slider visually discrete by itself.",
@@ -531,7 +637,7 @@ describe("Toolcraft template component contracts", () => {
       "Large or precision stepped ranges such as speed, FPS, rate, duration, density, size, and intensity stay visually continuous even when they declare step.",
     );
     expect(rangeSlider.aiUsageRules).toContain(
-      "Use rangeSlider unit only for measurement or scale suffixes; do not use it for repeated entity nouns already named by the section or label.",
+      "Use rangeSlider unit only for real measurement suffixes; do not use it for repeated entity nouns already named by the section or label, and do not use x as a unit.",
     );
     expect(rangeSlider.aiUsageRules).toContain(
       "When a range label needs an entity noun to make sense, improve the label or section title instead of appending that noun as the value unit.",
@@ -552,13 +658,13 @@ describe("Toolcraft template component contracts", () => {
       "Visual discrete sliders must still drag smoothly; browser performance tests should use expectToolcraftDiscreteSliderDragSmoothness for real pointer drag.",
     );
     expect(rangeSlider.aiUsageRules).toContain(
-      "Use schema disabled: true for unavailable range sliders; do not recreate a disabled-looking range slider with custom markup.",
+      "Use visibleWhen for range sliders that are meaningful only in some mode/type/source/include/count states; inactive branches should disappear so the panel shows only controls usable in the current state.",
     );
     expect(rangeSlider.aiUsageRules).toContain(
-      "Use disabledWhen for range sliders that are only meaningful in some mode values; keep the value so it returns when the mode becomes relevant again.",
+      "Do not use schema disabled: true or disabledWhen for product range sliders; product panels should show only controls usable in the current state. Use visibleWhen for unavailable product states instead of rendering disabled controls.",
     );
     expect(rangeSlider.aiUsageRules).toContain(
-      "Do not leave a mode-dependent range slider active while making the renderer ignore it; the UI must expose the unavailable state.",
+      "Do not leave an inactive conditional range slider visible while making the renderer ignore it; hide it with visibleWhen.",
     );
     expect(rangeSlider.aiUsageRules).toContain(
       "Acceptance must prove both rangeSlider.lower and rangeSlider.upper change the product output; testing one handle is not enough.",
@@ -590,7 +696,7 @@ describe("Toolcraft template component contracts", () => {
       "When one short numeric/text field and one Color field configure the same entity, keep them in one two-column inline layout group.",
     );
     expect(color.aiUsageRules).toContain(
-      'Mixed inline rows require visible labels on both controls. The required Background row is the section-title-owned exception: use the Switch label "Include" and set the background Color control label to false. Palette variation color banks are the other exception when the group/section label already names the color bank.',
+      'Mixed inline rows usually require visible labels on both controls. Toggle-plus-parameter rows are the section-owned exception: keep the Switch/Checkbox label visible and set the non-toggle parameter label to false; if the parameter label is needed, stack the controls instead. All 50/50 inline rows use the same horizontal column gap as paired Select controls. The required Background row uses the Switch label "Include" and sets the background Color control label to false. Palette variation color banks are the other exception when the group/section label already names the color bank.',
     );
     expect(color.aiUsageRules).toContain(
       "Plain Color popovers must not show opacity controls. If opacity is editable, use ColorOpacity instead.",
@@ -728,6 +834,9 @@ describe("Toolcraft template component contracts", () => {
     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.",
     );
@@ -747,16 +856,19 @@ describe("Toolcraft template component contracts", () => {
       "Conditional entities require fixtures that make the condition observable.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Use visibleWhen for mode-, type-, variant-, or count-exclusive sections or controls that do not belong to the current selected state.",
+      "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(
-      "Use disabledWhen for controls that belong to the current entity but are temporarily unavailable for the selected mode; the disabled value must be preserved.",
+      "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 and enabled while making the renderer ignore them.",
+      "Do not leave inactive conditional controls visible while making the renderer ignore them.",
     );
   });
 
@@ -792,7 +904,7 @@ describe("Toolcraft template component contracts", () => {
       "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 with pnpm verify:perf 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.",
+      "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 pnpm verify:perf 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.",
@@ -917,12 +1029,21 @@ describe("Toolcraft template component contracts", () => {
     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.",
+    );
   });
 
   it("documents concise control label rules", () => {
@@ -949,22 +1070,22 @@ describe("Toolcraft template component contracts", () => {
       "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/settings sections use the technical title Setup but render without a visible heading; sticky footer action sections use the technical title Export but render without a visible heading.",
+      "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 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.",
+      "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(
-      "Ordinary 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 technical Setup/settings sections and sticky footer Export sections are not collapsible.",
+      "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(
-      "Ordinary controls-panel body sections use 8px top spacing and 24px bottom spacing for their control content. Runtime technical Setup/settings sections use 12px top and bottom spacing to match side padding. Sticky footer action sections keep their dedicated spacing.",
+      "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.",
@@ -1054,21 +1175,51 @@ describe("Toolcraft template component contracts", () => {
     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(
-      "Do not enable the timeline panel just because a renderer is animated.",
+      "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, or export-at-time behavior.',
+      '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(
-      "Playback renderers may compute an initial default duration, but must not watch state.timeline.durationSeconds and dispatch timeline.setDuration back to a computed local duration. User-edited timeline duration is the source of truth after initialization or reset.",
+      '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.",
@@ -1112,6 +1263,12 @@ describe("Toolcraft template component contracts", () => {
     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.",
     );
@@ -1140,6 +1297,9 @@ describe("Toolcraft template component contracts", () => {
     expect(contract.aiUsageRules).toContain(
       "Product-output apps must always include export in panelActions.",
     );
+    expect(contract.aiUsageRules).toContain(
+      'Export-labeled panelActions use icon "upload-simple", matching the Setup "Export Settings" action; do not use "download", "download-simple", or "export" icons for Export PNG or Export Video.',
+    );
     expect(contract.aiUsageRules).toContain(
       "Static or still-output apps include Export PNG as the primary footer action.",
     );
@@ -1161,6 +1321,9 @@ describe("Toolcraft template component contracts", () => {
     expect(contract.aiUsageRules).toContain(
       "Animated apps include Export Video as the primary footer action and Export PNG as a secondary footer action.",
     );
+    expect(contract.aiUsageRules).toContain(
+      "Any app with Export Video must enable the top Toolcraft timeline; video duration, loop, and rendered timestamps come from runtime timeline state.",
+    );
     expect(contract.aiUsageRules).toContain(
       'Animated apps with Export Video must expose a separate "Video Export" controls section.',
     );
@@ -1191,6 +1354,12 @@ describe("Toolcraft template component contracts", () => {
     expect(contract.aiUsageRules).toContain(
       "Video export code must choose the actual MIME/container through MediaRecorder.isTypeSupported or an equivalent encoder capability check, then fall back safely.",
     );
+    expect(contract.aiUsageRules).toContain(
+      "Video export must use getToolcraftVideoExportSize for current and 4K dimensions. Current video export uses the current canvas/output size with even encoder-safe rounding; 4K video fits inside an encoder-safe 3840x2160 box, preserves canvas aspect ratio, and uses even pixel dimensions. Do not hand-roll 4096px long-edge video sizing.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Video export must set recording canvas dimensions before captureStream, MediaRecorder, VideoEncoder, or equivalent encoder setup, and must reject recorder/encoder errors instead of returning corrupt blobs.",
+    );
     expect(contract.aiUsageRules).toContain(
       "Offline video export duration must be encoded from runtime timeline timestamps. Do not rely on canvas.captureStream plus MediaRecorder wall-clock recording time as the only duration mechanism for rendered-frame export.",
     );
@@ -1213,7 +1382,7 @@ describe("Toolcraft template component contracts", () => {
       "PNG export must use createToolcraftPngExportCanvas so background transparency and selected image dimensions or retina fallback are applied consistently; turning Include off makes preview product background and PNG alpha transparent without hiding the Toolcraft canvas backing or video background.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Video export must keep product background and use getToolcraftRetinaExportSize for retina dimensions.",
+      "Video export must keep product background and use getToolcraftVideoExportSize for current/4K output dimensions.",
     );
     expect(contract.aiUsageRules).toContain(
       "Copy PNG can be a secondary action when clipboard output is useful, but copy does not replace export.",
@@ -1235,18 +1404,41 @@ describe("Toolcraft template component contracts", () => {
   it("documents file upload ownership across single-layer and multi-layer apps", () => {
     const contract = getToolcraftComponentContract("fileDrop");
 
-    expect(contract.commands).toEqual(["media.delete", "media.import", "media.reorder"]);
+    expect(contract.commands).toEqual([
+      "media.delete",
+      "media.import",
+      "media.reorder",
+      "media.transform",
+    ]);
     expect(contract.aiUsageRules).toContain(
       'Use fileDrop with assetKind: "image" for image-only source media and assetKind: "file" for arbitrary uploaded files.',
     );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
     expect(contract.aiUsageRules).toContain(
       "In single-layer apps, the runtime shows the uploaded image as the fileDrop preview and provides the clear action.",
     );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
     expect(contract.aiUsageRules).toContain(
       "In file mode, the runtime shows uploaded files as a sortable list with paperclip icons, file names, remove buttons, and --border/5 separators.",
     );
     expect(contract.aiUsageRules).toContain(
-      "In single-layer apps, global Reset controls and section reset must remove uploaded fileDrop source media and return the fileDrop target to defaultValue.",
+      "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.",
     );
     expect(contract.aiUsageRules).toContain(
       "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.",
@@ -1260,6 +1452,9 @@ describe("Toolcraft template component contracts", () => {
     expect(contract.aiUsageRules).toContain(
       "Dragging thumbnails reorders runtime mediaAssets; preview, export, and renderer mapping must consume that media order instead of maintaining a separate product-only order.",
     );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
     expect(contract.aiUsageRules).toContain(
       "Do not create custom upload buttons, file lists, or file sorting for generic source uploads when fileDrop can represent the source set.",
     );
@@ -1310,10 +1505,16 @@ describe("Toolcraft template component contracts", () => {
       "CodeTextarea is the multiline text input for any potentially long value, not only source code.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Use text for short single-line strings such as names, small numeric values, compact prompts, titles, and short tokens.",
+      "Do not use CodeTextarea for short single-line canvas text, button labels, names, titles, captions, badges, or short tokens; use TextInput.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Use text for short single-line strings such as names, button labels, small numeric values, compact prompts, titles, captions, and short tokens.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Use code when the user may enter long prompts, multiline text, JSON, CSS, shader code, scripts, templates, or other long structured data.",
+      "Use code only when the user may enter long prompts, multiline text, instructions, JSON, CSS, shader code, scripts, templates, or other long structured data.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "If CodeTextarea has a short single-line default value, the schema description must make the long, multiline, or structured-content reason explicit.",
     );
     expect(contract.aiUsageRules).toContain(
       "CodeTextarea is a content editor and applies values while typing; do not wait for blur, Enter, or Cmd/Ctrl+Enter to update runtime state.",
@@ -1329,6 +1530,9 @@ describe("Toolcraft template component contracts", () => {
     expect(contract.visualComponent).toBe("TextInput");
     expect(contract.defaultSectionLayout).toBe("grouped");
     expect(contract.labelPolicy).toBe("required");
+    expect(contract.aiUsageRules).toContain(
+      "TextInput owns short single-line product text: button labels, labels on the canvas, names, titles, captions, badges, short tokens, and compact prompts.",
+    );
     expect(contract.aiUsageRules).toContain(
       'TextInput commitMode defaults to "content": text content, prompts, names, tokens, titles, and instructions apply while typing.',
     );