@pixel-point/toolcraft 0.0.17 → 0.0.19

package/templates/starter/scripts/toolcraft-vitest-runtime-contract.test.mjs

@@ -2,11 +2,16 @@ import assert from "node:assert/strict";
 import test from "node:test";
 
 import {
+  TOOLCRAFT_VITEST_RUNTIME_ACCEPTANCE_SELECTION_ENV,
   TOOLCRAFT_VITEST_RUNTIME_MARKER_FILE_NAMES,
   TOOLCRAFT_VITEST_RUNTIME_REQUIREMENTS_ANNOTATION_TYPE,
   evaluateToolcraftVitestRuntimeEvidence,
   getToolcraftProductTestProcessArgs,
+  getToolcraftProductTestProcessEnvironment,
+  parseToolcraftVitestRuntimeAcceptanceSelection,
   parseToolcraftVitestRuntimeRequirements,
+  selectToolcraftVitestRuntimeRequirements,
+  serializeToolcraftVitestRuntimeAcceptanceSelection,
   serializeToolcraftVitestRuntimeRequirements,
 } from "./toolcraft-vitest-runtime-contract.mjs";
 
@@ -15,6 +20,11 @@ const requirement = {
   requirementId: "appearance.opacity",
   testName: "opacity changes product output",
 };
+const unrelatedRequirement = {
+  kind: "acceptance",
+  requirementId: "material.host",
+  testName: "keeps the baseline material extension inactive",
+};
 
 function requiredTest(overrides = {}) {
   return {
@@ -61,6 +71,27 @@ test("product-test process args execute only planned files and gate runtime evid
   }
 });
 
