@pixel-point/toolcraft 0.0.17 → 0.0.18

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

@@ -0,0 +1,224 @@
+import {
+  defineToolcraft,
+  type ToolcraftControlSchema,
+} from "@repo/toolcraft-runtime";
+import { describe, expect, it } from "vitest";
+
+import { getToolcraftControlApplicabilityErrors } from "./acceptance/control-applicability";
+import type { ToolcraftProductReadiness } from "./acceptance/types";
+import { collectToolcraftVisibleAcceptanceControls } from "./acceptance/validate-coverage";
+
+const productReadiness: ToolcraftProductReadiness = {
+  exportIntent: {
+    image: { mode: "toolcraft-default" },
+    video: { mode: "not-requested" },
+  },
+  interactionOwnership: [],
+  mode: "product",
+  productName: "Shape fixture",
+  productSummary: "Neutral applicability contract fixture.",
+  requestedBehavior: "Show only controls that apply to the selected shape.",
+  viewInteraction: { mode: "non-spatial", reason: "Schema-only fixture." },
+};
+
+const shapeKind: ToolcraftControlSchema = {
+  applicability: { mode: "always" },
+  defaultValue: "circle",
+  options: [
+    { label: "Circle", value: "circle" },
+    { label: "Square", value: "square" },
+    { label: "Polygon", value: "polygon" },
+    { label: "Star", value: "star" },
+  ],
+  target: "shape.kind",
+  type: "segmented",
+};
+
+const alwaysControls: Record<string, ToolcraftControlSchema> = {
+  kind: shapeKind,
+  cornerRadius: {
+    applicability: {
+      all: [
+        {
+          oneOf: ["square", "polygon", "star"],
+          target: "shape.kind",
+        },
+      ],
+      mode: "conditional",
+    },
+    target: "shape.cornerRadius",
+    type: "slider",
+  },
+  depth: {
+    applicability: {
+      all: [{ equals: "star", target: "shape.kind" }],
+      mode: "conditional",
+    },
+    target: "shape.depth",
+    type: "slider",
+  },
+  sides: {
+    applicability: {
+      all: [
+        { oneOf: ["polygon", "star"], target: "shape.kind" },
+      ],
+      mode: "conditional",
+    },
+    target: "shape.sides",
+    type: "slider",
+  },
+};
+
+function validateProduct(
+  controls: Record<string, ToolcraftControlSchema>,
+): string[] {
+  const schema = defineToolcraft({
+    canvas: { enabled: true },
+    panels: {
+      controls: {
+        sections: [{ controls, id: "shape", title: "Shape" }],
+        title: "Controls",
+      },
+    },
+  });
+
+  return getToolcraftControlApplicabilityErrors({
+    controls: collectToolcraftVisibleAcceptanceControls(schema),
+    productReadiness,
+  });
+}
+
+describe("starter product control applicability", () => {
+  it("requires explicit product applicability and rejects legacy visibility", () => {
+    expect(
+      validateProduct({
+        kind: shapeKind,
+        sides: { target: "shape.sides", type: "slider" },
+      }),
+    ).toContainEqual(
+      expect.stringContaining("shape.sides must declare explicit applicability"),
+    );
+
+    expect(
+      validateProduct({
+        kind: shapeKind,
+        sides: {
+          target: "shape.sides",
+          type: "slider",
+          visibleWhen: { equals: "star", target: "shape.kind" },
+        },
+      }),
+    ).toContainEqual(
+      expect.stringContaining("shape.sides uses legacy visibleWhen"),
+    );
+  });
+
+  it("rejects missing, invalid, contradictory, and unsupported selectors", () => {
+    expect(
+      validateProduct({
+        kind: shapeKind,
+        sides: {
+          applicability: {
+            all: [{ equals: true, target: "shape.missing" }],
+            mode: "conditional",
+          },
+          target: "shape.sides",
+          type: "slider",
+        },
+      }),
+    ).toContainEqual(
+      expect.stringContaining('predicate target "shape.missing" does not exist'),
+    );
+
+    expect(
+      validateProduct({
+        kind: shapeKind,
+        sides: {
+          applicability: {
+            all: [{ equals: "triangle", target: "shape.kind" }],
+            mode: "conditional",
+          },
+          target: "shape.sides",
+          type: "slider",
+        },
+      }),
+    ).toContainEqual(
+      expect.stringContaining(
+        'value "triangle" is not an option of shape.kind',
+      ),
+    );
+
+    expect(
+      validateProduct({
+        kind: shapeKind,
+        sides: {
+          applicability: {
+            all: [
+              { equals: "polygon", target: "shape.kind" },
+              { equals: "star", target: "shape.kind" },
+            ],
+            mode: "conditional",
+          },
+          target: "shape.sides",
+          type: "slider",
+        },
+      }),
+    ).toContainEqual(
+      expect.stringContaining("shape.sides applicability is unsatisfiable"),
+    );
+
+    expect(
+      validateProduct({
+        kind: shapeKind,
+        name: {
+          applicability: { mode: "always" },
+          target: "shape.name",
+          type: "text",
+        },
+        sides: {
+          applicability: {
+            all: [{ equals: "named", target: "shape.name" }],
+            mode: "conditional",
+          },
+          target: "shape.sides",
+          type: "slider",
+        },
+      }),
+    ).toContainEqual(
+      expect.stringContaining(
+        "shape.name is not a supported applicability selector",
+      ),
+    );
+  });
+
+  it("rejects numeric gates with no satisfying selector value", () => {
+    expect(
+      validateProduct({
+        count: {
+          applicability: { mode: "always" },
+          defaultValue: 2,
+          max: 3,
+          min: 1,
+          step: 1,
+          target: "shape.count",
+          type: "slider",
+          variant: "discrete",
+        },
+        sides: {
+          applicability: {
+            all: [{ greaterThan: 10, target: "shape.count" }],
+            mode: "conditional",
+          },
+          target: "shape.sides",
+          type: "slider",
+        },
+      }),
+    ).toContainEqual(
+      expect.stringContaining("shape.sides has no satisfying value in shape.count"),
+    );
+  });
+
+  it("accepts a complete finite applicability declaration", () => {
+    expect(validateProduct(alwaysControls)).toEqual([]);
+  });
+});

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

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 import {
   getToolcraftSegmentedStaticFitError,
+  type ToolcraftCollectionItemControlType,
 } from "@repo/toolcraft-runtime";
 
 import {
@@ -18,7 +19,7 @@ const SCREENSHOT_LABELS = ["Default", "Ink Drops", "Solar", "Background"];
 const BOUNDARY_LABELS = ["Ink Drops", "Default", "Solar", "RGB"];
 
 function createRawCollectionModesSchema(
-  itemControlType: string,
+  itemControlType: ToolcraftCollectionItemControlType,
   labels: readonly string[],
 ) {
   return {
@@ -64,6 +65,11 @@ const collectionModesAcceptance = [
     browser: true,
     browserTestName: "browser: collection modes update rendered output",
     componentType: "collectionActions",
+    controlPartCoverage: [
+      "collectionActions.add",
+      "collectionActions.remove",
+      "collectionActions.items",
+    ] as const,
     evidence: "rendered-pixels" as const,
     expectedObservable: "Adding and editing modes changes rendered output.",
     fixture: "collection modes fixture",
@@ -339,7 +345,7 @@ describe("starter acceptance control order contract", () => {
   it("reports canonical fit guidance for an overwide collectionActions itemControl", () => {
     const itemControl = {
       options: SCREENSHOT_LABELS.map((label) => ({ label })),
-      type: "segmented",
+      type: "segmented" as const,
     };
     const fitGuidance = getToolcraftSegmentedStaticFitError(itemControl);
 
@@ -359,10 +365,59 @@ describe("starter acceptance control order contract", () => {
     );
   });
 
+  it("reports canonical fit guidance for every compound itemControls field", () => {
+    const schema = createRawCollectionModesSchema("segmented", SCREENSHOT_LABELS);
+    const modes = schema.panels.controls.sections[0]!.controls.modes;
+    const compoundSchema = {
+      ...schema,
+      panels: {
+        ...schema.panels,
+        controls: {
+          ...schema.panels.controls,
+          sections: [
+            {
+              ...schema.panels.controls.sections[0],
+              controls: {
+                modes: {
+                  ...modes,
+                  defaultValue: [{ enabled: true, mode: "default" }],
+                  itemControl: undefined,
+                  itemControls: {
+                    enabled: {
+                      defaultValue: true,
+                      label: "Enabled",
+                      type: "switch" as const,
+                    },
+                    mode: modes.itemControl,
+                  },
+                },
+              },
+            },
+          ],
+        },
+      },
+    };
+    const fitGuidance = getToolcraftSegmentedStaticFitError(
+      modes.itemControl,
+    );
+
+    expect(fitGuidance).not.toBeNull();
+    expect(
+      validateContractAcceptance({
+        schema: compoundSchema,
+        acceptance: collectionModesAcceptance,
+      }),
+    ).toEqual(
+      expect.arrayContaining([
+        `Style / modes (appearance.modes) itemControls.mode ${fitGuidance}`,
+      ]),
+    );
+  });
+
   it.each([
     { labels: BOUNDARY_LABELS, type: "segmented" },
     { labels: SCREENSHOT_LABELS, type: "select" },
-  ])(
+  ] as const)(
     "does not report itemControl fit guidance for nested $type",
     ({ labels, type }) => {
       const errors = validateContractAcceptance({

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

@@ -160,115 +160,4 @@ describe("starter acceptance control state contract", () => {
     );
   });
 
-  it("requires visibleWhen controls to reference a real target and prove hidden behavior", () => {
-    const schemaWithVisibleDependency = defineContractSchemaFixture({
-      canvas: { enabled: true },
-      panels: {
-        controls: {
-          sections: [
-            {
-              controls: {
-                shadeCount: {
-                  defaultValue: 2,
-                  label: "Shades",
-                  max: 5,
-                  min: 1,
-                  step: 1,
-                  target: "shapes.shadeCount",
-                  type: "slider",
-                  variant: "discrete",
-                },
-                shade3: {
-                  defaultValue: { hex: "#BBBBBB" },
-                  label: "Shade 3",
-                  target: "shapes.color3",
-                  type: "color",
-                  visibleWhen: {
-                    greaterThanOrEqual: 3,
-                    target: "shapes.count",
-                  },
-                },
-              },
-              title: "Shapes",
-            },
-          ],
-          title: "Controls",
-        },
-      },
-    });
-
-    expect(
-      validateContractAcceptance({
-        schema: schemaWithVisibleDependency,
-        acceptance: [
-          makeControlAcceptance("shapes.shadeCount", "slider"),
-          makeControlAcceptance("shapes.color3", "color"),
-        ],
-      }),
-    ).toEqual(
-      expect.arrayContaining([
-        expect.stringContaining(
-          "visibleWhen target shapes.count does not match another schema control target",
-        ),
-        expect.stringContaining(
-          "uses visibleWhen and must declare visibilityCoverage",
-        ),
-      ]),
-    );
-
-    const schemaWithValidVisibleDependency = defineContractSchemaFixture({
-      canvas: { enabled: true },
-      panels: {
-        controls: {
-          sections: [
-            {
-              controls: {
-                shadeCount: {
-                  defaultValue: 2,
-                  label: "Shades",
-                  max: 5,
-                  min: 1,
-                  step: 1,
-                  target: "shapes.shadeCount",
-                  type: "slider",
-                  variant: "discrete",
-                },
-                shade3: {
-                  defaultValue: { hex: "#BBBBBB" },
-                  label: "Shade 3",
-                  target: "shapes.color3",
-                  type: "color",
-                  visibleWhen: {
-                    greaterThanOrEqual: 3,
-                    target: "shapes.shadeCount",
-                  },
-                },
-              },
-              title: "Shapes",
-            },
-          ],
-          title: "Controls",
-        },
-      },
-    });
-    const errors = validateContractAcceptance({
-      schema: schemaWithValidVisibleDependency,
-      acceptance: [
-        makeControlAcceptance("shapes.shadeCount", "slider"),
-        {
-          ...makeControlAcceptance("shapes.color3", "color"),
-          expectedObservable: "Третий цвет доступен только для соответствующего состояния продукта.",
-          userAction: "Переключить количество оттенков и проверить оба состояния.",
-          visibilityCoverage: ["hidden", "visible"],
-        },
-      ],
-    });
-
-    expect(errors).not.toEqual(
-      expect.arrayContaining([
-        expect.stringContaining("visibleWhen target"),
-        expect.stringContaining("uses visibleWhen and must declare visibilityCoverage"),
-      ]),
-    );
-  });
 });

package/templates/starter/src/app/starter-acceptance.custom-control-collections.test.ts

@@ -6,7 +6,7 @@ import {
 } from "./starter-acceptance.contract-fixtures";
 
 describe("starter acceptance custom control collection contract", () => {
-  it("requires collection-like custom controls to compare actions and collectionActions", () => {
+  it("requires collection-like custom controls to compare both cardinality owners and actions", () => {
     const schema = defineContractSchemaFixture({
       canvas: { enabled: true },
       panels: {
@@ -71,6 +71,7 @@ describe("starter acceptance custom control collection contract", () => {
         ],
       }),
     ).toEqual([
+      "Masks / maskEditor (masks) builtInFitCheck.checkedBuiltIns must include sourceCollection when the custom control owns a repeated runtime item set whose cardinality could be source-owned.",
       "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.",
     ]);
@@ -135,6 +136,7 @@ describe("starter acceptance custom control collection contract", () => {
         ],
       }),
     ).toEqual([
+      "Pattern / patternSet (pattern.set) builtInFitCheck.checkedBuiltIns must include sourceCollection when the custom control owns a repeated runtime item set whose cardinality could be source-owned.",
       "Pattern / patternSet (pattern.set) builtInFitCheck.checkedBuiltIns must include collectionActions when the custom control owns a growable, removable, selectable, or reorderable runtime item set.",
     ]);
   });

package/templates/starter/src/app/starter-acceptance.custom-control-valid.test.ts

@@ -48,7 +48,7 @@ describe("starter acceptance valid custom control contract", () => {
                 "reorder",
                 "selection",
               ],
-              checkedBuiltIns: ["actions", "collectionActions", "fileDrop", "imagePicker", "select"],
+              checkedBuiltIns: ["actions", "collectionActions", "fileDrop", "imagePicker", "select", "sourceCollection"],
               closestBuiltIn: "fileDrop",
               productObservable: "Ordering uploaded glyphs changes the rendered glyph ramp output.",
               whyInsufficient: "FileDrop imports source files, but it does not provide density ordering, per-glyph preview, reorder, and remove behavior in one runtime value.",

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

@@ -1,3 +1,25 @@
+import type {
+  ToolcraftArtifactExportIntent,
+  ToolcraftProductReadiness,
+} from "./acceptance/types";
+
+export function makeExportSettingsProductReadiness(
+  exportIntent: ToolcraftArtifactExportIntent,
+): Extract<ToolcraftProductReadiness, { mode: "product" }> {
+  return {
+    exportIntent,
+    interactionOwnership: [],
+    mode: "product",
+    productName: "Export settings fixture",
+    productSummary: "A synthetic product for image and video export settings.",
+    requestedBehavior: "Export the explicitly requested artifact types.",
+    viewInteraction: {
+      mode: "non-spatial",
+      reason: "The synthetic output is two-dimensional.",
+    },
+  };
+}
+
 export function makeBackgroundSection() {
   return {
     controls: {

package/templates/starter/src/app/{starter-acceptance.image-video-export-settings.test.ts → starter-acceptance.image-export-settings.test.ts}

@@ -3,12 +3,26 @@ import { describe, expect, it } from "vitest";
 import { defineContractSchemaFixture, validateContractAcceptance } from "./starter-acceptance.contract-fixtures";
 import {
   makeBackgroundSection,
+  makeExportSettingsProductReadiness,
   makeImageExportSection,
   makeVideoExportSection,
 } from "./starter-acceptance.export-test-utils";
 import { makeControlAcceptance } from "./starter-acceptance.test-utils";
 
-describe("Toolcraft image and video export settings acceptance contract", () => {
+const imageOnlyProductReadiness = makeExportSettingsProductReadiness({
+  image: { mode: "toolcraft-default" },
+  video: { mode: "not-requested" },
+});
+
+const imageAndVideoProductReadiness = makeExportSettingsProductReadiness({
+  image: { mode: "toolcraft-default" },
+  video: {
+    evidence: "The user explicitly requested video delivery.",
+    mode: "user-requested",
+  },
+});
+
+describe("Toolcraft image export settings acceptance contract", () => {
   it("requires still-output apps to expose image export format and resolution settings", () => {
     const schemaWithoutImageExportSettings = defineContractSchemaFixture({
       canvas: {
@@ -58,13 +72,15 @@ describe("Toolcraft image and video export settings acceptance contract", () =>
             componentType: "panelActions",
             evidence: "exported-bytes",
             expectedObservable: "Export PNG creates output bytes and reads image format, image resolution, background color, and include-background state.",
+            exportArtifactCoverage: "all-required-image-export-behavior",
             fixture: "export fixture",
             id: "actions.output",
             kind: "control",
             target: "actions.output",
-            userAction: "Toggle Include off, verify preview has no product background, export PNG with alpha, and verify video export keeps the background.",
+            userAction: "Toggle Include off, verify preview has no product background, export PNG with alpha, and verify the image artifact preserves transparency.",
           },
         ],
+        productReadiness: imageOnlyProductReadiness,
       }),
     ).toEqual(
       expect.arrayContaining([
@@ -142,6 +158,7 @@ describe("Toolcraft image and video export settings acceptance contract", () =>
             componentType: "panelActions",
             evidence: "exported-bytes",
             expectedObservable: "Export PNG creates output bytes and reads image format, image resolution, background color, and include-background state. JPG changes file type; 8K changes exported pixel dimensions to an 8192px long edge.",
+            exportArtifactCoverage: "all-required-image-export-behavior",
             fixture: "export fixture",
             id: "actions.output",
             kind: "control",
@@ -149,6 +166,7 @@ describe("Toolcraft image and video export settings acceptance contract", () =>
             userAction: "Set format to JPG and resolution to 8K, then export and decode the output image to verify file type and long-edge dimensions.",
           },
         ],
+        productReadiness: imageOnlyProductReadiness,
       }),
     ).not.toEqual(
       expect.arrayContaining([
@@ -159,7 +177,7 @@ describe("Toolcraft image and video export settings acceptance contract", () =>
     );
   });
 
-  it("requires animated apps with PNG and video actions to expose Image Export before Video Export", () => {
+  it("requires explicit image-plus-video delivery to expose Image Export before Video Export", () => {
     const schemaWithoutImageSettings = defineContractSchemaFixture({
       canvas: {
         enabled: true,
@@ -211,19 +229,24 @@ describe("Toolcraft image and video export settings acceptance contract", () =>
           {
             actionCoverage: ["export.video", "export.png"],
             automated: true,
-            automatedTestName: "exports animated and still output",
+            automatedTestName: "exports image and explicitly requested video output",
             browser: true,
             browserTestName: "browser: exports video and image output",
             componentType: "panelActions",
             evidence: "exported-bytes",
             expectedObservable: "Export Video and Export PNG both create output bytes and read their runtime export settings.",
-            fixture: "animated export fixture",
+            exportArtifactCoverage: [
+              "all-required-image-export-behavior",
+              "all-required-video-export-behavior",
+            ],
+            fixture: "explicit image-plus-video export fixture",
             id: "actions.output",
             kind: "control",
             target: "actions.output",
-            userAction: "Export video and PNG from the same timeline state, then verify both files exist.",
+            userAction: "Export video and PNG with their configured settings, then verify both files exist.",
           },
         ],
+        productReadiness: imageAndVideoProductReadiness,
       }),
     ).toEqual(
       expect.arrayContaining([
@@ -234,7 +257,7 @@ describe("Toolcraft image and video export settings acceptance contract", () =>
     );
   });
 
-  it("accepts animated apps with Image Export immediately before Video Export", () => {
+  it("accepts explicit image-plus-video delivery with Image Export immediately before Video Export", () => {
     const schemaWithDualExportSettings = defineContractSchemaFixture({
       canvas: {
         enabled: true,
@@ -303,19 +326,24 @@ describe("Toolcraft image and video export settings acceptance contract", () =>
           {
             actionCoverage: ["export.video", "export.png"],
             automated: true,
-            automatedTestName: "exports animated and still output",
+            automatedTestName: "exports image and explicitly requested video output",
             browser: true,
             browserTestName: "browser: exports video and image output",
             componentType: "panelActions",
             evidence: "exported-bytes",
             expectedObservable: "Export Video and Export PNG both create output bytes and read their runtime export settings.",
-            fixture: "animated export fixture",
+            exportArtifactCoverage: [
+              "all-required-image-export-behavior",
+              "all-required-video-export-behavior",
+            ],
+            fixture: "explicit image-plus-video export fixture",
             id: "actions.output",
             kind: "control",
             target: "actions.output",
             userAction: "Choose JPG and 8K, choose MP4 and Current, then export PNG and video and verify both outputs use their selected settings.",
           },
         ],
+        productReadiness: imageAndVideoProductReadiness,
       }),
     ).not.toEqual(
       expect.arrayContaining([

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

@@ -100,6 +100,10 @@ function readiness(
   interactionOwnership: readonly ToolcraftInteractionOwnershipEntry[],
 ): ToolcraftProductReadiness {
   return {
+    exportIntent: {
+      image: { mode: "toolcraft-default" },
+      video: { mode: "not-requested" },
+    },
     interactionOwnership,
     mode: "product",
     productName: "Interaction fixture",
@@ -151,6 +155,10 @@ function acceptance({
 describe("Toolcraft interaction surface ownership", () => {
   it("runs ownership validation through the protected acceptance pipeline", () => {
     const productReadiness = {
+      exportIntent: {
+        image: { mode: "toolcraft-default" },
+        video: { mode: "not-requested" },
+      },
       mode: "product",
       productName: "Legacy fixture",
       productSummary: "A product declaration created before interaction ownership.",
@@ -172,6 +180,10 @@ describe("Toolcraft interaction surface ownership", () => {
 
   it("rejects product readiness that omits the ownership inventory", () => {
     const productReadiness = {
+      exportIntent: {
+        image: { mode: "toolcraft-default" },
+        video: { mode: "not-requested" },
+      },
       mode: "product",
       productName: "Legacy fixture",
       productSummary: "A product declaration created before interaction ownership.",