@pixel-point/toolcraft 0.0.17 → 0.0.18

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,11 +177,11 @@ const toolcraftAcceptanceValidators: readonly ToolcraftAcceptanceValidator[] = [
   {
     path: "schema.export",
     ruleId: "output-export-required",
-    validate: ({ acceptance, 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);

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

@@ -1,5 +1,7 @@
 import {
   defineToolcraft,
+  resolveToolcraftControlApplicability,
+  type ResolvedToolcraftAppSchema,
   type ToolcraftAppSchema,
 } from "@repo/toolcraft-runtime";
 
@@ -16,8 +18,32 @@ import {
 } from "./acceptance/validate-coverage";
 
 export function defineContractSchemaFixture(schema: ToolcraftAppSchema) {
+  const controls = schema.panels.controls
+    ? {
+        ...schema.panels.controls,
+        sections: schema.panels.controls.sections.map((section) => ({
+          ...section,
+          controls: Object.fromEntries(
+            Object.entries(section.controls).map(([controlId, control]) => [
+              controlId,
+              control.applicability || control.visibleWhen
+                ? control
+                : {
+                    ...control,
+                    applicability: { mode: "always" as const },
+                  },
+            ]),
+          ),
+        })),
+      }
+    : undefined;
+
   return defineToolcraft({
     ...schema,
+    panels: {
+      ...schema.panels,
+      ...(controls ? { controls } : {}),
+    },
     persistence: { storage: "none" },
   });
 }
@@ -54,28 +80,98 @@ export const contractProductReadinessFixture: ToolcraftProductReadiness = {
   reason: "Neutral contract fixture without a product-owned spatial scene.",
 };
 
-export function validateContractAcceptance(
-  overrides: Partial<ToolcraftAcceptanceValidationInput> = {},
-): string[] {
-  return validateToolcraftAcceptanceCoverage({
+type ContractAcceptanceOverrides = Omit<
+  Partial<ToolcraftAcceptanceValidationInput>,
+  "schema"
+> & {
+  schema?: ContractValidationSchemaFixture;
+};
+
+type ContractValidationSchemaFixture = Omit<
+  ResolvedToolcraftAppSchema,
+  "panels"
+> & {
+  panels: Omit<ResolvedToolcraftAppSchema["panels"], "controls"> & {
+    controls?: ToolcraftAppSchema["panels"]["controls"];
+  };
+};
+
+function resolveContractValidationSchemaFixture(
+  schema: ContractValidationSchemaFixture,
+): ResolvedToolcraftAppSchema {
+  const {
+    controls: _fixtureControls,
+    ...panelsWithoutFixtureControls
+  } = schema.panels;
+  const controls = schema.panels.controls
+    ? {
+        ...schema.panels.controls,
+        sections: schema.panels.controls.sections.map((section) => ({
+          ...section,
+          controls: Object.fromEntries(
+            Object.entries(section.controls).map(([controlId, control]) => {
+              const {
+                applicability: authoredApplicability,
+                visibleWhen,
+                ...controlWithoutApplicability
+              } = control;
+
+              return [
+                controlId,
+                {
+                  ...controlWithoutApplicability,
+                  applicability: resolveToolcraftControlApplicability({
+                    applicability:
+                      authoredApplicability ??
+                      (visibleWhen ? undefined : { mode: "always" }),
+                    visibleWhen,
+                  }),
+                },
+              ];
+            }),
+          ),
+        })),
+      }
+    : undefined;
+
+  // Contract tests deliberately preserve malformed post-normalization fields so
+  // the matching acceptance validator, rather than defineToolcraft, reports them.
+  return {
+    ...schema,
+    panels: {
+      ...panelsWithoutFixtureControls,
+      ...(controls ? { controls } : {}),
+    },
+  } as ResolvedToolcraftAppSchema;
+}
+
+function resolveContractAcceptanceInput(
+  overrides: ContractAcceptanceOverrides,
+): ToolcraftAcceptanceValidationInput {
+  const { schema = contractSchemaFixture, ...remainingOverrides } = overrides;
+
+  return {
     acceptance: contractAcceptanceFixture,
     productReadiness: contractProductReadinessFixture,
-    schema: contractSchemaFixture,
+    schema: resolveContractValidationSchemaFixture(schema),
     sectionInventory: contractSectionInventoryFixture,
     transferMode: contractTransferModeFixture,
-    ...overrides,
-  });
+    ...remainingOverrides,
+  };
+}
+
+export function validateContractAcceptance(
+  overrides: ContractAcceptanceOverrides = {},
+): string[] {
+  return validateToolcraftAcceptanceCoverage(
+    resolveContractAcceptanceInput(overrides),
+  );
 }
 
 export function validateContractAcceptanceDiagnostics(
-  overrides: Partial<ToolcraftAcceptanceValidationInput> = {},
+  overrides: ContractAcceptanceOverrides = {},
 ) {
-  return validateToolcraftAcceptanceDiagnostics({
-    acceptance: contractAcceptanceFixture,
-    productReadiness: contractProductReadinessFixture,
-    schema: contractSchemaFixture,
-    sectionInventory: contractSectionInventoryFixture,
-    transferMode: contractTransferModeFixture,
-    ...overrides,
-  });
+  return validateToolcraftAcceptanceDiagnostics(
+    resolveContractAcceptanceInput(overrides),
+  );
 }