@pixel-point/toolcraft 0.0.9 → 0.0.12

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

@@ -66,9 +66,9 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       'Specs, plans, and app-schema tests must assert explicit discrete sliders render as variant: "discrete" with markers derived from min, max, and step.',
       'Browser verification can inspect [data-slot="slider"][data-variant="discrete"] plus slider markers to prove the Toolcraft component variant rendered.',
       "Visual discrete sliders must still drag smoothly; browser performance tests should use expectToolcraftDiscreteSliderDragSmoothness for real pointer drag.",
-      "Use schema disabled: true for unavailable sliders; do not recreate a disabled-looking slider with custom markup.",
-      "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 leave a mode-dependent slider active while making the renderer ignore it; the UI must expose the unavailable state.",
+      "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.",
+      "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.",
+      "Do not leave an inactive conditional slider visible while making the renderer ignore it; hide it with visibleWhen.",
     ],
   },
   rangeSlider: {
@@ -115,12 +115,12 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       "Compact symbol/CSS units render tight, such as 20% – 80% or 12px – 48px; word units render with a space when truly needed.",
       "RangeSlider is always a full-width two-thumb control; never place it in an inline two-column layout group with another slider or range slider.",
       "RangeSlider defaultValue must start with different lower and upper values so the two-thumb control does not collapse into a single-value slider.",
-      "Manual range value editing accepts common separators such as slash, hyphen, spaces, and dashes; do not create custom parsers for RangeSlider labels.",
+      "Manual range value editing accepts common separators such as slash, hyphen, spaces, and dashes, including when values include unit suffixes such as 30%-150% or 30% - 90%; do not create custom parsers for RangeSlider labels.",
       'Specs, plans, and app-schema tests must assert explicit discrete range sliders render as variant: "discrete" with markers derived from min, max, and step.',
       "Visual discrete sliders must still drag smoothly; browser performance tests should use expectToolcraftDiscreteSliderDragSmoothness for real pointer drag.",
-      "Use schema disabled: true for unavailable range sliders; do not recreate a disabled-looking range slider with custom markup.",
-      "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 leave a mode-dependent range slider active while making the renderer ignore it; the UI must expose the unavailable state.",
+      "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.",
+      "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.",
+      "Do not leave an inactive conditional range slider visible while making the renderer ignore it; hide it with visibleWhen.",
       "Acceptance must prove both rangeSlider.lower and rangeSlider.upper change the product output; testing one handle is not enough.",
     ],
   },
@@ -136,7 +136,7 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       ],
       useWhen: [
         "Use Select for finite choices with long labels, many options, or values that would not fit in Segmented.",
-        "Use Select when a compact dropdown is more readable than a row of cells.",
+        "Use Select when a dropdown choice is more readable than a row of segmented cells.",
       ],
       doNotReplaceWith: [
         "Do not use Select to recreate FontPicker, Gradient, ImagePicker, FileDrop, Curves, Vector, or Palette value models.",
@@ -145,8 +145,9 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
         "Use Segmented for two to four short closely related options that fit without clipping.",
       ],
       layoutConstraints: [
-        "Prefer compact two-column inline layout for related short Select pairs that tune one workflow or entity.",
-        "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.",
+        "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.",
+        "Prefer compact two-column inline layout only for related short Select pairs that tune one workflow or entity.",
+        "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.",
         "If a compact Select pair falls back to vertical layout, record the fit reason in the spec or worklog.",
       ],
       requiredAcceptance: [
@@ -502,6 +503,7 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       "The sticky footer top accent indicator is determinate when reportProgress receives 0..1 values and falls back to pending state only when progress is unavailable.",
       "defineToolcraft hoists panelActions into the controls panel sticky footer automatically.",
       "Product-output apps must always include export in panelActions.",
+      '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.',
       "Static or still-output apps include Export PNG as the primary footer action.",
       'Every app with Export PNG must expose a separate "Image Export" controls section.',
       'The Image Export section must include "export.image.format" as a Select control with PNG and JPG choices, defaulting to "png".',
@@ -509,6 +511,7 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       "Image Export format and resolution render as one compact two-column inline Select pair, matching the Video Export settings structure.",
       "Image Export resolution controls the actual exported image long edge: 2K = 2048px, 4K = 4096px, 8K = 8192px. Pass the selected runtime value to createToolcraftPngExportCanvas resolution and prove decoded image width/height in browser acceptance.",
       "Animated apps include Export Video as the primary footer action and Export PNG as a secondary footer action.",
+      "Any app with Export Video must enable the top Toolcraft timeline; video duration, loop, and rendered timestamps come from runtime timeline state.",
       'Animated apps with Export Video must expose a separate "Video Export" controls section.',
       'Animated apps with both Export PNG and Export Video must expose both "Image Export" and "Video Export"; Image Export sits immediately before Video Export.',
       'The Video Export section must include format and resolution controls such as targets "export.video.format" and "export.video.resolution".',
@@ -519,6 +522,8 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       "Video Export format and resolution are a compact semantic pair and should use a two-column inline layout by default; use stacked rows only when labels or selected values do not fit without clipping.",
       'Baseline browser video formats are "mp4" and "webm"; MOV or ProRes require an explicit custom encoder/transcoder and dedicated acceptance plus performance coverage.',
       "Video export code must choose the actual MIME/container through MediaRecorder.isTypeSupported or an equivalent encoder capability check, then fall back safely.",
+      "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.",
+      "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.",
       "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.",
       'Video resolution must control exported dimensions. Use "current" output size by default; "4K" is an export resolution target, not a hardcoded 3840x2160 canvas lock.',
       "Video export browser coverage must load the exported blob metadata and prove video.duration matches the edited runtime timeline duration; blobSize/blobType checks alone are not enough.",
@@ -526,7 +531,7 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       'Product-output apps must expose a dedicated "Background" section directly before the first export settings section. With PNG export that first section is Image Export; with video-only export it is Video Export.',
       "Product-output apps must pass the includeBackground runtime value to createToolcraftPngExportCanvas for PNG alpha and call shouldIncludeToolcraftPreviewBackground(state) for live preview product background.",
       "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.",
-      "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.",
       "Copy PNG can be a secondary action when clipboard output is useful, but copy does not replace export.",
       "Add Copy PNG as a secondary action only when the prompt/reference includes clipboard output or the product clearly benefits from paste/share workflows.",
       "Footer actions must be one compact horizontal group; do not split them into stacked full-width sections.",
@@ -566,6 +571,7 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       ],
       requiredAcceptance: [
         "Prove palette.family and palette.shade both affect product output.",
+        "Prove Palette family and shade selections update runtime state immediately, before delayed persistence/commit settles.",
       ],
     }),
     aiUsageRules: [
@@ -575,6 +581,7 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       "Do not use Palette when opacity belongs to the same color entity; use ColorOpacity instead.",
       "Do not use Palette for gradients or color transitions; use Gradient instead.",
       "Do not split typography color out to Palette when the text styling belongs to FontPicker.",
+      "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.",
       "Palette is a compound control; acceptance must prove palette.family and palette.shade both affect the product output.",
       "Do not accept a palette test that only changes a swatch preview without proving the renderer/export consumes the selected family and shade.",
     ],
