@pixel-point/toolcraft 0.0.14 → 0.0.15

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

@@ -0,0 +1,210 @@
+import { describe, expect, it } from "vitest";
+
+import { getToolcraftComponentContract } from "./component-contracts";
+
+describe("Toolcraft template component contracts: inputs", () => {
+  it("documents slider visual variants as explicit schema choices", () => {
+    const slider = getToolcraftComponentContract("slider");
+    const rangeSlider = getToolcraftComponentContract("rangeSlider");
+
+    expect(slider.decisionCatalog.requiredAcceptance).toContain(
+      "Prove dragging the slider changes product output or the intended runtime side effect while the drag is in progress, not only after pointer release, blur, Apply, or a final commit.",
+    );
+    expect(slider.aiUsageRules).toContain(
+      "Sliders are live canvas controls: dragging must update runtime state and product output in real time by default.",
+    );
+    expect(slider.aiUsageRules).toContain(
+      "Do not implement slider values as deferred local drafts, Apply-only updates, pointer-up-only commits, or renderer changes that appear only after the user asks again.",
+    );
+    expect(slider.aiUsageRules).toContain(
+      "Slider performance coverage must use a real control-drag scenario; control-change coverage is not enough to prove live canvas feedback or drag smoothness.",
+    );
+    expect(slider.aiUsageRules).toContain(
+      "If a live slider causes jank, optimize the renderer path first: update uniforms or stable buffers, cache expensive inputs, coalesce preview work to requestAnimationFrame, cancel stale async renders, move heavy work off React, or switch renderer strategy.",
+    );
+    expect(slider.aiUsageRules).toContain(
+      "Only in an extreme documented performance ceiling may a slider use a degraded live preview or delayed heavy refinement; the user must still see immediate canvas feedback while dragging and the worklog must record the measured reason.",
+    );
+    expect(slider.aiUsageRules).toContain(
+      "Slider step means numeric snapping only; it does not make the slider visually discrete by itself.",
+    );
+    expect(slider.aiUsageRules).toContain(
+      'Every slider declares sliderValueKind: "continuous" or "discrete" from the product value model. Labels and descriptions are not slider-kind evidence.',
+    );
+    expect(slider.aiUsageRules).toContain(
+      'Use variant: "discrete" only with sliderValueKind: "discrete"; the typed value kind lets validation stay language-independent.',
+    );
+    expect(slider.aiUsageRules).toContain(
+      "Classify every stepped slider as stepped continuous or visual discrete before writing the schema.",
+    );
+    expect(slider.aiUsageRules).toContain(
+      'Small semantic integer domains such as rows, cols, gaps, jitter, counts, levels, bands, passes, points, tiles, and segments must use variant: "discrete".',
+    );
+    expect(slider.aiUsageRules).toContain(
+      'Finite animation step domains such as flip depth, character count, glyph steps, and frame steps must use variant: "discrete" when the marker count stays within the Toolcraft visual budget.',
+    );
+    expect(slider.aiUsageRules).toContain(
+      "Large or precision stepped ranges such as speed, FPS, rate, duration, density, size, and intensity stay visually continuous even when they declare step.",
+    );
+    expect(slider.aiUsageRules).toContain(
+      "Use slider unit only for real measurement suffixes such as %, px, °, s, ms, fps, rows/cols, or similar domain units.",
+    );
+    expect(slider.aiUsageRules).toContain(
+      "Do not use unit for repeated entity nouns already named by the section or label, such as Letters + letters, Shape Density / Count + shapes, Words + words, Symbols + symbols, Items + items, Particles + particles, or Layers + layers.",
+    );
+    expect(slider.aiUsageRules).toContain(
+      'Do not use unit: "x"; scale, multiplier, intensity, opacity, strength, depth, and shader amount sliders display plain numbers unless a real measurement unit applies.',
+    );
+    expect(slider.aiUsageRules).toContain(
+      "When the value needs an entity noun to make sense, improve the label or section title instead of appending that noun as the value unit.",
+    );
+    expect(slider.aiUsageRules).toContain(
+      "Compact symbol/CSS units render tight, such as 70%, 24px, and 8s; word units render with a space, such as 5 cols, when they are truly needed.",
+    );
+    expect(slider.aiUsageRules).toContain(
+      "Slider valueLabel is editable only when it contains a numeric value; textual state labels such as Normal are display-only and must not expose hover or click editing affordances.",
+    );
+    expect(slider.aiUsageRules).toContain(
+      "Schema sliders render stacked at full width; do not put sliders in two-column inline layout groups.",
+    );
+    expect(slider.aiUsageRules).toContain(
+      "The fontPicker component is the only built-in exception with two internal footer sliders for letter spacing and line height.",
+    );
+    expect(slider.aiUsageRules).toContain(
+      'Browser verification can inspect [data-slot="slider"][data-variant="discrete"] plus slider markers to prove the Toolcraft component variant rendered.',
+    );
+    expect(slider.aiUsageRules).toContain(
+      "Visual discrete sliders must still drag smoothly; browser performance tests should use expectToolcraftDiscreteSliderDragSmoothness for real pointer drag.",
+    );
+    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.",
+    );
+    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.",
+    );
+    expect(slider.aiUsageRules).toContain(
+      "Do not leave an inactive conditional slider visible while making the renderer ignore it; hide it with visibleWhen.",
+    );
+    expect(rangeSlider.decisionCatalog.requiredAcceptance).toContain(
+      "Prove dragging rangeSlider.lower and rangeSlider.upper both affect product output while the drag is in progress, not only after pointer release, blur, Apply, or a final commit.",
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      "Range sliders are live canvas controls: dragging either thumb must update runtime state and product output in real time by default.",
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      "Do not implement range slider values as deferred local drafts, Apply-only updates, pointer-up-only commits, or renderer changes that appear only after the user asks again.",
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      "Range slider performance coverage must use a real control-drag scenario; control-change coverage is not enough to prove live canvas feedback or drag smoothness.",
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      "If a live range slider causes jank, optimize the renderer path first: update uniforms or stable buffers, cache expensive inputs, coalesce preview work to requestAnimationFrame, cancel stale async renders, move heavy work off React, or switch renderer strategy.",
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      "Only in an extreme documented performance ceiling may a range slider use a degraded live preview or delayed heavy refinement; the user must still see immediate canvas feedback while dragging and the worklog must record the measured reason.",
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      "Range slider step means numeric snapping only; it does not make the range slider visually discrete by itself.",
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      "Classify every stepped range slider as stepped continuous or visual discrete before writing the schema.",
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      'Small semantic integer domains such as rows, cols, gaps, jitter, counts, levels, bands, passes, points, tiles, and segments must use variant: "discrete".',
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      'Finite animation step domains such as flip depth, character count, glyph steps, and frame steps must use variant: "discrete" when the marker count stays within the Toolcraft visual budget.',
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      "Large or precision stepped ranges such as speed, FPS, rate, duration, density, size, and intensity stay visually continuous even when they declare step.",
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      "Use rangeSlider unit only for real measurement suffixes; do not use it for repeated entity nouns already named by the section or label, and do not use x as a unit.",
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      "When a range label needs an entity noun to make sense, improve the label or section title instead of appending that noun as the value unit.",
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      "Compact symbol/CSS units render tight, such as 20% – 80% or 12px – 48px; word units render with a space when truly needed.",
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      "RangeSlider is always a full-width two-thumb control; never place it in an inline two-column layout group with another slider or range slider.",
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      "RangeSlider defaultValue must start with different lower and upper values so the two-thumb control does not collapse into a single-value slider.",
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      "Visual discrete sliders must still drag smoothly; browser performance tests should use expectToolcraftDiscreteSliderDragSmoothness for real pointer drag.",
+    );
+    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.",
+    );
+    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.",
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      "Do not leave an inactive conditional range slider visible while making the renderer ignore it; hide it with visibleWhen.",
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      "Acceptance must prove both rangeSlider.lower and rangeSlider.upper change the product output; testing one handle is not enough.",
+    );
+  });
+
+  it("documents CodeTextarea as generic multiline text input", () => {
+    const contract = getToolcraftComponentContract("code");
+
+    expect(contract.visualComponent).toBe("CodeTextarea");
+    expect(contract.defaultSectionLayout).toBe("standalone");
+    expect(contract.labelPolicy).toBe("required");
+    expect(contract.aiUsageRules).toContain(
+      "CodeTextarea is the multiline text input for any potentially long value, not only source code.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      'Every CodeTextarea declares textValueKind: "multiline" or "structured". Control selection must not be inferred from English labels or a short default value.',
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Do not use CodeTextarea for short single-line canvas text, button labels, names, titles, captions, badges, or short tokens; use TextInput.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Use text for short single-line strings such as names, button labels, small numeric values, compact prompts, titles, captions, and short tokens.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Use code only when the user may enter long prompts, multiline text, instructions, JSON, CSS, shader code, scripts, templates, or other long structured data.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "If CodeTextarea has a short single-line default value, the schema description must make the long, multiline, or structured-content reason explicit.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "CodeTextarea is a content editor and applies values while typing; do not wait for blur, Enter, or Cmd/Ctrl+Enter to update runtime state.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "CodeTextarea height is capped at 12 visible text lines; long content scrolls inside the textarea instead of making the controls panel taller.",
+    );
+  });
+
+  it("documents TextInput content and setting commit modes", () => {
+    const contract = getToolcraftComponentContract("text");
+
+    expect(contract.visualComponent).toBe("TextInput");
+    expect(contract.defaultSectionLayout).toBe("grouped");
+    expect(contract.labelPolicy).toBe("required");
+    expect(contract.aiUsageRules).toContain(
+      "TextInput owns short single-line product text: button labels, labels on the canvas, names, titles, captions, badges, short tokens, and compact prompts.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      'Every TextInput declares textValueKind: "single-line". Control selection must not be inferred from the label, description, or default string length.',
+    );
+    expect(contract.aiUsageRules).toContain(
+      'TextInput commitMode defaults to "content": text content, prompts, names, tokens, titles, and instructions apply while typing.',
+    );
+    expect(contract.aiUsageRules).toContain(
+      'Use commitMode: "setting" for text inputs that edit settings such as font size, numeric-like style values, dimensions, ids, or configuration fields; setting text commits on blur or Enter.',
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Canvas width and Canvas height are runtime editable-size fields and always commit on blur or Enter like editor size fields.",
+    );
+  });
+});

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

