@pixel-point/toolcraft 0.0.2

package/templates/runtime/testing/performance.test.ts

@@ -0,0 +1,1058 @@
+import { describe, expect, it } from "vitest";
+
+import { defineToolcraft } from "../schema/define-toolcraft";
+import {
+  collectToolcraftPerformanceSensitiveControls,
+  collectToolcraftUnclassifiedPerformanceControls,
+  defineToolcraftPerformance,
+  validateToolcraftPerformanceCoverage,
+} from "./performance";
+
+const testSchema = defineToolcraft({
+  canvas: {
+    enabled: true,
+    sizing: { mode: "intrinsic-media" },
+  },
+  panels: {
+    controls: {
+      sections: [
+        {
+          controls: {
+            density: {
+              defaultValue: 4,
+              label: "Density",
+              max: 12,
+              min: 1,
+              performanceReason: "Density changes the amount of rendered output.",
+              performanceRole: "workload",
+              target: "render.density",
+              type: "slider",
+            },
+            mode: {
+              defaultValue: "soft",
+              label: "Mode",
+              options: [
+                { label: "Soft", value: "soft" },
+                { label: "Sharp", value: "sharp" },
+              ],
+              performanceReason: "Mode changes rendering branches but not workload size.",
+              performanceRole: "responsiveness",
+              target: "render.mode",
+              type: "select",
+            },
+          },
+        },
+      ],
+      title: "Runtime Controls",
+    },
+  },
+});
+
+const ordinarySliderSchema = defineToolcraft({
+  canvas: {
+    enabled: true,
+    sizing: { mode: "intrinsic-media" },
+  },
+  panels: {
+    controls: {
+      sections: [
+        {
+          controls: {
+            opacity: {
+              defaultValue: 50,
+              label: "Opacity",
+              max: 100,
+              min: 0,
+              performanceReason: "Opacity changes a lightweight uniform value.",
+              performanceRole: "responsiveness",
+              target: "render.opacity",
+              type: "slider",
+            },
+          },
+        },
+      ],
+      title: "Runtime Controls",
+    },
+  },
+});
+
+const largeTextSchema = defineToolcraft({
+  canvas: {
+    enabled: true,
+    sizing: { mode: "intrinsic-media" },
+  },
+  panels: {
+    controls: {
+      sections: [
+        {
+          controls: {
+            content: {
+              defaultValue: "",
+              label: "Content",
+              performanceReason: "Content length changes text layout and renderer workload.",
+              performanceRole: "workload",
+              target: "product.content",
+              type: "code",
+            },
+          },
+        },
+      ],
+      title: "Runtime Controls",
+    },
+  },
+});
+
+function createViewportZoomStressScenario() {
+  return {
+    automated: true,
+    automatedTestName: "perf: detailed canvas zoom stays smooth",
+    browser: true,
+    browserTestName: "browser perf: detailed canvas zoom stays smooth",
+    budget: { maxFrameGapMs: 80, maxInteractionMs: 500, maxLongTaskMs: 80 },
+    expectedObservable:
+      "Zooming detailed product output does not shake the canvas or block frames.",
+    fixture: "detailed renderer zoom fixture",
+    id: "viewport-zoom-stress",
+    interaction: "viewport-zoom-stress" as const,
+    stress: true,
+    target: "canvas.viewport",
+    workload: false,
+  };
+}
+
+function createMaxValueStressFixture(value: unknown, reason = "Maximum workload value.") {
+  return {
+    kind: "max-value" as const,
+    reason,
+    value,
+  };
+}
+
+function createLargeTextStressValue(): string {
+  return Array.from(
+    { length: 1_000 },
+    (_, index) =>
+      `Line ${String(index + 1).padStart(4, "0")} performance stress text with enough glyphs to exercise layout.`,
+  ).join("\n");
+}
+
+function createLargeTextStressFixture() {
+  return {
+    kind: "large-text" as const,
+    minChars: 50_000,
+    minLines: 1_000,
+    reason: "Long multiline content is the heaviest realistic text workload.",
+    value: createLargeTextStressValue(),
+  };
+}
+
+function createTextRendererScenarios(
+  options: { includeStressPreview?: boolean; includeViewportZoomStress?: boolean } = {},
+) {
+  const includeStressPreview = options.includeStressPreview ?? true;
+  const includeViewportZoomStress = options.includeViewportZoomStress ?? true;
+
+  return [
+    {
+      automated: true,
+      automatedTestName: "perf: text preview render stays under budget",
+      browser: true,
+      browserTestName: "browser perf: text preview render stays under budget",
+      budget: { maxLongTaskMs: 80, maxPreviewMs: 1000 },
+      expectedObservable: "Text preview renders crisply without freezing.",
+      fixture: "native-resolution glyph output fixture",
+      id: "text-preview-render",
+      interaction: "preview-render" as const,
+      stress: includeStressPreview,
+      workload: false,
+    },
+    {
+      automated: true,
+      automatedTestName: "perf: density drag stays responsive",
+      browser: true,
+      browserTestName: "browser perf: density drag stays responsive",
+      budget: { maxFrameGapMs: 80, maxInteractionMs: 500 },
+      controlLabel: "Density",
+      expectedObservable: "Dragging Density updates text output without blocking the UI.",
+      fixture: "runtime density fixture",
+      id: "density-drag",
+      interaction: "control-drag" as const,
+      stressFixture: createMaxValueStressFixture(
+        12,
+        "Density max is the heaviest glyph output fixture.",
+      ),
+      target: "render.density",
+      values: { default: 4, max: 12, min: 1 },
+      workload: true,
+    },
+    {
+      automated: true,
+      automatedTestName: "perf: mode change stays responsive",
+      browser: true,
+      browserTestName: "browser perf: mode change stays responsive",
+      budget: { maxFrameGapMs: 80, maxInteractionMs: 500 },
+      controlLabel: "Mode",
+      expectedObservable: "Changing Mode updates text output without blocking the UI.",
+      fixture: "runtime mode fixture",
+      id: "mode-change",
+      interaction: "control-change" as const,
+      target: "render.mode",
+      values: { default: "soft", max: "sharp", min: "soft" },
+      workload: false,
+    },
+    {
+      automated: true,
+      automatedTestName: "perf: viewport stays stable",
+      browser: true,
+      browserTestName: "browser perf: viewport stays stable",
+      budget: { maxFrameGapMs: 80 },
+      expectedObservable: "Viewport remains stable.",
+      fixture: "native-resolution glyph output fixture",
+      id: "viewport-stability",
+      interaction: "viewport-stability" as const,
+      workload: false,
+    },
+    ...(includeViewportZoomStress ? [createViewportZoomStressScenario()] : []),
+  ];
+}
+
+function createAnimationFrameScenario() {
+  return {
+    automated: true,
+    automatedTestName: "perf: animation frame loop stays smooth",
+    browser: true,
+    browserTestName: "browser perf: animation frame loop stays smooth",
+    budget: { maxFrameGapMs: 80, maxLongTaskMs: 80 },
+    expectedObservable: "Animated renderer advances without long frame gaps.",
+    fixture: "animated renderer fixture",
+    id: "animation-frame-loop",
+    interaction: "animation-frame" as const,
+    stress: true,
+    workload: false,
+  };
+}
+
+function createAnimationViewportDragScenario() {
+  return {
+    automated: true,
+    automatedTestName: "perf: animated canvas drag stays smooth",
+    browser: true,
+    browserTestName: "browser perf: animated canvas drag stays smooth",
+    budget: { maxFrameGapMs: 80, maxInteractionMs: 500, maxLongTaskMs: 80 },
+    expectedObservable: "Animated renderer stays smooth while the canvas viewport is dragged.",
+    fixture: "animated renderer canvas drag fixture",
+    id: "animation-viewport-drag",
+    interaction: "animation-viewport-drag" as const,
+    stress: true,
+    target: "canvas.viewport",
+    workload: false,
+  };
+}
+
+function createAnimatedVectorRendererConfig(options: { includeViewportDrag: boolean }) {
+  return defineToolcraftPerformance({
+    rendererStrategy: "svg",
+    rendererTechnique: {
+      exportRenderer: "svg",
+      fidelityRisks: ["animated vector output must stay crisp while panning"],
+      performanceRisks: ["dense vector animation can jank while the viewport moves"],
+      previewRenderer: "svg",
+      productRepresentation: "vector",
+      rendererStrategy: "svg",
+      rendererWorkload: "vector-output",
+      sourceRepresentation: "procedural-data",
+      whyNotAlternativeStrategies: ["svg preserves semantic vector output for this fixture"],
+    },
+    rendererWorkload: "vector-output",
+    scenarios: [
+      ...createTextRendererScenarios(),
+      createAnimationFrameScenario(),
+      ...(options.includeViewportDrag ? [createAnimationViewportDragScenario()] : []),
+    ],
+    usesCustomRenderer: true,
+    workloadTargets: ["render.density"],
+  });
+}
+
+describe("Toolcraft template performance contract", () => {
+  it("collects performance-sensitive controls from schema", () => {
+    expect(collectToolcraftPerformanceSensitiveControls(testSchema)).toEqual([
+      expect.objectContaining({
+        controlId: "density",
+        target: "render.density",
+      }),
+    ]);
+  });
+
+  it("does not classify every slider as workload-sensitive", () => {
+    expect(collectToolcraftPerformanceSensitiveControls(ordinarySliderSchema)).toEqual([]);
+  });
+
+  it("collects explicit workload controls even when labels do not match fallback keywords", () => {
+    const explicitWorkloadSchema = defineToolcraft({
+      canvas: {
+        enabled: true,
+        sizing: { mode: "intrinsic-media" },
+      },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                complexity: {
+                  defaultValue: 4,
+                  label: "Complexity",
+                  max: 12,
+                  min: 1,
+                  performanceReason: "Complexity changes the number of render passes.",
+                  performanceRole: "workload",
+                  target: "render.complexity",
+                  type: "slider",
+                },
+              },
+            },
+          ],
+          title: "Runtime Controls",
+        },
+      },
+    });
+
+    expect(collectToolcraftPerformanceSensitiveControls(explicitWorkloadSchema)).toEqual([
+      expect.objectContaining({
+        controlId: "complexity",
+        target: "render.complexity",
+      }),
+    ]);
+  });
+
+  it("collects visible controls without explicit performance classification", () => {
+    const unclassifiedSchema = defineToolcraft({
+      canvas: {
+        enabled: true,
+        sizing: { mode: "intrinsic-media" },
+      },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                mode: {
+                  defaultValue: "soft",
+                  label: "Mode",
+                  options: [
+                    { label: "Soft", value: "soft" },
+                    { label: "Sharp", value: "sharp" },
+                  ],
+                  target: "render.mode",
+                  type: "select",
+                },
+              },
+            },
+          ],
+          title: "Runtime Controls",
+        },
+      },
+    });
+
+    expect(collectToolcraftUnclassifiedPerformanceControls(unclassifiedSchema)).toEqual([
+      expect.objectContaining({
+        controlId: "mode",
+        target: "render.mode",
+      }),
+    ]);
+  });
+
+  it("allows ordinary sliders to use lightweight responsiveness coverage", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "none",
+      rendererWorkload: "none",
+      scenarios: [
+        {
+          automated: true,
+          automatedTestName: "perf: opacity drag stays responsive",
+          browser: true,
+          browserTestName: "browser perf: opacity drag stays responsive",
+          budget: { maxFrameGapMs: 80, maxInteractionMs: 500 },
+          controlLabel: "Opacity",
+          expectedObservable: "Dragging Opacity stays responsive.",
+          fixture: "opacity responsiveness fixture",
+          id: "opacity-drag",
+          interaction: "control-drag",
+          target: "render.opacity",
+          workload: false,
+        },
+      ],
+      usesCustomRenderer: false,
+      workloadTargets: [],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(ordinarySliderSchema, config)).toEqual([]);
+  });
+
+  it("requires performance-sensitive controls to be listed in workloadTargets", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "none",
+      rendererWorkload: "none",
+      scenarios: [
+        {
+          automated: true,
+          automatedTestName: "perf: density drag stays responsive",
+          browser: true,
+          browserTestName: "browser perf: density drag stays responsive",
+          budget: { maxFrameGapMs: 80, maxInteractionMs: 500 },
+          controlLabel: "Density",
+          expectedObservable: "Dragging Density stays responsive.",
+          fixture: "runtime density fixture",
+          id: "density-drag",
+          interaction: "control-drag",
+          target: "render.density",
+          workload: false,
+        },
+        {
+          automated: true,
+          automatedTestName: "perf: mode change stays responsive",
+          browser: true,
+          browserTestName: "browser perf: mode change stays responsive",
+          budget: { maxFrameGapMs: 80, maxInteractionMs: 500 },
+          controlLabel: "Mode",
+          expectedObservable: "Changing Mode updates the product without blocking the UI.",
+          fixture: "runtime mode fixture",
+          id: "mode-change",
+          interaction: "control-change",
+          target: "render.mode",
+          values: { default: "soft", max: "sharp", min: "soft" },
+          workload: false,
+        },
+      ],
+      usesCustomRenderer: false,
+      workloadTargets: [],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toContain(
+      "render.density is performance-sensitive and must be listed in workloadTargets with min/default/max workload coverage.",
+    );
+  });
+
+  it("rejects responsiveness role on semantically workload controls", () => {
+    const misclassifiedSchema = defineToolcraft({
+      canvas: {
+        enabled: true,
+        sizing: { mode: "intrinsic-media" },
+      },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                density: {
+                  defaultValue: 4,
+                  label: "Density",
+                  max: 12,
+                  min: 1,
+                  performanceReason: "AI incorrectly treated density as lightweight.",
+                  performanceRole: "responsiveness",
+                  target: "render.density",
+                  type: "slider",
+                },
+              },
+            },
+          ],
+          title: "Runtime Controls",
+        },
+      },
+    });
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "none",
+      rendererWorkload: "none",
+      scenarios: [
+        {
+          automated: true,
+          automatedTestName: "perf: density drag stays responsive",
+          browser: true,
+          browserTestName: "browser perf: density drag stays responsive",
+          budget: { maxFrameGapMs: 80, maxInteractionMs: 500 },
+          controlLabel: "Density",
+          expectedObservable: "Dragging Density updates the product without blocking the UI.",
+          fixture: "runtime density fixture",
+          id: "density-drag",
+          interaction: "control-drag",
+          target: "render.density",
+          values: { default: 4, max: 12, min: 1 },
+          workload: false,
+        },
+      ],
+      usesCustomRenderer: false,
+      workloadTargets: [],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(misclassifiedSchema, config)).toEqual(
+      expect.arrayContaining([
+        'density (render.density) looks performance-sensitive but declares performanceRole "responsiveness". Use performanceRole "workload" with workloadTargets and min/default/max coverage, or rename/restructure the control if it is truly lightweight.',
+        "render.density is performance-sensitive and must be listed in workloadTargets with min/default/max workload coverage.",
+      ]),
+    );
+  });
+
+  it("validates coverage without app-local helper defaults", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "none",
+      rendererWorkload: "none",
+      scenarios: [
+        {
+          automated: true,
+          automatedTestName: "perf: density drag stays responsive",
+          browser: true,
+          browserTestName: "browser perf: density drag stays responsive",
+          budget: { maxFrameGapMs: 80, maxInteractionMs: 500 },
+          controlLabel: "Density",
+          expectedObservable: "Dragging Density updates the product without blocking the UI.",
+          fixture: "runtime density fixture",
+          id: "density-drag",
+          interaction: "control-drag",
+          stressFixture: createMaxValueStressFixture(
+            12,
+            "Density max is the heaviest rendered output fixture.",
+          ),
+          target: "render.density",
+          values: { default: 4, max: 12, min: 1 },
+          workload: true,
+        },
+        {
+          automated: true,
+          automatedTestName: "perf: mode change stays responsive",
+          browser: true,
+          browserTestName: "browser perf: mode change stays responsive",
+          budget: { maxFrameGapMs: 80, maxInteractionMs: 500 },
+          controlLabel: "Mode",
+          expectedObservable: "Changing Mode updates the product without blocking the UI.",
+          fixture: "runtime mode fixture",
+          id: "mode-change",
+          interaction: "control-change",
+          target: "render.mode",
+          values: { default: "soft", max: "sharp", min: "soft" },
+          workload: false,
+        },
+      ],
+      usesCustomRenderer: false,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toEqual([]);
+  });
+
+  it("requires workload scenarios to declare a reusable stress fixture", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "none",
+      rendererWorkload: "none",
+      scenarios: [
+        {
+          automated: true,
+          automatedTestName: "perf: content input stays responsive",
+          browser: true,
+          browserTestName: "browser perf: content input stays responsive",
+          budget: { maxFrameGapMs: 80, maxInteractionMs: 500 },
+          controlLabel: "Content",
+          expectedObservable: "Large text content updates without blocking the UI.",
+          fixture: "large text content fixture",
+          id: "content-change",
+          interaction: "control-change",
+          target: "product.content",
+          values: { default: "", max: createLargeTextStressValue(), min: "" },
+          workload: true,
+        },
+      ],
+      usesCustomRenderer: false,
+      workloadTargets: ["product.content"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(largeTextSchema, config)).toContain(
+      "content-change workload scenario must declare stressFixture with the real heaviest value used by browser performance tests.",
+    );
+  });
+
+  it("rejects short stress fixtures for large text workload scenarios", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "none",
+      rendererWorkload: "none",
+      scenarios: [
+        {
+          automated: true,
+          automatedTestName: "perf: content input stays responsive",
+          browser: true,
+          browserTestName: "browser perf: content input stays responsive",
+          budget: { maxFrameGapMs: 80, maxInteractionMs: 500 },
+          controlLabel: "Content",
+          expectedObservable: "Large text content updates without blocking the UI.",
+          fixture: "large text content fixture",
+          id: "content-change",
+          interaction: "control-change",
+          stressFixture: {
+            kind: "large-text",
+            minChars: 50_000,
+            minLines: 1_000,
+            reason: "Long multiline content is the heaviest realistic text workload.",
+            value: "short text",
+          },
+          target: "product.content",
+          values: { default: "", max: "short text", min: "" },
+          workload: true,
+        },
+      ],
+      usesCustomRenderer: false,
+      workloadTargets: ["product.content"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(largeTextSchema, config)).toEqual(
+      expect.arrayContaining([
+        "content-change large-text stressFixture.value must contain at least 50000 characters.",
+        "content-change large-text stressFixture.value must contain at least 1000 lines.",
+      ]),
+    );
+  });
+
+  it("accepts large text workload scenarios with machine-checkable stress fixtures", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "none",
+      rendererWorkload: "none",
+      scenarios: [
+        {
+          automated: true,
+          automatedTestName: "perf: content input stays responsive",
+          browser: true,
+          browserTestName: "browser perf: content input stays responsive",
+          budget: { maxFrameGapMs: 80, maxInteractionMs: 500 },
+          controlLabel: "Content",
+          expectedObservable: "Large text content updates without blocking the UI.",
+          fixture: "large text content fixture",
+          id: "content-change",
+          interaction: "control-change",
+          stressFixture: createLargeTextStressFixture(),
+          target: "product.content",
+          values: { default: "", max: createLargeTextStressValue(), min: "" },
+          workload: true,
+        },
+      ],
+      usesCustomRenderer: false,
+      workloadTargets: ["product.content"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(largeTextSchema, config)).toEqual([]);
+  });
+
+  it("rejects visible controls without performance scenarios", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "none",
+      rendererWorkload: "none",
+      scenarios: [
+        {
+          automated: true,
+          automatedTestName: "perf: density drag stays responsive",
+          browser: true,
+          browserTestName: "browser perf: density drag stays responsive",
+          budget: { maxFrameGapMs: 80, maxInteractionMs: 500 },
+          controlLabel: "Density",
+          expectedObservable: "Dragging Density updates the product without blocking the UI.",
+          fixture: "runtime density fixture",
+          id: "density-drag",
+          interaction: "control-drag",
+          target: "render.density",
+          values: { default: 4, max: 12, min: 1 },
+          workload: true,
+        },
+      ],
+      usesCustomRenderer: false,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toContain(
+      "render.mode must have a performance scenario because every visible control can affect app responsiveness.",
+    );
+  });
+
+  it("allows text-output renderers without forcing a GPU strategy", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "canvas-2d",
+      rendererTechnique: {
+        exportRenderer: "canvas-2d",
+        fidelityRisks: ["glyph metrics must stay crisp at product output size"],
+        performanceRisks: ["large glyph grids can be expensive during drag"],
+        previewRenderer: "canvas-2d",
+        productRepresentation: "text",
+        rendererStrategy: "canvas-2d",
+        rendererWorkload: "text-output",
+        sourceRepresentation: "dom-text",
+        whyNotAlternativeStrategies: ["webgl texture output would rasterize text too early"],
+      },
+      rendererWorkload: "text-output",
+      scenarios: createTextRendererScenarios(),
+      usesCustomRenderer: true,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toEqual([]);
+  });
+
+  it("requires animated custom renderers to test viewport dragging during animation", () => {
+    const config = createAnimatedVectorRendererConfig({ includeViewportDrag: false });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toContain(
+      "Animated custom renderers must include an animation-viewport-drag performance scenario that samples frames while physically moving the canvas viewport.",
+    );
+  });
+
+  it("requires detail-heavy custom renderers to test real viewport zoom stress", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "canvas-2d",
+      rendererTechnique: {
+        exportRenderer: "canvas-2d",
+        fidelityRisks: ["glyph metrics must stay crisp at product output size"],
+        performanceRisks: ["large glyph grids can shake or jank during canvas zoom"],
+        previewRenderer: "canvas-2d",
+        productRepresentation: "text",
+        rendererStrategy: "canvas-2d",
+        rendererWorkload: "text-output",
+        sourceRepresentation: "dom-text",
+        whyNotAlternativeStrategies: ["webgl texture output would rasterize text too early"],
+      },
+      rendererWorkload: "text-output",
+      scenarios: createTextRendererScenarios({ includeViewportZoomStress: false }),
+      usesCustomRenderer: true,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toContain(
+      "Detail-heavy or animated custom renderers must include a viewport-zoom-stress performance scenario that uses real zoom controls while sampling frame gaps and long tasks.",
+    );
+  });
+
+  it("requires detail-heavy custom renderers to prove worst-case preview or animation stress", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "canvas-2d",
+      rendererTechnique: {
+        exportRenderer: "canvas-2d",
+        fidelityRisks: ["dense texture output must stay visually stable"],
+        layers: [
+          {
+            content: ["dense-pattern"],
+            exportMode: "included",
+            id: "dense-pattern",
+            kind: "product-foreground",
+            primitiveCount: "high",
+            renderer: "canvas-2d",
+            uiSelector: '[data-toolcraft-renderer-layer="dense-pattern"]',
+          },
+          {
+            content: ["geometry"],
+            exportMode: "included",
+            id: "foreground-geometry",
+            kind: "product-foreground",
+            primitiveCount: "low",
+            renderer: "svg",
+            uiSelector: '[data-toolcraft-renderer-layer="foreground-geometry"]',
+          },
+        ],
+        performanceRisks: ["maximum density may overload the renderer"],
+        previewRenderer: "canvas-2d",
+        productRepresentation: "mixed",
+        rendererStrategy: "canvas-2d",
+        rendererWorkload: "simple-composition",
+        sourceRepresentation: "procedural-data",
+        whyNotAlternativeStrategies: ["canvas is simple"],
+      },
+      rendererWorkload: "simple-composition",
+      scenarios: createTextRendererScenarios({ includeStressPreview: false }),
+      usesCustomRenderer: true,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toEqual(
+      expect.arrayContaining([
+        "Detail-heavy custom renderers must include a stress preview-render or animation-frame scenario for the largest product canvas and heaviest workload values.",
+      ]),
+    );
+  });
+
+  it("requires high-count Canvas 2D semantic or dense layers to carry measurable stress evidence", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "canvas-2d",
+      rendererTechnique: {
+        exportRenderer: "canvas-2d",
+        fidelityRisks: ["glyphs must stay legible"],
+        layers: [
+          {
+            content: ["text", "dense-pattern"],
+            exportMode: "included",
+            id: "dense-text-field",
+            intentionalRasterizationReason:
+              "The product exports raster video and PNG, so text is drawn into one canvas frame.",
+            kind: "product-foreground",
+            primitiveCount: "high",
+            renderer: "canvas-2d",
+            uiSelector: '[data-toolcraft-renderer-layer="dense-text-field"]',
+          },
+        ],
+        performanceRisks: ["maximum density may redraw many text runs per frame"],
+        previewRenderer: "canvas-2d",
+        productRepresentation: "text",
+        rendererStrategy: "canvas-2d",
+        rendererWorkload: "text-output",
+        sourceRepresentation: "dom-text",
+        whyNotAlternativeStrategies: ["webgl texture output would rasterize text too early"],
+      },
+      rendererWorkload: "text-output",
+      scenarios: createTextRendererScenarios({ includeStressPreview: false }),
+      usesCustomRenderer: true,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toEqual(
+      expect.arrayContaining([
+        "High-count Canvas 2D renderer layers must include stress preview-render or animation-frame evidence before delivery. If that stress evidence fails, revise renderer strategy instead of only lowering product workload.",
+      ]),
+    );
+  });
+
+  it("accepts animated custom renderers with stress coverage while dragging the viewport", () => {
+    const config = createAnimatedVectorRendererConfig({ includeViewportDrag: true });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toEqual([]);
+  });
+
+  it("requires custom renderers to declare typed renderer technique metadata", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "canvas-2d",
+      rendererWorkload: "text-output",
+      scenarios: createTextRendererScenarios(),
+      usesCustomRenderer: true,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toEqual(
+      expect.arrayContaining([
+        "Custom renderers must declare rendererTechnique so renderer choice is machine-checkable.",
+      ]),
+    );
+  });
+
+  it("rejects renderer technique mismatches and missing explanations", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "canvas-2d",
+      rendererTechnique: {
+        exportRenderer: "webgl",
+        fidelityRisks: [],
+        performanceRisks: [],
+        previewRenderer: "canvas-2d",
+        productRepresentation: "text",
+        rendererStrategy: "webgl",
+        rendererWorkload: "pixel-output",
+        sourceRepresentation: "reference-runtime",
+        whyNotAlternativeStrategies: [],
+      },
+      rendererWorkload: "text-output",
+      scenarios: createTextRendererScenarios(),
+      usesCustomRenderer: true,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toEqual(
+      expect.arrayContaining([
+        'rendererTechnique.rendererWorkload "pixel-output" must match rendererWorkload "text-output".',
+        'rendererTechnique.rendererStrategy "webgl" must match rendererStrategy "canvas-2d".',
+        "Custom renderer technique must explain why alternative renderer strategies were rejected.",
+        "Custom renderer technique must list fidelity risks.",
+        "Custom renderer technique must list performance risks.",
+        'productRepresentation "text" requires rendererWorkload "text-output" unless intentionalRasterizationReason is provided.',
+        "Different preview/export renderers require previewExportDifferenceReason.",
+        "Reference runtime renderer changes require referenceRendererChangeReason.",
+      ]),
+    );
+  });
+
+  it("allows dense raster backgrounds with semantic svg foreground layers", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "canvas-2d",
+      rendererTechnique: {
+        exportRenderer: "canvas-2d",
+        fidelityRisks: ["export composite must preserve foreground line and text edges"],
+        layers: [
+          {
+            content: ["dense-pattern"],
+            exportMode: "included",
+            id: "dot-grid-background",
+            kind: "background",
+            primitiveCount: "high",
+            renderer: "canvas-2d",
+          },
+          {
+            content: ["geometry", "text"],
+            exportMode: "included",
+            id: "semantic-foreground",
+            kind: "product-foreground",
+            primitiveCount: "low",
+            renderer: "svg",
+            uiSelector: '[data-toolcraft-renderer-layer="semantic-foreground"]',
+          },
+          {
+            content: ["composite"],
+            exportMode: "composited",
+            id: "png-export",
+            kind: "export-composite",
+            primitiveCount: "low",
+            renderer: "canvas-2d",
+          },
+        ],
+        performanceRisks: ["dense background redraw can be expensive at large output size"],
+        previewRenderer: "canvas-2d",
+        productRepresentation: "mixed",
+        rendererStrategy: "canvas-2d",
+        rendererWorkload: "simple-composition",
+        sourceRepresentation: "procedural-data",
+        whyNotAlternativeStrategies: [
+          "rendering thousands of background dots as DOM nodes would be expensive",
+        ],
+      },
+      rendererWorkload: "simple-composition",
+      scenarios: createTextRendererScenarios(),
+      usesCustomRenderer: true,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toEqual([]);
+  });
+
+  it("rejects canvas rasterization of low-count semantic foreground without a reason", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "canvas-2d",
+      rendererTechnique: {
+        exportRenderer: "canvas-2d",
+        fidelityRisks: ["foreground line edges can become soft"],
+        layers: [
+          {
+            content: ["dense-pattern"],
+            exportMode: "included",
+            id: "dot-grid-background",
+            kind: "background",
+            primitiveCount: "high",
+            renderer: "canvas-2d",
+          },
+          {
+            content: ["geometry", "text"],
+            exportMode: "included",
+            id: "semantic-foreground",
+            kind: "product-foreground",
+            primitiveCount: "low",
+            renderer: "canvas-2d",
+          },
+        ],
+        performanceRisks: ["background redraw can be expensive"],
+        previewRenderer: "canvas-2d",
+        productRepresentation: "mixed",
+        rendererStrategy: "canvas-2d",
+        rendererWorkload: "simple-composition",
+        sourceRepresentation: "procedural-data",
+        whyNotAlternativeStrategies: ["canvas is convenient"],
+      },
+      rendererWorkload: "simple-composition",
+      scenarios: createTextRendererScenarios(),
+      usesCustomRenderer: true,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toEqual(
+      expect.arrayContaining([
+        'rendererTechnique layer "semantic-foreground" uses canvas-2d for low-count semantic geometry/text. Use dom/svg for semantic foreground or provide intentionalRasterizationReason.',
+      ]),
+    );
+  });
+
+  it("requires visible foreground and handle layers to declare browser selectors", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "canvas-2d",
+      rendererTechnique: {
+        exportRenderer: "canvas-2d",
+        fidelityRisks: ["foreground and handles must be verified in browser tests"],
+        layers: [
+          {
+            content: ["dense-pattern"],
+            exportMode: "included",
+            id: "dot-grid-background",
+            kind: "background",
+            primitiveCount: "high",
+            renderer: "canvas-2d",
+          },
+          {
+            content: ["geometry", "text"],
+            exportMode: "included",
+            id: "semantic-foreground",
+            kind: "product-foreground",
+            primitiveCount: "low",
+            renderer: "svg",
+          },
+          {
+            content: ["handles"],
+            exportMode: "excluded",
+            id: "focus-handles",
+            kind: "editing-handles",
+            primitiveCount: "low",
+            renderer: "svg",
+          },
+        ],
+        performanceRisks: ["background redraw can be expensive"],
+        previewRenderer: "canvas-2d",
+        productRepresentation: "mixed",
+        rendererStrategy: "canvas-2d",
+        rendererWorkload: "simple-composition",
+        sourceRepresentation: "procedural-data",
+        whyNotAlternativeStrategies: ["background dots are too dense for DOM"],
+      },
+      rendererWorkload: "simple-composition",
+      scenarios: createTextRendererScenarios(),
+      usesCustomRenderer: true,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toEqual(
+      expect.arrayContaining([
+        'rendererTechnique layer "semantic-foreground" is product-foreground and must declare uiSelector so browser tests can verify the visible renderer layer.',
+        'rendererTechnique layer "focus-handles" is editing-handles and must declare uiSelector so browser tests can verify the visible renderer layer.',
+      ]),
+    );
+  });
+
+  it("rejects mixed product representation without a real layer inventory", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "canvas-2d",
+      rendererTechnique: {
+        exportRenderer: "canvas-2d",
+        fidelityRisks: ["mixed representation must be proven by layers"],
+        layers: [
+          {
+            content: ["dense-pattern"],
+            exportMode: "included",
+            id: "background",
+            kind: "background",
+            primitiveCount: "high",
+            renderer: "canvas-2d",
+          },
+        ],
+        performanceRisks: ["dense redraw can be expensive"],
+        previewRenderer: "canvas-2d",
+        productRepresentation: "mixed",
+        rendererStrategy: "canvas-2d",
+        rendererWorkload: "simple-composition",
+        sourceRepresentation: "procedural-data",
+        whyNotAlternativeStrategies: ["canvas is faster than DOM for many dots"],
+      },
+      rendererWorkload: "simple-composition",
+      scenarios: createTextRendererScenarios(),
+      usesCustomRenderer: true,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toEqual(
+      expect.arrayContaining([
+        'productRepresentation "mixed" requires rendererTechnique.layers with at least two different content families.',
+      ]),
+    );
+  });
+});