@pixel-point/toolcraft 0.0.16 → 0.0.18

package/src/generate.test.mjs

@@ -64,6 +64,20 @@ describe("generateToolcraft", () => {
     );
     assert.match(performanceSource, /workloadEnvelope:\s*\{\s*dimensions:\s*\[\]\s*\}/u);
     assert.doesNotMatch(performanceSource, /\bworkloadTargets\s*:/u);
+
+    assert.ok(
+      await fs.stat(
+        path.join(
+          targetDir,
+          "src/toolcraft/runtime/schema/canvas-render-scale.ts",
+        ),
+      ),
+    );
+    const gitignoreSource = await fs.readFile(
+      path.join(targetDir, ".gitignore"),
+      "utf8",
+    );
+    assert.match(gitignoreSource, /^\.playwright-mcp$/mu);
   });
 
   it("tests, typechecks, and builds a non-neutral generated product in isolation", async () => {

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

@@ -152,6 +152,38 @@ describe("Toolcraft template component contracts: choices and actions", () => {
     expect(contract.aiUsageRules).toContain(
       "Use FontPicker as the collection item control when each repeated item is a typography/text-style entity; do not split its font, color, opacity, size, case, letter-spacing, or line-height into sibling collection fields.",
     );
+    expect(contract.aiUsageRules).toContain(
+      "Use itemControl when each repeated entity is one built-in value. Use itemControls only when two or more built-in fields describe one logical repeated product entity and are added or removed atomically.",
+    );
+    expect(contract.decisionCatalog?.layoutConstraints).toContain(
+      "Compound itemControls records render one line only between adjacent logical items, with no generated Item N headings; standalone color itemControl collections keep the compact two-column grid without item dividers.",
+    );
+    expect(contract.decisionCatalog?.requiredAcceptance).toContain(
+      "For itemControls, prove plus creates every declared default field in one runtime record, editing preserves sibling fields, and minus removes the whole final record from preview and export.",
+    );
+  });
+
+  it("documents SourceCollection as source-cardinality built-in item controls", () => {
+    const contract = getToolcraftComponentContract("sourceCollection");
+
+    expect(contract.stateMode).toBe("controlled");
+    expect(contract.visualComponent).toBe("ControlsPanelCollectionItems");
+    expect(contract.decisionCatalog?.strictness).toBe("exact-owner");
+    expect(contract.decisionCatalog?.ownsValueModel).toContain(
+      "source-owned collection cardinality",
+    );
+    expect(contract.decisionCatalog?.useWhen.join(" ")).toMatch(
+      /loaded|derived|detected/i,
+    );
+    expect(contract.decisionCatalog?.doNotReplaceWith?.join(" ")).toMatch(
+      /custom control|copied|recreated/i,
+    );
+    expect(contract.decisionCatalog?.requiredAcceptance.join(" ")).toMatch(
+      /source item count.*canvas preview.*export/i,
+    );
+    expect(contract.aiUsageRules.join(" ")).toMatch(
+      /built-in itemControl.*must not render add or remove/i,
+    );
   });
 
   it("documents segmented controls as compact selector-only choices", () => {
@@ -216,10 +248,10 @@ describe("Toolcraft template component contracts: choices and actions", () => {
       "Do not use panelActions for resetting controls; the controls panel header owns Reset controls.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Handle product-specific panelActions through ToolcraftApp onPanelAction.",
+      "Handle product-specific non-export panelActions through ToolcraftApp onPanelAction. Typed export-image and export-video actions are runtime-owned and consume ToolcraftAppComposition.exportRenderer.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Async product actions such as Export, Download, Copy, Generate, or Apply must return the real Promise from onPanelAction and report progress through the onPanelAction reportProgress callback.",
+      "Async non-export product actions such as Download, Copy, Generate, or Apply must return the real Promise from onPanelAction and report progress through the onPanelAction reportProgress callback.",
     );
     expect(contract.aiUsageRules).toContain(
       "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.",
@@ -228,13 +260,13 @@ describe("Toolcraft template component contracts: choices and actions", () => {
       "defineToolcraft hoists panelActions into the controls panel sticky footer automatically.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Product-output apps must always include export in panelActions.",
+      "Every product must declare productReadiness.exportIntent before authoring export panelActions or settings sections.",
     );
     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.",
+      'Image export is the Toolcraft product default. Keep Export PNG unless productReadiness.exportIntent.image is "user-removed" with non-empty explicit user-removal evidence.',
     );
     expect(contract.aiUsageRules).toContain(
       'Every app with Export PNG must expose a separate "Image Export" controls section.',
@@ -249,10 +281,13 @@ describe("Toolcraft template component contracts: choices and actions", () => {
       "Image Export format and resolution render as one compact two-column inline Select pair, matching the Video Export settings structure.",
     );
     expect(contract.aiUsageRules).toContain(
-      "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.",
+      "Image Export resolution controls the actual exported image long edge: 2K = 2048px, 4K = 4096px, 8K = 8192px. Runtime resolves the selected value and protected browser acceptance proves decoded image width and height.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Apps that deliver animation include Export Video as the primary footer action and Export PNG as a secondary footer action; timeline playback alone does not invent video delivery.",
+      'Add Export Video only when productReadiness.exportIntent.video is "user-requested" with non-empty explicit user-request evidence.',
+    );
+    expect(contract.aiUsageRules).toContain(
+      'Animation, playback, keyframes, and timeline presence never add Export Video when productReadiness.exportIntent.video is "not-requested".',
     );
     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.",
@@ -263,6 +298,15 @@ describe("Toolcraft template component contracts: choices and actions", () => {
     expect(contract.aiUsageRules).toContain(
       'Apps with both Export PNG and Export Video must expose both "Image Export" and "Video Export"; Image Export sits immediately before Video Export.',
     );
+    expect(contract.aiUsageRules).toContain(
+      'Image-only apps place "Image Export" directly above sticky footer panelActions.',
+    );
+    expect(contract.aiUsageRules).toContain(
+      'Video-only apps require explicit image user-removal evidence and place "Video Export" directly above sticky footer panelActions.',
+    );
+    expect(contract.aiUsageRules).toContain(
+      'Explicit no-export apps require image user-removal evidence with video "not-requested" and omit export actions and settings sections.',
+    );
     expect(contract.aiUsageRules).toContain(
       'The Video Export section must include format and resolution controls such as targets "export.video.format" and "export.video.resolution".',
     );
@@ -285,16 +329,16 @@ describe("Toolcraft template component contracts: choices and actions", () => {
       'Baseline browser video formats are "mp4" and "webm"; MOV or ProRes require an explicit custom encoder/transcoder and dedicated acceptance plus performance coverage.',
     );
     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.",
+      "Runtime video export chooses the actual MIME, container, and codec through the timestamped Mediabunny encoder capability check, then returns the real supported format or a typed visible failure.",
     );
     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.",
+      "Runtime video export allocates the selected recording canvas dimensions before timestamped encoder setup and rejects renderer, encoder, muxer, and output-limit 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.",
+      "Offline video export duration is encoded from the fixed runtime 30 FPS timeline schedule. Product code must not use canvas.captureStream, MediaRecorder, or wall-clock time as a fallback.",
     );
     expect(contract.aiUsageRules).toContain(
       'Video resolution must control exported dimensions. Use "current" output size by default; "4K" is an export resolution target, not a hardcoded 3840x2160 canvas lock.',
@@ -309,13 +353,16 @@ describe("Toolcraft template component contracts: choices and actions", () => {
       'Product-output apps declare the standard background pair in an authored "Background" source section. Runtime removes that visible section and places Background plus Infinity canvas, then Background color, in Setup; Timeline is the final Setup control.',
     );
     expect(contract.aiUsageRules).toContain(
-      "Product-output apps pass the includeBackground runtime value to createToolcraftPngExportCanvas for PNG alpha and call shouldIncludeToolcraftPreviewBackground(state) for bounded live preview background. In Infinity mode CanvasShell owns the selected full-viewport background color, and Background off restores finite mode and disables Infinity.",
+      "Product-output apps call shouldIncludeToolcraftPreviewBackground(state) for bounded live preview background. Runtime artifact export owns Background semantics: PNG may be transparent, JPEG and video remain opaque, Infinity uses the full-viewport color, and Background off restores finite mode and disables Infinity.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "ToolcraftAppComposition.exportRenderer draws one deterministic product frame in scene coordinates for both image and video. Runtime owns canvas allocation, background, runtime media/model compositing, selected dimensions, encoding, download, progress, and typed failures.",
     );
     expect(contract.aiUsageRules).toContain(
-      "PNG export must use createToolcraftPngExportCanvas so background transparency and selected image dimensions or retina fallback are applied consistently; turning Background off makes preview product background and PNG alpha transparent without hiding the Toolcraft canvas backing or video background.",
+      "Product modules must not encode or download export canvases directly and must not instantiate MediaRecorder or VideoEncoder; the generated-source boundary rejects those duplicate export paths.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Video export must keep product background and use getToolcraftVideoExportSize for current/4K output dimensions.",
+      "Runtime video export keeps the selected background and uses 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.",

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

@@ -264,6 +264,7 @@ export const TOOLCRAFT_CHOICE_COMPONENT_CONTRACTS = {
         "CollectionActions sits at the start of its section, renders the collection label on the left, and keeps remove/add icon buttons together on the right.",
         "Homogeneous repeated item controls do not render visible per-item labels when the collection label already names the group.",
         "Collection item controls follow normal density rules: plain color items use equal 50% columns when they fit, while color+opacity items stay stacked.",
+        "Compound itemControls records render one line only between adjacent logical items, with no generated Item N headings; standalone color itemControl collections keep the compact two-column grid without item dividers.",
         "CollectionActions is a compound control and follows content-width compound divider rules when sharing a section with sibling controls.",
         "recommendedMaxItems is an agent/layout/performance hint, not a hard add limit; hardMaxItems is allowed only for real algorithm, format, API, export, or proven performance limits.",
       ],
@@ -271,6 +272,7 @@ export const TOOLCRAFT_CHOICE_COMPONENT_CONTRACTS = {
         "Prove plus adds a runtime item and that the new item appears in or affects canvas preview and export.",
         "Prove minus removes a runtime item and that the removed item disappears from or stops affecting canvas preview and export.",
         "Prove minItems prevents deleting below the minimum and recommendedMaxItems does not silently block adding more items.",
+        "For itemControls, prove plus creates every declared default field in one runtime record, editing preserves sibling fields, and minus removes the whole final record from preview and export.",
       ],
     }),
     stateMode: "controlled",
@@ -280,12 +282,51 @@ export const TOOLCRAFT_CHOICE_COMPONENT_CONTRACTS = {
       "Do not model add/remove item behavior with a Slider count when users need to edit the actual items.",
       "recommendedMaxItems is advisory only and must not disable the plus button. Use hardMaxItems only when a real product, algorithm, API, export, or measured performance limit requires it.",
       "CollectionActions item controls use built-in controls whenever possible, such as Color, ColorOpacity, TextInput, Select, Segmented, Slider, Switch, Checkbox, RangeInput, or FontPicker.",
+      "Use itemControl when each repeated entity is one built-in value. Use itemControls only when two or more built-in fields describe one logical repeated product entity and are added or removed atomically.",
+      "Every itemControls field must belong to the same repeated product entity, share one parent array record, and affect that entity's product outcome; never group unrelated settings because they happen to use add/remove UI.",
       "Use FontPicker as the collection item control when each repeated item is a typography/text-style entity; do not split its font, color, opacity, size, case, letter-spacing, or line-height into sibling collection fields.",
       "Do not add visible labels like Color 1, Color 2, Item 1, or Item 2 for homogeneous collection items when the collection label already explains the group.",
       "Use compact half-width item layout whenever the child control is allowed to fit in a half row; color items without opacity are the default two-column case.",
       "Acceptance must add and remove items through the browser UI and prove canvas/export output follows the changed collection.",
     ],
   },
+  sourceCollection: {
+    ...control(
+      "sourceCollection",
+      "ControlsPanelCollectionItems",
+      "standalone",
+      "component-owned",
+    ),
+    decisionCatalog: decisionCatalog({
+      strictness: "exact-owner",
+      ownsValueModel: [
+        "source-owned collection cardinality",
+        "source-defined repeatable product entity collection",
+        "source-defined dynamic list of visible controls",
+      ],
+      useWhen: [
+        "Use SourceCollection when a loaded, derived, or detected source owns the item array length and the user edits only existing item values.",
+      ],
+      doNotReplaceWith: [
+        "Do not use CollectionActions when the user must not add or remove source-defined items.",
+        "Do not rebuild, copy, or recreate the repeated built-in item control in a custom control renderer.",
+      ],
+      acceptableAlternatives: [
+        "Use CollectionActions when the user owns add/remove cardinality.",
+      ],
+      layoutConstraints: [
+        "SourceCollection uses the same built-in item layout as CollectionActions and renders no add/remove header.",
+      ],
+      requiredAcceptance: [
+        "Prove the source item count, item editing, canvas preview, export output, and absence of add/remove commands.",
+      ],
+    }),
+    aiUsageRules: [
+      "Use SourceCollection for externally sized arrays of built-in item controls.",
+      "Declare a built-in itemControl; SourceCollection must not render add or remove commands.",
+      "The source workflow writes the complete target array; the panel edits item values only.",
+    ],
+  },
   panelActions: {
     ...control("panelActions", "PanelActions", "standalone", "component-owned"),
     decisionCatalog: decisionCatalog({
@@ -319,22 +360,26 @@ export const TOOLCRAFT_CHOICE_COMPONENT_CONTRACTS = {
     aiUsageRules: [
       "Use panelActions only for sticky footer product actions such as Generate, Export, Copy, or Download.",
       "Do not use panelActions for resetting controls; the controls panel header owns Reset controls.",
-      "Handle product-specific panelActions through ToolcraftApp onPanelAction.",
-      "Async product actions such as Export, Download, Copy, Generate, or Apply must return the real Promise from onPanelAction and report progress through the onPanelAction reportProgress callback.",
+      "Handle product-specific non-export panelActions through ToolcraftApp onPanelAction. Typed export-image and export-video actions are runtime-owned and consume ToolcraftAppComposition.exportRenderer.",
+      "Async non-export product actions such as Download, Copy, Generate, or Apply must return the real Promise from onPanelAction and report progress through the onPanelAction reportProgress callback.",
       "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.",
+      "Every product must declare productReadiness.exportIntent before authoring export panelActions or settings sections.",
       '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.",
+      'Image export is the Toolcraft product default. Keep Export PNG unless productReadiness.exportIntent.image is "user-removed" with non-empty explicit user-removal evidence.',
       '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".',
       'The Image Export section must include "export.image.resolution" as a Select control with 2K, 4K, and 8K choices, defaulting to "4k".',
       "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.",
-      "Apps that deliver animation include Export Video as the primary footer action and Export PNG as a secondary footer action; timeline playback alone does not invent video delivery.",
+      "Image Export resolution controls the actual exported image long edge: 2K = 2048px, 4K = 4096px, 8K = 8192px. Runtime resolves the selected value and protected browser acceptance proves decoded image width and height.",
+      'Add Export Video only when productReadiness.exportIntent.video is "user-requested" with non-empty explicit user-request evidence.',
+      'Animation, playback, keyframes, and timeline presence never add Export Video when productReadiness.exportIntent.video is "not-requested".',
       "Any app with Export Video must enable the top Toolcraft timeline; video duration, loop, and rendered timestamps come from runtime timeline state.",
       'Apps with Export Video must expose a separate "Video Export" controls section.',
       'Apps with both Export PNG and Export Video must expose both "Image Export" and "Video Export"; Image Export sits immediately before Video Export.',
+      'Image-only apps place "Image Export" directly above sticky footer panelActions.',
+      'Video-only apps require explicit image user-removal evidence and place "Video Export" directly above sticky footer panelActions.',
+      'Explicit no-export apps require image user-removal evidence with video "not-requested" and omit export actions and settings sections.',
       'The Video Export section must include format and resolution controls such as targets "export.video.format" and "export.video.resolution".',
       "Use Select controls for Video Export format and resolution; do not use Segmented unless the product has a deliberately tiny fixed output menu and browser tests prove every cell keeps padding.",
       'Place the Video Export section as the final controls section directly above sticky footer panelActions.',
@@ -342,17 +387,18 @@ export const TOOLCRAFT_CHOICE_COMPONENT_CONTRACTS = {
       'Video Export resolution defaults to "current"; keep "4k" available as the high-resolution alternate.',
       "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.",
+      "Runtime video export chooses the actual MIME, container, and codec through the timestamped Mediabunny encoder capability check, then returns the real supported format or a typed visible failure.",
       "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.",
+      "Runtime video export allocates the selected recording canvas dimensions before timestamped encoder setup and rejects renderer, encoder, muxer, and output-limit errors instead of returning corrupt blobs.",
+      "Offline video export duration is encoded from the fixed runtime 30 FPS timeline schedule. Product code must not use canvas.captureStream, MediaRecorder, or wall-clock time as a fallback.",
       '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.",
       "Video export must report frame-based progress through reportProgress during render/encode steps. PNG export should report phase progress for render, blob, and handoff when those phases are asynchronous.",
       'Product-output apps declare the standard background pair in an authored "Background" source section. Runtime removes that visible section and places Background plus Infinity canvas, then Background color, in Setup; Timeline is the final Setup control.',
-      "Product-output apps pass the includeBackground runtime value to createToolcraftPngExportCanvas for PNG alpha and call shouldIncludeToolcraftPreviewBackground(state) for bounded live preview background. In Infinity mode CanvasShell owns the selected full-viewport background color, and Background off restores finite mode and disables Infinity.",
-      "PNG export must use createToolcraftPngExportCanvas so background transparency and selected image dimensions or retina fallback are applied consistently; turning Background 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 getToolcraftVideoExportSize for current/4K output dimensions.",
+      "Product-output apps call shouldIncludeToolcraftPreviewBackground(state) for bounded live preview background. Runtime artifact export owns Background semantics: PNG may be transparent, JPEG and video remain opaque, Infinity uses the full-viewport color, and Background off restores finite mode and disables Infinity.",
+      "ToolcraftAppComposition.exportRenderer draws one deterministic product frame in scene coordinates for both image and video. Runtime owns canvas allocation, background, runtime media/model compositing, selected dimensions, encoding, download, progress, and typed failures.",
+      "Product modules must not encode or download export canvases directly and must not instantiate MediaRecorder or VideoEncoder; the generated-source boundary rejects those duplicate export paths.",
+      "Runtime video export keeps the selected background and uses 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.",

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

@@ -77,13 +77,13 @@ describe("Toolcraft template component contracts: inputs", () => {
       "Visual discrete sliders must still drag smoothly; their canonical performance path adapter should use dragToolcraftSliderByTarget for real pointer drag and let the central path profile own the budget.",
     );
     expect(slider.aiUsageRules).toContain(
-      "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.",
+      'Every product slider declares applicability as mode: "always" or mode: "conditional"; omitted applicability and legacy visibleWhen are runtime compatibility only.',
     );
     expect(slider.aiUsageRules).toContain(
-      "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.",
+      "Use conditional applicability for sliders that are meaningful only in some mode/type/source/include/count states; every predicate must match and inactive branches disappear.",
     );
     expect(slider.aiUsageRules).toContain(
-      "Do not leave an inactive conditional slider visible while making the renderer ignore it; hide it with visibleWhen.",
+      "Do not use schema disabled: true or disabledWhen for product sliders, and do not leave a visible slider in a branch where its value has no product effect.",
     );
     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.",
@@ -140,13 +140,13 @@ describe("Toolcraft template component contracts: inputs", () => {
       "Visual discrete sliders must still drag smoothly; their canonical performance path adapter should use dragToolcraftSliderByTarget for real pointer drag and let the central path profile own the budget.",
     );
     expect(rangeSlider.aiUsageRules).toContain(
-      "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.",
+      'Every product range slider declares applicability as mode: "always" or mode: "conditional"; omitted applicability and legacy visibleWhen are runtime compatibility only.',
     );
     expect(rangeSlider.aiUsageRules).toContain(
-      "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.",
+      "Use conditional applicability for range sliders that are meaningful only in some mode/type/source/include/count states; every predicate must match and inactive branches disappear.",
     );
     expect(rangeSlider.aiUsageRules).toContain(
-      "Do not leave an inactive conditional range slider visible while making the renderer ignore it; hide it with visibleWhen.",
+      "Do not use schema disabled: true or disabledWhen for product range sliders, and do not leave a visible range slider in a branch where its value has no product effect.",
     );
     expect(rangeSlider.aiUsageRules).toContain(
       "Acceptance must prove both rangeSlider.lower and rangeSlider.upper change the product output; testing one handle is not enough.",

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

@@ -85,9 +85,9 @@ export const TOOLCRAFT_INPUT_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; their canonical performance path adapter should use dragToolcraftSliderByTarget for real pointer drag and let the central path profile own the budget.",
-      "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.",
+      'Every product slider declares applicability as mode: "always" or mode: "conditional"; omitted applicability and legacy visibleWhen are runtime compatibility only.',
+      "Use conditional applicability for sliders that are meaningful only in some mode/type/source/include/count states; every predicate must match and inactive branches disappear.",
+      "Do not use schema disabled: true or disabledWhen for product sliders, and do not leave a visible slider in a branch where its value has no product effect.",
     ],
   },
   rangeSlider: {
@@ -137,9 +137,9 @@ export const TOOLCRAFT_INPUT_COMPONENT_CONTRACTS = {
       "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; their canonical performance path adapter should use dragToolcraftSliderByTarget for real pointer drag and let the central path profile own the budget.",
-      "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.",
+      'Every product range slider declares applicability as mode: "always" or mode: "conditional"; omitted applicability and legacy visibleWhen are runtime compatibility only.',
+      "Use conditional applicability for range sliders that are meaningful only in some mode/type/source/include/count states; every predicate must match and inactive branches disappear.",
+      "Do not use schema disabled: true or disabledWhen for product range sliders, and do not leave a visible range slider in a branch where its value has no product effect.",
       "Acceptance must prove both rangeSlider.lower and rangeSlider.upper change the product output; testing one handle is not enough.",
     ],
   },

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

@@ -14,13 +14,13 @@ describe("Toolcraft template component contracts: media and custom controls", ()
       "Every visible custom-control element must justify its space by enabling selection, ordering, preview, removal, upload, editing, or status that affects the product.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Do not use a custom control to recreate a built-in Slider, RangeSlider, Select, Segmented, Switch, Checkbox, Color, ColorOpacity, Gradient, FontPicker, ImagePicker, FileDrop, TextInput, CodeTextarea, RangeInput, Palette, Actions, CollectionActions, Curves, AnchorGrid, ChannelMixer, Vector, or PanelActions control.",
+      "Do not use a custom control to recreate a built-in Slider, RangeSlider, Select, Segmented, Switch, Checkbox, Color, ColorOpacity, Gradient, FontPicker, ImagePicker, FileDrop, TextInput, CodeTextarea, RangeInput, Palette, Actions, CollectionActions, SourceCollection, Curves, AnchorGrid, ChannelMixer, Vector, or PanelActions control.",
     );
     expect(contract.aiUsageRules).toContain(
       "Every custom-control builtInFitCheck declares typed capabilities. Use collection, reorder, selection, commands, custom-interaction, custom-value-model, and custom-visualization to describe behavior without relying on product nouns.",
     );
     expect(contract.aiUsageRules).toContain(
-      "When a custom control owns a growable, removable, selectable, or reorderable runtime item set, its builtInFitCheck must explicitly check collectionActions and actions before choosing custom; this is based on the value model and user workflow, not on entity names such as masks or glyphs.",
+      "When a custom control owns a repeated runtime item set, its builtInFitCheck must explicitly check sourceCollection, collectionActions, and actions before choosing custom; this is based on source versus user cardinality and the value workflow, not on entity names such as masks or glyphs.",
     );
     expect(contract.aiUsageRules).toContain(
       "Do not justify custom controls with icons, layout, styling, compactness, or custom buttons alone. The fit check must name the product interaction or value model that built-ins cannot express.",
@@ -107,6 +107,12 @@ describe("Toolcraft template component contracts: media and custom controls", ()
     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.",
     );
+    expect(contract.aiUsageRules).toContain(
+      'Use fileDrop variant: "collection-actions" only with assetKind: "file" and multiple: true when the user explicitly wants collectionActions-style compact − / + cardinality. The variant keeps runtime media order, uses + to add an empty upload slot, and uses − to remove the final slot or attached file.',
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Each collection-actions FileDrop slot and its itemControls settings form one logical item group; runtime renders one line only between adjacent groups.",
+    );
     expect(contract.aiUsageRules).toContain(
       "fileDrop recommendedMaxItems is advisory and never rejects an import. A finite nonnegative safe-integer hardMaxItems is an actual admission limit: additive imports count existing assets for the same source target plus the incoming logical batch, replacement imports count only the replacement batch, and overflow is rejected before decoding or repository allocation.",
     );

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

@@ -29,6 +29,9 @@ export const TOOLCRAFT_MEDIA_CUSTOM_COMPONENT_CONTRACTS = {
         "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.",
+        'A multiple file-kind fileDrop may use variant: "collection-actions" when collection cardinality should use the same compact − / + header as collectionActions. In that variant + adds one empty FileDrop slot and − removes the final slot or its attached file.',
+        "A collection-actions fileDrop may declare itemControls so every attached file renders its own built-in settings immediately below its upload row. The parent target stores records keyed by mediaId while binary lifecycle remains in runtime media state.",
+        "Each collection-actions FileDrop slot and its itemControls settings form one logical item group; runtime renders one line only between adjacent groups.",
         "When fileDrop has assetKind: model, standard model preview remains runtime-owned even when renderDefaultCanvasMedia is false; custom presentation is selected only through ToolcraftAppComposition modelPresentation.",
       ],
       requiredAcceptance: [
@@ -56,6 +59,9 @@ export const TOOLCRAFT_MEDIA_CUSTOM_COMPONENT_CONTRACTS = {
       "In file mode, the runtime shows uploaded files as a sortable list with paperclip icons, file names, remove buttons, and --border/5 separators.",
       "In single-layer apps, global Reset controls and section reset must restore fileDrop source media to schema media.defaultAssets for that target; when no default asset exists, Reset removes uploaded media and returns the fileDrop target to defaultValue.",
       "Use fileDrop with multiple: true when the app needs several uploaded images as one source set; do not build a custom thumbnail uploader for this.",
+      'Use fileDrop variant: "collection-actions" only with assetKind: "file" and multiple: true when the user explicitly wants collectionActions-style compact − / + cardinality. The variant keeps runtime media order, uses + to add an empty upload slot, and uses − to remove the final slot or attached file.',
+      "Use fileDrop itemControls when settings belong to individual attached files. Each nested control declares a defaultValue; only attached slots render settings, and the runtime commits a parent-target array keyed by mediaId for reset, undo, and persistence.",
+      "Each collection-actions FileDrop slot and its itemControls settings form one logical item group; runtime renders one line only between adjacent groups.",
       "fileDrop recommendedMaxItems is advisory and never rejects an import. A finite nonnegative safe-integer hardMaxItems is an actual admission limit: additive imports count existing assets for the same source target plus the incoming logical batch, replacement imports count only the replacement batch, and overflow is rejected before decoding or repository allocation.",
       "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.",
@@ -134,9 +140,9 @@ export const TOOLCRAFT_MEDIA_CUSTOM_COMPONENT_CONTRACTS = {
     }),
     aiUsageRules: [
       "Use custom controls only for product interactions that built-in controls cannot express.",
-      "Do not use a custom control to recreate a built-in Slider, RangeSlider, Select, Segmented, Switch, Checkbox, Color, ColorOpacity, Gradient, FontPicker, ImagePicker, FileDrop, TextInput, CodeTextarea, RangeInput, Palette, Actions, CollectionActions, Curves, AnchorGrid, ChannelMixer, Vector, or PanelActions control.",
+      "Do not use a custom control to recreate a built-in Slider, RangeSlider, Select, Segmented, Switch, Checkbox, Color, ColorOpacity, Gradient, FontPicker, ImagePicker, FileDrop, TextInput, CodeTextarea, RangeInput, Palette, Actions, CollectionActions, SourceCollection, Curves, AnchorGrid, ChannelMixer, Vector, or PanelActions control.",
       "Every custom-control builtInFitCheck declares typed capabilities. Use collection, reorder, selection, commands, custom-interaction, custom-value-model, and custom-visualization to describe behavior without relying on product nouns.",
-      "When a custom control owns a growable, removable, selectable, or reorderable runtime item set, its builtInFitCheck must explicitly check collectionActions and actions before choosing custom; this is based on the value model and user workflow, not on entity names such as masks or glyphs.",
+      "When a custom control owns a repeated runtime item set, its builtInFitCheck must explicitly check sourceCollection, collectionActions, and actions before choosing custom; this is based on source versus user cardinality and the value workflow, not on entity names such as masks or glyphs.",
       "Do not justify custom controls with icons, layout, styling, compactness, or custom buttons alone. The fit check must name the product interaction or value model that built-ins cannot express.",
       "Custom controls may use Toolcraft primitives for small app-specific chrome, but must not import or render low-level runtime surfaces or duplicate toolbar, timeline, layers, canvas, panel, or built-in control mechanics.",
       "Custom controls must render the minimum UI needed to understand the value, context, and available actions; avoid decorative metadata and text that repeats what the section, label, or visible item already explains.",

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

@@ -38,16 +38,16 @@ describe("Toolcraft template component contracts: runtime and composition", () =
       "Conditional entities require fixtures that make the condition observable.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Use visibleWhen for mode-, type-, source-, include-, variant-, or count-exclusive sections or controls that do not belong to the current selected state.",
+      'Every generated product control declares applicability as mode: "always" or mode: "conditional"; omitted applicability and legacy visibleWhen are runtime compatibility only and fail starter acceptance.',
     );
     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.",
+      "Conditional applicability combines every predicate with AND, hides controls outside mode/type/source/include/variant/count branches, and preserves their runtime values while hidden.",
     );
     expect(contract.aiUsageRules).toContain(
-      "If a switch/select/segmented/tabs/imagePicker/checkbox chooses a branch for the same product entity, controls outside the current branch use visibleWhen, not disabledWhen.",
+      "A visible product control must prove its existing product outcome in every supported finite sibling-selector branch from its Control Section Inventory, including always controls and selectors omitted from its predicates.",
     );
     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.",
+      "Do not use schema disabled: true or disabledWhen for generated product availability; runtime primitives may use disabled styling internally, but product controls outside the active branch are absent.",
     );
     expect(contract.aiUsageRules).toContain(
       "Do not leave inactive conditional controls visible while making the renderer ignore them.",
@@ -82,10 +82,22 @@ describe("Toolcraft template component contracts: runtime and composition", () =
     );
     expect(rules).toContain("performance-iteration");
     expect(rules).toContain(
-      "one exact authority-selected targeted performance iteration",
+      "Only a localized complaint or a post-clarification targeted choice creates performance-iteration intent",
     );
     expect(rules).toContain(
-      "Complaint wording and repetition never select the complete performance matrix",
+      "Classifier output establishes complaint authority only and never path localization",
+    );
+    expect(rules).toContain(
+      "Regardless of whether the classifier returned high-confidence performance-iteration or needs-agent-judgment, unresolved localization creates neither performance-iteration intent nor canonical path authority",
+    );
+    expect(rules).toContain(
+      "repetition alone never expands scope or selects the complete performance matrix",
+    );
+    expect(rules).not.toContain(
+      "One complaint maps to one exact authority-selected targeted performance iteration",
+    );
+    expect(rules).not.toContain(
+      "Direct and repeated performance complaints each start one bounded targeted iteration",
     );
     expect(rules).toContain(
       "After two consecutive compatible protected performance iterations, the agent must offer a slower complete audit",
@@ -135,6 +147,9 @@ describe("Toolcraft template component contracts: runtime and composition", () =
     expect(rules).toContain(
       TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.renderScaleFidelity,
     );
+    expect(rules).toContain(
+      TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.complaintRouting,
+    );
     expect(contract.aiUsageRules).toContain(
       "Every export performance scenario must declare the exact panelActions actionValue, visible controlLabel, and completionEvidence it exercises; selectors, unrelated export actions, and injectable completion callbacks are not output evidence. The named browser scenario must resolve to test or it imported from @playwright/test, be statically registered at module scope or inside an executable test.describe, test.describe.serial, or test.describe.parallel suite, and directly await the matching unshadowed protected output-action helper in its root callback block without focus, skip, condition, or nesting; local test runners, uncalled or conditional test declarations, skipped/fixme suites, and runtime skip/fixme/fail annotations are invalid, and generated integrity protects the focused-test Playwright config.",
     );

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

@@ -24,7 +24,13 @@ describe("Toolcraft template component contracts: runtime and composition", () =
       "Acceptance validators suggest semantic replacement labels for weak generic labels; fix the schema label instead of relying on runtime fallback rewriting.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Controls-panel sections should stay discrete: two to seven product controls is the normal size, and larger sections must split by product sub-entity or workflow stage.",
+      "One to seven controls is the normal section size. Eight to ten controls are allowed only for one cohesive entity and require semanticGroup on every control; ten is the hard maximum.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Every Control Section Inventory entry declares required entityId, entity, exact targets, and groupingReason. One entity with ten or fewer controls stays in one section regardless of control type, visual height, or target namespace.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "An entity above ten controls splits into balanced workflow sections of two to ten controls. Every split section keeps the same entityId and entity and declares a unique workflowStage plus splitReason.",
     );
     expect(contract.aiUsageRules).toContain(
       "Every app-authored controls-panel body section must have a short meaningful visible title. Runtime-created Setup renders as the first visible headerless controls block with no title, reset action, collapse button, or collapsed state; sticky footer action sections use the technical title Export but render without a visible heading.",

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

@@ -62,7 +62,10 @@ describe("Toolcraft template component contracts: runtime and composition", () =
       '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.",
+      'Export Video is valid only when productReadiness.exportIntent.video is "user-requested" with non-empty explicit user-request evidence; animation, playback, keyframes, and timeline presence never authorize video export.',
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      "Video export frames are rendered deterministically from the runtime-owned 30 FPS timeline schedule; product code must not use autonomous wall-clock time, captureStream, or MediaRecorder as the source or fallback for 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.",

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

@@ -58,7 +58,10 @@ describe("Toolcraft template component contracts: runtime and composition", () =
       "When the standard Background pair exists, disabling Background atomically restores finite mode and disables Infinity canvas; re-enabling Background restores switch availability without enabling Infinity automatically.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Infinite exports use canonical world-space scene frames: ToolcraftAppComposition.sceneBoundsProvider contributes product bounds, runtime image and model bounds are unioned once, hidden or suppressed content is excluded, PNG crops tightly, and video uses one time-range envelope.",
+      "Infinite exports use canonical world-space scene frames: ToolcraftAppComposition.sceneBoundsProvider contributes exact-state product bounds, runtime image and model bounds are unioned, hidden or suppressed content is excluded, PNG crops tightly, and runtime video unions every scheduled frame state into one envelope.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Infinite live preview uses that same exact-state product frame: runtime positions one product scene surface from sceneBoundsProvider, and custom raster/WebGL output consumes useToolcraftProductSceneFrame for backing size and world-to-local translation instead of dormant canvas.size.",
     );
     expect(contract.aiUsageRules).toContain(
       "Do not let canvas.upload choose intrinsic-media by default. Upload without explicit sizing resolves to editable-output so source/background images do not own product output size.",