@pixel-point/toolcraft 0.0.8 → 0.0.9

package/templates/starter/src/app/starter-acceptance.test.ts

@@ -13,6 +13,7 @@ import {
   getToolcraftControlOrderTargets,
   type ToolcraftComponentAcceptance,
   starterAcceptance,
+  starterControlSectionInventory,
   starterProductReadiness,
   starterTransferMode,
   validateToolcraftAcceptanceCoverage,
@@ -806,6 +807,26 @@ describe("Toolcraft template app acceptance coverage", () => {
     expect(validateToolcraftAcceptanceCoverage(starterSchema, starterAcceptance)).toEqual([]);
   });
 
+  it("requires generated product apps to publish a control section inventory", () => {
+    if (!schemaHasProductSurface()) {
+      expect(starterControlSectionInventory).toEqual([]);
+      return;
+    }
+
+    expect(
+      starterControlSectionInventory.length,
+      "Product apps must export starterControlSectionInventory so section grouping decisions are machine-checkable.",
+    ).toBeGreaterThan(0);
+    expect(
+      validateToolcraftAcceptanceCoverage(
+        starterSchema,
+        starterAcceptance,
+        starterTransferMode,
+        starterControlSectionInventory,
+      ),
+    ).toEqual([]);
+  });
+
   it("requires fileDrop acceptance to prove upload, clear, and reset lifecycle", () => {
     const fileDropSchema = defineToolcraft({
       canvas: { enabled: true },
@@ -994,7 +1015,7 @@ describe("Toolcraft template app acceptance coverage", () => {
 
     expect(validateToolcraftAcceptanceCoverage(fixedOutputSchema, starterAcceptance)).toEqual(
       expect.arrayContaining([
-        'canvas.sizing mode "fixed-output" requires a runtime acceptance entry with canvasSizingCoverage "fixed-output-size" explaining why width and height are intentionally non-editable. A user-provided base/default size should normally use "editable-output".',
+        'canvas.sizing mode "fixed-output" requires a runtime acceptance entry with canvasSizingCoverage "fixed-output-size" explaining why width and height are intentionally non-editable. Product/output apps must use "editable-output"; user-provided, reference, fixed-format, or base/default sizes belong in canvas.size as editable initial values.',
       ]),
     );
   });
@@ -1047,7 +1068,118 @@ describe("Toolcraft template app acceptance coverage", () => {
       ]),
     ).toEqual(
       expect.arrayContaining([
-        'canvas.sizing canvasSizingCoverage "fixed-output-size" must explain why the product output dimensions are intentionally fixed, not merely initialized from a default size.',
+        'canvas.sizing canvasSizingCoverage "fixed-output-size" must explain why the output dimensions are intentionally fixed for a non-product/internal fixture, not merely initialized from a default size.',
+      ]),
+    );
+  });
+
+  it("rejects fixed canvas sizing justified only by a missing reference size editor", () => {
+    const fixedOutputSchema = defineToolcraft({
+      canvas: {
+        enabled: true,
+        size: { height: 1080, unit: "px", width: 1920 },
+        sizing: { mode: "fixed-output" },
+      },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                prompt: {
+                  defaultValue: "Describe the effect",
+                  label: "Prompt",
+                  orderRole: "input",
+                  target: "generation.prompt",
+                  type: "text",
+                },
+              },
+              title: "Generation",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateToolcraftAcceptanceCoverage(fixedOutputSchema, [
+        ...starterAcceptance,
+        {
+          automated: true,
+          automatedTestName: "canvas output remains fixed",
+          browser: true,
+          browserTestName: "browser: canvas output remains fixed",
+          canvasSizingCoverage: "fixed-output-size",
+          componentType: "fixed-output canvas",
+          evidence: "product-output",
+          expectedObservable:
+            "The WebGL output remains fixed at 1920x1080 because the reference app has no user-facing output size editor.",
+          fixture: "default canvas fixture",
+          id: "canvas.sizing",
+          kind: "runtime",
+          userAction: "Open the app.",
+        },
+      ]),
+    ).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining("cannot be justified by the reference or previous app lacking a size editor"),
+      ]),
+    );
+  });
+
+  it("rejects fixed canvas sizing for exportable product apps even when reference dimensions are fixed", () => {
+    const fixedExportSchema = defineToolcraft({
+      canvas: {
+        enabled: true,
+        size: { height: 900, unit: "px", width: 1440 },
+        sizing: { mode: "fixed-output" },
+      },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                outputActions: {
+                  actions: [
+                    {
+                      icon: "export",
+                      label: "Export PNG",
+                      value: "export.png",
+                    },
+                  ],
+                  target: "actions.output",
+                  type: "panelActions",
+                },
+              },
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateToolcraftAcceptanceCoverage(fixedExportSchema, [
+        ...starterAcceptance,
+        {
+          automated: true,
+          automatedTestName: "fixed reference size is preserved",
+          browser: true,
+          browserTestName: "browser: fixed reference size is preserved",
+          canvasSizingCoverage: "fixed-output-size",
+          componentType: "fixed-output canvas",
+          evidence: "product-output",
+          expectedObservable:
+            "The exported shader canvas remains reference-defined and fixed at 1440x900.",
+          fixture: "shader reference fixture",
+          id: "canvas.sizing",
+          kind: "runtime",
+          userAction: "Open the app.",
+        },
+      ]),
+    ).toEqual(
+      expect.arrayContaining([
+        'Product/output apps with export actions must use canvas.sizing mode "editable-output" so Aspect ratio, Canvas width, and Canvas height are always available. Put reference, fixed-format, or user-requested dimensions in canvas.size as the initial value instead of hiding size controls with "fixed-output".',
       ]),
     );
   });
