@pixel-point/toolcraft 0.0.18 → 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

@@ -1,13 +1,17 @@
+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;
 }>;
@@ -22,6 +26,7 @@ export function resolveToolcraftArtifactExportIntent(
 ): ToolcraftArtifactExportDelivery {
   return Object.freeze({
     imageEnabled: intent.image.mode !== "user-removed",
+    svgEnabled: intent.svg.mode === "user-requested",
     videoEnabled: intent.video.mode === "user-requested",
   });
 }
@@ -31,6 +36,15 @@ export function getToolcraftArtifactExportIntentEvidenceErrors(
 ): 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() === ""
@@ -52,6 +66,29 @@ export function getToolcraftArtifactExportIntentEvidenceErrors(
   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,
@@ -59,20 +96,8 @@ function getToolcraftArtifactCorrespondenceErrors({
   hasAction,
   hasSection,
   intentMode,
-  sectionArticle,
-  sectionTitle,
-}: Readonly<{
-  actionRole: "export-image" | "export-video";
-  artifact: "Image" | "Video";
-  enabled: boolean;
-  hasAction: boolean;
-  hasSection: boolean;
-  intentMode:
-    | ToolcraftArtifactExportIntent["image"]["mode"]
-    | ToolcraftArtifactExportIntent["video"]["mode"];
-  sectionArticle: "a" | "an";
-  sectionTitle: "Image Export" | "Video Export";
-}>): string[] {
+  section,
+}: ToolcraftArtifactCorrespondence): string[] {
   const errors: string[] = [];
   const requirement = enabled ? "requires" : "must not have";
 
@@ -82,9 +107,9 @@ function getToolcraftArtifactCorrespondenceErrors({
     );
   }
 
-  if (hasSection !== enabled) {
+  if (section && hasSection !== enabled) {
     errors.push(
-      `${artifact} export intent "${intentMode}" ${requirement} ${sectionArticle} "${sectionTitle}" section.`,
+      `${artifact} export intent "${intentMode}" ${requirement} ${section.article} "${section.title}" section.`,
     );
   }
 
@@ -94,6 +119,7 @@ function getToolcraftArtifactCorrespondenceErrors({
 export function validateToolcraftArtifactExportIntentCorrespondence({
   hasImageExportAction,
   hasImageExportSection,
+  hasSvgExportAction,
   hasVideoExportAction,
   hasVideoExportSection,
   intent,
@@ -111,8 +137,14 @@ export function validateToolcraftArtifactExportIntentCorrespondence({
       hasAction: hasImageExportAction,
       hasSection: hasImageExportSection,
       intentMode: intent.image.mode,
-      sectionArticle: "an",
-      sectionTitle: "Image Export",
+      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",
@@ -121,8 +153,7 @@ export function validateToolcraftArtifactExportIntentCorrespondence({
       hasAction: hasVideoExportAction,
       hasSection: hasVideoExportSection,
       intentMode: intent.video.mode,
-      sectionArticle: "a",
-      sectionTitle: "Video Export",
+      section: { article: "a", title: "Video Export" },
     }),
   ];
 

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/control-acceptance-coverage.ts

@@ -222,7 +222,6 @@ function getControlPartAndRuntimeCoverageErrors({
 }): string[] {
   const errors: string[] = [];
   const keyframeCapability = getToolcraftControlKeyframeCapability(control);
-  const isSelectedLayerTarget = control.target.startsWith("selectedLayer.");
   const requiredControlParts = getRequiredToolcraftControlPartCoverage(control);
 
   if (
@@ -241,16 +240,6 @@ function getControlPartAndRuntimeCoverageErrors({
     }
   }
 
-  if (
-    isSelectedLayerTarget &&
-    layersEnabled &&
-    entry.layerCoverage !== "selected-layer-controls"
-  ) {
-    errors.push(
-      `${label} targets selectedLayer.* and must have acceptance layerCoverage "selected-layer-controls" proving the control edits the currently selected layer output.`,
-    );
-  }
-
   return errors;
 }
 

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

@@ -18,13 +18,12 @@ function getControlComponentPolicyErrors({
   control,
   controlId,
   label,
-  sectionTitle,
 }: Pick<
   ToolcraftControlRuleContext,
-  "control" | "controlId" | "label" | "sectionTitle"
+  "control" | "controlId" | "label"
 >): string[] {
   const errors: string[] = [];
-  const toggleLabelError = getToggleControlLabelError(control, sectionTitle);
+  const toggleLabelError = getToggleControlLabelError(control);
   const singleActionsLabelError = getSingleActionsControlLabelError(control);
   const codeTextareaError = getCodeTextareaControlError({
     control,

package/templates/starter/src/app/acceptance/control-component-rules.ts

@@ -168,7 +168,6 @@ export function getCurveIntentError(
 
 export function getToggleControlLabelError(
   control: ToolcraftControlSchema,
-  sectionTitle?: string,
 ): string | undefined {
   if (control.type !== "switch" && control.type !== "checkbox") {
     return undefined;
@@ -180,15 +179,6 @@ export function getToggleControlLabelError(
     return `toggle labels must name the setting context only; use "CRT", "Background", "Glow", or "Loop" instead of "${label}".`;
   }
 
-  if (
-    label &&
-    sectionTitle &&
-    normalizeToolcraftSemanticText(label) ===
-      normalizeToolcraftSemanticText(sectionTitle)
-  ) {
-    return `toggle label "${label}" duplicates section title "${sectionTitle}". Use a shorter contextual label such as "Include" or rename the toggle to a more specific setting.`;
-  }
-
   return undefined;
 }
 

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

@@ -1,6 +1,9 @@
 import type { ToolcraftControlSchema } from "@repo/toolcraft-runtime";
 
-import { getControlLabelText } from "./controls";
+import {
+  getControlLabelText,
+  hasVisibleControlLabel,
+} from "./controls";
 import {
   getToolcraftLooseTargetPrefix,
   getToolcraftTargetParts,
@@ -157,6 +160,32 @@ export function getToolcraftFontPickerOwnedTypographyPart(
   return undefined;
 }
 
+export function getToolcraftDuplicateSectionTitleLabelError({
+  control,
+  controlId,
+  sectionLabel,
+  sectionTitle,
+}: {
+  control: ToolcraftControlSchema;
+  controlId: string;
+  sectionLabel: string;
+  sectionTitle: string | undefined;
+}): string | undefined {
+  if (
+    control.type === "tabs" ||
+    !sectionTitle ||
+    !hasVisibleControlLabel(control) ||
+    normalizeToolcraftSemanticText(getControlLabelText(control)) !==
+      normalizeToolcraftSemanticText(sectionTitle)
+  ) {
+    return undefined;
+  }
+
+  const label = getControlLabelText(control).trim();
+
+  return `${sectionLabel} / ${controlId} visible label "${label}" duplicates section title "${sectionTitle}". Set label: false when the section supplies the complete visible context, or use a more specific label for a distinct setting.`;
+}
+
 export function getToolcraftGenericControlLabelError({
   control,
   controlId,