@pixel-point/toolcraft 0.0.17 → 0.0.19

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

@@ -0,0 +1,312 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  getToolcraftArtifactExportIntentEvidenceErrors,
+  resolveToolcraftArtifactExportIntent,
+  validateToolcraftArtifactExportIntentCorrespondence,
+} from "./acceptance/artifact-export-intent";
+import type { ToolcraftArtifactExportIntent } from "./acceptance/types";
+
+const deliveryCases: readonly Readonly<{
+  expected: Readonly<{
+    imageEnabled: boolean;
+    svgEnabled: boolean;
+    videoEnabled: boolean;
+  }>;
+  intent: ToolcraftArtifactExportIntent;
+  name: string;
+}>[] = [
+  {
+    expected: { imageEnabled: true, svgEnabled: false, videoEnabled: false },
+    intent: {
+      image: { mode: "toolcraft-default" },
+      svg: { mode: "not-requested" },
+      video: { mode: "not-requested" },
+    },
+    name: "enables default image export without unrequested video export",
+  },
+  {
+    expected: { imageEnabled: true, svgEnabled: false, videoEnabled: false },
+    intent: {
+      image: {
+        evidence: "The user explicitly requested PNG delivery.",
+        mode: "user-requested",
+      },
+      svg: { mode: "not-requested" },
+      video: { mode: "not-requested" },
+    },
+    name: "enables explicitly requested image export",
+  },
+  {
+    expected: { imageEnabled: false, svgEnabled: false, videoEnabled: false },
+    intent: {
+      image: {
+        evidence: "The user explicitly requested no image export.",
+        mode: "user-removed",
+      },
+      svg: { mode: "not-requested" },
+      video: { mode: "not-requested" },
+    },
+    name: "disables explicitly removed image export",
+  },
+  {
+    expected: { imageEnabled: true, svgEnabled: false, videoEnabled: true },
+    intent: {
+      image: { mode: "toolcraft-default" },
+      svg: { mode: "not-requested" },
+      video: {
+        evidence: "The user explicitly requested MP4 delivery.",
+        mode: "user-requested",
+      },
+    },
+    name: "enables explicitly requested video export",
+  },
+  {
+    expected: { imageEnabled: true, svgEnabled: false, videoEnabled: true },
+    intent: {
+      image: {
+        evidence: "The user explicitly requested PNG delivery.",
+        mode: "user-requested",
+      },
+      svg: { mode: "not-requested" },
+      video: {
+        evidence: "The user explicitly requested MP4 delivery.",
+        mode: "user-requested",
+      },
+    },
+    name: "enables explicitly requested image and video export",
+  },
+  {
+    expected: { imageEnabled: false, svgEnabled: false, videoEnabled: true },
+    intent: {
+      image: {
+        evidence: "The user explicitly requested no image export.",
+        mode: "user-removed",
+      },
+      svg: { mode: "not-requested" },
+      video: {
+        evidence: "The user explicitly requested MP4 delivery.",
+        mode: "user-requested",
+      },
+    },
+    name: "keeps requested video export when image export is removed",
+  },
+  {
+    expected: { imageEnabled: false, svgEnabled: true, videoEnabled: false },
+    intent: {
+      image: {
+        evidence: "The user explicitly requested SVG instead of image export.",
+        mode: "user-removed",
+      },
+      svg: {
+        evidence: "The user explicitly requested editable SVG delivery.",
+        mode: "user-requested",
+      },
+      video: { mode: "not-requested" },
+    },
+    name: "enables requested SVG without retaining default image export",
+  },
+];
+
+const evidenceCases: readonly Readonly<{
+  expected: readonly string[];
+  intent: ToolcraftArtifactExportIntent;
+  name: string;
+}>[] = [
+  {
+    expected: [],
+    intent: {
+      image: { mode: "toolcraft-default" },
+      svg: { mode: "not-requested" },
+      video: { mode: "not-requested" },
+    },
+    name: "accepts default image and not-requested video modes",
+  },
+  {
+    expected: [],
+    intent: {
+      image: {
+        evidence: "The user explicitly requested PNG delivery.",
+        mode: "user-requested",
+      },
+      svg: { mode: "not-requested" },
+      video: { mode: "not-requested" },
+    },
+    name: "accepts nonblank requested image evidence",
+  },
+  {
+    expected: [],
+    intent: {
+      image: {
+        evidence: "The user explicitly requested no image export.",
+        mode: "user-removed",
+      },
+      svg: { mode: "not-requested" },
+      video: { mode: "not-requested" },
+    },
+    name: "accepts nonblank image removal evidence",
+  },
+  {
+    expected: [],
+    intent: {
+      image: { mode: "toolcraft-default" },
+      svg: { mode: "not-requested" },
+      video: {
+        evidence: "The user explicitly requested MP4 delivery.",
+        mode: "user-requested",
+      },
+    },
+    name: "accepts nonblank requested video evidence",
+  },
+  {
+    expected: [
+      "Image export user-removed intent requires non-empty evidence.",
+    ],
+    intent: {
+      image: { evidence: " \n\t ", mode: "user-removed" },
+      svg: { mode: "not-requested" },
+      video: { mode: "not-requested" },
+    },
+    name: "rejects blank image removal evidence",
+  },
+  {
+    expected: [
+      "Image export user-requested intent requires non-empty evidence.",
+    ],
+    intent: {
+      image: { evidence: "   ", mode: "user-requested" },
+      svg: { mode: "not-requested" },
+      video: { mode: "not-requested" },
+    },
+    name: "rejects blank requested image evidence",
+  },
+  {
+    expected: [
+      "Video export user-requested intent requires non-empty evidence.",
+    ],
+    intent: {
+      image: { mode: "toolcraft-default" },
+      svg: { mode: "not-requested" },
+      video: { evidence: "\t", mode: "user-requested" },
+    },
+    name: "rejects blank requested video evidence",
+  },
+  {
+    expected: [
+      "SVG export user-requested intent requires non-empty evidence.",
+    ],
+    intent: {
+      image: { mode: "toolcraft-default" },
+      svg: { evidence: "\t", mode: "user-requested" },
+      video: { mode: "not-requested" },
+    },
+    name: "rejects blank requested SVG evidence",
+  },
+  {
+    expected: [
+      "Image export user-removed intent requires non-empty evidence.",
+      "Video export user-requested intent requires non-empty evidence.",
+    ],
+    intent: {
+      image: { evidence: " ", mode: "user-removed" },
+      svg: { mode: "not-requested" },
+      video: { evidence: "\n", mode: "user-requested" },
+    },
+    name: "aggregates blank image and video evidence errors",
+  },
+];
+
+describe("Toolcraft artifact export intent", () => {
+  it.each(deliveryCases)("$name", ({ expected, intent }) => {
+    const delivery = resolveToolcraftArtifactExportIntent(intent);
+
+    expect(delivery).toEqual(expected);
+    expect(Object.isFrozen(delivery)).toBe(true);
+  });
+
+  it.each(evidenceCases)("$name", ({ expected, intent }) => {
+    expect(getToolcraftArtifactExportIntentEvidenceErrors(intent)).toEqual(
+      expected,
+    );
+  });
+
+  it("validates enabled and disabled delivery against typed schema facts", () => {
+    expect(
+      validateToolcraftArtifactExportIntentCorrespondence({
+        hasImageExportAction: false,
+        hasImageExportSection: false,
+        hasSvgExportAction: false,
+        hasVideoExportAction: true,
+        hasVideoExportSection: true,
+        intent: {
+          image: { mode: "toolcraft-default" },
+          svg: { mode: "not-requested" },
+          video: { mode: "not-requested" },
+        },
+      }),
+    ).toEqual({
+      delivery: { imageEnabled: true, svgEnabled: false, videoEnabled: false },
+      errors: [
+        'Image export intent "toolcraft-default" requires an export-image panel action.',
+        'Image export intent "toolcraft-default" requires an "Image Export" section.',
+        'Video export intent "not-requested" must not have an export-video panel action.',
+        'Video export intent "not-requested" must not have a "Video Export" section.',
+      ],
+    });
+  });
+
+  it("aggregates evidence and correspondence errors without prose inference", () => {
+    expect(
+      validateToolcraftArtifactExportIntentCorrespondence({
+        hasImageExportAction: true,
+        hasImageExportSection: true,
+        hasSvgExportAction: false,
+        hasVideoExportAction: false,
+        hasVideoExportSection: false,
+        intent: {
+          image: { evidence: "  ", mode: "user-removed" },
+          svg: { mode: "not-requested" },
+          video: { evidence: "\t", mode: "user-requested" },
+        },
+      }),
+    ).toEqual({
+      delivery: { imageEnabled: false, svgEnabled: false, videoEnabled: true },
+      errors: [
+        "Image export user-removed intent requires non-empty evidence.",
+        "Video export user-requested intent requires non-empty evidence.",
+        'Image export intent "user-removed" must not have an export-image panel action.',
+        'Image export intent "user-removed" must not have an "Image Export" section.',
+        'Video export intent "user-requested" requires an export-video panel action.',
+        'Video export intent "user-requested" requires a "Video Export" section.',
+      ],
+    });
+  });
+
+  it("requires requested SVG to correspond to one typed action without a settings section", () => {
+    expect(
+      validateToolcraftArtifactExportIntentCorrespondence({
+        hasImageExportAction: false,
+        hasImageExportSection: false,
+        hasSvgExportAction: false,
+        hasVideoExportAction: false,
+        hasVideoExportSection: false,
+        intent: {
+          image: {
+            evidence: "The user requested SVG only.",
+            mode: "user-removed",
+          },
+          svg: {
+            evidence: "The user requested editable SVG.",
+            mode: "user-requested",
+          },
+          video: { mode: "not-requested" },
+        },
+      }),
+    ).toEqual({
+      delivery: { imageEnabled: false, svgEnabled: true, videoEnabled: false },
+      errors: [
+        'SVG export intent "user-requested" requires an export-svg panel action.',
+      ],
+    });
+  });
+});

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

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 
+import type { ToolcraftProductReadiness } from "./acceptance/types";
 import { defineContractSchemaFixture, validateContractAcceptance } from "./starter-acceptance.contract-fixtures";
 import {
   makeBackgroundSection,
@@ -7,6 +8,35 @@ import {
 } from "./starter-acceptance.export-test-utils";
 import { makeControlAcceptance } from "./starter-acceptance.test-utils";
 
+const imageExportProductReadiness: ToolcraftProductReadiness = {
+  exportIntent: {
+    image: { mode: "toolcraft-default" },
+    svg: { mode: "not-requested" },
+    video: { mode: "not-requested" },
+  },
+  interactionOwnership: [],
+  mode: "product",
+  productName: "Background image export fixture",
+  productSummary: "A static image fixture for background export validation.",
+  requestedBehavior: "Export the image with configurable background output.",
+  viewInteraction: {
+    mode: "non-spatial",
+    reason: "The fixture renders a static two-dimensional image.",
+  },
+};
+
+const videoExportProductReadiness: ToolcraftProductReadiness = {
+  ...imageExportProductReadiness,
+  exportIntent: {
+    image: { mode: "toolcraft-default" },
+    svg: { mode: "not-requested" },
+    video: {
+      evidence: "The background fixture explicitly exercises video background export.",
+      mode: "user-requested",
+    },
+  },
+};
+
 describe("Toolcraft background export acceptance contract", () => {
   it("requires png export apps to expose background color and png background toggle controls", () => {
     const schemaWithoutBackgroundControls = defineContractSchemaFixture({
@@ -43,6 +73,7 @@ describe("Toolcraft background export acceptance contract", () => {
     expect(
       validateContractAcceptance({
         schema: schemaWithoutBackgroundControls,
+        productReadiness: imageExportProductReadiness,
         acceptance: [
           {
             actionCoverage: ["export.png"],
@@ -118,6 +149,7 @@ describe("Toolcraft background export acceptance contract", () => {
     expect(
       validateContractAcceptance({
         schema: schemaWithLegacyBackgroundControls,
+        productReadiness: imageExportProductReadiness,
         acceptance: [
           makeControlAcceptance("appearance.background", "color"),
           makeControlAcceptance("export.includeBackground", "switch"),
@@ -185,6 +217,7 @@ describe("Toolcraft background export acceptance contract", () => {
     });
     const errors = validateContractAcceptance({
       schema: schemaWithBackgroundControls,
+      productReadiness: imageExportProductReadiness,
       acceptance: [
         makeControlAcceptance("appearance.background", "color"),
         {
@@ -262,6 +295,7 @@ describe("Toolcraft background export acceptance contract", () => {
     expect(
       validateContractAcceptance({
         schema: schemaWithBackgroundControls,
+        productReadiness: imageExportProductReadiness,
         acceptance: [
           makeControlAcceptance("appearance.background", "color"),
           makeControlAcceptance("export.includeBackground", "switch"),
@@ -332,6 +366,7 @@ describe("Toolcraft background export acceptance contract", () => {
     expect(
       validateContractAcceptance({
         schema: schemaWithVideoExport,
+        productReadiness: videoExportProductReadiness,
         acceptance: [
           makeControlAcceptance("appearance.background", "color"),
           {

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

@@ -9,6 +9,11 @@ import { makeControlAcceptance } from "./starter-acceptance.test-utils";
 import type { ToolcraftProductReadiness } from "./acceptance/types";
 
 const infinityProductReadiness: ToolcraftProductReadiness = {
+  exportIntent: {
+    image: { mode: "toolcraft-default" },
+    svg: { mode: "not-requested" },
+    video: { mode: "not-requested" },
+  },
   interactionOwnership: [],
   mode: "product",
   productName: "Infinity contract fixture",
@@ -20,6 +25,18 @@ const infinityProductReadiness: ToolcraftProductReadiness = {
   },
 };
 
+const infinityVideoProductReadiness: ToolcraftProductReadiness = {
+  ...infinityProductReadiness,
+  exportIntent: {
+    image: { mode: "toolcraft-default" },
+    svg: { mode: "not-requested" },
+    video: {
+      evidence: "The Infinity canvas fixture explicitly exercises video export bounds.",
+      mode: "user-requested",
+    },
+  },
+};
+
 function createFixedOutputSchema({
   height = 1080,
   width = 1920,
@@ -167,7 +184,7 @@ describe("Toolcraft canvas sizing acceptance coverage", () => {
       validateContractAcceptance({
         schema: createEditableOutputSchema("export-video"),
         acceptance: [makeInfinityCanvasAcceptance("mode-and-restoration")],
-        productReadiness: infinityProductReadiness,
+        productReadiness: infinityVideoProductReadiness,
       }),
     ).toEqual(
       expect.arrayContaining([

package/templates/starter/src/app/starter-acceptance.color-row-grouping.test.ts

@@ -0,0 +1,118 @@
+import { defineToolcraft } from "@repo/toolcraft-runtime";
+import { describe, expect, it } from "vitest";
+
+import { getToolcraftControlSectionInvariantErrors } from "./acceptance/control-layout";
+
+function makeMixedColorSchema(includeSemanticGroups: boolean) {
+  const withSemanticGroup = (
+    semanticGroup: string,
+  ): { semanticGroup: string } | Record<string, never> =>
+    includeSemanticGroups ? { semanticGroup } : {};
+
+  return defineToolcraft({
+    canvas: { enabled: true },
+    panels: {
+      controls: {
+        sections: [
+          {
+            controls: {
+              trackEnabled: {
+                defaultValue: true,
+                label: "Track",
+                target: "track.enabled",
+                type: "switch",
+              },
+              trackColor: {
+                ...withSemanticGroup("track-line"),
+                defaultValue: { hex: "#F1F1F1" },
+                label: "Track color",
+                target: "track.color",
+                type: "color",
+              },
+              lowerColor: {
+                ...withSemanticGroup("track-range"),
+                defaultValue: { hex: "#7A9CBD" },
+                label: "Lower",
+                target: "track.lower",
+                type: "color",
+              },
+              upperColor: {
+                ...withSemanticGroup("track-range"),
+                defaultValue: { hex: "#52AAFF" },
+                label: "Upper",
+                target: "track.upper",
+                type: "color",
+              },
+            },
+            id: "track-appearance",
+            title: "Track Appearance",
+          },
+        ],
+        title: "Controls",
+      },
+    },
+  });
+}
+
+function makeColorOnlySchema() {
+  return defineToolcraft({
+    canvas: { enabled: true },
+    panels: {
+      controls: {
+        sections: [
+          {
+            controls: {
+              trackColor: {
+                defaultValue: { hex: "#F1F1F1" },
+                label: "Track",
+                target: "track.color",
+                type: "color",
+              },
+              lowerColor: {
+                defaultValue: { hex: "#7A9CBD" },
+                label: "Lower",
+                target: "track.lower",
+                type: "color",
+              },
+              upperColor: {
+                defaultValue: { hex: "#52AAFF" },
+                label: "Upper",
+                target: "track.upper",
+                type: "color",
+              },
+            },
+            id: "track-palette",
+            title: "Track Palette",
+          },
+        ],
+        title: "Controls",
+      },
+    },
+  });
+}
+
+describe("starter acceptance semantic color rows", () => {
+  it("rejects ambiguous plain colors in a mixed section", () => {
+    expect(
+      getToolcraftControlSectionInvariantErrors(makeMixedColorSchema(false)),
+    ).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining(
+          "must declare semanticGroup for every plain Color",
+        ),
+      ]),
+    );
+  });
+
+  it("accepts explicit color banks in a mixed section", () => {
+    expect(
+      getToolcraftControlSectionInvariantErrors(makeMixedColorSchema(true)),
+    ).toEqual([]);
+  });
+
+  it("keeps a color-only section as one implicit bank", () => {
+    expect(
+      getToolcraftControlSectionInvariantErrors(makeColorOnlySchema()),
+    ).toEqual([]);
+  });
+});

package/templates/starter/src/app/starter-acceptance.compound-part-coverage.test.ts

@@ -7,6 +7,71 @@ import {
 import { makeControlAcceptance } from "./starter-acceptance.test-utils";
 
 describe("starter acceptance compound control part coverage contract", () => {
+  it("distinguishes user-owned and source-owned collection parts", () => {
+    const collectionSchema = defineContractSchemaFixture({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                editableColors: {
+                  defaultValue: [{ hex: "#DFFF1A" }],
+                  itemControl: { label: false, type: "color" },
+                  target: "colors.editable",
+                  type: "collectionActions",
+                },
+                editableLayers: {
+                  defaultValue: [{ enabled: true, strength: 0.5 }],
+                  itemControls: {
+                    enabled: {
+                      defaultValue: true,
+                      label: "Enabled",
+                      type: "switch",
+                    },
+                    strength: {
+                      defaultValue: 0.5,
+                      label: "Strength",
+                      max: 1,
+                      min: 0,
+                      type: "slider",
+                    },
+                  },
+                  itemLabel: "Layer",
+                  target: "layers.editable",
+                  type: "collectionActions",
+                },
+                sourceColors: {
+                  defaultValue: [{ hex: "#8CFF3A" }],
+                  itemControl: { label: false, type: "color" },
+                  target: "colors.source",
+                  type: "sourceCollection",
+                },
+              },
+              title: "Fill Sections",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+    const acceptance = [
+      makeControlAcceptance("colors.editable", "collectionActions"),
+      makeControlAcceptance("layers.editable", "collectionActions"),
+      makeControlAcceptance("colors.source", "sourceCollection"),
+    ];
+
+    expect(
+      validateContractAcceptance({ schema: collectionSchema, acceptance }),
+    ).toEqual(
+      expect.arrayContaining([
+        "Fill Sections / editableColors (colors.editable) must declare controlPartCoverage for every semantic value part: collectionActions.add, collectionActions.remove, collectionActions.items.",
+        "Fill Sections / editableLayers (layers.editable) must declare controlPartCoverage for every semantic value part: collectionActions.add, collectionActions.remove, collectionActions.items.",
+        "Fill Sections / sourceColors (colors.source) must declare controlPartCoverage for every semantic value part: sourceCollection.items.",
+      ]),
+    );
+  });
+
   it("requires compound controls to cover every semantic value part", () => {
     const compoundSchema = defineContractSchemaFixture({
       canvas: { enabled: true },
@@ -200,7 +265,7 @@ describe("starter acceptance compound control part coverage contract", () => {
                       { color: "#FFE97A", opacity: 100, position: "100%" },
                     ],
                   },
-                  label: "Gradient",
+                  label: false,
                   orderRole: "color",
                   target: "mesh.gradient",
                   type: "gradient",

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

@@ -20,6 +20,47 @@ const schema = {
 } satisfies ToolcraftAppSchema;
 
 describe("Toolcraft acceptance contract schema fixtures", () => {
+  it("authors neutral fixture controls explicitly without masking legacy input", () => {
+    const fixture = defineContractSchemaFixture({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                legacy: {
+                  target: "shape.legacy",
+                  type: "slider",
+                  visibleWhen: { equals: true, target: "shape.enabled" },
+                },
+                neutral: {
+                  target: "shape.enabled",
+                  type: "switch",
+                },
+              },
+              id: "shape",
+              title: "Shape",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+    const controls = fixture.panels.controls?.sections.find(
+      (section) => section.id === "shape",
+    )?.controls;
+
+    expect(controls?.neutral?.applicability).toEqual({
+      mode: "always",
+      origin: "explicit",
+    });
+    expect(controls?.legacy?.applicability).toEqual({
+      all: [{ equals: true, target: "shape.enabled" }],
+      mode: "conditional",
+      origin: "legacy",
+    });
+  });
+
   it("opts unrelated unit fixtures out without changing the production default", () => {
     const productionDefault = defineToolcraft(schema);
     const contractFixture = defineContractSchemaFixture(schema);