@pixel-point/toolcraft 0.0.16 → 0.0.18

package/templates/starter/src/app/acceptance/types.ts

@@ -1,7 +1,7 @@
 import type {
   ToolcraftBuiltInControlType as RuntimeToolcraftBuiltInControlType,
   ToolcraftControlOrderRole,
-  ToolcraftControlSchema,
+  ResolvedToolcraftControlSchema,
   ToolcraftPersistableStateSlice,
 } from "@repo/toolcraft-runtime";
 import { TOOLCRAFT_BUILT_IN_CONTROL_TYPES } from "@repo/toolcraft-runtime";
@@ -58,6 +58,10 @@ export type ToolcraftAcceptanceEvidence =
   | "timeline-output"
   | "viewport-side-effect";
 
+export type ToolcraftExportArtifactCoverage =
+  | "all-required-image-export-behavior"
+  | "all-required-video-export-behavior";
+
 export type ToolcraftReferenceCoverage =
   | "canvas-sizing"
   | "control-mapping"
@@ -98,8 +102,6 @@ export type ToolcraftPersistenceCoverage = "reload";
 
 export type ToolcraftSettingsTransferCoverage = "opt-out";
 
-export type ToolcraftConditionalVisibilityCoverage = "hidden" | "visible";
-
 export type ToolcraftOrientationGizmoCoverage =
   | "axis-drag"
   | "axis-snap"
@@ -195,6 +197,9 @@ export type ToolcraftControlPartCoverage =
   | "anchorGrid.position"
   | "channelMixer.activeChannel"
   | "channelMixer.values"
+  | "collectionActions.add"
+  | "collectionActions.items"
+  | "collectionActions.remove"
   | "curves.activeChannel"
   | "curves.points"
   | "colorOpacity.hex"
@@ -218,6 +223,7 @@ export type ToolcraftControlPartCoverage =
   | "rangeInput.start"
   | "rangeSlider.lower"
   | "rangeSlider.upper"
+  | "sourceCollection.items"
   | "vector.x"
   | "vector.y";
 
@@ -268,12 +274,27 @@ export type ToolcraftTransferMode =
       videoReferenceStudy?: ToolcraftVideoReferenceStudyEvidence;
     };
 
