@pixel-point/toolcraft 0.0.9 → 0.0.12

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

@@ -5,6 +5,8 @@ import {
   collectToolcraftPerformanceSensitiveControls,
   collectToolcraftUnclassifiedPerformanceControls,
   defineToolcraftPerformance,
+  defaultToolcraftBrowserCheckPolicy,
+  type ToolcraftBrowserCheckPolicy,
   validateToolcraftPerformanceCoverage,
 } from "./performance";
 
@@ -180,6 +182,14 @@ function createViewportZoomStressScenario() {
 function createMaxValueStressFixture(value: unknown, reason = "Maximum workload value.") {
   return {
     kind: "max-value" as const,
+    loadProfile: {
+      hardLimit: value,
+      metric: "numeric-max" as const,
+      smoothTarget: value,
+      smoothTargetRatio: 1,
+      target: "render.density",
+      userFacingRange: "fully-guaranteed" as const,
+    },
     reason,
     value,
   };
@@ -191,6 +201,14 @@ function createCustomStressFixture(
 ) {
   return {
     kind: "custom" as const,
+    loadProfile: {
+      hardLimit: value,
+      metric: "custom" as const,
+      smoothTarget: value,
+      smoothTargetRatio: 1,
+      target: "renderer.output",
+      userFacingRange: "fully-guaranteed" as const,
+    },
     reason,
     value,
   };
@@ -227,11 +245,60 @@ function createMediaStressFixture(
 ) {
   return {
     kind: "media" as const,
+    loadProfile: {
+      hardLimit: value,
+      metric: "media-area" as const,
+      smoothTarget: value,
+      smoothTargetRatio: 1,
+      target: "source.image",
+      userFacingRange: "fully-guaranteed" as const,
+    },
     reason,
     value,
   };
 }
 
+function createDegradedMaxValueStressFixture() {
+  return {
+    kind: "max-value" as const,
+    loadProfile: {
+      degradationStepPercent: 10 as const,
+      evidence: [
+        {
+          attemptedTarget: 12,
+          decision: "Keep 12 available as high density while guaranteeing smooth drag through 11.",
+          measuredResult: "At density 12, maxFrameGapMs 148 exceeded the 80ms budget.",
+          optimizationAttempted: "Cached glyph atlas and coalesced preview work to requestAnimationFrame.",
+          result: "failed" as const,
+          scenarioId: "density-drag",
+        },
+      ],
+      hardLimit: 12,
+      metric: "numeric-max" as const,
+      smoothTarget: 11,
+      smoothTargetRatio: 0.9,
+      target: "render.density",
+      userFacingRange: "experimental-above-smooth" as const,
+    },
+    reason: "Density 11 is the measured smooth target after hard-limit testing.",
+    value: 11,
+  };
+}
+
+function createMeasuredWebglEvidence(scenarioId = "text-preview-render") {
+  return [
+    {
+      alternativeStrategy: "webgl" as const,
+      decision:
+        "Canvas 2D remains selected because cached CPU rendering stayed within budget for this product fixture while preserving export parity.",
+      fixture: "large product stress fixture at render scale 2",
+      measuredResult:
+        "WebGL comparison: maxFrameGapMs 72, maxLongTaskMs 64; Canvas 2D comparison: maxFrameGapMs 68, maxLongTaskMs 58.",
+      scenarioId,
+    },
+  ];
+}
+
 function createTextRendererPipeline() {
   return {
     interactionInvalidation: [
@@ -395,6 +462,61 @@ function createDenseCanvasPipeline() {
   } as const;
 }
 
+function createMainThreadCanvasCompositePipeline() {
+  return {
+    interactionInvalidation: [
+      {
+        interaction: "control-drag",
+        invalidates: ["text-texture", "warp-composite", "optical-composite"],
+        targets: ["render.density"],
+      },
+      {
+        interaction: "control-change",
+        invalidates: ["text-texture", "warp-composite", "optical-composite"],
+        targets: ["render.mode"],
+      },
+      {
+        interaction: "viewport-zoom",
+        invalidates: [],
+        mustNotInvalidate: ["text-texture", "warp-composite", "optical-composite"],
+        targets: ["canvas.viewport"],
+      },
+    ],
+    passes: [
+      {
+        cacheKey: ["product.content", "render.density", "canvas.size", "canvas.renderScale"],
+        id: "text-texture",
+        inputs: ["product.content", "render.density", "canvas.size", "canvas.renderScale"],
+        invalidatedBy: ["product.content", "render.density", "canvas.size", "canvas.renderScale"],
+        kind: "rasterize",
+        output: "intermediate",
+        quality: "retina",
+        runsOn: "main",
+      },
+      {
+        cacheKey: ["text-texture", "render.density", "canvas.size"],
+        id: "warp-composite",
+        inputs: ["text-texture", "render.density", "canvas.size"],
+        invalidatedBy: ["text-texture", "render.density", "canvas.size"],
+        kind: "composite",
+        output: "preview",
+        quality: "retina",
+        runsOn: "main",
+      },
+      {
+        cacheKey: ["warp-composite", "render.mode", "canvas.renderScale"],
+        id: "optical-composite",
+        inputs: ["warp-composite", "render.mode", "canvas.renderScale"],
+        invalidatedBy: ["warp-composite", "render.mode", "canvas.renderScale"],
+        kind: "composite",
+        output: "preview",
+        quality: "retina",
+        runsOn: "main",
+      },
+    ],
+  } as const;
+}
+
 function createPixelRendererPipeline() {
   return {
     interactionInvalidation: [
@@ -628,6 +750,71 @@ function createAnimatedVectorRendererConfig(options: { includeViewportDrag: bool
 }
 
 describe("Toolcraft template performance contract", () => {
+  it("defaults browser checks to agent browser with Playwright fallback", () => {
+    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(config.browserCheckPolicy).toEqual(defaultToolcraftBrowserCheckPolicy);
+    expect(validateToolcraftPerformanceCoverage(ordinarySliderSchema, config)).toEqual([]);
+  });
+
+  it("rejects explicit Playwright-first browser check policies", () => {
+    const config = defineToolcraftPerformance({
+      browserCheckPolicy: {
+        fallbackRunner: "playwright",
+        fallbackWhen: ["agent-browser-unavailable"],
+        preferredRunner: "playwright",
+      } as unknown as ToolcraftBrowserCheckPolicy,
+      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(
+      expect.arrayContaining([
+        'browserCheckPolicy.preferredRunner must be "agent-browser" so AI agents use their controlled browser before fallback automation.',
+        'browserCheckPolicy.fallbackWhen must include "ci" so CI/non-agent automation has a portable performance runner.',
+      ]),
+    );
+  });
+
   it("collects performance-sensitive controls from schema", () => {
     expect(collectToolcraftPerformanceSensitiveControls(testSchema)).toEqual([
       expect.objectContaining({
@@ -682,6 +869,7 @@ describe("Toolcraft template performance contract", () => {
     const unclassifiedSchema = defineToolcraft({
       canvas: {
         enabled: true,
+        renderScale: true,
         sizing: { mode: "intrinsic-media" },
       },
       panels: {
@@ -704,6 +892,7 @@ describe("Toolcraft template performance contract", () => {
           ],
           title: "Runtime Controls",
         },
+        timeline: { mode: "playback" },
       },
     });
 
@@ -1195,6 +1384,81 @@ describe("Toolcraft template performance contract", () => {
     );
   });
 
+  it("rejects short large-text values hidden inside custom fixtures", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "none",
+      rendererWorkload: "none",
+      scenarios: [
+        {
+          automated: true,
+          automatedTestName: "perf: preview render stays under budget",
+          browser: true,
+          browserTestName: "browser perf: preview render stays under budget",
+          budget: { maxLongTaskMs: 80, maxPreviewMs: 1000 },
+          expectedObservable: "Preview renders the heaviest output without freezing.",
+          fixture: "combined large text fixture",
+          id: "preview-render",
+          interaction: "preview-render",
+          stress: true,
+          stressFixture: {
+            kind: "custom",
+            reason: "Combined renderer stress includes pasted product content.",
+            value: {
+              content: "short text",
+              renderScale: 2,
+            },
+          },
+          workload: false,
+        },
+      ],
+      usesCustomRenderer: false,
+      workloadTargets: [],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(largeTextSchema, config)).toEqual(
+      expect.arrayContaining([
+        "preview-render custom stressFixture.content must contain at least 50000 characters.",
+        "preview-render custom stressFixture.content must contain at least 1000 lines.",
+      ]),
+    );
+  });
+
+  it("rejects custom render scale fixtures that are not concrete high-resolution values", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "none",
+      rendererWorkload: "none",
+      scenarios: [
+        {
+          automated: true,
+          automatedTestName: "perf: preview render stays under budget",
+          browser: true,
+          browserTestName: "browser perf: preview render stays under budget",
+          budget: { maxLongTaskMs: 80, maxPreviewMs: 1000 },
+          expectedObservable: "Preview renders the heaviest output without freezing.",
+          fixture: "combined render scale fixture",
+          id: "preview-render",
+          interaction: "preview-render",
+          stress: true,
+          stressFixture: {
+            kind: "custom",
+            reason: "Combined renderer stress includes selected resolution scale.",
+            value: {
+              density: 12,
+              renderScale: "2",
+            },
+          },
+          workload: false,
+        },
+      ],
+      usesCustomRenderer: false,
+      workloadTargets: [],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(ordinarySliderSchema, config)).toContain(
+      "preview-render custom stressFixture.renderScale must be a numeric Resolution scale greater than 1 so browser tests prove high-resolution backing pixels.",
+    );
+  });
+
   it("accepts large text workload scenarios with machine-checkable stress fixtures", () => {
     const config = defineToolcraftPerformance({
       rendererStrategy: "none",
@@ -1224,6 +1488,352 @@ describe("Toolcraft template performance contract", () => {
     expect(validateToolcraftPerformanceCoverage(largeTextSchema, config)).toEqual([]);
   });
 
+  it("requires max-value fixtures to declare a measured load profile", () => {
+    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 text output without blocking the UI.",
+          fixture: "runtime density fixture",
+          id: "density-drag",
+          interaction: "control-drag",
+          stressFixture: {
+            kind: "max-value",
+            reason: "Density 11 is claimed as the smooth target without hard-limit evidence.",
+            value: 11,
+          },
+          target: "render.density",
+          values: { default: 4, max: 12, min: 1 },
+          workload: true,
+        },
+      ],
+      usesCustomRenderer: false,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toContain(
+      "density-drag stressFixture.loadProfile must declare hardLimit, smoothTarget, and smoothTargetRatio so performance workload is a measured smooth target rather than a hidden toy fixture.",
+    );
+  });
+
+  it("rejects load profiles whose smooth target does not match the applied fixture", () => {
+    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 text output without blocking the UI.",
+          fixture: "runtime density fixture",
+          id: "density-drag",
+          interaction: "control-drag",
+          stressFixture: {
+            kind: "max-value",
+            loadProfile: {
+              hardLimit: 12,
+              metric: "numeric-max",
+              smoothTarget: 11,
+              smoothTargetRatio: 0.9,
+              target: "render.density",
+              userFacingRange: "experimental-above-smooth",
+            },
+            reason: "Density 10 does not match the documented smooth target.",
+            value: 10,
+          },
+          target: "render.density",
+          values: { default: 4, max: 12, min: 1 },
+          workload: true,
+        },
+      ],
+      usesCustomRenderer: false,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toEqual(
+      expect.arrayContaining([
+        "density-drag stressFixture.loadProfile.smoothTarget must match stressFixture.value so browser tests apply the documented smooth workload target.",
+        "density-drag stressFixture.loadProfile.degradationStepPercent must be 10 when smoothTargetRatio is below 1.",
+        "density-drag stressFixture.loadProfile.evidence must include failed measurements for each 10 percent step above smoothTargetRatio 0.9.",
+      ]),
+    );
+  });
+
+  it("rejects load profiles whose ratio does not describe the measured smooth target", () => {
+    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 text output without blocking the UI.",
+          fixture: "runtime density fixture",
+          id: "density-drag",
+          interaction: "control-drag",
+          stressFixture: {
+            kind: "max-value",
+            loadProfile: {
+              degradationStepPercent: 10,
+              evidence: [
+                {
+                  attemptedTarget: 12,
+                  decision:
+                    "Density 12 remains experimental because it misses frame budget after optimization.",
+                  measuredResult: "At density 12, maxFrameGapMs 148 exceeded the 80ms budget.",
+                  optimizationAttempted:
+                    "Cached glyph atlas and coalesced preview work to requestAnimationFrame.",
+                  result: "failed",
+                  scenarioId: "density-drag",
+                },
+              ],
+              hardLimit: 12,
+              metric: "numeric-max",
+              smoothTarget: 2,
+              smoothTargetRatio: 0.9,
+              target: "render.density",
+              userFacingRange: "experimental-above-smooth",
+            },
+            reason: "Density 2 is far below the claimed 90 percent smooth target.",
+            value: 2,
+          },
+          target: "render.density",
+          values: { default: 4, max: 12, min: 1 },
+          workload: true,
+        },
+      ],
+      usesCustomRenderer: false,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toContain(
+      "density-drag stressFixture.loadProfile.smoothTargetRatio 0.9 must describe the actual smooth target ratio 0.1667.",
+    );
+  });
+
+  it("rejects fully guaranteed custom load profiles whose smooth target is not the hard limit", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "canvas-2d",
+      rendererWorkload: "pixel-output",
+      scenarios: [
+        {
+          automated: true,
+          automatedTestName: "perf: combined preview stays responsive",
+          browser: true,
+          browserTestName: "browser perf: combined preview stays responsive",
+          budget: { maxPreviewMs: 200, maxRenderMs: 200 },
+          expectedObservable: "Preview renders the combined source and effect workload.",
+          fixture: "combined custom fixture",
+          id: "combined-preview",
+          interaction: "preview-render",
+          stress: true,
+          stressFixture: {
+            kind: "custom",
+            loadProfile: {
+              hardLimit: { density: 12, sourceMedia: { height: 2160, width: 3840 } },
+              metric: "custom",
+              smoothTarget: { density: 4, sourceMedia: { height: 1080, width: 1920 } },
+              smoothTargetRatio: 1,
+              target: "renderer.output",
+              userFacingRange: "fully-guaranteed",
+            },
+            reason: "This claims full coverage while applying a smaller custom state.",
+            value: { density: 4, sourceMedia: { height: 1080, width: 1920 } },
+          },
+          target: "renderer.output",
+          workload: false,
+        },
+      ],
+      usesCustomRenderer: true,
+      workloadTargets: [],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toContain(
+      "combined-preview stressFixture.loadProfile.smoothTargetRatio 1 requires smoothTarget to equal hardLimit.",
+    );
+  });
+
+  it("accepts a 10 percent degraded smooth target with hard-limit failure evidence", () => {
+    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 text output without blocking the UI.",
+          fixture: "runtime density fixture",
+          id: "density-drag",
+          interaction: "control-drag",
+          stressFixture: createDegradedMaxValueStressFixture(),
+          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",
+          target: "render.mode",
+          values: { default: "soft", max: "sharp", min: "soft" },
+          workload: false,
+        },
+      ],
+      usesCustomRenderer: false,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toEqual([]);
+  });
+
+  it("requires evidence for every skipped 10 percent degradation step", () => {
+    const degradedFixture = createDegradedMaxValueStressFixture();
+    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 text output without blocking the UI.",
+          fixture: "runtime density fixture",
+          id: "density-drag",
+          interaction: "control-drag",
+          stressFixture: {
+            ...degradedFixture,
+            loadProfile: {
+              ...degradedFixture.loadProfile,
+              smoothTarget: 10,
+              smoothTargetRatio: 0.8,
+            },
+            value: 10,
+          },
+          target: "render.density",
+          values: { default: 4, max: 12, min: 1 },
+          workload: true,
+        },
+      ],
+      usesCustomRenderer: false,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toContain(
+      "density-drag stressFixture.loadProfile.evidence must include failed measurements for each 10 percent step above smoothTargetRatio 0.8.",
+    );
+  });
+
+  it("rejects numeric hard limits that do not match schema max", () => {
+    const fixture = createDegradedMaxValueStressFixture();
+    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 text output without blocking the UI.",
+          fixture: "runtime density fixture",
+          id: "density-drag",
+          interaction: "control-drag",
+          stressFixture: {
+            ...fixture,
+            loadProfile: {
+              ...fixture.loadProfile,
+              hardLimit: 10,
+            },
+          },
+          target: "render.density",
+          values: { default: 4, max: 12, min: 1 },
+          workload: true,
+        },
+      ],
+      usesCustomRenderer: false,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toContain(
+      "density-drag stressFixture.loadProfile.hardLimit must match schema max 12.",
+    );
+  });
+
+  it("rejects toy many-items fixtures below their declared useful count", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "none",
+      rendererWorkload: "none",
+      scenarios: [
+        {
+          automated: true,
+          automatedTestName: "perf: items drag stays responsive",
+          browser: true,
+          browserTestName: "browser perf: items drag stays responsive",
+          budget: { maxFrameGapMs: 80, maxInteractionMs: 500 },
+          controlLabel: "Density",
+          expectedObservable: "Dragging Density updates many items without blocking the UI.",
+          fixture: "many item fixture",
+          id: "items-density-drag",
+          interaction: "control-drag",
+          stressFixture: {
+            kind: "many-items",
+            loadProfile: {
+              hardLimit: 100,
+              metric: "count",
+              smoothTarget: 2,
+              smoothTargetRatio: 1,
+              target: "items.count",
+              userFacingRange: "fully-guaranteed",
+            },
+            minCount: 10,
+            reason: "Two items is too small to prove collection performance.",
+            value: 2,
+          },
+          target: "render.density",
+          values: { default: 4, max: 12, min: 1 },
+          workload: true,
+        },
+      ],
+      usesCustomRenderer: false,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toContain(
+      "items-density-drag stressFixture.value must include at least 10 items for many-items fixtures.",
+    );
+  });
+
   it("requires workload controls in custom renderers to declare an independent workload fixture", () => {
     const config = defineToolcraftPerformance({
       rendererStrategy: "canvas-2d",
@@ -1469,6 +2079,49 @@ describe("Toolcraft template performance contract", () => {
     expect(validateToolcraftPerformanceCoverage(testSchema, config)).toEqual([]);
   });
 
+  it("rejects main-thread Canvas 2D raster/composite pipelines misclassified as text output", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "canvas-2d",
+      rendererTechnique: {
+        exportRenderer: "canvas-2d",
+        fidelityRisks: ["rasterized text must preserve the shader-style composite"],
+        layers: [
+          {
+            content: ["text", "noise"],
+            exportMode: "composited",
+            id: "product-text-composite",
+            intentionalRasterizationReason:
+              "The product text is warped, tinted, and exported as final pixels.",
+            kind: "product-foreground",
+            primitiveCount: "medium",
+            renderer: "canvas-2d",
+            uiSelector: '[data-toolcraft-renderer-layer="product-text-composite"]',
+          },
+        ],
+        performanceRisks: [
+          "WebGL measured stress evidence was reviewed before keeping the text composite on Canvas 2D.",
+        ],
+        previewRenderer: "canvas-2d",
+        productRepresentation: "mixed",
+        rendererStrategy: "canvas-2d",
+        rendererWorkload: "text-output",
+        sourceRepresentation: "dom-text",
+        whyNotAlternativeStrategies: [
+          "WebGL measured stress evidence showed text atlas uploads dominated this fixture.",
+        ],
+      },
+      rendererWorkload: "text-output",
+      rendererPipeline: createMainThreadCanvasCompositePipeline(),
+      scenarios: createTextRendererScenarios(),
+      usesCustomRenderer: true,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toContain(
+      'Canvas 2D pipelines with main-thread rasterize/composite preview pressure must use rendererWorkload "pixel-output" or move expensive passes off the main thread; received "text-output".',
+    );
+  });
+
   it("requires animated custom renderers to test viewport dragging during animation", () => {
     const config = createAnimatedVectorRendererConfig({ includeViewportDrag: false });
 
@@ -1621,10 +2274,10 @@ describe("Toolcraft template performance contract", () => {
     });
 
     expect(validateToolcraftPerformanceCoverage(testSchema, config)).toContain(
-      "Detail-heavy Canvas 2D renderers must evaluate WebGL/WebGPU in rendererTechnique.whyNotAlternativeStrategies or performanceRisks with measured stress evidence before keeping the pixel work on CPU.",
+      "Detail-heavy Canvas 2D renderers must include rendererTechnique.measuredAlternativeEvidence for WebGL/WebGPU stress comparison before keeping the pixel work on CPU.",
     );
     expect(validateToolcraftPerformanceCoverage(testSchema, config)).toContain(
-      'rendererWorkload "pixel-output" should use rendererStrategy "webgl" or "webgpu", received "canvas-2d". Keeping a CPU renderer requires measured WebGL/WebGPU evidence in rendererTechnique.whyNotAlternativeStrategies or performanceRisks.',
+      'rendererWorkload "pixel-output" should use rendererStrategy "webgl" or "webgpu", received "canvas-2d". Keeping a CPU renderer requires rendererTechnique.measuredAlternativeEvidence for WebGL/WebGPU stress comparison.',
     );
   });
 
@@ -1637,6 +2290,7 @@ describe("Toolcraft template performance contract", () => {
         performanceRisks: [
           "Measured WebGL stress evidence showed setup overhead exceeded cached Canvas 2D worker output for this static fixture.",
         ],
+        measuredAlternativeEvidence: createMeasuredWebglEvidence(),
         previewRenderer: "canvas-2d",
         productRepresentation: "pixel",
         rendererStrategy: "canvas-2d",
@@ -2267,6 +2921,7 @@ describe("Toolcraft template performance contract", () => {
             renderer: "canvas-2d",
           },
         ],
+        measuredAlternativeEvidence: createMeasuredWebglEvidence(),
         performanceRisks: ["dense background redraw can be expensive at large output size"],
         previewRenderer: "canvas-2d",
         productRepresentation: "mixed",