@@ -585,21 +592,23 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       strictness: "exact-owner",
       ownsValueModel: [
         "x/y vector",
-        "position",
-        "offset",
-        "direction",
+        "user-authored stable position",
+        "user-authored stable offset",
+        "user-authored stable direction",
         "focus point",
         "light vector",
         "color balance pad",
       ],
       useWhen: [
-        "Use Vector for paired X/Y values such as position, offset, direction, focus, anchor, light direction, or color-balance movement.",
+        "Use Vector for paired X/Y values only when the user is meant to manually author a stable two-axis product parameter such as position, offset, direction, focus, anchor, light direction, or color-balance movement.",
       ],
       doNotReplaceWith: [
         "Do not replace Vector with two unrelated sliders or text inputs when direct two-axis editing is the product interaction.",
+        "Do not replace animation, keyboard input, pointer input, physics, timeline phase, velocity, or simulated pose state with Vector just because the internal value has x/y coordinates.",
       ],
       acceptableAlternatives: [
         "Use two numeric text fields only when exact numeric entry is the primary product requirement.",
+        "Use timeline, keyboard/pointer handlers, motion sliders, path/step controls, or renderer simulation state when movement is generated by animation or user input rather than authored as a stable panel value.",
       ],
       layoutConstraints: [
         "One vector renders as a square pad; multiple vectors render compact pads.",
@@ -612,16 +621,20 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       "If the controls panel contains exactly one vector control, the runtime renders the vector pad as a square.",
       "If the controls panel contains multiple vector controls, the runtime renders compact vector pads.",
       "Multiple vector controls should live in separate semantic sections unless they intentionally belong to the same entity with other related controls.",
+      "Use Vector only for user-authored stable two-axis product parameters. Do not expose Vector for current animation state, keyboard movement, pointer movement, physics state, timeline phase, velocity, target pose, current pose, or simulated position/direction.",
+      "Before adding a Vector control to an animated or interactive product, classify movement ownership as direct-authored, timeline-driven, keyboard/pointer-driven, or simulation-owned. Only direct-authored movement may become a visible Vector control; the other ownership modes stay in renderer/runtime interaction state and use controls such as Speed, Step, Spread, Path, Duration, or Timeline when the user needs tuning.",
       'Use variant: "whiteBalance" for temperature/tint pads: X maps cool blue to warm amber, Y maps green to magenta.',
       'Use variant: "colorBalance" for paired color-balance axes such as cyan/red and blue/yellow correction.',
       'Use variant: "chromaOffset" for RGB/chromatic offset vectors where the X/Y movement controls channel separation.',
       'Use variant: "toneBias" for split-tone, duotone, or color-grading vectors where both axes describe tone or hue bias.',
       'Use the default vector variant for spatial values such as position, offset, direction, focus, anchor, and light direction.',
       '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.',
-      "Holding Shift while dragging a vector pad locks movement to the dominant axis; do not build a custom pad just to support axis-constrained movement.",
+      "Vector pad value labels render compact rounded coordinates. Do not expose raw floating-point strings such as -0.07070312499999998 in the controls panel.",
+      "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.",
+      "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.",
       'Use coordinateMode: "cartesian" only when the product intentionally exposes mathematical Y-up coordinates instead of canvas/screen movement.',
       "Do not add custom vector sizing props in generated schemas; choose the number, variant, and section grouping from product need and let the runtime size the pads.",
-      "Vector is a compound control; acceptance must prove vector.x and vector.y both affect the product output.",
+      "Vector is a compound control; acceptance must prove vector.x and vector.y both affect the product output and that the vector represents a user-authored stable two-axis parameter rather than current animation, input, or simulation state.",
     ],
   },
   color: {
@@ -823,7 +836,7 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
         "Do not use AnchorGrid for freeform two-axis movement; use Vector.",
       ],
       acceptableAlternatives: [
-        "Use Vector for continuous position or direction.",
+        "Use Vector only for stable direct-authored continuous position or direction parameters.",
       ],
       layoutConstraints: [
         "AnchorGrid is a standalone position selector.",
@@ -895,29 +908,38 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       ],
       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, and section/global reset update source material.",