+export type ToolcraftImageExportIntent =
+  | Readonly<{ mode: "toolcraft-default" }>
+  | Readonly<{ evidence: string; mode: "user-requested" }>
+  | Readonly<{ evidence: string; mode: "user-removed" }>;
+
+export type ToolcraftVideoExportIntent =
+  | Readonly<{ mode: "not-requested" }>
+  | Readonly<{ evidence: string; mode: "user-requested" }>;
+
+export type ToolcraftArtifactExportIntent = Readonly<{
+  image: ToolcraftImageExportIntent;
+  video: ToolcraftVideoExportIntent;
+}>;
+
 export type ToolcraftProductReadiness =
   | {
       mode: "starter";
       reason: string;
     }
   | {
+      exportIntent: ToolcraftArtifactExportIntent;
       mode: "product";
       interactionOwnership: readonly ToolcraftInteractionOwnershipEntry[];
       productName: string;
@@ -290,6 +311,9 @@ export type ToolcraftComponentAcceptance = {
   browserTestName: string;
   componentType: string;
   evidence: ToolcraftAcceptanceEvidence;
+  exportArtifactCoverage?:
+    | ToolcraftExportArtifactCoverage
+    | readonly ToolcraftExportArtifactCoverage[];
   expectedObservable: string;
   fixture: string;
   id: string;
@@ -335,13 +359,10 @@ export type ToolcraftComponentAcceptance = {
     | "all-required-background-output"
     | readonly ToolcraftBackgroundOutputCoverage[];
   userAction: string;
-  visibilityCoverage?:
-    | "all-conditional-visibility"
-    | readonly ToolcraftConditionalVisibilityCoverage[];
 };
 
 export type ToolcraftVisibleControl = {
-  control: ToolcraftControlSchema;
+  control: ResolvedToolcraftControlSchema;
   controlId: string;
   sectionTitle?: string;
 };
@@ -356,7 +377,8 @@ export type ToolcraftControlOrderItem = {
 };
 
 export type ToolcraftControlSectionInventoryEntry = {
-  entity?: string;
+  entity: string;
+  entityId: string;
   groupingReason: string;
   id: string;
   splitReason?: string;

package/templates/starter/src/app/acceptance/validate-coverage.ts

@@ -5,11 +5,13 @@ import {
   getToolcraftAnimationModeChoiceErrors,
 } from "./animation-intent";
 import { getToolcraftControlAcceptanceErrors } from "./control-acceptance";
+import { getToolcraftControlApplicabilityErrors } from "./control-applicability";
 import {
   getToolcraftControlSectionHeuristicErrors,
   getToolcraftControlSectionInvariantErrors,
 } from "./control-layout";
 import { getToolcraftControlOrderErrors } from "./control-order";
+import { getToolcraftControlSectionEntityCohesionErrors } from "./control-section-entity-cohesion";
 import { getToolcraftControlSectionInventoryErrors } from "./control-section-inventory";
 import { isToolcraftVisibleAcceptanceControl } from "./controls";
 import { getToolcraftInlineLayoutErrors } from "./inline-layout";
@@ -146,12 +148,27 @@ const toolcraftAcceptanceValidators: readonly ToolcraftAcceptanceValidator[] = [
     ruleId: "controls-product-coverage",
     validate: ({ schema }) => getToolcraftOrientationGizmoErrors(schema),
   },
+  {
+    path: "schema.panels.controls.sections[].controls[].applicability",
+    ruleId: "controls-product-coverage",
+    validate: ({ controls, productReadiness }) =>
+      getToolcraftControlApplicabilityErrors({
+        controls,
+        productReadiness,
+      }),
+  },
   {
     path: "starterControlSectionInventory",
     ruleId: "controls-section-inventory-required",
     validate: ({ schema, sectionInventory }) =>
       getToolcraftControlSectionInventoryErrors(schema, sectionInventory),
   },
+  {
+    path: "starterControlSectionInventory",
+    ruleId: "controls-section-inventory-required",
+    validate: ({ sectionInventory }) =>
+      getToolcraftControlSectionEntityCohesionErrors(sectionInventory),
+  },
   {
     path: "schema.panels.controls.sections[].layoutGroups",
     ruleId: "controls-component-layout-invariants",
@@ -160,10 +177,11 @@ const toolcraftAcceptanceValidators: readonly ToolcraftAcceptanceValidator[] = [
   {
     path: "schema.export",
     ruleId: "output-export-required",
-    validate: ({ controls, hasVideoExportAction, schema }) =>
+    validate: ({ acceptance, controls, productReadiness, schema }) =>
       getToolcraftOutputExportErrors({
+        acceptance,
         controls,
-        hasVideoExportAction,
+        productReadiness,
         schema,
       }),
   },

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

@@ -0,0 +1,239 @@
+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;
+    videoEnabled: boolean;
+  }>;
+  intent: ToolcraftArtifactExportIntent;
+  name: string;
+}>[] = [
+  {
+    expected: { imageEnabled: true, videoEnabled: false },
+    intent: {
+      image: { mode: "toolcraft-default" },
+      video: { mode: "not-requested" },
+    },
+    name: "enables default image export without unrequested video export",
+  },
+  {
+    expected: { imageEnabled: true, videoEnabled: false },
+    intent: {
+      image: {
+        evidence: "The user explicitly requested PNG delivery.",
+        mode: "user-requested",
+      },
+      video: { mode: "not-requested" },
+    },
+    name: "enables explicitly requested image export",
+  },
+  {
+    expected: { imageEnabled: false, videoEnabled: false },
+    intent: {
+      image: {
+        evidence: "The user explicitly requested no image export.",
+        mode: "user-removed",
+      },
+      video: { mode: "not-requested" },
+    },
+    name: "disables explicitly removed image export",
+  },
+  {
+    expected: { imageEnabled: true, videoEnabled: true },
+    intent: {
+      image: { mode: "toolcraft-default" },
+      video: {
+        evidence: "The user explicitly requested MP4 delivery.",
+        mode: "user-requested",
+      },
+    },
+    name: "enables explicitly requested video export",
+  },
+  {
+    expected: { imageEnabled: true, videoEnabled: true },
+    intent: {
+      image: {
+        evidence: "The user explicitly requested PNG delivery.",
+        mode: "user-requested",
+      },
+      video: {
+        evidence: "The user explicitly requested MP4 delivery.",
+        mode: "user-requested",
+      },
+    },
+    name: "enables explicitly requested image and video export",
+  },
+  {
+    expected: { imageEnabled: false, videoEnabled: true },
+    intent: {
+      image: {
+        evidence: "The user explicitly requested no image export.",
+        mode: "user-removed",
+      },
+      video: {
+        evidence: "The user explicitly requested MP4 delivery.",
+        mode: "user-requested",
+      },
+    },
+    name: "keeps requested video export when image export is removed",
+  },
+];
+
+const evidenceCases: readonly Readonly<{
+  expected: readonly string[];
+  intent: ToolcraftArtifactExportIntent;
+  name: string;
+}>[] = [
+  {
+    expected: [],
+    intent: {
+      image: { mode: "toolcraft-default" },
+      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",
+      },
+      video: { mode: "not-requested" },
+    },
+    name: "accepts nonblank requested image evidence",
+  },
+  {
+    expected: [],
+    intent: {
+      image: {
+        evidence: "The user explicitly requested no image export.",
+        mode: "user-removed",
+      },
+      video: { mode: "not-requested" },
+    },
+    name: "accepts nonblank image removal evidence",
+  },
+  {
+    expected: [],
+    intent: {
+      image: { mode: "toolcraft-default" },
+      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" },
+      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" },
+      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" },
+      video: { evidence: "\t", mode: "user-requested" },
+    },
+    name: "rejects blank requested video 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" },
+      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,
+        hasVideoExportAction: true,
+        hasVideoExportSection: true,
+        intent: {
+          image: { mode: "toolcraft-default" },
+          video: { mode: "not-requested" },
+        },
+      }),
+    ).toEqual({
+      delivery: { imageEnabled: true, 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,
+        hasVideoExportAction: false,
+        hasVideoExportSection: false,
+        intent: {
+          image: { evidence: "  ", mode: "user-removed" },
+          video: { evidence: "\t", mode: "user-requested" },
+        },
+      }),
+    ).toEqual({
+      delivery: { imageEnabled: 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.',
+      ],
+    });
+  });
+});

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,33 @@ import {
 } from "./starter-acceptance.export-test-utils";
 import { makeControlAcceptance } from "./starter-acceptance.test-utils";
 
