@pixel-point/toolcraft 0.0.16 → 0.0.18

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

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { schemaHasVideoExportPanelAction } from "./acceptance/output-export";
+import { resolveToolcraftArtifactExportIntent } from "./acceptance/artifact-export-intent";
 import { starterProductReadiness } from "./starter-acceptance";
 import {
   textLooksLikePngExport,
@@ -14,38 +14,37 @@ import {
   getSchemaVideoExportSection,
   getSectionControlByTarget,
   getSectionControlIdByTarget,
-  schemaHasProductSurface,
 } from "./starter-acceptance.schema-test-utils";
-import { starterSchema } from "./starter-schema";
 
 describe("Toolcraft output export acceptance contract", () => {
   it("requires product output apps to expose export actions in the sticky footer", () => {
-    if (starterProductReadiness.mode !== "product" && !schemaHasProductSurface()) {
+    if (starterProductReadiness.mode === "starter") {
       return;
     }
 
+    const delivery = resolveToolcraftArtifactExportIntent(
+      starterProductReadiness.exportIntent,
+    );
     const panelActionTexts = getSchemaPanelActionSearchTexts();
     const backgroundColorTargets = getSchemaBackgroundControlTargets(new Set(["color"]));
     const backgroundToggleTargets = getSchemaBackgroundControlTargets(
       new Set(["checkbox", "select", "segmented", "switch"]),
     );
 
-    expect(
-      panelActionTexts.length,
-      "Product apps must define panelActions in the controls panel sticky footer.",
-    ).toBeGreaterThan(0);
-    expect(
-      panelActionTexts.some(textLooksLikePngExport),
-      "Every product app must expose Export PNG or Download PNG through panelActions.",
-    ).toBe(true);
-    expect(
-      backgroundColorTargets.length,
-      "Every product app with Export PNG must expose a user-facing background color control.",
-    ).toBeGreaterThan(0);
-    expect(
-      backgroundToggleTargets.length,
-      'Every product app with Export PNG must expose export.includeBackground in runtime Setup as a Switch labeled "Background".',
-    ).toBeGreaterThan(0);
+    if (delivery.imageEnabled || delivery.videoEnabled) {
+      expect(
+        panelActionTexts.length,
+        "Product apps with artifact delivery must define panelActions in the controls panel sticky footer.",
+      ).toBeGreaterThan(0);
+      expect(
+        backgroundColorTargets.length,
+        "Product apps with artifact delivery must expose a user-facing background color control.",
+      ).toBeGreaterThan(0);
+      expect(
+        backgroundToggleTargets.length,
+        'Product apps with artifact delivery must expose export.includeBackground in runtime Setup as a Switch labeled "Background".',
+      ).toBeGreaterThan(0);
+    }
 
     const imageExportSection = getSchemaImageExportSection();
     const imageFormatControl = getSectionControlByTarget(
@@ -78,47 +77,51 @@ describe("Toolcraft output export acceptance contract", () => {
           ) === true;
 
     expect(
-      imageExportSection,
-      'Apps with Export PNG must expose image settings in a separate controls section titled "Image Export".',
-    ).toBeDefined();
-    expect(
-      imageFormatControl,
-      'The separate "Image Export" section must include a format control with target "export.image.format".',
-    ).toBeDefined();
-    expect(
-      imageFormatControl?.type,
-      "Image Export format must use the same Select/dropdown structure as Video Export.",
-    ).toBe("select");
-    expect(
-      imageFormatOptionValues,
-      'Image format options must include "png" and "jpg".',
-    ).toEqual(expect.arrayContaining(["png", "jpg"]));
-    expect(
-      imageFormatControl?.defaultValue,
-      'Image format must default to "png".',
-    ).toBe("png");
-    expect(
-      imageResolutionControl,
-      'The separate "Image Export" section must include a resolution control with target "export.image.resolution".',
-    ).toBeDefined();
-    expect(
-      imageResolutionControl?.type,
-      "Image Export resolution must use the same Select/dropdown structure as Video Export.",
-    ).toBe("select");
-    expect(
-      imageResolutionOptionValues,
-      'Image resolution options must include "2k", "4k", and "8k".',
-    ).toEqual(expect.arrayContaining(["2k", "4k", "8k"]));
-    expect(
-      imageResolutionControl?.defaultValue,
-      'Image resolution must default to "4k".',
-    ).toBe("4k");
+      panelActionTexts.some(textLooksLikePngExport),
+      "Image export action presence must match resolved product export intent.",
+    ).toBe(delivery.imageEnabled);
     expect(
-      imageExportHasInlinePair,
-      "Image Export format and resolution must render as a compact inline pair.",
-    ).toBe(true);
-    if (!schemaHasVideoExportPanelAction(starterSchema)) {
-      return;
+      imageExportSection !== undefined,
+      '"Image Export" section presence must match resolved product export intent.',
+    ).toBe(delivery.imageEnabled);
+
+    if (delivery.imageEnabled) {
+      expect(
+        imageFormatControl,
+        'The separate "Image Export" section must include a format control with target "export.image.format".',
+      ).toBeDefined();
+      expect(
+        imageFormatControl?.type,
+        "Image Export format must use the same Select/dropdown structure as Video Export.",
+      ).toBe("select");
+      expect(
+        imageFormatOptionValues,
+        'Image format options must include "png" and "jpg".',
+      ).toEqual(expect.arrayContaining(["png", "jpg"]));
+      expect(
+        imageFormatControl?.defaultValue,
+        'Image format must default to "png".',
+      ).toBe("png");
+      expect(
+        imageResolutionControl,
+        'The separate "Image Export" section must include a resolution control with target "export.image.resolution".',
+      ).toBeDefined();
+      expect(
+        imageResolutionControl?.type,
+        "Image Export resolution must use the same Select/dropdown structure as Video Export.",
+      ).toBe("select");
+      expect(
+        imageResolutionOptionValues,
+        'Image resolution options must include "2k", "4k", and "8k".',
+      ).toEqual(expect.arrayContaining(["2k", "4k", "8k"]));
+      expect(
+        imageResolutionControl?.defaultValue,
+        'Image resolution must default to "4k".',
+      ).toBe("4k");
+      expect(
+        imageExportHasInlinePair,
+        "Image Export format and resolution must render as a compact inline pair.",
+      ).toBe(true);
     }
 
     const videoExportSection = getSchemaVideoExportSection();
@@ -134,48 +137,12 @@ describe("Toolcraft output export acceptance contract", () => {
     const videoResolutionOptionValues = getControlOptionValues(videoResolutionControl);
     expect(
       panelActionTexts.some(textLooksLikeVideoExport),
-      "Apps that declare video delivery must expose Export Video through panelActions.",
-    ).toBe(true);
-    expect(
-      panelActionTexts.length,
-      "Apps with image and video delivery need separate footer actions for Export Video and Export PNG.",
-    ).toBeGreaterThanOrEqual(2);
-    expect(
-      videoExportSection,
-      'Apps with Export Video must expose video settings in a separate controls section titled "Video Export".',
-    ).toBeDefined();
-    expect(
-      videoFormatControl,
-      'The separate "Video Export" section must include a format control with target "export.video.format".',
-    ).toBeDefined();
-    expect(
-      ["select", "segmented"],
-      "Video format must be a Select or Segmented control so the user chooses a supported container instead of typing a freeform value.",
-    ).toContain(videoFormatControl?.type);
+      "Video export action presence must match resolved product export intent.",
+    ).toBe(delivery.videoEnabled);
     expect(
-      videoFormatOptionValues,
-      'Video format options must include safe browser baseline choices: "webm" and "mp4".',
-    ).toEqual(expect.arrayContaining(["webm", "mp4"]));
-    expect(
-      videoResolutionControl,
-      'The separate "Video Export" section must include a resolution control with target "export.video.resolution".',
-    ).toBeDefined();
-    expect(
-      ["select"],
-      "Video resolution must be a Select control with explicit output-size choices.",
-    ).toContain(videoResolutionControl?.type);
-    expect(
-      videoResolutionOptionValues,
-      'Video resolution options must include "current" and "4k".',
-    ).toEqual(expect.arrayContaining(["current", "4k"]));
-    expect(
-      videoResolutionControl?.defaultValue,
-      'Video resolution must default to "current".',
-    ).toBe("current");
-    expect(
-      videoFormatControl?.defaultValue,
-      'Video format must default to "mp4".',
-    ).toBe("mp4");
+      videoExportSection !== undefined,
+      '"Video Export" section presence must match resolved product export intent.',
+    ).toBe(delivery.videoEnabled);
     const videoFormatControlId = getSectionControlIdByTarget(
       videoExportSection,
       "export.video.format",
@@ -194,9 +161,49 @@ describe("Toolcraft output export acceptance contract", () => {
               group.controls.includes(videoResolutionControlId),
           ) === true;
 
-    expect(
-      videoExportHasInlinePair,
-      "Video Export format and resolution must render as a compact inline pair unless a documented fit fallback is used.",
-    ).toBe(true);
+    if (delivery.videoEnabled) {
+      if (delivery.imageEnabled) {
+        expect(
+          panelActionTexts.length,
+          "Apps with image and video delivery need separate footer actions for Export Video and Export PNG.",
+        ).toBeGreaterThanOrEqual(2);
+      }
+      expect(
+        videoFormatControl,
+        'The separate "Video Export" section must include a format control with target "export.video.format".',
+      ).toBeDefined();
+      expect(
+        ["select", "segmented"],
+        "Video format must be a Select or Segmented control so the user chooses a supported container instead of typing a freeform value.",
+      ).toContain(videoFormatControl?.type);
+      expect(
+        videoFormatOptionValues,
+        'Video format options must include safe browser baseline choices: "webm" and "mp4".',
+      ).toEqual(expect.arrayContaining(["webm", "mp4"]));
+      expect(
+        videoResolutionControl,
+        'The separate "Video Export" section must include a resolution control with target "export.video.resolution".',
+      ).toBeDefined();
+      expect(
+        ["select"],
+        "Video resolution must be a Select control with explicit output-size choices.",
+      ).toContain(videoResolutionControl?.type);
+      expect(
+        videoResolutionOptionValues,
+        'Video resolution options must include "current" and "4k".',
+      ).toEqual(expect.arrayContaining(["current", "4k"]));
+      expect(
+        videoResolutionControl?.defaultValue,
+        'Video resolution must default to "current".',
+      ).toBe("current");
+      expect(
+        videoFormatControl?.defaultValue,
+        'Video format must default to "mp4".',
+      ).toBe("mp4");
+      expect(
+        videoExportHasInlinePair,
+        "Video Export format and resolution must render as a compact inline pair unless a documented fit fallback is used.",
+      ).toBe(true);
+    }
   });
 });

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

@@ -4,6 +4,7 @@ import {
   starterProductReadiness,
   starterTransferMode,
 } from "./starter-acceptance";
+import { schemaHasVideoExportPanelAction } from "./acceptance/output-export";
 import { isNeutralTemplateProject } from "./starter-acceptance.product-readiness-test-utils";
 import { schemaHasProductSurface } from "./starter-acceptance.schema-test-utils";
 import { starterSchema } from "./starter-schema";
@@ -22,6 +23,17 @@ describe("Toolcraft product readiness", () => {
 
   it("allows neutral readiness only for the source starter/template folder", () => {
     if (starterProductReadiness.mode === "product") {
+      expect(starterProductReadiness.exportIntent).toBeDefined();
+      if (starterProductReadiness.exportIntent.image.mode === "toolcraft-default") {
+        expect(starterProductReadiness.exportIntent.image).toEqual({
+          mode: "toolcraft-default",
+        });
+      }
+      expect(starterProductReadiness.exportIntent.video.mode).toBe(
+        schemaHasVideoExportPanelAction(starterSchema)
+          ? "user-requested"
+          : "not-requested",
+      );
       expect(starterProductReadiness.productName.trim()).not.toBe("");
       expect(starterProductReadiness.productSummary.trim()).not.toBe("");
       expect(starterProductReadiness.requestedBehavior.trim()).not.toBe("");

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

@@ -311,7 +311,7 @@ describe("starter acceptance section cohesion contract", () => {
       }),
     ).toEqual(
       expect.arrayContaining([
-        'Controls for product entity "squares.right" are split across sections: Square 1 (Right), Appearance. Keep controls for the same product entity in one semantic section unless the Control Section Inventory declares workflowStage and splitReason for every split section.',
+        'Controls for target family "squares.right" are split across sections: Square 1 (Right), Appearance. Assign one shared entityId when the sections edit one logical entity; the entity cohesion validator decides whether that split is allowed.',
       ]),
     );
   });

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

@@ -58,6 +58,7 @@ describe("starter acceptance section dependency contract", () => {
         sectionInventory: [
           {
             entity: "Shape",
+            entityId: "shape",
             groupingReason: "Shape setup",
             id: "shape",
             targets: ["shape.kind"],
@@ -73,7 +74,7 @@ describe("starter acceptance section dependency contract", () => {
     );
   });
 
-  it("allows explicit workflow split evidence for one target entity", () => {
+  it("rejects workflow splitting when one entity fits in one section", () => {
     const schemaWithWorkflowSplit = defineContractSchemaFixture({
       canvas: { enabled: true },
       panels: {
@@ -118,6 +119,33 @@ describe("starter acceptance section dependency contract", () => {
       },
     });
 
+    const workflowSplitInventory = [
+      {
+        entity: "Object shape",
+        entityId: "object-shape",
+        groupingReason:
+          "Structure controls tune the physical footprint of the object.",
+        id: "shape-structure",
+        splitReason:
+          "Structure and density are separate workflow stages in this editor.",
+        targets: ["object.shape.size"],
+        title: "Shape Structure",
+        workflowStage: "structure",
+      },
+      {
+        entity: "Object shape",
+        entityId: "object-shape",
+        groupingReason:
+          "Density controls tune how many objects appear after structure is set.",
+        id: "shape-density",
+        splitReason:
+          "Density is separated from structure because users set count after the shape footprint.",
+        targets: ["object.shape.count"],
+        title: "Shape Density",
+        workflowStage: "density",
+      },
+    ] as const;
+
     expect(
       validateContractAcceptance({
         schema: schemaWithWorkflowSplit,
@@ -126,28 +154,11 @@ describe("starter acceptance section dependency contract", () => {
           makeControlAcceptance("object.shape.count", "slider"),
         ],
         transferMode: contractTransferModeFixture,
-        sectionInventory: [
-          {
-            entity: "Object shape",
-            groupingReason: "Structure controls tune the physical footprint of the object.",
-            id: "shape-structure",
-            splitReason: "Structure and density are separate workflow stages in this editor.",
-            targets: ["object.shape.size"],
-            title: "Shape Structure",
-            workflowStage: "structure",
-          },
-          {
-            entity: "Object shape",
-            groupingReason: "Density controls tune how many objects appear after structure is set.",
-            id: "shape-density",
-            splitReason: "Density is separated from structure because users set count after the shape footprint.",
-            targets: ["object.shape.count"],
-            title: "Shape Density",
-            workflowStage: "density",
-          },
-        ],
+        sectionInventory: workflowSplitInventory,
       }),
-    ).toEqual([]);
+    ).toContain(
+      'Control Section Inventory entity "object-shape" owns 2 controls across 2 sections (Shape Structure, Shape Density). Entities with 10 or fewer controls must stay in one section.',
+    );
   });
 
   it("rejects mode-gated controls split away from their selector section", () => {
@@ -203,7 +214,7 @@ describe("starter acceptance section dependency contract", () => {
       }),
     ).toEqual(
       expect.arrayContaining([
-        'Image / sourceUpload is gated by visibleWhen target "source.mode" in Source, but it belongs to the same dependency group. Keep selectors and their dependent controls in one semantic section when they describe one product entity or branch; use visibleWhen for branch-specific controls inside that section instead of splitting branch controls into their own section. Do not use disabledWhen for product controls.',
+        'Image / sourceUpload is gated by applicability target "source.mode" in Source, but it belongs to the same dependency group. Keep selectors and their dependent controls in one semantic section when they describe one product entity or branch; use conditional applicability for branch-specific controls inside that section instead of splitting branch controls into their own section. Do not use disabledWhen for product controls.',
       ]),
     );
   });
@@ -259,7 +270,7 @@ describe("starter acceptance section dependency contract", () => {
       }),
     ).toEqual(
       expect.arrayContaining([
-        'Library / libraryAsset is gated by visibleWhen target "shape.kind" in Shape, but it belongs to the same dependency group. Keep selectors and their dependent controls in one semantic section when they describe one product entity or branch; use visibleWhen for branch-specific controls inside that section instead of splitting branch controls into their own section. Do not use disabledWhen for product controls.',
+        'Library / libraryAsset is gated by applicability target "shape.kind" in Shape, but it belongs to the same dependency group. Keep selectors and their dependent controls in one semantic section when they describe one product entity or branch; use conditional applicability for branch-specific controls inside that section instead of splitting branch controls into their own section. Do not use disabledWhen for product controls.',
       ]),
     );
   });

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

@@ -0,0 +1,72 @@
+import { defineToolcraft } from "@repo/toolcraft-runtime";
+import { describe, expect, it } from "vitest";
+
+import { getToolcraftControlSectionInvariantErrors } from "./acceptance/control-layout";
+
+function makeSliderControls(count: number, includeSemanticGroup: boolean) {
+  return Object.fromEntries(
+    Array.from({ length: count }, (_, index) => {
+      const control = {
+        defaultValue: 0,
+        label: `Value ${index + 1}`,
+        max: 1,
+        min: 0,
+        orderRole: "detail" as const,
+        target: `dense.value${index + 1}`,
+        type: "slider" as const,
+        variant: "continuous" as const,
+      };
+
+      return [
+        `value${index + 1}`,
+        includeSemanticGroup
+          ? { ...control, semanticGroup: "dense-entity" }
+          : control,
+      ];
+    }),
+  );
+}
+
+function makeDenseSchema(count: number, includeSemanticGroup = true) {
+  return defineToolcraft({
+    canvas: { enabled: true },
+    panels: {
+      controls: {
+        sections: [
+          {
+            controls: makeSliderControls(count, includeSemanticGroup),
+            id: "dense-entity",
+            title: "Dense Entity",
+          },
+        ],
+        title: "Controls",
+      },
+    },
+  });
+}
+
+describe("starter acceptance section size boundaries", () => {
+  it("does not require semanticGroup at seven controls", () => {
+    expect(
+      getToolcraftControlSectionInvariantErrors(makeDenseSchema(7, false)),
+    ).toEqual([]);
+  });
+
+  it("accepts ten grouped controls in one section", () => {
+    expect(
+      getToolcraftControlSectionInvariantErrors(makeDenseSchema(10)),
+    ).toEqual([]);
+  });
+
+  it("requires semanticGroup beginning at eight controls", () => {
+    expect(
+      getToolcraftControlSectionInvariantErrors(makeDenseSchema(8, false)),
+    ).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining(
+          "has 8 controls and must declare semanticGroup for every control",
+        ),
+      ]),
+    );
+  });
+});

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

@@ -4,6 +4,17 @@ import {
 } from "@repo/toolcraft-runtime";
 
 import { getRequiredToolcraftControlPartCoverage } from "./acceptance/control-parts";
+export {
+  getToolcraftApplicabilitySelectorDomain,
+  getToolcraftControlApplicabilityErrors,
+  type ToolcraftApplicabilitySelectorDomain,
+  type ToolcraftApplicabilitySelectorValue,
+} from "./acceptance/control-applicability";
+export {
+  getToolcraftApplicabilityRequirementId,
+  getToolcraftControlApplicabilityCases,
+  type ToolcraftControlApplicabilityCase,
+} from "./acceptance/control-applicability-cases";
 import {
   getToolcraftControlOrder as getToolcraftControlOrderForSchema,
   getToolcraftControlOrderTargets as getToolcraftControlOrderTargetsForSchema,
@@ -17,12 +28,12 @@ import type {
   ToolcraftBuiltInFitCheck,
   ToolcraftBackgroundOutputCoverage,
   ToolcraftCanvasSizingCoverage,
-  ToolcraftConditionalVisibilityCoverage,
   ToolcraftComponentAcceptance,
   ToolcraftControlOrderItem,
   ToolcraftControlPartCoverage,
   ToolcraftControlSectionInventoryEntry,
   ToolcraftCustomControlCoverage,
+  ToolcraftExportArtifactCoverage,
   ToolcraftLayerCoverage,
   ToolcraftInteractionCapability,
   ToolcraftInteractionEvidenceSource,
@@ -90,12 +101,12 @@ export type {
   ToolcraftBuiltInFitCheck,
   ToolcraftBackgroundOutputCoverage,
   ToolcraftCanvasSizingCoverage,
-  ToolcraftConditionalVisibilityCoverage,
   ToolcraftComponentAcceptance,
   ToolcraftControlOrderItem,
   ToolcraftControlPartCoverage,
   ToolcraftControlSectionInventoryEntry,
   ToolcraftCustomControlCoverage,
+  ToolcraftExportArtifactCoverage,
   ToolcraftLayerCoverage,
   ToolcraftInteractionCapability,
   ToolcraftInteractionEvidenceSource,