+        "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 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.",
       "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"],
+    commands: ["media.delete", "media.import", "media.reorder", "media.transform"],
   },
   imagePicker: {
     ...control("imagePicker", "ImagePicker", "standalone", "component-owned"),
@@ -1045,15 +1067,17 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
   canvas: {
     aiUsageRules: [
       "Choose canvas.sizing.mode from product context instead of copying a universal 1024px artboard.",
-      "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.",
+      "Use intrinsic-media only for true media-viewer or source-native apps where the natural uploaded/generated media size is the product output; record the reason and prove it with intrinsic-media-size acceptance.",
       "Use editable-output for generated, exportable, shader, poster, badge, wall, banner, thumbnail, procedural, reference-clone, and product-output apps so users always see Aspect ratio, Canvas width, and Canvas height.",
+      "When an uploaded image is a background/source inside the product canvas, keep the current canvas.size, keep Setup/canvas controls visible, and render the image as cover/crop inside the current canvas bounds without letterbox or aspect distortion.",
       "When no explicit product size is provided, the runtime default canvas is 16:9 at 1920x1080; do not reset a new product-output app to 1:1 unless the product meaning requires it.",
       "A user-provided, reference, fixed-format, or base/default size is not a reason to remove size controls; model it as canvas.size plus editable-output so the size is an initial value, not a hidden lock.",
       "Do not use fixed-output for generated product/output apps with export actions. Reserve fixed-output for non-product internal fixtures where width and height truly must never be user-editable, and prove that lock with canvasSizingCoverage fixed-output-size acceptance.",
       "A reference or previous app lacking a size editor, or defining a fixed-size baseline, is not a fixed-output reason for a generated product app; product-output clones still use editable-output.",
-      "Resolved canvas.size exists for every canvas app, but visible Canvas width and Canvas height controls are mandatory only for editable-output sizing and do not depend on settingsTransfer.",
+      "Resolved canvas.size exists for every canvas app, but visible Canvas width and Canvas height controls are mandatory only for editable-output sizing and live in the mandatory runtime Setup section.",
       "If canvas.size is provided without an explicit sizing mode, defineToolcraft treats it as editable-output and adds Canvas width and Canvas height controls.",
-      "The runtime Canvas width and Canvas height block uses the 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.",
       "When the user manually edits Canvas width or Canvas height, the runtime keeps the typed dimension, keeps the other dimension unchanged, switches Aspect ratio to Custom, and shows the reduced current ratio in the custom ratio inputs.",
       "Aspect ratio presets are the only interaction that may resize both canvas dimensions from a preset; manual size inputs are exact output dimensions.",
       "For non-vector raster, Canvas 2D, WebGL, and WebGPU previews, set canvas.renderScale: true so the runtime adds Resolution scale after canvas sizing. The scale changes backing pixels from 1 to 2 without changing visible canvas size, and adding/enabling it requires targeted browser evidence that the canvas stays responsive at the selected scale.",
@@ -1072,6 +1096,8 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       "canvas.zoomReset",
       "media.delete",
       "media.import",
+      "media.reorder",
+      "media.transform",
     ],
     historyPolicy: "patch",
     id: "canvas",
@@ -1084,10 +1110,11 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
     aiUsageRules: [
       "Do not write app state to localStorage directly.",
       "Use schema persistence policy for app state that should survive reload.",
-      "Persistence may include values, canvas, panels, timeline, and layers; history and media blobs are not persisted.",
+      "Persistence may include values, canvas, panels, timeline, layers, and media; history is not persisted.",
+      "Use persistence include: [\"media\"] only when runtime media state must survive reload, such as predefined attached files that users can delete, reorder, or transform. Do not use ad hoc storage for media state.",
       'Apps with visible runtime panels and localStorage persistence must include "panels" so dragged panel positions survive reload.',
       'Apps with localStorage persistence must include acceptance coverage for changing a user setting, reloading the browser page, and seeing the restored value or product output.',
-      "Settings import/export is a 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.",
       "Do not store media blobs, files, or large generated images in localStorage.",
     ],
     capabilities: ["themePreference", "appStatePolicy"],
@@ -1101,12 +1128,13 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
   },
   settingsTransfer: {
     aiUsageRules: [
-      'Use schema settingsTransfer: "auto" for complex apps unless the prompt explicitly disables settings import/export.',
-      "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.",
+      "Generated apps keep a controls panel so runtime Setup is visible from the first run; product controls are added after that mandatory runtime section.",
+      "Do not gate Export Settings / Import Settings behind complexity thresholds, app size, or prompt wording.",
       "Do not hand-roll settings import/export through app routes, hidden file inputs, or panelActions.",
-      "Settings transfer appears 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.",
-      "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 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.",
+      "Settings transfer appears in the first visible headerless Setup controls-panel block; it imports and exports control values, canvas size, and timeline state.",
+      "App-authored sections must not declare runtime Setup targets such as runtime.settingsTransfer, canvas.aspectRatio, canvas.size.width, canvas.size.height, canvas.renderScale, or panels.timeline.extended; those controls never suppress the mandatory runtime Setup controls.",
+      "When editable-output canvas sizing is enabled, the first visible Setup runtime section contains Export Settings, Import Settings, Aspect ratio, Canvas width, Canvas height, and optional Resolution scale in that order.",
+      "When panels.timeline is enabled, Setup appends the Timeline switch as the last control; when panels.timeline is omitted, the Timeline switch must not appear.",
       "Keep sticky footer panelActions for product delivery actions only, such as Export PNG, Export Video, Copy, Generate, Apply, or Download.",
     ],
     capabilities: ["settings-import-export"],
@@ -1126,14 +1154,16 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       "Acceptance tests must fail when an entity is disconnected from runtime state, renderer output, export output, or command side effects.",
       "Do not accept typecheck, component existence, registered commands, runtime state mutation, renderer input objects, shader uniform presence, or signature strings as final proof.",
       "Use product-level observables such as rendered pixels, exported image bytes, canvas hash, clipboard payload, cleared media preview, selected layer result, changed viewport, or timeline-rendered frame.",
+      "Any supplied video, GIF, screen-recording, contact-sheet, or extracted-frame reference requires a Video Reference Study before implementation: storyboard frames, frame-to-frame transition analysis, behavior decomposition, and acceptance mapping. Do not implement video references from a single screenshot or high-level summary.",
       "A generic canvas hash difference is not enough for workload or semantic controls; assert the intended direction of the effect.",
       "Component variants are accepted entities too; tests should fail if a non-default Toolcraft control variant falls back to the default variant or custom markup.",
       "Conditional entities require fixtures that make the condition observable.",
-      "Use visibleWhen for mode-, type-, variant-, or count-exclusive sections or controls that do not belong to the current selected state.",
-      "When visibleWhen or disabledWhen references a selector for the same product entity or selected branch, keep the selector and its dependent controls in one semantic section. A section that exists only because one selector option is active is not a separate product section just because the branch uses a standalone control.",
+      "Use visibleWhen for mode-, type-, source-, include-, variant-, or count-exclusive sections or controls that do not belong to the current selected state.",
+      "When visibleWhen references a selector for the same product entity or selected branch, keep the selector and its dependent controls in one semantic section. A section that exists only because one selector option is active is not a separate product section just because the branch uses a standalone control.",
       "When a count/quantity control determines how many sibling controls are available, hide unavailable siblings with visibleWhen; do not render all possible controls while the renderer reads only the first N.",
-      "Use disabledWhen for controls that belong to the current entity but are temporarily unavailable for the selected mode; the disabled value must be preserved.",
-      "Do not leave inactive conditional controls visible and enabled while making the renderer ignore them.",
+      "If a switch/select/segmented/imagePicker/checkbox chooses a branch for the same product entity, controls outside the current branch use visibleWhen, not disabledWhen.",
+      "Do not use schema disabled: true or disabledWhen for generated product controls; the panel should show only controls usable in the current state. Runtime primitives may still have disabled styling internally, but app schemas should model product availability with visibleWhen.",
+      "Do not leave inactive conditional controls visible while making the renderer ignore them.",
       "If an entity cannot be tested against a product-level observable, remove it from the app schema or ask whether it is required.",
     ],
     capabilities: ["acceptance-tests", "product-output-verification"],
@@ -1156,7 +1186,7 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       "Expensive renderers must cache decoded media, source pixels, glyph atlases, gradients, and other reusable inputs by media id, canvas size, and stable control keys.",
       "Slider drags and high-frequency controls must debounce or coalesce preview work, cancel stale async renders, and avoid re-decoding media on every control change.",
       "Performance matrices must declare rendererWorkload as none, simple-composition, text-output, vector-output, or pixel-output.",
-      "A full performance checkpoint must run 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.",
       "Renderer, canvas, animation, export, timeline, layers, canvas.renderScale, bug fixes, and performance-sensitive control changes use targeted functional/browser checks first and targeted performance scenarios only for touched workload, viewport, or export paths.",
       "Performance fixes must preserve selected output and preview quality; do not reduce image quality, selected renderScale, export resolution, source media fidelity, or canvas backing pixels as the hidden way to pass budgets.",
       "When canvas or slider interactions lag, diagnose where the slowdown comes from before changing output quality: renderer technique, React update frequency, decoded media, shader/program setup, buffer uploads, layout work, async render cancellation, or animation scheduling.",
@@ -1208,11 +1238,14 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       'Use referenceTimeline.mode "toolcraft-keyframes" when controls need keyframe diamonds, expanded keyframe rows, easing, or editable keyframes.',
       'Use referenceTimeline.mode "none" only when the reference has no user-facing transport behavior at all.',
       "Reference clone specs must list every detected transport behavior explicitly, including pause-resume, restart, time-progress, export-at-time, playback, scrub, duration, loop, and keyframes when present.",
+      'Toolcraft reference timelines must declare referenceTimeline.loopDuration with source "reference", "user-request", or "product-derived", plus seconds and evidence; runtime/template fallback 8s is not a valid source.',
+      "panels.timeline.defaultDurationSeconds must match referenceTimeline.loopDuration.seconds for referenceTimeline.mode toolcraft-playback/toolcraft-keyframes.",
       "Do not create right-panel controls named or targeted as Play, Pause, Paused, Animate, Restart animation, or equivalent app-wide transport toggles.",
       'Do not downgrade custom reference timelines to panels.timeline mode "playback". State buttons, trim handles, selected-range playback, or range export require referenceTimeline.mode "custom-reference-timeline" and dedicated acceptance.',
       "Generated reference clone apps must declare starterTransferMode.referenceTimeline with mode none, toolcraft-playback, toolcraft-keyframes, or custom-reference-timeline.",
       "Custom reference timeline behavior needs referenceTimelineCoverage entries such as state-jump, trim-range, range-playback, all-range, jump-to-trim-start, and export-range.",
       "Reference clone acceptance must include referenceCoverage rows for canvas sizing, control mapping, renderer state, and any renderer loop, spawn/update cadence, pause/resume, export/copy, or media lifecycle behavior in the reference.",
+      "Video reference assets used in a reference clone also require starterTransferMode.videoReferenceStudy with storyboard frames, frame-to-frame transition analysis, behavior decomposition, and acceptance mapping.",
       "Browser tests must compare reference behavior or a reference-derived baseline, not only Toolcraft state mutation.",
     ],
     capabilities: [
@@ -1238,13 +1271,13 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       "Acceptance validators suggest semantic replacement labels for weak generic labels; fix the schema label instead of relying on runtime fallback rewriting.",
       "Controls-panel sections should stay discrete: two to seven product controls is the normal size, and larger sections must split by product sub-entity or workflow stage.",
       "Generated product apps must export starterControlSectionInventory beside acceptance. Every product controls section declares title, exact targets, groupingReason, and entity or workflowStage; intentional splits of one target entity require workflowStage and splitReason on every split section.",
-      "Section splitting must preserve dependency cohesion: a selector stays with the visibleWhen/disabledWhen controls it gates when they share the same target entity or selected branch. Use internal spacing/dividers or a more specific section title before splitting dependent branch controls away.",
-      "Every app-authored controls-panel body section must have a short meaningful visible title. Runtime-created setup/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 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.",
+      "Section splitting must preserve dependency cohesion: a selector stays with the visibleWhen controls it gates when they share the same target entity or selected branch. Use internal spacing/dividers or a more specific section title before splitting dependent branch controls away.",
+      "Every app-authored controls-panel body section must have a short meaningful visible title. Runtime-created Setup renders as the first visible headerless controls block with no title, reset action, collapse button, or collapsed state; sticky footer action sections use the technical title Export but render without a visible heading.",
+      "Every visible app-authored controls-panel section title renders through the standard 36px collapsible header row with vertically centered text and the runtime collapse icon; generated apps must not hand-build section headers.",
       "Controls-panel section expand and collapse uses the standard runtime height/opacity animation; generated apps must not replace it with instant custom section visibility.",
-      "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.",
       "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.",
-      "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.",
       "Broad section titles such as Flow, Icon, Shapes, Scene, Text, Typography, or Motion are only valid for small cohesive groups; use specific titles such as Flow Motion, Flow Geometry, Letter Burst, Shape Colors, Logo Glow, Logo Plate, or Text Block for larger groups.",
       "Section titles in one controls panel must be unique.",
       "Use section titles, option labels, tests, or renderer/spec prose for details instead of long field labels.",
@@ -1303,12 +1336,21 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
   timelinePanel: {
     ...panel("timelinePanel", "TimelinePanel", "top", ["top", "bottom"], "panel"),
     aiUsageRules: [
-      "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.",
       "Before choosing no timeline for any animated product, write an Animation Intent Inventory: product transport, editable keyframes, or autonomous decorative output, plus the user-facing time behaviors present or intentionally absent.",
-      'User-requested product animation defaults to panels.timeline mode "playback" unless the spec explicitly declares autonomous decorative/self-running output with no play, pause, scrub, duration, loop, or export-at-time behavior.',
-      'Use panels.timeline: { mode: "playback" } when the product needs user-facing play, pause, scrubbing, duration, loop, restart, time progress, or export-at-time controls.',
+      'User-requested product animation defaults to panels.timeline mode "playback" unless the spec explicitly declares autonomous decorative/self-running output with no play, pause, scrub, duration, loop, export-at-time behavior, or video export.',
+      'Any product app with Export Video must enable the top Toolcraft timeline: use panels.timeline mode "playback" for product animation transport, or mode "keyframes" when exported animation is driven by keyframes.',
+      'Use panels.timeline: { mode: "playback" } when the product needs user-facing play, pause, scrubbing, duration, loop, restart, time progress, export-at-time controls, or video export.',
+      'When panels.timeline is enabled for a new Toolcraft app, appTransferMode.animationIntent must match it: mode "timeline-playback" for playback, or mode "timeline-keyframes" for keyframes.',
       "Playback renderers must consume runtime timeline state; pause freezes output, scrubbing renders a deterministic frame, and the full animation cycle maps to state.timeline.durationSeconds instead of a local fixed duration.",
-      "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 the product has a known loop duration, declare it as panels.timeline.defaultDurationSeconds; the runtime timeline duration starts from that loop duration instead of an unrelated 8s default.",
+      'Timeline animation intent must declare loopDuration with source "reference", "user-request", or "product-derived", plus seconds and evidence; runtime/template fallback 8s is not a valid source.',
+      "panels.timeline.defaultDurationSeconds must match animationIntent.loopDuration.seconds for playback/keyframe animation, so the initial timeline UI shows the declared product loop instead of a generic default.",
+      "Video export renderers must render deterministic frames from runtime timeline timestamps and duration; do not treat autonomous wall-clock time or captureStream recording time as the source of product duration.",
+      "Playback renderers may compute an initial loop duration default during app initialization or reset, but must not watch state.timeline.durationSeconds and dispatch timeline.setDuration back to a computed local duration. User-edited timeline duration becomes the loop duration source of truth after initialization or reset.",
+      "Playback renderers should use getToolcraftTimelineLoopTime or getToolcraftTimelineLoopProgress to derive product loop phase from state.timeline.currentTimeSeconds and state.timeline.durationSeconds; do not hand-roll wall-clock, fixed-duration, mirror, yoyo, ping-pong, or reverse phase math.",
+      "Product animation loop means a seamless forward-only cycle by default: motion advances in one direction, first and last frames stitch without a visible jump, and mirror/yoyo/ping-pong/reverse loops require explicit user request.",
+      "Changing timeline duration must preserve seamless forward-loop semantics: one full product animation cycle maps from 0 to state.timeline.durationSeconds, first and last frames still stitch, direction does not reverse, and changing duration must not switch the renderer to wall-clock or fixed local speed.",
       "When non-looping playback reaches the end, pressing Play again restarts playback from time 0.",
       "Intrinsic-media upload timelines must stay paused at time 0 until source media exists; clearing the last media asset must pause and reset playback.",
       'Use panels.timeline: { mode: "keyframes" } or panels.timeline: true only when controls need keyframe diamonds, expanded timeline rows, easing, or keyframe editing.',
@@ -1324,6 +1366,8 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       "Do not put Pause or Resume in panelActions; playback belongs to TimelinePanel transport controls.",
       "Do not replace TimelinePanel with an app-level playback, transport, or timeline panel to avoid runtime performance issues; fix the Toolcraft runtime clock/state path instead.",
       'Custom timeline UI is allowed only for explicit referenceTimeline.mode "custom-reference-timeline" transfers with browser-backed referenceTimelineCoverage.',
+      'When panels.timeline is enabled, runtime inserts a Setup switch labeled "Timeline" as the last runtime setup control after Resolution scale.',
+      "The Timeline Setup switch controls only compact versus extended runtime presentation: off shows the compact Play-only transport, on shows the extended timeline with scrubber, duration, loop, and keyframe UI. It must not stop playback, change keyframes, affect export, enter product values, or be reset by Reset controls/settings transfer.",
       "Playback-only timelines stay collapsed and do not show keyframe diamonds or expanded keyframe rows.",
       "If timeline verification fails, wire the renderer to runtime timeline state or remove panels.timeline.",
     ],
@@ -1342,6 +1386,7 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       "timeline.deleteKeyframe",
       "timeline.moveKeyframe",
       "timeline.selectKeyframe",
+      "panels.setHidden",
       "timeline.setCurrentTime",
       "timeline.setDuration",
       "timeline.setPlaying",

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

@@ -24,7 +24,7 @@ describe("Toolcraft template decision contract", () => {
     for (const rule of TOOLCRAFT_DECISION_CONTRACT) {
       expect(rule.id).toMatch(/^[a-z0-9-]+$/);
       expect(rule.area).toMatch(
-        /^(runtime-shell|canvas|panels|layers|timeline|controls|renderer|reference-clone|acceptance|performance|persistence|workflow)$/,
+        /^(runtime-shell|canvas|panels|layers|timeline|controls|renderer|reference-analysis|reference-clone|acceptance|performance|persistence|workflow)$/,
       );
       expect(rule.title.trim().length).toBeGreaterThan(0);
       expect(rule.currentConstraint.trim().length).toBeGreaterThan(0);
@@ -85,6 +85,36 @@ describe("Toolcraft template decision contract", () => {
     expect(rule?.enforcement).toContain("performance-validator");
   });
 
+  it("requires reference clone functionality to be inventoried and acceptance-backed", () => {
+    const rule = getToolcraftDecisionRule("reference-clone-source-of-truth");
+
+    expect(rule?.level).toBe("invariant");
+    expect(rule?.desiredBehavior).toMatch(/referenceStudy evidence/i);
+    expect(rule?.desiredBehavior).toMatch(/running the original or restoring it locally/i);
+    expect(rule?.desiredBehavior).toMatch(/reference feature inventory/i);
+    expect(rule?.desiredBehavior).toMatch(/feature-level behavior evidence/i);
+    expect(rule?.desiredBehavior).toMatch(/user-visible and output-affecting feature/i);
+    expect(rule?.desiredBehavior).toMatch(/Toolcraft implementation/i);
+    expect(rule?.desiredBehavior).toMatch(/acceptance coverage/i);
+    expect(rule?.desiredBehavior).toMatch(/explicit user approval/i);
+    expect(rule?.enforcement).toContain("acceptance-validator");
+  });
+
+  it("requires video references to be studied as behavior before implementation", () => {
+    const rule = getToolcraftDecisionRule("video-reference-analysis");
+
+    expect(rule?.level).toBe("invariant");
+    expect(rule?.area).toBe("reference-analysis");
+    expect(rule?.desiredBehavior).toMatch(/video, GIF, screen recording/i);
+    expect(rule?.desiredBehavior).toMatch(/storyboard/i);
+    expect(rule?.desiredBehavior).toMatch(/timecoded frame observations/i);
+    expect(rule?.desiredBehavior).toMatch(/frame-to-frame transitions/i);
+    expect(rule?.desiredBehavior).toMatch(/map those observed behaviors to acceptance rows/i);
+    expect(rule?.desiredBehavior).toMatch(/independent from loop duration or timeline choice/i);
+    expect(rule?.enforcement).toContain("acceptance-validator");
+    expect(rule?.enforcement).toContain("starter-agents");
+  });
+
   it("splits performance into workload and lightweight responsiveness coverage", () => {
     const rule = getToolcraftDecisionRule("performance-coverage-levels");
 
@@ -94,6 +124,8 @@ describe("Toolcraft template decision contract", () => {
     expect(rule?.desiredBehavior).toMatch(/canvas drag, pan, pinch, zoom, and radar\/center/i);
     expect(rule?.desiredBehavior).toMatch(/playback state/i);
     expect(rule?.desiredBehavior).toMatch(/first working version/i);
+    expect(rule?.desiredBehavior).toMatch(/agent's controlled browser/i);
+    expect(rule?.desiredBehavior).toMatch(/Playwright is only the fallback runner/i);
     expect(rule?.desiredBehavior).toMatch(/optimize performance/i);
     expect(rule?.desiredBehavior).toMatch(/otherwise complains about performance/i);
     expect(rule?.desiredBehavior).toMatch(/targeted functional\/browser checks/i);

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

@@ -6,6 +6,7 @@ export type ToolcraftDecisionArea =
   | "panels"
   | "performance"
   | "persistence"
+  | "reference-analysis"
   | "reference-clone"
   | "renderer"
   | "runtime-shell"
@@ -139,10 +140,10 @@ export const TOOLCRAFT_DECISION_CONTRACT = [
   {
     area: "timeline",
     currentConstraint:
-      "Timeline is optional, but animated products must first classify animation intent as product transport, editable keyframes, custom reference timeline, or autonomous decorative output.",
+      "Timeline is optional only for animated products that have no video export and are explicitly classified as autonomous decorative output.",
     desiredBehavior:
-      "AI writes an Animation Intent Inventory before choosing no timeline, playback, keyframes, or custom reference timeline; user-requested product animation defaults to playback unless explicitly justified as autonomous output.",
-    enforcement: ["starter-agents", "spec-checklist"],
+      "AI writes an Animation Intent Inventory before choosing no timeline, playback, keyframes, or custom reference timeline; user-requested product animation defaults to playback unless explicitly justified as autonomous output without video export. Export Video always requires a top Toolcraft timeline.",
+    enforcement: ["starter-agents", "spec-checklist", "acceptance-validator"],
     id: "timeline-mode-choice",
     level: "heuristic",
     title: "Timeline mode is chosen from behavior",
@@ -211,15 +212,27 @@ export const TOOLCRAFT_DECISION_CONTRACT = [
   {
     area: "reference-clone",
     currentConstraint:
-      "Reference-runtime-clone mode preserves the reference runtime as source of truth unless a redesign is explicit.",
+      "Reference-runtime-clone mode preserves the reference runtime as source of truth unless a redesign is explicit; functionality must be inventoried from inspected reference behavior before implementation.",
     desiredBehavior:
-      "Ported apps keep reference loops, mutable state, transport semantics, media lifecycle, and export behavior before Toolcraft refinements.",
+      "Ported apps keep reference loops, mutable state, transport semantics, media lifecycle, and export behavior before Toolcraft refinements. The agent records referenceStudy evidence from source inspection plus running the original or restoring it locally when runnable/reconstructable, builds a reference feature inventory from inspected source/runtime/UI behavior, gives each inventory item feature-level behavior evidence from that study, maps every user-visible and output-affecting feature to Toolcraft implementation and acceptance coverage, and marks intentional behavior changes only with explicit user approval evidence.",
     enforcement: ["acceptance-validator", "browser-helper", "starter-agents"],
     id: "reference-clone-source-of-truth",
     level: "invariant",
     title: "Reference clone preserves behavior",
     verdict: "keep-hard",
   },
+  {
+    area: "reference-analysis",
+    currentConstraint:
+      "Video, GIF, and screen-recording references are often treated as static visual inspiration or summarized from a few frames.",
+    desiredBehavior:
+      "Whenever a supplied reference is a video, GIF, screen recording, contact sheet, or extracted frame sequence, the agent studies it as behavioral evidence before implementation: extract or inspect a storyboard, record timecoded frame observations, compare frame-to-frame transitions, decompose changing entities and state into product behavior, and map those observed behaviors to acceptance rows. This applies to new Toolcraft apps and reference-runtime-clone work; it is independent from loop duration or timeline choice.",
+    enforcement: ["acceptance-validator", "browser-helper", "docs", "starter-agents"],
+    id: "video-reference-analysis",
+    level: "invariant",
+    title: "Video references require storyboard behavior study",
+    verdict: "move-to-validator",
+  },
   {
     area: "acceptance",
     currentConstraint:
@@ -237,7 +250,7 @@ export const TOOLCRAFT_DECISION_CONTRACT = [
     currentConstraint:
       "Performance coverage currently asks every visible non-action control for a performance scenario.",
     desiredBehavior:
-      "Heavy workload controls get min/default/max workload coverage; ordinary controls get lightweight responsiveness coverage so they cannot hang or break input. Animated previews suspend or coalesce non-essential animation work during canvas drag, pan, pinch, zoom, and radar/center interactions without changing user playback state. A full performance checkpoint is required only when the first working version of an app exists, or whenever the user explicitly asks to optimize performance, fix lag, remove jank, speed up animation, stabilize drag/zoom, or otherwise complains about performance. Renderer, canvas, animation, export, timeline, layers, canvas.renderScale, bug fixes, and performance-sensitive controls need targeted functional/browser checks first and targeted performance scenarios only for touched workload/viewport/export paths. Performance fixes must preserve the selected render scale and must not pass budgets by silently downsampling, stretching a lower-resolution backing canvas, blurring output, or clamping canvas.renderScale below the user's chosen value. Browser performance tests read budgets from typed performance config and run sequentially for stable measurements.",
+      "Heavy workload controls get min/default/max workload coverage; ordinary controls get lightweight responsiveness coverage so they cannot hang or break input. Animated previews suspend or coalesce non-essential animation work during canvas drag, pan, pinch, zoom, and radar/center interactions without changing user playback state. A full performance checkpoint is required only when the first working version of an app exists, or whenever the user explicitly asks to optimize performance, fix lag, remove jank, speed up animation, stabilize drag/zoom, or otherwise complains about performance. The checkpoint uses the current AI agent's controlled browser first; Playwright is only the fallback runner when no agent browser is available or in CI/non-agent automation. Renderer, canvas, animation, export, timeline, layers, canvas.renderScale, bug fixes, and performance-sensitive controls need targeted functional/browser checks first and targeted performance scenarios only for touched workload/viewport/export paths. Performance fixes must preserve the selected render scale and must not pass budgets by silently downsampling, stretching a lower-resolution backing canvas, blurring output, or clamping canvas.renderScale below the user's chosen value. Browser performance checks read budgets from typed performance config and run sequentially for stable measurements.",
     enforcement: ["performance-validator", "browser-helper", "starter-agents"],
     id: "performance-coverage-levels",
     level: "invariant",