+const imageExportProductReadiness: ToolcraftProductReadiness = {
+  exportIntent: {
+    image: { mode: "toolcraft-default" },
+    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" },
+    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 +71,7 @@ describe("Toolcraft background export acceptance contract", () => {
     expect(
       validateContractAcceptance({
         schema: schemaWithoutBackgroundControls,
+        productReadiness: imageExportProductReadiness,
         acceptance: [
           {
             actionCoverage: ["export.png"],
@@ -118,6 +147,7 @@ describe("Toolcraft background export acceptance contract", () => {
     expect(
       validateContractAcceptance({
         schema: schemaWithLegacyBackgroundControls,
+        productReadiness: imageExportProductReadiness,
         acceptance: [
           makeControlAcceptance("appearance.background", "color"),
           makeControlAcceptance("export.includeBackground", "switch"),
@@ -185,6 +215,7 @@ describe("Toolcraft background export acceptance contract", () => {
     });
     const errors = validateContractAcceptance({
       schema: schemaWithBackgroundControls,
+      productReadiness: imageExportProductReadiness,
       acceptance: [
         makeControlAcceptance("appearance.background", "color"),
         {
@@ -262,6 +293,7 @@ describe("Toolcraft background export acceptance contract", () => {
     expect(
       validateContractAcceptance({
         schema: schemaWithBackgroundControls,
+        productReadiness: imageExportProductReadiness,
         acceptance: [
           makeControlAcceptance("appearance.background", "color"),
           makeControlAcceptance("export.includeBackground", "switch"),
@@ -332,6 +364,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,10 @@ import { makeControlAcceptance } from "./starter-acceptance.test-utils";
 import type { ToolcraftProductReadiness } from "./acceptance/types";
 
 const infinityProductReadiness: ToolcraftProductReadiness = {
+  exportIntent: {
+    image: { mode: "toolcraft-default" },
+    video: { mode: "not-requested" },
+  },
   interactionOwnership: [],
   mode: "product",
   productName: "Infinity contract fixture",
@@ -20,6 +24,17 @@ const infinityProductReadiness: ToolcraftProductReadiness = {
   },
 };
 
+const infinityVideoProductReadiness: ToolcraftProductReadiness = {
+  ...infinityProductReadiness,
+  exportIntent: {
+    image: { mode: "toolcraft-default" },
+    video: {
+      evidence: "The Infinity canvas fixture explicitly exercises video export bounds.",
+      mode: "user-requested",
+    },
+  },
+};
+
 function createFixedOutputSchema({
   height = 1080,
   width = 1920,
@@ -167,7 +182,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.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 },

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);