@@ -0,0 +1,252 @@
+import { control, decisionCatalog } from "./component-contract-builders";
+import type { ToolcraftComponentContract } from "./types";
+export const TOOLCRAFT_INPUT_COMPONENT_CONTRACTS = {
+  aspectRatio: {
+    ...control("aspectRatio", "CanvasAspectRatioControl", "grouped", "required"),
+    decisionCatalog: decisionCatalog({
+      strictness: "exact-owner",
+      ownsValueModel: [
+        "canvas aspect-ratio preset",
+        "custom canvas width-to-height ratio",
+      ],
+      useWhen: [
+        "Use AspectRatio for the runtime-owned editable canvas ratio in Setup.",
+      ],
+      doNotReplaceWith: [
+        "Do not recreate canvas aspect ratio with a product Select or detached width and height controls.",
+      ],
+      layoutConstraints: [
+        "AspectRatio belongs to the mandatory runtime Setup block before Canvas width and Canvas height.",
+      ],
+      requiredAcceptance: [
+        "Prove presets resize the current canvas and custom dimensions report the current reduced ratio.",
+      ],
+    }),
+    aiUsageRules: [
+      "AspectRatio is runtime-owned Setup UI and is not authored as a product control.",
+      "Manual canvas dimension edits switch the value to Custom without changing the other dimension.",
+    ],
+  },
+  slider: {
+    ...control("slider", "Slider", "grouped", "required"),
+    decisionCatalog: decisionCatalog({
+      strictness: "best-fit",
+      ownsValueModel: [
+        "single numeric value",
+        "bounded continuous range",
+        "bounded stepped range",
+        "small semantic integer range",
+      ],
+      useWhen: [
+        "Use Slider for one numeric value inside fixed min and max bounds.",
+        "Use Slider when dragging through approximate values is useful and every intermediate value is valid.",
+        "Use variant discrete only for small semantic integer domains where markers help choose positions.",
+      ],
+      doNotReplaceWith: [
+        "Do not use Slider for finite named options; use Select or Segmented.",
+        "Do not use two Slider controls for a lower/upper range; use RangeSlider or RangeInput.",
+        "Do not use Slider as a detached opacity field for a color entity; use ColorOpacity.",
+      ],
+      acceptableAlternatives: [
+        "Use Select for small named option sets.",
+        "Use RangeSlider or RangeInput for from/to ranges.",
+      ],
+      layoutConstraints: [
+        "Schema sliders stay stacked at full width.",
+        "Only FontPicker may pair its internal letter-spacing and line-height sliders.",
+      ],
+      requiredAcceptance: [
+        "Prove dragging the slider changes product output or the intended runtime side effect while the drag is in progress, not only after pointer release, blur, Apply, or a final commit.",
+        "For discrete sliders, prove the discrete variant renders markers and dragging remains smooth.",
+      ],
+    }),
+    aiUsageRules: [
+      "Sliders are live canvas controls: dragging must update runtime state and product output in real time by default.",
+      "Do not implement slider values as deferred local drafts, Apply-only updates, pointer-up-only commits, or renderer changes that appear only after the user asks again.",
+      "Slider performance coverage must use a real control-drag scenario; control-change coverage is not enough to prove live canvas feedback or drag smoothness.",
+      "If a live slider causes jank, optimize the renderer path first: update uniforms or stable buffers, cache expensive inputs, coalesce preview work to requestAnimationFrame, cancel stale async renders, move heavy work off React, or switch renderer strategy.",
+      "Only in an extreme documented performance ceiling may a slider use a degraded live preview or delayed heavy refinement; the user must still see immediate canvas feedback while dragging and the worklog must record the measured reason.",
+      "Slider step means numeric snapping only; it does not make the slider visually discrete by itself.",
+      'Every slider declares sliderValueKind: "continuous" or "discrete" from the product value model. Labels and descriptions are not slider-kind evidence.',
+      'Use variant: "discrete" only with sliderValueKind: "discrete"; the typed value kind lets validation stay language-independent.',
+      "Classify every stepped slider as stepped continuous or visual discrete before writing the schema.",
+      'Small semantic integer domains such as rows, cols, gaps, jitter, counts, levels, bands, passes, points, tiles, and segments must use variant: "discrete".',
+      'Finite animation step domains such as flip depth, character count, glyph steps, and frame steps must use variant: "discrete" when the marker count stays within the Toolcraft visual budget.',
+      "Large or precision stepped ranges such as speed, FPS, rate, duration, density, size, and intensity stay visually continuous even when they declare step.",
+      "Use slider unit only for real measurement suffixes such as %, px, °, s, ms, fps, rows/cols, or similar domain units.",
+      "Do not use unit for repeated entity nouns already named by the section or label, such as Letters + letters, Shape Density / Count + shapes, Words + words, Symbols + symbols, Items + items, Particles + particles, or Layers + layers.",
+      'Do not use unit: "x"; scale, multiplier, intensity, opacity, strength, depth, and shader amount sliders display plain numbers unless a real measurement unit applies.',
+      "When the value needs an entity noun to make sense, improve the label or section title instead of appending that noun as the value unit.",
+      "Compact symbol/CSS units render tight, such as 70%, 24px, and 8s; word units render with a space, such as 5 cols, when they are truly needed.",
+      "Slider valueLabel is editable only when it contains a numeric value; textual state labels such as Normal are display-only and must not expose hover or click editing affordances.",
+      "Schema sliders render stacked at full width; do not put sliders in two-column inline layout groups.",
+      "The fontPicker component is the only built-in exception with two internal footer sliders for letter spacing and line height.",
+      "For a small named option set, prefer Select or Segmented instead of forcing a discrete Slider.",
+      'Specs, plans, and app-schema tests must assert explicit discrete sliders render as variant: "discrete" with markers derived from min, max, and step.',
+      'Browser verification can inspect [data-slot="slider"][data-variant="discrete"] plus slider markers to prove the Toolcraft component variant rendered.',
+      "Visual discrete sliders must still drag smoothly; browser performance tests should use expectToolcraftDiscreteSliderDragSmoothness for real pointer drag.",
+      "Use visibleWhen for sliders that are meaningful only in some mode/type/source/include/count states; inactive branches should disappear so the panel shows only controls usable in the current state.",
+      "Do not use schema disabled: true or disabledWhen for product sliders; product panels should show only controls usable in the current state. Use visibleWhen for unavailable product states instead of rendering disabled controls.",
+      "Do not leave an inactive conditional slider visible while making the renderer ignore it; hide it with visibleWhen.",
+    ],
+  },
+  rangeSlider: {
+    ...control("rangeSlider", "RangeSlider", "grouped", "required"),
+    decisionCatalog: decisionCatalog({
+      strictness: "exact-owner",
+      ownsValueModel: [
+        "numeric lower and upper bounds",
+        "from/to numeric range",
+        "two-thumb bounded interval",
+      ],
+      useWhen: [
+        "Use RangeSlider when users edit lower and upper bounds on the same numeric scale.",
+        "Use RangeSlider when the relationship between the two values matters visually.",
+      ],
+      doNotReplaceWith: [
+        "Do not replace RangeSlider with two independent Slider controls.",
+        "Do not place RangeSlider beside another slider in an inline row.",
+      ],
+      acceptableAlternatives: [
+        "Use RangeInput when manual exact text entry matters more than dragging handles.",
+      ],
+      layoutConstraints: [
+        "RangeSlider is always full-width and stacked.",
+        "Default lower and upper values must be different.",
+      ],
+      requiredAcceptance: [
+        "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.",
+      ],
+    }),
+    aiUsageRules: [
+      "Range sliders are live canvas controls: dragging either thumb must update runtime state and product output in real time by default.",
+      "Do not implement range slider values as deferred local drafts, Apply-only updates, pointer-up-only commits, or renderer changes that appear only after the user asks again.",
+      "Range slider performance coverage must use a real control-drag scenario; control-change coverage is not enough to prove live canvas feedback or drag smoothness.",
+      "If a live range slider causes jank, optimize the renderer path first: update uniforms or stable buffers, cache expensive inputs, coalesce preview work to requestAnimationFrame, cancel stale async renders, move heavy work off React, or switch renderer strategy.",
+      "Only in an extreme documented performance ceiling may a range slider use a degraded live preview or delayed heavy refinement; the user must still see immediate canvas feedback while dragging and the worklog must record the measured reason.",
+      "Range slider step means numeric snapping only; it does not make the range slider visually discrete by itself.",
+      "Classify every stepped range slider as stepped continuous or visual discrete before writing the schema.",
+      'Small semantic integer domains such as rows, cols, gaps, jitter, counts, levels, bands, passes, points, tiles, and segments must use variant: "discrete".',
+      'Finite animation step domains such as flip depth, character count, glyph steps, and frame steps must use variant: "discrete" when the marker count stays within the Toolcraft visual budget.',
+      "Large or precision stepped ranges such as speed, FPS, rate, duration, density, size, and intensity stay visually continuous even when they declare step.",
+      "Use rangeSlider unit only for real measurement suffixes; do not use it for repeated entity nouns already named by the section or label, and do not use x as a unit.",
+      "When a range label needs an entity noun to make sense, improve the label or section title instead of appending that noun as the value unit.",
+      "Compact symbol/CSS units render tight, such as 20% – 80% or 12px – 48px; word units render with a space when truly needed.",
+      "RangeSlider is always a full-width two-thumb control; never place it in an inline two-column layout group with another slider or range slider.",
+      "RangeSlider defaultValue must start with different lower and upper values so the two-thumb control does not collapse into a single-value slider.",
+      "Manual range value editing accepts common separators such as slash, hyphen, spaces, and dashes, including when values include unit suffixes such as 30%-150% or 30% - 90%; do not create custom parsers for RangeSlider labels.",
+      'Specs, plans, and app-schema tests must assert explicit discrete range sliders render as variant: "discrete" with markers derived from min, max, and step.',
+      "Visual discrete sliders must still drag smoothly; browser performance tests should use expectToolcraftDiscreteSliderDragSmoothness for real pointer drag.",
+      "Use visibleWhen for range sliders that are meaningful only in some mode/type/source/include/count states; inactive branches should disappear so the panel shows only controls usable in the current state.",
+      "Do not use schema disabled: true or disabledWhen for product range sliders; product panels should show only controls usable in the current state. Use visibleWhen for unavailable product states instead of rendering disabled controls.",
+      "Do not leave an inactive conditional range slider visible while making the renderer ignore it; hide it with visibleWhen.",
+      "Acceptance must prove both rangeSlider.lower and rangeSlider.upper change the product output; testing one handle is not enough.",
+    ],
+  },
+  text: {
+    ...control("text", "TextInput", "grouped", "required"),
+    decisionCatalog: decisionCatalog({
+      strictness: "best-fit",
+      ownsValueModel: [
+        "short single-line text",
+        "single-line content",
+        "single-line setting value",
+      ],
+      useWhen: [
+        "Use TextInput for short names, button labels, titles, captions, tokens, compact prompts, and small setting strings.",
+        "Use commitMode content for real product content and commitMode setting for configuration-like values.",
+      ],
+      doNotReplaceWith: [
+        "Do not use TextInput for long multiline content; use CodeTextarea.",
+      ],
+      acceptableAlternatives: [
+        "Use CodeTextarea for multiline or long structured content.",
+        "Use Select for finite choices.",
+      ],
+      layoutConstraints: [
+        "Short numeric/text pairs can share inline rows when they tune one product meaning.",
+      ],
+      requiredAcceptance: [
+        "Prove text edits change product content or the intended setting at the correct commit timing.",
+      ],
+    }),
+    aiUsageRules: [
+      "TextInput owns short single-line product text: button labels, labels on the canvas, names, titles, captions, badges, short tokens, and compact prompts.",
+      'Every TextInput declares textValueKind: "single-line". Control selection must not be inferred from the label, description, or default string length.',
+      'TextInput commitMode defaults to "content": text content, prompts, names, tokens, titles, and instructions apply while typing.',
+      'Use commitMode: "setting" for text inputs that edit settings such as font size, numeric-like style values, dimensions, ids, or configuration fields; setting text commits on blur or Enter.',
+      "Canvas width and Canvas height are runtime editable-size fields and always commit on blur or Enter like editor size fields.",
+    ],
+  },
+  rangeInput: {
+    ...control("rangeInput", "RangeInput", "grouped", "required"),
+    decisionCatalog: decisionCatalog({
+      strictness: "exact-owner",
+      ownsValueModel: [
+        "manual lower and upper values",
+        "from/to text range",
+        "compact paired range input",
+      ],
+      useWhen: [
+        "Use RangeInput when users need to type or inspect a lower and upper bound more than drag them.",
+      ],
+      doNotReplaceWith: [
+        "Do not replace RangeInput with two unrelated TextInput controls for one range.",
+      ],
+      acceptableAlternatives: [
+        "Use RangeSlider when dragging the range relationship is the primary interaction.",
+      ],
+      layoutConstraints: [
+        "Keep the two range fields together as one compound control.",
+      ],
+      requiredAcceptance: [
+        "Prove rangeInput.start and rangeInput.end both affect product output.",
+      ],
+    }),
+    aiUsageRules: [
+      "RangeInput is a compound control; acceptance must prove rangeInput.start and rangeInput.end both affect the product output.",
+      "Do not accept a range input test that edits only the first field or only checks runtime state.",
+    ],
+  },
+  code: {
+    ...control("code", "CodeTextarea", "standalone", "required"),
+    decisionCatalog: decisionCatalog({
+      strictness: "best-fit",
+      ownsValueModel: [
+        "long text",
+        "multiline content",
+        "structured text",
+        "prompt",
+        "JSON",
+        "CSS",
+        "shader code",
+      ],
+      useWhen: [
+        "Use CodeTextarea for potentially long, multiline, or structured text values.",
+      ],
+      doNotReplaceWith: [
+        "Do not use repeated TextInput controls for one long content value.",
+      ],
+      acceptableAlternatives: [
+        "Use TextInput for short single-line values.",
+      ],
+      layoutConstraints: [
+        "CodeTextarea is capped at 12 visible lines and scrolls internally.",
+      ],
+      requiredAcceptance: [
+        "Prove long text edits affect product content while typing.",
+      ],
+    }),
+    aiUsageRules: [
+      "CodeTextarea is the multiline text input for any potentially long value, not only source code.",
+      'Every CodeTextarea declares textValueKind: "multiline" or "structured". Control selection must not be inferred from English labels or a short default value.',
+      "Do not use CodeTextarea for short single-line canvas text, button labels, names, titles, captions, badges, or short tokens; use TextInput.",
+      "Use text for short single-line strings such as names, button labels, small numeric values, compact prompts, titles, captions, and short tokens.",
+      "Use code only when the user may enter long prompts, multiline text, instructions, JSON, CSS, shader code, scripts, templates, or other long structured data.",
+      "If CodeTextarea has a short single-line default value, the schema description must make the long, multiline, or structured-content reason explicit.",
+      "CodeTextarea is a content editor and applies values while typing; do not wait for blur, Enter, or Cmd/Ctrl+Enter to update runtime state.",
+      "CodeTextarea height is capped at 12 visible text lines; long content scrolls inside the textarea instead of making the controls panel taller.",
+      "Do not name a section Code unless the product value is actually code; use the product role such as Prompt, Instructions, Template, JSON, Shader, or CSS.",
+    ],
+  },
+} as const satisfies Record<string, ToolcraftComponentContract>;

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

