@pixel-point/toolcraft 0.0.17 → 0.0.18

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", () => {
@@ -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.',
@@ -252,7 +284,10 @@ describe("Toolcraft template component contracts: choices and actions", () => {
       "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".',
     );

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({
@@ -323,18 +364,22 @@ export const TOOLCRAFT_CHOICE_COMPONENT_CONTRACTS = {
       "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. Runtime resolves the selected value and protected browser acceptance proves decoded image width and height.",
-      "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.',
+      '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.',

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.",

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

@@ -61,6 +61,9 @@ describe("Toolcraft template component contracts: runtime and composition", () =
     expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
       'Any product app with Export Video must enable the top Toolcraft timeline: use panels.timeline mode "playback" for product animation transport, or mode "keyframes" when exported animation is driven by keyframes.',
     );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      '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.",
     );

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

@@ -60,6 +60,9 @@ describe("Toolcraft template component contracts: runtime and composition", () =
     expect(contract.aiUsageRules).toContain(
       "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.",
     );

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

@@ -27,6 +27,7 @@ export const TOOLCRAFT_RUNTIME_COMPONENT_CONTRACTS = {
       "Infinity canvas suppresses the bounded product-rendered preview background so the dormant finite output does not appear as a second canvas; when the standard Background pair is enabled, CanvasShell fills the complete infinite viewport with the selected Background color.",
       "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.",
       "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.",
+      "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.",
       "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.",
@@ -127,11 +128,12 @@ export const TOOLCRAFT_RUNTIME_COMPONENT_CONTRACTS = {
       "A generic canvas hash difference is not enough for workload or semantic controls; assert the intended direction of the effect.",
       "Component variants are accepted entities too; tests should fail if a non-default Toolcraft control variant falls back to the default variant or custom markup.",
       "Conditional entities require fixtures that make the condition observable.",
-      "Use visibleWhen for mode-, type-, source-, include-, variant-, or count-exclusive sections or controls that do not belong to the current selected state.",
-      "When visibleWhen references a selector for the same product entity or selected branch, keep the selector and its dependent controls in one semantic section. A section that exists only because one selector option is active is not a separate product section just because the branch uses a standalone control.",
-      "When a count/quantity control determines how many sibling controls are available, hide unavailable siblings with visibleWhen; do not render all possible controls while the renderer reads only the first N.",
-      "If a switch/select/segmented/tabs/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.",
+      '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.',
+      "Conditional applicability combines every predicate with AND, hides controls outside mode/type/source/include/variant/count branches, and preserves their runtime values while hidden.",
+      "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.",
+      "When applicability 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 applicable, conditional applicability hides unavailable siblings; do not render all possible controls while the renderer reads only the first N.",
+      "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.",
       "Do not leave inactive conditional controls visible while making the renderer ignore them.",
       "Before controls or canvas interactions, declare typed interactionOwnership for every operation that could plausibly live on either surface. User request, inspected reference, or product usability selects one primary owner.",
       "Do not mirror one operation across canvas and panel, even with different labels, ids, styling, or custom chrome. The same target and operation capability has one surface owner.",
@@ -238,9 +240,10 @@ export const TOOLCRAFT_RUNTIME_COMPONENT_CONTRACTS = {
       "A concise property label such as Speed, Color, Size, or Opacity is allowed when the nearest visible section or group clearly names the affected product entity.",
       "When the section is generic, mixed, missing, or otherwise weak context, include the affected entity or role in the label: Pattern color, Background opacity, Wave speed, Stroke width.",
       "Acceptance validators suggest semantic replacement labels for weak generic labels; fix the schema label instead of relying on runtime fallback rewriting.",
-      "Controls-panel sections should stay discrete: two to seven product controls is the normal size, and larger sections must split by product sub-entity or workflow stage.",
-      "Generated product apps must export starterControlSectionInventory beside acceptance. Every product controls section declares title, exact targets, groupingReason, and entity or workflowStage; intentional splits of one target entity require workflowStage and splitReason on every split section.",
-      "Section splitting must preserve dependency cohesion: a selector stays with the visibleWhen controls it gates when they share the same target entity or selected branch. Use internal spacing/dividers or a more specific section title before splitting dependent branch controls away.",
+      "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.",
+      "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.",
+      "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.",
+      "Section splitting must preserve dependency cohesion: a selector stays with the applicability-gated controls it owns 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.",
@@ -319,6 +322,7 @@ export const TOOLCRAFT_RUNTIME_COMPONENT_CONTRACTS = {
       "Before choosing no timeline for any animated product, write an Animation Intent Inventory: product transport, editable keyframes, or autonomous decorative output, plus the user-facing time behaviors present or intentionally absent.",
       'User-requested product animation defaults to panels.timeline mode "playback" unless the spec explicitly declares autonomous decorative/self-running output with no play, pause, scrub, duration, loop, export-at-time behavior, or video export.',
       'Any product app with Export Video must enable the top Toolcraft timeline: use panels.timeline mode "playback" for product animation transport, or mode "keyframes" when exported animation is driven by keyframes.',
+      '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.',
       '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.",

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

@@ -26,6 +26,7 @@ describe("Toolcraft template component contracts: core", () => {
       "checkbox",
       "actions",
       "collectionActions",
+      "sourceCollection",
       "panelActions",
       "colorOpacity",
       "palette",
@@ -72,6 +73,7 @@ describe("Toolcraft template component contracts: core", () => {
       "palette",
       "actions",
       "collectionActions",
+      "sourceCollection",
       "panelActions",
       "customControl",
     ] as const) {

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

@@ -54,6 +54,8 @@ describe("Toolcraft template decision contract", () => {
 
     expect(rule?.level).toBe("invariant");
     expect(rule?.desiredBehavior).toMatch(/sceneBoundsProvider/i);
+    expect(rule?.desiredBehavior).toMatch(/useToolcraftProductSceneFrame/i);
+    expect(rule?.desiredBehavior).toMatch(/live infinite preview/i);
     expect(rule?.desiredBehavior).toMatch(/one exact state/i);
     expect(rule?.desiredBehavior).toMatch(/runtime-owned timestamp schedule/i);
     expect(rule?.desiredBehavior).toMatch(/finite canvas size/i);
@@ -116,6 +118,22 @@ describe("Toolcraft template decision contract", () => {
     );
   });
 
+  it("requires artifact delivery to correspond exactly to explicit product export intent", () => {
+    const rule = getToolcraftDecisionRule("output-export-required");
+
+    expect(rule?.level).toBe("invariant");
+    expect(rule?.desiredBehavior).toMatch(/productReadiness\.exportIntent/);
+    expect(rule?.desiredBehavior).toMatch(/image[^.]*Toolcraft default/i);
+    expect(rule?.desiredBehavior).toMatch(/video[^.]*explicit user request[^.]*evidence/i);
+    expect(rule?.desiredBehavior).toMatch(
+      /animation, playback, keyframes, or timeline[^.]*never/i,
+    );
+    expect(rule?.desiredBehavior).toMatch(/image[^.]*removed[^.]*explicit user[^.]*evidence/i);
+    expect(rule?.desiredBehavior).toMatch(
+      /intent[^.]*correspond exactly[^.]*schema actions, settings sections, and acceptance coverage/i,
+    );
+  });
+
   it("makes renderer technology a default with escape hatches", () => {
     const rule = getToolcraftDecisionRule("renderer-technique-inventory");