@pixel-point/toolcraft 0.0.6 → 0.0.8

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

@@ -538,7 +538,7 @@ function makeBackgroundSection() {
       includeBackground: {
         defaultValue: true,
         description:
-          "Controls PNG background transparency while preview and video keep the background.",
+          "Controls preview and PNG background visibility while video keeps the background.",
         label: "Include",
         target: "export.includeBackground",
         type: "switch",
@@ -734,13 +734,6 @@ function getProductRuntimeImplementationSource(): string {
   )}`;
 }
 
-function removePngExportCanvasHelperCalls(source: string): string {
-  return source.replace(
-    /\bcreateToolcraftPngExportCanvas\s*\(\s*\{[\s\S]*?\}\s*\)/g,
-    "createToolcraftPngExportCanvas({})",
-  );
-}
-
 function getSchemaBackgroundControlTargets(
   controlTypes: ReadonlySet<string>,
 ): string[] {
@@ -813,6 +806,101 @@ describe("Toolcraft template app acceptance coverage", () => {
     expect(validateToolcraftAcceptanceCoverage(starterSchema, starterAcceptance)).toEqual([]);
   });
 
+  it("requires fileDrop acceptance to prove upload, clear, and reset lifecycle", () => {
+    const fileDropSchema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                source: {
+                  defaultValue: null,
+                  label: "Source image",
+                  target: "media.source",
+                  type: "fileDrop",
+                },
+              },
+              title: "Source",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateToolcraftAcceptanceCoverage(fileDropSchema, [
+        {
+          automated: true,
+          automatedTestName: "source image upload and clear update media",
+          browser: true,
+          browserTestName: "browser: source image upload and clear update media",
+          componentType: "fileDrop",
+          evidence: "media-lifecycle",
+          expectedObservable:
+            "Uploading a source image changes the media preview and Clear removes it.",
+          fixture: "source image fixture",
+          id: "media.source",
+          kind: "control",
+          target: "media.source",
+          userAction: "Upload a source image, then clear the preview.",
+        },
+      ]),
+    ).toEqual(
+      expect.arrayContaining([
+        "Source / source (media.source) fileDrop acceptance must prove upload/import, clear/remove, and section or global reset remove source media.",
+      ]),
+    );
+  });
+
+  it("accepts fileDrop lifecycle coverage that includes reset", () => {
+    const fileDropSchema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                source: {
+                  defaultValue: null,
+                  label: "Source image",
+                  target: "media.source",
+                  type: "fileDrop",
+                },
+              },
+              title: "Source",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    const errors = validateToolcraftAcceptanceCoverage(fileDropSchema, [
+      {
+        automated: true,
+        automatedTestName: "source image upload clear and reset update media",
+        browser: true,
+        browserTestName: "browser: source image upload clear and reset update media",
+        componentType: "fileDrop",
+        evidence: "media-lifecycle",
+        expectedObservable:
+          "Uploading a source image changes the media preview; Clear, section reset, and global Reset controls remove the source media and restore the empty upload state.",
+        fixture: "source image fixture",
+        id: "media.source",
+        kind: "control",
+        target: "media.source",
+        userAction:
+          "Upload a source image, clear it, upload again, then use section reset and Reset controls.",
+      },
+    ]);
+
+    expect(
+      errors.filter((error) => error.includes("fileDrop acceptance")),
+    ).toEqual([]);
+  });
+
   it("rejects fake video duration browser coverage that falls back to expected duration", () => {
     const fakeCoverage = `
       async function getVideoDuration(page, buffer, mimeType) {
@@ -1629,9 +1717,259 @@ describe("Toolcraft template app acceptance coverage", () => {
     ).toEqual([
       "Glyphs / glyphRamp (glyph.ramp) builtInFitCheck.checkedBuiltIns contains unknown built-in controls: imaginaryPicker.",
       'Glyphs / glyphRamp (glyph.ramp) builtInFitCheck.closestBuiltIn must be one of the checked built-ins or "none".',
+      "Glyphs / glyphRamp (glyph.ramp) builtInFitCheck.checkedBuiltIns must include collectionActions when the custom control owns a growable, removable, selectable, or reorderable runtime item set.",
+      "Glyphs / glyphRamp (glyph.ramp) builtInFitCheck.checkedBuiltIns must include actions when the custom control exposes local command buttons such as add, remove, delete, duplicate, sort, normalize, or clear.",
     ]);
   });
 
+  it("requires collection-like custom controls to compare actions and collectionActions", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                maskEditor: {
+                  defaultValue: { items: [], selectedId: null },
+                  label: "Mask shapes",
+                  orderRole: "spatial",
+                  target: "masks",
+                  type: "maskEditor",
+                } as never,
+              },
+              title: "Masks",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateToolcraftAcceptanceCoverage(schema, [
+        {
+          automated: true,
+          automatedTestName: "mask editor changes output",
+          browser: true,
+          browserTestName: "browser: mask editor changes output",
+          builtInFitCheck: {
+            checkedBuiltIns: ["select", "vector"],
+            closestBuiltIn: "vector",
+            productObservable:
+              "Adding, selecting, deleting, dragging, and resizing masks changes the composited output.",
+            whyInsufficient:
+              "Vector can edit one point, but this product needs multiple shape commands, selected item state, deletion, drag, and resize handles.",
+          },
+          componentType: "maskEditor",
+          customControlCoverage: [
+            "built-in-gap",
+            "kit-primitives",
+            "minimal-ui",
+            "product-output",
+            "runtime-state",
+          ],
+          evidence: "product-output",
+          expectedObservable:
+            "Adding rectangle, circle, and triangle masks creates selected editable shapes.",
+          fixture: "uploaded image with masks",
+          id: "masks",
+          kind: "control",
+          target: "masks",
+          userAction:
+            "Add each mask shape, select a mask in the list, delete one mask, drag a canvas mask handle, and resize a selected mask.",
+        },
+      ]),
+    ).toEqual([
+      "Masks / maskEditor (masks) builtInFitCheck.checkedBuiltIns must include collectionActions when the custom control owns a growable, removable, selectable, or reorderable runtime item set.",
+      "Masks / maskEditor (masks) builtInFitCheck.checkedBuiltIns must include actions when the custom control exposes local command buttons such as add, remove, delete, duplicate, sort, normalize, or clear.",
+    ]);
+  });
+
+  it("detects collection-like custom controls from the value model instead of entity names", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                patternSet: {
+                  defaultValue: { entries: [], selectedId: null },
+                  label: "Pattern set",
+                  orderRole: "style",
+                  target: "pattern.set",
+                  type: "patternSetEditor",
+                } as never,
+              },
+              title: "Pattern",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateToolcraftAcceptanceCoverage(schema, [
+        {
+          automated: true,
+          automatedTestName: "pattern set changes output",
+          browser: true,
+          browserTestName: "browser: pattern set changes output",
+          builtInFitCheck: {
+            checkedBuiltIns: ["select", "vector"],
+            closestBuiltIn: "select",
+            productObservable:
+              "Editing the chosen pattern entry changes the rendered pattern output.",
+            whyInsufficient:
+              "Select can choose one preset, but this product needs runtime entry state with selected item editing.",
+          },
+          componentType: "patternSetEditor",
+          customControlCoverage: [
+            "built-in-gap",
+            "kit-primitives",
+            "minimal-ui",
+            "product-output",
+            "runtime-state",
+          ],
+          evidence: "product-output",
+          expectedObservable:
+            "Editing the pattern set changes the rendered product output.",
+          fixture: "pattern set fixture",
+          id: "pattern.set",
+          kind: "control",
+          target: "pattern.set",
+          userAction: "Edit the selected entry.",
+        },
+      ]),
+    ).toEqual([
+      "Pattern / patternSet (pattern.set) builtInFitCheck.checkedBuiltIns must include collectionActions when the custom control owns a growable, removable, selectable, or reorderable runtime item set.",
+    ]);
+  });
+
+  it("rejects custom controls justified only by visual chrome", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                shapeButtons: {
+                  defaultValue: "rect",
+                  label: "Shape",
+                  orderRole: "style",
+                  target: "shape.kind",
+                  type: "shapeButtons",
+                } as never,
+              },
+              title: "Shape",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateToolcraftAcceptanceCoverage(schema, [
+        {
+          automated: true,
+          automatedTestName: "shape buttons change output",
+          browser: true,
+          browserTestName: "browser: shape buttons change output",
+          builtInFitCheck: {
+            checkedBuiltIns: ["actions", "segmented", "select"],
+            closestBuiltIn: "segmented",
+            productObservable:
+              "Choosing a shape changes the rendered product geometry.",
+            whyInsufficient:
+              "The custom control uses icon buttons and a compact visual layout.",
+          },
+          componentType: "shapeButtons",
+          customControlCoverage: [
+            "built-in-gap",
+            "kit-primitives",
+            "minimal-ui",
+            "product-output",
+            "runtime-state",
+          ],
+          evidence: "product-output",
+          expectedObservable:
+            "Choosing rectangle, circle, or triangle changes the rendered output.",
+          fixture: "shape fixture",
+          id: "shape.kind",
+          kind: "control",
+          target: "shape.kind",
+          userAction: "Choose each shape icon button.",
+        },
+      ]),
+    ).toEqual([
+      "Shape / shapeButtons (shape.kind) builtInFitCheck.whyInsufficient cannot justify a custom control only with icons, layout, styling, or custom buttons; name the product interaction or value model that built-ins cannot express.",
+    ]);
+  });
+
+  it("does not treat numeric tuple custom values as collection owners", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                focalPoint: {
+                  defaultValue: [0.5, 0.5],
+                  label: "Focal point",
+                  orderRole: "spatial",
+                  target: "focal.point",
+                  type: "focalPointPad",
+                } as never,
+              },
+              title: "Focus",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateToolcraftAcceptanceCoverage(schema, [
+        {
+          automated: true,
+          automatedTestName: "focal point changes output",
+          browser: true,
+          browserTestName: "browser: focal point changes output",
+          builtInFitCheck: {
+            checkedBuiltIns: ["vector"],
+            closestBuiltIn: "vector",
+            productObservable:
+              "Dragging the focal point changes the rendered focus position.",
+            whyInsufficient:
+              "Vector edits x/y, but this product needs a canvas hit target with validation tied to the rendered focal point.",
+          },
+          componentType: "focalPointPad",
+          customControlCoverage: [
+            "built-in-gap",
+            "kit-primitives",
+            "minimal-ui",
+            "product-output",
+            "runtime-state",
+          ],
+          evidence: "product-output",
+          expectedObservable:
+            "Dragging the focal point changes the rendered product output.",
+          fixture: "focus fixture",
+          id: "focal.point",
+          kind: "control",
+          target: "focal.point",
+          userAction: "Drag the focal point.",
+        },
+      ]),
+    ).toEqual([]);
+  });
+
   it("accepts custom controls with explicit custom control coverage", () => {
     const schema = defineToolcraft({
       canvas: { enabled: true },
@@ -1664,7 +2002,7 @@ describe("Toolcraft template app acceptance coverage", () => {
           browser: true,
           browserTestName: "browser: glyph ramp changes output",
           builtInFitCheck: {
-            checkedBuiltIns: ["fileDrop", "imagePicker", "select"],
+            checkedBuiltIns: ["actions", "collectionActions", "fileDrop", "imagePicker", "select"],
             closestBuiltIn: "fileDrop",
             productObservable:
               "Ordering uploaded glyphs changes the rendered glyph ramp output.",
@@ -2334,9 +2672,9 @@ describe("Toolcraft template app acceptance coverage", () => {
       "PNG export must pass includeBackground from runtime state to createToolcraftPngExportCanvas; do not hardcode PNG transparency or background inclusion in schema only.",
     ).toMatch(/\bcreateToolcraftPngExportCanvas\s*\(\s*\{[\s\S]*\bincludeBackground\s*:/);
     expect(
-      removePngExportCanvasHelperCalls(productRuntimeImplementationSource),
-      "export.includeBackground may only be read by the PNG export helper. Live preview, workspace canvas backing, and video renderers must not become transparent when Include background is off.",
-    ).not.toMatch(/\bexport\.includeBackground\b/);
+      productRuntimeImplementationSource,
+      "Live preview must read include-background state through shouldIncludeToolcraftPreviewBackground(state) so turning Include off hides the product preview background without affecting video export.",
+    ).toMatch(/\bshouldIncludeToolcraftPreviewBackground\b/);
     expect(
       backgroundColorTargets.length,
       "Every product app with Export PNG must expose a user-facing background color control.",
@@ -2346,13 +2684,18 @@ describe("Toolcraft template app acceptance coverage", () => {
       'Every product app with Export PNG must expose export.includeBackground in the required "Background" section as a Switch labeled "Include".',
     ).toBeGreaterThan(0);
 
-    for (const target of [...backgroundColorTargets, ...backgroundToggleTargets]) {
+    for (const target of backgroundColorTargets) {
       expect(
         productRuntimeImplementationSource,
         `Runtime renderer/export code must read ${target}; declaring the control in schema is not enough.`,
       ).toContain(target);
     }
 
+    expect(
+      productRuntimeImplementationSource,
+      `Runtime renderer/export code must read ${backgroundToggleTargets.join(", ")} through shouldIncludeToolcraftPreviewBackground(state); declaring the control in schema is not enough.`,
+    ).toMatch(/\bshouldIncludeToolcraftPreviewBackground\b|\bexport\.includeBackground\b/);
+
     const imageExportSection = getSchemaImageExportSection();
     const imageFormatControl = getSectionControlByTarget(
       imageExportSection,
@@ -2788,9 +3131,9 @@ describe("Toolcraft template app acceptance coverage", () => {
       {
         ...makeControlAcceptance("export.includeBackground", "switch"),
         expectedObservable:
-          "Turning Include background off makes PNG output transparent while live preview, workspace canvas backing, and video output keep the product background.",
+          "Turning Include off makes PNG output transparent, hides the live preview product background, and video output keeps the product background.",
         userAction:
-          "Toggle Include background off, export PNG, then verify the PNG has alpha while the live preview canvas still preserves the background.",
+          "Toggle Include off, verify preview has no product background, export PNG with alpha, and verify video export keeps the background.",
       },
       {
         actionCoverage: ["export.png"],
@@ -2818,7 +3161,7 @@ describe("Toolcraft template app acceptance coverage", () => {
     );
   });
 
-  it("requires include-background acceptance to keep live preview and canvas backing visible", () => {
+  it("requires include-background acceptance to hide preview background and keep video background", () => {
     const schemaWithBackgroundControls = defineToolcraft({
       canvas: {
         enabled: true,
@@ -2875,7 +3218,7 @@ describe("Toolcraft template app acceptance coverage", () => {
     ).toEqual(
       expect.arrayContaining([
         expect.stringContaining(
-          "controls PNG background inclusion and acceptance must prove disabling it makes PNG output transparent while live preview, workspace canvas backing, and video output keep the product background.",
+          "controls background inclusion and acceptance must prove disabling it makes PNG output transparent, hides the live preview product background, and keeps video output with the product background.",
         ),
       ]),
     );
@@ -2933,7 +3276,7 @@ describe("Toolcraft template app acceptance coverage", () => {
           kind: "control",
           target: "actions.output",
           userAction:
-            "Toggle Include background off, export PNG, then verify the PNG has alpha while the live preview canvas still preserves the background.",
+            "Toggle Include off, verify preview has no product background, export PNG with alpha, and verify video export keeps the background.",
         },
       ]),
     ).toEqual(
@@ -3540,7 +3883,7 @@ describe("Toolcraft template app acceptance coverage", () => {
                 includeBackground: {
                   defaultValue: true,
                   description:
-                    "Controls PNG background transparency while preview and video keep the background.",
+                    "Controls preview and PNG background visibility while video keeps the background.",
                   label: "Include",
                   target: "export.includeBackground",
                   type: "switch",
@@ -6052,6 +6395,173 @@ describe("Toolcraft template app acceptance coverage", () => {
     );
   });
 
+  it("rejects visible labels for palette variation color banks", () => {
+    const schemaWithLabeledPaletteBank = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                accent1: {
+                  defaultValue: { hex: "#9CE6FF" },
+                  label: "Color 1",
+                  target: "palette.accent1",
+                  type: "color",
+                },
+                accent2: {
+                  defaultValue: { hex: "#FF7A90" },
+                  label: "Color 2",
+                  target: "palette.accent2",
+                  type: "color",
+                },
+                spread: {
+                  defaultValue: 34,
+                  label: "Spread",
+                  max: 100,
+                  min: 0,
+                  target: "palette.spread",
+                  type: "slider",
+                  unit: "%",
+                },
+              },
+              title: "Accent Shades",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateToolcraftAcceptanceCoverage(schemaWithLabeledPaletteBank, [
+        makeControlAcceptance("palette.accent1", "color"),
+        makeControlAcceptance("palette.accent2", "color"),
+        makeControlAcceptance("palette.spread", "slider"),
+      ]),
+    ).toEqual(
+      expect.arrayContaining([
+        'Accent Shades / accent1 uses visible label "Color 1" for a palette variation color. When colors only add variety to one shared palette, set label: false or use collectionActions with unlabeled items. Keep visible labels only when each color edits a distinct user-facing entity such as Fill, Stroke, Background, Connector, or Object color.',
+        'Accent Shades / accent2 uses visible label "Color 2" for a palette variation color. When colors only add variety to one shared palette, set label: false or use collectionActions with unlabeled items. Keep visible labels only when each color edits a distinct user-facing entity such as Fill, Stroke, Background, Connector, or Object color.',
+      ]),
+    );
+  });
+
+  it("rejects mixed label visibility inside one palette variation color group", () => {
+    const schemaWithMixedPaletteBankLabels = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                accent1: {
+                  defaultValue: { hex: "#9CE6FF" },
+                  label: false,
+                  target: "palette.accent1",
+                  type: "color",
+                },
+                accent2: {
+                  defaultValue: { hex: "#FF7A90" },
+                  label: "Color 2",
+                  target: "palette.accent2",
+                  type: "color",
+                },
+                accent3: {
+                  defaultValue: { hex: "#FFD166" },
+                  label: false,
+                  target: "palette.accent3",
+                  type: "color",
+                },
+              },
+              title: "Accent Shades",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateToolcraftAcceptanceCoverage(schemaWithMixedPaletteBankLabels, [
+        makeControlAcceptance("palette.accent1", "color"),
+        makeControlAcceptance("palette.accent2", "color"),
+        makeControlAcceptance("palette.accent3", "color"),
+      ]),
+    ).toEqual(
+      expect.arrayContaining([
+        "Accent Shades mixes labeled and unlabeled color items in one palette variation group. Decide label visibility for the whole group: omit all per-item labels when colors only add variety, or label every item only when each color has a distinct user-facing role.",
+        'Accent Shades / accent2 uses visible label "Color 2" for a palette variation color. When colors only add variety to one shared palette, set label: false or use collectionActions with unlabeled items. Keep visible labels only when each color edits a distinct user-facing entity such as Fill, Stroke, Background, Connector, or Object color.',
+      ]),
+    );
+  });
+
+  it("allows unlabeled palette variation colors and labeled distinct color roles", () => {
+    const schemaWithUsefulColorLabels = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                accent1: {
+                  defaultValue: { hex: "#9CE6FF" },
+                  label: false,
+                  target: "palette.accent1",
+                  type: "color",
+                },
+                accent2: {
+                  defaultValue: { hex: "#FF7A90" },
+                  label: false,
+                  target: "palette.accent2",
+                  type: "color",
+                },
+                spread: {
+                  defaultValue: 34,
+                  label: "Spread",
+                  max: 100,
+                  min: 0,
+                  target: "palette.spread",
+                  type: "slider",
+                  unit: "%",
+                },
+              },
+              title: "Accent Shades",
+            },
+            {
+              controls: {
+                fill: {
+                  defaultValue: { hex: "#FFFFFF" },
+                  label: "Fill",
+                  target: "object.fill",
+                  type: "color",
+                },
+                stroke: {
+                  defaultValue: { hex: "#111111" },
+                  label: "Stroke",
+                  target: "object.stroke",
+                  type: "color",
+                },
+              },
+              title: "Object Colors",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateToolcraftAcceptanceCoverage(schemaWithUsefulColorLabels, [
+        makeControlAcceptance("palette.accent1", "color"),
+        makeControlAcceptance("palette.accent2", "color"),
+        makeControlAcceptance("palette.spread", "slider"),
+        makeControlAcceptance("object.fill", "color"),
+        makeControlAcceptance("object.stroke", "color"),
+      ]),
+    ).toEqual([]);
+  });
+
   it("requires mode selectors to appear before dependent controls", () => {
     const schemaWithLateModeSelector = {
       ...starterSchema,