@@ -2109,7 +2241,6 @@ describe("Toolcraft template app acceptance coverage", () => {
                   step: 0.1,
                   target: "field.speed",
                   type: "slider",
-                  unit: "x",
                 },
               },
               layoutGroups: [
@@ -2167,6 +2298,57 @@ describe("Toolcraft template app acceptance coverage", () => {
     );
   });
 
+  it("rejects x units on slider value labels", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                strength: {
+                  defaultValue: 0.4,
+                  label: "Strength",
+                  max: 1,
+                  min: 0,
+                  step: 0.01,
+                  target: "glass.strength",
+                  type: "slider",
+                  unit: "x",
+                },
+              },
+              title: "Glass",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateToolcraftAcceptanceCoverage(schema, [
+        {
+          automated: true,
+          automatedTestName: "strength changes glass output",
+          browser: true,
+          browserTestName: "browser: strength slider changes glass output",
+          componentType: "slider",
+          evidence: "rendered-pixels",
+          expectedObservable: "Changing Strength changes the rendered glass strength.",
+          fixture: "glass strength fixture",
+          id: "glass.strength",
+          kind: "control",
+          target: "glass.strength",
+          userAction: "Drag the Strength slider.",
+        },
+      ]),
+    ).toEqual(
+      expect.arrayContaining([
+        'Glass / strength (glass.strength) uses unit "x", but Toolcraft slider values do not use x suffixes. Omit unit for scale, multiplier, intensity, opacity, strength, depth, and shader amount values unless a real measurement unit applies.',
+      ]),
+    );
+  });
+
   it("accepts compound controls only when every semantic value part is declared", () => {
     const gradientSchema = defineToolcraft({
       canvas: { enabled: true },
@@ -3872,6 +4054,78 @@ describe("Toolcraft template app acceptance coverage", () => {
     );
   });
 
+  it("rejects single Actions controls that duplicate their only button label", () => {
+    const schemaWithDuplicateActionLabel = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                wash: {
+                  actions: [{ label: "Wash", value: "wash" }],
+                  defaultValue: null,
+                  label: "Wash",
+                  target: "flow.washSignal",
+                  type: "actions",
+                },
+              },
+              title: "Flow",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateToolcraftAcceptanceCoverage(schemaWithDuplicateActionLabel, [
+        makeControlAcceptance("flow.washSignal", "actions"),
+      ]),
+    ).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining(
+          'flow.washSignal) single Actions control label "Wash" duplicates its only button label "Wash". Keep the button as the command and use a short context label such as "Ink wash", "Palette action", or "Current layer".',
+        ),
+      ]),
+    );
+  });
+
+  it("allows single Actions controls with a concise context label", () => {
+    const schemaWithContextActionLabel = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                wash: {
+                  actions: [{ label: "Wash", value: "wash" }],
+                  defaultValue: null,
+                  label: "Ink wash",
+                  target: "flow.washSignal",
+                  type: "actions",
+                },
+              },
+              title: "Flow",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    const errors = validateToolcraftAcceptanceCoverage(schemaWithContextActionLabel, [
+      makeControlAcceptance("flow.washSignal", "actions"),
+    ]);
+
+    expect(errors).not.toEqual(
+      expect.arrayContaining([
+        expect.stringContaining("single Actions control label"),
+      ]),
+    );
+  });
+
   it("allows short Include toggle plus an unlabeled background color in the required row", () => {
     const schema = defineToolcraft({
       canvas: { enabled: true },
@@ -3941,7 +4195,7 @@ describe("Toolcraft template app acceptance coverage", () => {
                 },
                 duration: {
                   defaultValue: "8",
-                  label: "Duration",
+                  label: false,
                   target: "animation.duration",
                   type: "text",
                 },
@@ -3971,7 +4225,7 @@ describe("Toolcraft template app acceptance coverage", () => {
     );
   });
 
-  it("rejects long visible toggle labels beside one related parameter", () => {
+  it("rejects CodeTextarea for short single-line text content", () => {
     const schema = defineToolcraft({
       canvas: { enabled: true },
       panels: {
@@ -3979,27 +4233,14 @@ describe("Toolcraft template app acceptance coverage", () => {
           sections: [
             {
               controls: {
-                transparentBackground: {
-                  defaultValue: true,
-                  label: "Transparent background",
-                  target: "export.transparentBackground",
-                  type: "switch",
-                },
-                background: {
-                  defaultValue: "#0F0F0F",
-                  label: "Background",
-                  target: "appearance.background",
-                  type: "color",
+                buttonText: {
+                  defaultValue: "Glass",
+                  label: "Text",
+                  target: "button.text",
+                  type: "code",
                 },
               },
-              layoutGroups: [
-                {
-                  columns: 2,
-                  controls: ["transparentBackground", "background"],
-                  layout: "inline",
-                },
-              ],
-              title: "Background",
+              title: "Button",
             },
           ],
           title: "Controls",
@@ -4009,19 +4250,16 @@ describe("Toolcraft template app acceptance coverage", () => {
 
     expect(
       validateToolcraftAcceptanceCoverage(schema, [
-        makeControlAcceptance("export.transparentBackground", "switch"),
-        makeControlAcceptance("appearance.background", "color"),
+        makeControlAcceptance("button.text", "code"),
       ]),
     ).toEqual(
       expect.arrayContaining([
-        expect.stringContaining(
-          'Background layoutGroups inline row "transparentBackground, background" includes toggle label transparentBackground "Transparent background" that is too long for a compact toggle-plus-parameter row.',
-        ),
+        expect.stringContaining("uses CodeTextarea for short single-line text"),
       ]),
     );
   });
 
-  it("allows inline switch pairs when both labels are compact", () => {
+  it("allows CodeTextarea when a short default documents long multiline intent", () => {
     const schema = defineToolcraft({
       canvas: { enabled: true },
       panels: {
@@ -4029,27 +4267,16 @@ describe("Toolcraft template app acceptance coverage", () => {
           sections: [
             {
               controls: {
-                glow: {
-                  defaultValue: true,
-                  label: "Glow",
-                  target: "style.glow",
-                  type: "switch",
-                },
-                loop: {
-                  defaultValue: false,
-                  label: "Loop",
-                  target: "animation.loop",
-                  type: "switch",
+                prompt: {
+                  defaultValue: "Describe the scene",
+                  description:
+                    "Long multiline prompt content for generated output.",
+                  label: "Prompt",
+                  target: "generation.prompt",
+                  type: "code",
                 },
               },
-              layoutGroups: [
-                {
-                  columns: 2,
-                  controls: ["glow", "loop"],
-                  layout: "inline",
-                },
-              ],
-              title: "Style",
+              title: "Generation",
             },
           ],
           title: "Controls",
@@ -4057,10 +4284,211 @@ describe("Toolcraft template app acceptance coverage", () => {
       },
     });
 
-    const errors = validateToolcraftAcceptanceCoverage(schema, [
-      makeControlAcceptance("style.glow", "switch"),
-      makeControlAcceptance("animation.loop", "switch"),
-    ]);
+    expect(
+      validateToolcraftAcceptanceCoverage(schema, [
+        makeControlAcceptance("generation.prompt", "code"),
+      ]),
+    ).not.toEqual(
+      expect.arrayContaining([
+        expect.stringContaining("uses CodeTextarea for short single-line text"),
+      ]),
+    );
+  });
+
+  it("rejects visible parameter labels beside one related toggle", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                loop: {
+                  defaultValue: true,
+                  label: "Loop",
+                  target: "animation.loop",
+                  type: "switch",
+                },
+                duration: {
+                  defaultValue: "8",
+                  label: "Duration",
+                  target: "animation.duration",
+                  type: "text",
+                },
+              },
+              layoutGroups: [
+                {
+                  columns: 2,
+                  controls: ["loop", "duration"],
+                  layout: "inline",
+                },
+              ],
+              title: "Playback",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateToolcraftAcceptanceCoverage(schema, [
+        makeControlAcceptance("animation.loop", "switch"),
+        makeControlAcceptance("animation.duration", "text"),
+      ]),
+    ).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining(
+          'Playback layoutGroups inline row "loop, duration" pairs a toggle with parameter labels duration "Duration". In toggle-plus-parameter rows, the non-toggle parameter must use label false; if that label is needed, stack the controls instead.',
+        ),
+      ]),
+    );
+  });
+
+  it("rejects segmented controls in inline half-width layout rows", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                includeText: {
+                  defaultValue: true,
+                  label: "Include",
+                  target: "text.enabled",
+                  type: "switch",
+                },
+                dragTarget: {
+                  defaultValue: "glass",
+                  label: "Drag",
+                  options: [
+                    { label: "Glass", value: "glass" },
+                    { label: "Text", value: "text" },
+                  ],
+                  target: "text.dragTarget",
+                  type: "segmented",
+                },
+              },
+              layoutGroups: [
+                {
+                  columns: 2,
+                  controls: ["includeText", "dragTarget"],
+                  layout: "inline",
+                },
+              ],
+              title: "Glass Text",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateToolcraftAcceptanceCoverage(schema, [
+        makeControlAcceptance("text.enabled", "switch"),
+        makeControlAcceptance("text.dragTarget", "segmented"),
+      ]),
+    ).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining(
+          'Glass Text layoutGroups inline row "includeText, dragTarget" includes segmented control dragTarget. Segmented is full-width and must not share a two-column or half-width row; use Select when a finite choice must fit beside another control.',
+        ),
+      ]),
+    );
+  });
+
+  it("rejects long visible toggle labels beside one related parameter", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                transparentBackground: {
+                  defaultValue: true,
+                  label: "Transparent background",
+                  target: "export.transparentBackground",
+                  type: "switch",
+                },
+                background: {
+                  defaultValue: "#0F0F0F",
+                  label: "Background",
+                  target: "appearance.background",
+                  type: "color",
+                },
+              },
+              layoutGroups: [
+                {
+                  columns: 2,
+                  controls: ["transparentBackground", "background"],
+                  layout: "inline",
+                },
+              ],
+              title: "Background",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateToolcraftAcceptanceCoverage(schema, [
+        makeControlAcceptance("export.transparentBackground", "switch"),
+        makeControlAcceptance("appearance.background", "color"),
+      ]),
+    ).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining(
+          'Background layoutGroups inline row "transparentBackground, background" includes toggle label transparentBackground "Transparent background" that is too long for a compact toggle-plus-parameter row.',
+        ),
+      ]),
+    );
+  });
+
+  it("allows inline switch pairs when both labels are compact", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                glow: {
+                  defaultValue: true,
+                  label: "Glow",
+                  target: "style.glow",
+                  type: "switch",
+                },
+                loop: {
+                  defaultValue: false,
+                  label: "Loop",
+                  target: "animation.loop",
+                  type: "switch",
+                },
+              },
+              layoutGroups: [
+                {
+                  columns: 2,
+                  controls: ["glow", "loop"],
+                  layout: "inline",
+                },
+              ],
+              title: "Style",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    const errors = validateToolcraftAcceptanceCoverage(schema, [
+      makeControlAcceptance("style.glow", "switch"),
+      makeControlAcceptance("animation.loop", "switch"),
+    ]);
 
     expect(errors).not.toEqual(
       expect.arrayContaining([expect.stringContaining("two-column toggle row")]),
@@ -5252,7 +5680,6 @@ describe("Toolcraft template app acceptance coverage", () => {
                   step: 0.1,
                   target: "animation.speed",
                   type: "slider",
-                  unit: "x",
                   variant: "continuous",
                 },
                 depth: {
@@ -6145,7 +6572,7 @@ describe("Toolcraft template app acceptance coverage", () => {
       ]),
     ).toEqual(
       expect.arrayContaining([
-        'Controls for product entity "squares.right" are split across sections: Square 1 (Right), Appearance. Keep controls for the same product entity in one semantic section unless the spec names a real workflow split.',
+        'Controls for product entity "squares.right" are split across sections: Square 1 (Right), Appearance. Keep controls for the same product entity in one semantic section unless the Control Section Inventory declares workflowStage and splitReason for every split section.',
       ]),
     );
   });
@@ -6201,6 +6628,252 @@ describe("Toolcraft template app acceptance coverage", () => {
     ).toEqual([]);
   });
 
+  it("rejects stale control section inventory entries", () => {
+    const schemaWithInventoryMismatch = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                kind: {
+                  defaultValue: "soft",
+                  label: "Kind",
+                  options: [
+                    { label: "Soft", value: "soft" },
+                    { label: "Sharp", value: "sharp" },
+                  ],
+                  orderRole: "mode",
+                  target: "shape.kind",
+                  type: "select",
+                },
+                count: {
+                  defaultValue: 12,
+                  label: "Count",
+                  max: 40,
+                  min: 1,
+                  orderRole: "detail",
+                  target: "shape.count",
+                  type: "slider",
+                  variant: "continuous",
+                },
+              },
+              title: "Shape",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateToolcraftAcceptanceCoverage(
+        schemaWithInventoryMismatch,
+        [
+          makeControlAcceptance("shape.kind", "select"),
+          makeControlAcceptance("shape.count", "slider"),
+        ],
+        starterTransferMode,
+        [
+          {
+            entity: "Shape",
+            groupingReason: "Shape setup",
+            targets: ["shape.kind"],
+            title: "Shape",
+          },
+        ],
+      ),
+    ).toEqual(
+      expect.arrayContaining([
+        'Control Section Inventory entry "Shape" must include a concrete groupingReason explaining why these controls belong together.',
+        'Control Section Inventory entry "Shape" is missing rendered target "shape.count". The inventory must cover every product control in the section.',
+      ]),
+    );
+  });
+
+  it("allows explicit workflow split evidence for one target entity", () => {
+    const schemaWithWorkflowSplit = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                size: {
+                  defaultValue: 64,
+                  label: "Size",
+                  max: 128,
+                  min: 16,
+                  orderRole: "primary",
+                  target: "object.shape.size",
+                  type: "slider",
+                  unit: "px",
+                  variant: "continuous",
+                },
+              },
+              title: "Shape Structure",
+            },
+            {
+              controls: {
+                count: {
+                  defaultValue: 12,
+                  label: "Count",
+                  max: 40,
+                  min: 1,
+                  orderRole: "detail",
+                  target: "object.shape.count",
+                  type: "slider",
+                  variant: "continuous",
+                },
+              },
+              title: "Shape Density",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateToolcraftAcceptanceCoverage(
+        schemaWithWorkflowSplit,
+        [
+          makeControlAcceptance("object.shape.size", "slider"),
+          makeControlAcceptance("object.shape.count", "slider"),
+        ],
+        starterTransferMode,
+        [
+          {
+            entity: "Object shape",
+            groupingReason: "Structure controls tune the physical footprint of the object.",
+            splitReason:
+              "Structure and density are separate workflow stages in this editor.",
+            targets: ["object.shape.size"],
+            title: "Shape Structure",
+            workflowStage: "structure",
+          },
+          {
+            entity: "Object shape",
+            groupingReason: "Density controls tune how many objects appear after structure is set.",
+            splitReason:
+              "Density is separated from structure because users set count after the shape footprint.",
+            targets: ["object.shape.count"],
+            title: "Shape Density",
+            workflowStage: "density",
+          },
+        ],
+      ),
+    ).toEqual([]);
+  });
+
+  it("rejects mode-gated controls split away from their selector section", () => {
+    const schemaWithSplitModeBranch = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                sourceMode: {
+                  defaultValue: "preset",
+                  label: "Source",
+                  options: [
+                    { label: "Preset", value: "preset" },
+                    { label: "Image", value: "image" },
+                  ],
+                  orderRole: "mode",
+                  target: "source.mode",
+                  type: "segmented",
+                },
+              },
+              title: "Source",
+            },
+            {
+              controls: {
+                sourceUpload: {
+                  accept: "image/*",
+                  assetKind: "image",
+                  defaultValue: null,
+                  label: "Image",
+                  orderRole: "input",
+                  target: "source.upload",
+                  type: "fileDrop",
+                  visibleWhen: { equals: "image", target: "source.mode" },
+                },
+              },
+              title: "Image",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateToolcraftAcceptanceCoverage(schemaWithSplitModeBranch, [
+        makeControlAcceptance("source.mode", "segmented"),
+        makeControlAcceptance("source.upload", "fileDrop"),
+      ]),
+    ).toEqual(
+      expect.arrayContaining([
+        'Image / sourceUpload is gated by visibleWhen target "source.mode" in Source, but it belongs to the same dependency group. Keep selectors and their dependent controls in one semantic section when they describe one product entity or branch; use visibleWhen/disabledWhen inside that section instead of splitting branch controls into their own section.',
+      ]),
+    );
+  });
+
+  it("rejects selector branch sections even when targets do not share a prefix", () => {
+    const schemaWithSplitOptionBranch = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                shapeKind: {
+                  defaultValue: "generated",
+                  label: "Shape",
+                  options: [
+                    { label: "Generated", value: "generated" },
+                    { label: "Library", value: "library" },
+                  ],
+                  orderRole: "mode",
+                  target: "shape.kind",
+                  type: "segmented",
+                },
+              },
+              title: "Shape",
+            },
+            {
+              controls: {
+                libraryAsset: {
+                  defaultValue: null,
+                  label: "Library",
+                  orderRole: "input",
+                  target: "asset.upload",
+                  type: "fileDrop",
+                  visibleWhen: { equals: "library", target: "shape.kind" },
+                },
+              },
+              title: "Library",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateToolcraftAcceptanceCoverage(schemaWithSplitOptionBranch, [
+        makeControlAcceptance("shape.kind", "segmented"),
+        makeControlAcceptance("asset.upload", "fileDrop"),
+      ]),
+    ).toEqual(
+      expect.arrayContaining([
+        'Library / libraryAsset is gated by visibleWhen target "shape.kind" in Shape, but it belongs to the same dependency group. Keep selectors and their dependent controls in one semantic section when they describe one product entity or branch; use visibleWhen/disabledWhen inside that section instead of splitting branch controls into their own section.',
+      ]),
+    );
+  });
+
   it("rejects splitting FontPicker-owned typography into sibling controls", () => {
     const schemaWithSplitTypographyBlock = defineToolcraft({
       canvas: { enabled: true },
@@ -6580,15 +7253,15 @@ describe("Toolcraft template app acceptance coverage", () => {
                   type: "slider",
                   variant: "continuous",
                 },
-                blend: {
+                mode: {
                   defaultValue: "liquid",
-                  label: "Blend",
+                  label: "Mode",
                   options: [
                     { label: "Silk", value: "silk" },
                     { label: "Liquid", value: "liquid" },
                     { label: "Crystal", value: "crystal" },
                   ],
-                  target: "shader.blend",
+                  target: "shader.mode",
                   type: "segmented",
                 },
               },
@@ -6618,23 +7291,23 @@ describe("Toolcraft template app acceptance coverage", () => {
         },
         {
           automated: true,
-          automatedTestName: "blend changes rendered output",
+          automatedTestName: "mode changes rendered output",
           browser: true,
-          browserTestName: "browser: blend selector changes rendered output",
+          browserTestName: "browser: mode selector changes rendered output",
           componentType: "segmented",
           evidence: "rendered-pixels",
-          expectedObservable: "Changing Blend switches shader pattern.",
-          fixture: "blend fixture",
-          id: "shader.blend",
+          expectedObservable: "Changing Mode switches shader pattern.",
+          fixture: "mode fixture",
+          id: "shader.mode",
           kind: "control",
           optionCoverage: "each-visible-item",
-          target: "shader.blend",
-          userAction: "Select each Blend option.",
+          target: "shader.mode",
+          userAction: "Select each Mode option.",
         },
       ]),
     ).toEqual(
       expect.arrayContaining([
-        'Volume / blend (shader.blend) has orderRole "mode" after depth (shader.depth) with orderRole "strength". Move mode/input/primary controls before dependent strength/detail/advanced controls or split them into an earlier section.',
+        'Volume / mode (shader.mode) has orderRole "mode" after depth (shader.depth) with orderRole "strength". Move mode/input/primary controls before dependent strength/detail/advanced controls or split them into an earlier section.',
       ]),
     );
   });