+test("product-test process environment distinguishes full and targeted proof", () => {
+  const inherited = {
+    KEEP_ME: "yes",
+    [TOOLCRAFT_VITEST_RUNTIME_ACCEPTANCE_SELECTION_ENV]: "forged",
+  };
+  const full = getToolcraftProductTestProcessEnvironment(null, inherited);
+  const targeted = getToolcraftProductTestProcessEnvironment([], inherited);
+
+  assert.deepEqual(full, { KEEP_ME: "yes" });
+  assert.deepEqual(
+    parseToolcraftVitestRuntimeAcceptanceSelection(
+      targeted[TOOLCRAFT_VITEST_RUNTIME_ACCEPTANCE_SELECTION_ENV],
+    ),
+    [],
+  );
+  assert.equal(
+    inherited[TOOLCRAFT_VITEST_RUNTIME_ACCEPTANCE_SELECTION_ENV],
+    "forged",
+  );
+});
+
 test("round-trips runtime requirements through a typed annotation", () => {
   assert.deepEqual(
     parseToolcraftVitestRuntimeRequirements({
@@ -71,6 +102,89 @@ test("round-trips runtime requirements through a typed annotation", () => {
   );
 });
 
+test("round-trips the protected canonical acceptance selection", () => {
+  const serialized = serializeToolcraftVitestRuntimeAcceptanceSelection([
+    "appearance.opacity",
+  ]);
+
+  assert.equal(
+    TOOLCRAFT_VITEST_RUNTIME_ACCEPTANCE_SELECTION_ENV,
+    "TOOLCRAFT_VITEST_RUNTIME_ACCEPTANCE_SELECTION",
+  );
+  assert.deepEqual(
+    parseToolcraftVitestRuntimeAcceptanceSelection(serialized),
+    ["appearance.opacity"],
+  );
+  assert.throws(
+    () => serializeToolcraftVitestRuntimeAcceptanceSelection([
+      "material.host",
+      "appearance.opacity",
+    ]),
+    /sorted and unique/iu,
+  );
+  assert.throws(
+    () => parseToolcraftVitestRuntimeAcceptanceSelection(
+      '{"acceptanceIds":["appearance.opacity","appearance.opacity"],"version":1}',
+    ),
+    /sorted and unique/iu,
+  );
+  const sparse = [];
+  sparse.length = 1;
+  assert.throws(
+    () => serializeToolcraftVitestRuntimeAcceptanceSelection(sparse),
+    /sorted and unique/iu,
+  );
+});
+
+test("selects only signed targeted acceptance requirements and fails closed", () => {
+  const requirements = [requirement, unrelatedRequirement];
+
+  assert.deepEqual(
+    selectToolcraftVitestRuntimeRequirements(requirements, undefined),
+    requirements,
+  );
+  assert.deepEqual(
+    selectToolcraftVitestRuntimeRequirements(
+      requirements,
+      serializeToolcraftVitestRuntimeAcceptanceSelection([
+        "appearance.opacity",
+      ]),
+    ),
+    [requirement],
+  );
+  assert.throws(
+    () => selectToolcraftVitestRuntimeRequirements(
+      requirements,
+      serializeToolcraftVitestRuntimeAcceptanceSelection([
+        "reference.flash-events",
+      ]),
+    ),
+    /unknown acceptance requirement.*reference\.flash-events/iu,
+  );
+});
+
+test("a selected reference requirement still requires its exact product test", () => {
+  const referenceRequirement = {
+    kind: "acceptance",
+    requirementId: "reference.flash-events",
+    testName: "reference flash events change product output",
+  };
+  const selected = selectToolcraftVitestRuntimeRequirements(
+    [referenceRequirement, unrelatedRequirement],
+    serializeToolcraftVitestRuntimeAcceptanceSelection([
+      "reference.flash-events",
+    ]),
+  );
+
+  assert.match(
+    evaluateToolcraftVitestRuntimeEvidence({
+      requirements: selected,
+      tests: [],
+    })[0],
+    /Missing required automated test.*reference flash events/iu,
+  );
+});
+
 test("accepts one passed product-owned test", () => {
   assert.deepEqual(
     evaluateToolcraftVitestRuntimeEvidence({

package/templates/starter/scripts/toolcraft-vitest-runtime-evidence-reporter.mjs

@@ -2,10 +2,12 @@ import path from "node:path";
 
 import { collectToolcraftFrameworkOwnedLocalPaths } from "./toolcraft-source-ownership.mjs";
 import {
+  TOOLCRAFT_VITEST_RUNTIME_ACCEPTANCE_SELECTION_ENV,
   TOOLCRAFT_VITEST_RUNTIME_MARKER_FILE_NAMES,
   TOOLCRAFT_VITEST_RUNTIME_MARKER_TEST_NAME,
   evaluateToolcraftVitestRuntimeEvidence,
   parseToolcraftVitestRuntimeRequirements,
+  selectToolcraftVitestRuntimeRequirements,
 } from "./toolcraft-vitest-runtime-contract.mjs";
 
 function normalizeModulePath(moduleId) {
@@ -59,15 +61,24 @@ export default class ToolcraftVitestRuntimeEvidenceReporter {
       );
     }
 
-    const requirements = marker
+    const publishedRequirements = marker
       .annotations()
       .map(parseToolcraftVitestRuntimeRequirements)
       .find(Boolean);
-    if (!requirements) {
+    if (!publishedRequirements) {
       throw new Error(
         "Toolcraft automated runtime marker did not publish valid requirements.",
       );
     }
+    const requirements = selectToolcraftVitestRuntimeRequirements(
+      publishedRequirements,
+      process.env[TOOLCRAFT_VITEST_RUNTIME_ACCEPTANCE_SELECTION_ENV],
+    );
+    if (requirements.length === 0) {
+      throw new Error(
+        "Toolcraft automated runtime coverage must select at least one runtime requirement.",
+      );
+    }
 
     const appRoot = resolveAppRoot(marker, markerFileName);
     const protectedPaths = new Set(

package/templates/starter/scripts/toolcraft-vitest-runtime-evidence-reporter.test.mjs

@@ -5,8 +5,10 @@ import path from "node:path";
 import test from "node:test";
 
 import {
+  TOOLCRAFT_VITEST_RUNTIME_ACCEPTANCE_SELECTION_ENV,
   TOOLCRAFT_VITEST_RUNTIME_MARKER_TEST_NAME,
   TOOLCRAFT_VITEST_RUNTIME_REQUIREMENTS_ANNOTATION_TYPE,
+  serializeToolcraftVitestRuntimeAcceptanceSelection,
   serializeToolcraftVitestRuntimeRequirements,
 } from "./toolcraft-vitest-runtime-contract.mjs";
 import ToolcraftVitestRuntimeEvidenceReporter, {
@@ -115,4 +117,112 @@ test("validates generated-app requirements from actual runner tasks", async (con
   await new ToolcraftVitestRuntimeEvidenceReporter().onTestRunEnd([
     createTestModule([marker, productTest]),
   ]);
+
+  const unrelatedRequirement = {
+    kind: "acceptance",
+    requirementId: "material.host",
+    testName: "keeps the baseline material extension inactive",
+  };
+  const targetedMarker = createTestTask({
+    annotations: [
+      {
+        message: serializeToolcraftVitestRuntimeRequirements([
+          requirement,
+          unrelatedRequirement,
+        ]),
+        type: TOOLCRAFT_VITEST_RUNTIME_REQUIREMENTS_ANNOTATION_TYPE,
+      },
+    ],
+    filePath: markerPath,
+    name: TOOLCRAFT_VITEST_RUNTIME_MARKER_TEST_NAME,
+  });
+  const previousSelection =
+    process.env[TOOLCRAFT_VITEST_RUNTIME_ACCEPTANCE_SELECTION_ENV];
+  context.after(() => {
+    if (previousSelection === undefined) {
+      delete process.env[TOOLCRAFT_VITEST_RUNTIME_ACCEPTANCE_SELECTION_ENV];
+    } else {
+      process.env[TOOLCRAFT_VITEST_RUNTIME_ACCEPTANCE_SELECTION_ENV] =
+        previousSelection;
+    }
+  });
+  delete process.env[TOOLCRAFT_VITEST_RUNTIME_ACCEPTANCE_SELECTION_ENV];
+  await assert.rejects(
+    new ToolcraftVitestRuntimeEvidenceReporter().onTestRunEnd([
+      createTestModule([targetedMarker, productTest]),
+    ]),
+    /Missing required automated test.*baseline material extension/iu,
+  );
+  process.env[TOOLCRAFT_VITEST_RUNTIME_ACCEPTANCE_SELECTION_ENV] =
+    serializeToolcraftVitestRuntimeAcceptanceSelection([
+      "appearance.opacity",
+    ]);
+
+  await new ToolcraftVitestRuntimeEvidenceReporter().onTestRunEnd([
+    createTestModule([targetedMarker, productTest]),
+  ]);
+
+  const sharedTestMarker = createTestTask({
+    annotations: [
+      {
+        message: serializeToolcraftVitestRuntimeRequirements([
+          requirement,
+          { ...unrelatedRequirement, testName: requirement.testName },
+        ]),
+        type: TOOLCRAFT_VITEST_RUNTIME_REQUIREMENTS_ANNOTATION_TYPE,
+      },
+    ],
+    filePath: markerPath,
+    name: TOOLCRAFT_VITEST_RUNTIME_MARKER_TEST_NAME,
+  });
+  process.env[TOOLCRAFT_VITEST_RUNTIME_ACCEPTANCE_SELECTION_ENV] =
+    serializeToolcraftVitestRuntimeAcceptanceSelection([
+      "appearance.opacity",
+      "material.host",
+    ]);
+  await new ToolcraftVitestRuntimeEvidenceReporter().onTestRunEnd([
+    createTestModule([sharedTestMarker, productTest]),
+  ]);
+
+  process.env[TOOLCRAFT_VITEST_RUNTIME_ACCEPTANCE_SELECTION_ENV] =
+    serializeToolcraftVitestRuntimeAcceptanceSelection([
+      "reference.flash-events",
+    ]);
+  await assert.rejects(
+    new ToolcraftVitestRuntimeEvidenceReporter().onTestRunEnd([
+      createTestModule([targetedMarker, productTest]),
+    ]),
+    /unknown acceptance requirement.*reference\.flash-events/iu,
+  );
+});
+
+test("full runtime evidence cannot pass with zero published requirements", async () => {
+  const marker = createTestTask({
+    annotations: [
+      {
+        message: serializeToolcraftVitestRuntimeRequirements([]),
+        type: TOOLCRAFT_VITEST_RUNTIME_REQUIREMENTS_ANNOTATION_TYPE,
+      },
+    ],
+    filePath: "/workspace/src/app/app-automated-runtime-evidence.test.ts",
+    name: TOOLCRAFT_VITEST_RUNTIME_MARKER_TEST_NAME,
+  });
+  const previousSelection =
+    process.env[TOOLCRAFT_VITEST_RUNTIME_ACCEPTANCE_SELECTION_ENV];
+  delete process.env[TOOLCRAFT_VITEST_RUNTIME_ACCEPTANCE_SELECTION_ENV];
+  try {
+    await assert.rejects(
+      new ToolcraftVitestRuntimeEvidenceReporter().onTestRunEnd([
+        createTestModule([marker]),
+      ]),
+      /at least one runtime requirement/iu,
+    );
+  } finally {
+    if (previousSelection === undefined) {
+      delete process.env[TOOLCRAFT_VITEST_RUNTIME_ACCEPTANCE_SELECTION_ENV];
+    } else {
+      process.env[TOOLCRAFT_VITEST_RUNTIME_ACCEPTANCE_SELECTION_ENV] =
+        previousSelection;
+    }
+  }
 });

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

@@ -0,0 +1,161 @@
+import type { ToolcraftArtifactExportActionRole } from "@repo/toolcraft-runtime";
+
+import type { ToolcraftArtifactExportIntent } from "./types";
+
+export type ToolcraftArtifactExportDelivery = Readonly<{
+  imageEnabled: boolean;
+  svgEnabled: boolean;
+  videoEnabled: boolean;
+}>;
+
+export type ToolcraftArtifactExportSchemaFacts = Readonly<{
+  hasImageExportAction: boolean;
+  hasImageExportSection: boolean;
+  hasSvgExportAction: boolean;
+  hasVideoExportAction: boolean;
+  hasVideoExportSection: boolean;
+}>;
+
+export type ToolcraftArtifactExportIntentValidation = Readonly<{
+  delivery: ToolcraftArtifactExportDelivery;
+  errors: readonly string[];
+}>;
+
+export function resolveToolcraftArtifactExportIntent(
+  intent: ToolcraftArtifactExportIntent,
+): ToolcraftArtifactExportDelivery {
+  return Object.freeze({
+    imageEnabled: intent.image.mode !== "user-removed",
+    svgEnabled: intent.svg.mode === "user-requested",
+    videoEnabled: intent.video.mode === "user-requested",
+  });
+}
+
+export function getToolcraftArtifactExportIntentEvidenceErrors(
+  intent: ToolcraftArtifactExportIntent,
+): readonly string[] {
+  const errors: string[] = [];
+
+  if (
+    intent.svg.mode === "user-requested" &&
+    intent.svg.evidence.trim() === ""
+  ) {
+    errors.push(
+      "SVG export user-requested intent requires non-empty evidence.",
+    );
+  }
+
+  if (
+    intent.image.mode !== "toolcraft-default" &&
+    intent.image.evidence.trim() === ""
+  ) {
+    errors.push(
+      `Image export ${intent.image.mode} intent requires non-empty evidence.`,
+    );
+  }
+
+  if (
+    intent.video.mode === "user-requested" &&
+    intent.video.evidence.trim() === ""
+  ) {
+    errors.push(
+      "Video export user-requested intent requires non-empty evidence.",
+    );
+  }
+
+  return errors;
+}
+
+type ToolcraftArtifactCorrespondenceBase = Readonly<{
+  actionRole: ToolcraftArtifactExportActionRole;
+  artifact: "Image" | "SVG" | "Video";
+  enabled: boolean;
+  hasAction: boolean;
+  intentMode:
+    | ToolcraftArtifactExportIntent["image"]["mode"]
+    | ToolcraftArtifactExportIntent["svg"]["mode"]
+    | ToolcraftArtifactExportIntent["video"]["mode"];
+}>;
+
+type ToolcraftArtifactCorrespondence = ToolcraftArtifactCorrespondenceBase &
+  (
+    | Readonly<{
+        hasSection: boolean;
+        section: Readonly<{
+          article: "a" | "an";
+          title: "Image Export" | "Video Export";
+        }>;
+      }>
+    | Readonly<{ hasSection?: never; section?: never }>
+  );
+
+function getToolcraftArtifactCorrespondenceErrors({
+  actionRole,
+  artifact,
+  enabled,
+  hasAction,
+  hasSection,
+  intentMode,
+  section,
+}: ToolcraftArtifactCorrespondence): string[] {
+  const errors: string[] = [];
+  const requirement = enabled ? "requires" : "must not have";
+
+  if (hasAction !== enabled) {
+    errors.push(
+      `${artifact} export intent "${intentMode}" ${requirement} an ${actionRole} panel action.`,
+    );
+  }
+
+  if (section && hasSection !== enabled) {
+    errors.push(
+      `${artifact} export intent "${intentMode}" ${requirement} ${section.article} "${section.title}" section.`,
+    );
+  }
+
+  return errors;
+}
+
+export function validateToolcraftArtifactExportIntentCorrespondence({
+  hasImageExportAction,
+  hasImageExportSection,
+  hasSvgExportAction,
+  hasVideoExportAction,
+  hasVideoExportSection,
+  intent,
+}: ToolcraftArtifactExportSchemaFacts &
+  Readonly<{
+    intent: ToolcraftArtifactExportIntent;
+  }>): ToolcraftArtifactExportIntentValidation {
+  const delivery = resolveToolcraftArtifactExportIntent(intent);
+  const errors = [
+    ...getToolcraftArtifactExportIntentEvidenceErrors(intent),
+    ...getToolcraftArtifactCorrespondenceErrors({
+      actionRole: "export-image",
+      artifact: "Image",
+      enabled: delivery.imageEnabled,
+      hasAction: hasImageExportAction,
+      hasSection: hasImageExportSection,
+      intentMode: intent.image.mode,
+      section: { article: "an", title: "Image Export" },
+    }),
+    ...getToolcraftArtifactCorrespondenceErrors({
+      actionRole: "export-svg",
+      artifact: "SVG",
+      enabled: delivery.svgEnabled,
+      hasAction: hasSvgExportAction,
+      intentMode: intent.svg.mode,
+    }),
+    ...getToolcraftArtifactCorrespondenceErrors({
+      actionRole: "export-video",
+      artifact: "Video",
+      enabled: delivery.videoEnabled,
+      hasAction: hasVideoExportAction,
+      hasSection: hasVideoExportSection,
+      intentMode: intent.video.mode,
+      section: { article: "a", title: "Video Export" },
+    }),
+  ];
+
+  return { delivery, errors };
+}

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

@@ -5,6 +5,7 @@ export type ToolcraftCanvasSizingCoverage =
 export type ToolcraftInfinityCanvasCoverage =
   | "mode-and-restoration"
   | "scene-bounds-image-export"
+  | "scene-bounds-svg-export"
   | "scene-bounds-video-export";
 
 export type ToolcraftRenderScaleState =

package/templates/starter/src/app/acceptance/color-bank-labels.ts

@@ -114,6 +114,15 @@ export function getToolcraftColorBankLabelErrors({
     return [];
   }
 
+  const sequentialColorControls = colorControls.filter(([, control]) =>
+    isToolcraftSequentialColorLabel(getControlLabelText(control)),
+  );
+  const errors = sequentialColorControls.map(([controlId, control]) => {
+    const label = getControlLabelText(control).trim();
+
+    return `${sectionLabel} / ${controlId} uses visible label "${label}" for one of multiple sibling colors. Set label: false when the colors form one shared bank, or use a distinct user-facing role such as Fill, Stroke, Background, Connector, or Object color.`;
+  });
+
   const loosePrefixes = new Set(
     colorControls
       .map(([, control]) => getToolcraftLooseTargetPrefix(control.target))
@@ -121,12 +130,9 @@ export function getToolcraftColorBankLabelErrors({
   );
 
   if (loosePrefixes.size !== 1) {
-    return [];
+    return errors;
   }
 
-  const sequentialColorControls = colorControls.filter(([, control]) =>
-    isToolcraftSequentialColorLabel(getControlLabelText(control)),
-  );
   const isPaletteVariationBank =
     colorControls.every(([, control]) =>
       isToolcraftPaletteVariationTarget(control.target),
@@ -135,14 +141,12 @@ export function getToolcraftColorBankLabelErrors({
       sequentialColorControls.length > 0);
 
   if (!isPaletteVariationBank) {
-    return [];
+    return errors;
   }
 
   const visibleColorControls = colorControls.filter(([, control]) =>
     hasVisibleControlLabel(control),
   );
-  const errors: string[] = [];
-
   if (
     visibleColorControls.length > 0 &&
     visibleColorControls.length < colorControls.length
@@ -152,13 +156,5 @@ export function getToolcraftColorBankLabelErrors({
     );
   }
 
-  for (const [controlId, control] of sequentialColorControls) {
-    const label = getControlLabelText(control).trim();
-
-    errors.push(
-      `${sectionLabel} / ${controlId} uses visible label "${label}" for a palette variation color. When colors only add variety to one shared palette, set label: false or use collectionActions with unlabeled items. Keep visible labels only when each color edits a distinct user-facing entity such as Fill, Stroke, Background, Connector, or Object color.`,
-    );
-  }
-
   return errors;
 }

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

@@ -0,0 +1,33 @@
+import type { ResolvedToolcraftControlSchema } from "@repo/toolcraft-runtime";
+
+export function getToolcraftColorRowGroupingErrors({
+  controls,
+  sectionLabel,
+}: {
+  controls: readonly [string, ResolvedToolcraftControlSchema][];
+  sectionLabel: string;
+}): string[] {
+  const plainColors = controls.filter(
+    ([, control]) => control.type === "color",
+  );
+  const isColorOnlySection =
+    controls.length > 0 &&
+    controls.every(
+      ([, control]) =>
+        control.type === "color" || control.type === "colorOpacity",
+    );
+
+  if (isColorOnlySection || plainColors.length < 2) {
+    return [];
+  }
+
+  const missingSemanticGroups = plainColors
+    .filter(([, control]) => !control.semanticGroup?.trim())
+    .map(([controlId]) => controlId);
+
+  return missingSemanticGroups.length === 0
+    ? []
+    : [
+        `${sectionLabel} has multiple plain Color controls in a mixed section and must declare semanticGroup for every plain Color so runtime rows follow product meaning instead of schema adjacency. Missing: ${missingSemanticGroups.join(", ")}.`,
+      ];
+}

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

@@ -26,7 +26,7 @@ export function getConditionValidationErrors({
   label,
 }: {
   condition: ToolcraftControlConditionSchema;
-  conditionName: "disabledWhen" | "visibleWhen";
+  conditionName: "disabledWhen";
   controlTargets: ReadonlySet<string>;
   label: string;
 }): string[] {

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

@@ -1,6 +1,6 @@
 import type {
   ResolvedToolcraftAppSchema,
-  ToolcraftControlSchema,
+  ResolvedToolcraftControlSchema,
   ToolcraftTimelineMode,
 } from "@repo/toolcraft-runtime";
 
@@ -21,7 +21,7 @@ export type ToolcraftControlAcceptanceContext = {
 };
 
 export type ToolcraftControlRuleContext = {
-  control: ToolcraftControlSchema;
+  control: ResolvedToolcraftControlSchema;
   controlId: string;
   controlTargets: ReadonlySet<string>;
   label: string;