@@ -0,0 +1,116 @@
+import { describe, expect, it } from "vitest";
+
+import { getToolcraftComponentContract } from "./component-contracts";
+
+describe("Toolcraft template component contracts: media and custom controls", () => {
+  it("documents minimal UI rules for custom controls", () => {
+    const contract = getToolcraftComponentContract("customControl");
+
+    expect(contract.visualComponent).toBe("CustomControlRenderer");
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    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.",
+    );
+    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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Custom-control action buttons must be sized for the interaction. Do not shrink destructive, reorder, upload, or primary actions below comfortable kit button/icon-button sizes just to fit more text.",
+    );
+  });
+
+  it("documents image picker option acceptance as product behavior", () => {
+    const contract = getToolcraftComponentContract("imagePicker");
+
+    expect(contract.kind).toBe("control");
+    expect(contract.defaultSectionLayout).toBe("standalone");
+    expect(contract.aiUsageRules).toContain(
+      "Every visible ImagePicker item must be actionable in the current product context.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Do not show selectable image choices that the renderer later sanitizes to a fallback or no-op.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Tests must choose each visible ImagePicker item and assert the selected image, texture, gradient, or exported pixels change in the product output.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Do not accept renderer data attributes, runtime target changes, or option existence as final proof that an image choice works.",
+    );
+  });
+
+  it("documents file upload ownership across single-layer and multi-layer apps", () => {
+    const contract = getToolcraftComponentContract("fileDrop");
+
+    expect(contract.commands).toEqual([
+      "media.delete",
+      "media.import",
+      "media.reorder",
+      "media.transform",
+    ]);
+    expect(contract.aiUsageRules).toContain(
+      'Use fileDrop with assetKind: "image" for image-only source media and assetKind: "file" for arbitrary uploaded files.',
+    );
+    expect(contract.aiUsageRules).toContain(
+      "If an app ships with predefined source files or background images, declare them as schema media.defaultAssets with sourceTarget matching the fileDrop control. They must render as ordinary attached files in fileDrop, not as hidden renderer constants or canvas placeholder artwork.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Predefined media files are default runtime state: users can remove them to get an empty source/canvas state, persistence may keep that removal with include: [\"media\"], and global or section Reset restores the default attached files.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "When uploaded/imported content is part of the source-material flow, the canvas must not show agent-invented artwork, CTA text, fake sample output, decorative placeholders, or preset source designs before real content exists; keep the canvas neutral/runtime-backed and put upload affordance in fileDrop.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Do not add procedural Source Preset modes only to avoid an empty canvas. A default procedural or reference source is allowed only when the prompt/reference explicitly defines it and the worklog records that evidence.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "In single-layer apps, the runtime shows the uploaded image as the fileDrop preview and provides the clear action.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "In image mode, the runtime owns image transform actions: 90° Right, Flip horizontal, and Flip vertical. These actions render through the built-in actions-control in one three-column row with compact visible labels: 90°, Flip H, Flip V; keep a 6px vertical gap between the uploader and action row. Do not create a custom image action button grid. They update runtime mediaAssets transform metadata, and product preview/export must consume that metadata instead of keeping a separate transform state.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "When exactly one uploaded image is present, image transform actions are visible immediately. When multiple images are present, users select a thumbnail first; no transform actions render until a thumbnail is selected, and the action applies only to that selected image.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "In file mode, the runtime shows uploaded files as a sortable list with paperclip icons, file names, remove buttons, and --border/5 separators.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "In single-layer apps, global Reset controls and section reset must restore fileDrop source media to schema media.defaultAssets for that target; when no default asset exists, Reset removes uploaded media and returns the fileDrop target to defaultValue.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Use fileDrop with multiple: true when the app needs several uploaded images as one source set; do not build a custom thumbnail uploader for this.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Dragging thumbnails reorders runtime mediaAssets; preview, export, and renderer mapping must consume that media order instead of maintaining a separate product-only order.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "When uploaded images are used as canvas/background source material, draw them with cover/crop behavior: scale proportionally until the current canvas bounds are fully covered, keep the canvas size/settings unchanged, and crop overflow at the canvas bounds.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Do not create custom upload buttons, file lists, or file sorting for generic source uploads when fileDrop can represent the source set.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "In multi-layer apps, deletion and visibility belong to the Layers panel; fileDrop remains an upload target.",
+    );
+  });
+});