@pixel-point/toolcraft 0.0.7 → 0.0.8

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

@@ -102,6 +102,34 @@ const largeTextSchema = defineToolcraft({
   },
 });
 
+const mediaUploadSchema = defineToolcraft({
+  canvas: {
+    enabled: true,
+    sizing: { mode: "intrinsic-media" },
+    upload: true,
+  },
+  panels: {
+    controls: {
+      sections: [
+        {
+          controls: {
+            source: {
+              defaultValue: null,
+              label: "Source image",
+              performanceReason: "Uploaded media dimensions change renderer workload.",
+              performanceRole: "responsiveness",
+              target: "source.image",
+              type: "fileDrop",
+            },
+          },
+          title: "Source",
+        },
+      ],
+      title: "Runtime Controls",
+    },
+  },
+});
+
 function createViewportZoomStressScenario() {
   return {
     automated: true,
@@ -115,6 +143,7 @@ function createViewportZoomStressScenario() {
     id: "viewport-zoom-stress",
     interaction: "viewport-zoom-stress" as const,
     stress: true,
+    stressFixture: createCombinedRendererStressFixture(),
     target: "canvas.viewport",
     workload: false,
   };
@@ -128,6 +157,24 @@ function createMaxValueStressFixture(value: unknown, reason = "Maximum workload
   };
 }
 
+function createCustomStressFixture(
+  value: unknown = { density: 12 },
+  reason = "Combined renderer stress state.",
+) {
+  return {
+    kind: "custom" as const,
+    reason,
+    value,
+  };
+}
+
+function createCombinedRendererStressFixture() {
+  return createCustomStressFixture(
+    { density: 12, zoom: "toolbar" },
+    "Stress checks must run with the densest product output visible.",
+  );
+}
+
 function createLargeTextStressValue(): string {
   return Array.from(
     { length: 1_000 },
@@ -146,6 +193,271 @@ function createLargeTextStressFixture() {
   };
 }
 
+function createMediaStressFixture(
+  value: { height: number; width: number } = { height: 1080, width: 1920 },
+  reason = "Large uploaded source media is the heaviest realistic import fixture.",
+) {
+  return {
+    kind: "media" as const,
+    reason,
+    value,
+  };
+}
+
+function createTextRendererPipeline() {
+  return {
+    interactionInvalidation: [
+      {
+        interaction: "control-drag",
+        invalidates: ["text-layout"],
+        targets: ["render.density"],
+      },
+      {
+        interaction: "control-change",
+        invalidates: ["text-layout"],
+        targets: ["render.mode"],
+      },
+      {
+        interaction: "viewport-zoom",
+        invalidates: [],
+        mustNotInvalidate: ["text-layout"],
+        targets: ["canvas.viewport"],
+      },
+    ],
+    passes: [
+      {
+        cacheKey: ["product.content", "render.density", "render.mode"],
+        id: "text-layout",
+        inputs: ["product.content", "render.density", "render.mode"],
+        invalidatedBy: ["product.content", "render.density", "render.mode"],
+        kind: "text-layout",
+        output: "preview",
+        quality: "full",
+        runsOn: "main",
+      },
+    ],
+  } as const;
+}
+
+function createAnimatedVectorRendererPipeline() {
+  return {
+    interactionInvalidation: [
+      {
+        interaction: "control-drag",
+        invalidates: ["vector-build"],
+        targets: ["render.density"],
+      },
+      {
+        interaction: "control-change",
+        invalidates: ["vector-build"],
+        targets: ["render.mode"],
+      },
+      {
+        interaction: "animation-frame",
+        invalidates: ["animation-composite"],
+        mustNotInvalidate: ["vector-build"],
+        targets: ["animation.time"],
+      },
+      {
+        interaction: "timeline-playback",
+        invalidates: ["animation-composite"],
+        mustNotInvalidate: ["vector-build"],
+        targets: ["timeline.currentTime"],
+      },
+      {
+        interaction: "timeline-scrub",
+        invalidates: ["animation-composite"],
+        mustNotInvalidate: ["vector-build"],
+        targets: ["timeline.currentTime"],
+      },
+      {
+        interaction: "viewport-drag",
+        invalidates: [],
+        mustNotInvalidate: ["vector-build", "animation-composite"],
+        targets: ["canvas.viewport"],
+      },
+      {
+        interaction: "viewport-zoom",
+        invalidates: [],
+        mustNotInvalidate: ["vector-build", "animation-composite"],
+        targets: ["canvas.viewport"],
+      },
+    ],
+    passes: [
+      {
+        id: "vector-build",
+        inputs: ["render.density", "render.mode"],
+        invalidatedBy: ["render.density", "render.mode"],
+        kind: "vector-build",
+        output: "preview",
+        quality: "full",
+        runsOn: "main",
+      },
+      {
+        cacheKey: ["vector-build", "animation.time", "timeline.currentTime"],
+        id: "animation-composite",
+        inputs: ["vector-build", "animation.time", "timeline.currentTime"],
+        invalidatedBy: ["animation.time", "timeline.currentTime"],
+        kind: "composite",
+        output: "preview",
+        quality: "preview",
+        runsOn: "main",
+      },
+    ],
+  } as const;
+}
+
+function createDenseCanvasPipeline() {
+  return {
+    interactionInvalidation: [
+      {
+        interaction: "control-drag",
+        invalidates: ["dense-background", "export-composite"],
+        targets: ["render.density"],
+      },
+      {
+        interaction: "control-change",
+        invalidates: ["export-composite"],
+        targets: ["render.mode"],
+      },
+      {
+        interaction: "viewport-zoom",
+        invalidates: [],
+        mustNotInvalidate: ["dense-background", "export-composite"],
+        targets: ["canvas.viewport"],
+      },
+      {
+        interaction: "export",
+        invalidates: ["export-composite"],
+        mustNotInvalidate: ["dense-background"],
+        targets: ["export.image.resolution"],
+      },
+    ],
+    passes: [
+      {
+        cacheKey: ["render.density", "canvas.size", "canvas.renderScale"],
+        id: "dense-background",
+        inputs: ["render.density", "canvas.size", "canvas.renderScale"],
+        invalidatedBy: ["render.density", "canvas.size", "canvas.renderScale"],
+        kind: "rasterize",
+        output: "preview",
+        quality: "retina",
+        runsOn: "worker",
+      },
+      {
+        id: "semantic-foreground",
+        inputs: ["product.geometry"],
+        invalidatedBy: ["product.geometry"],
+        kind: "vector-build",
+        output: "preview",
+        quality: "full",
+        runsOn: "main",
+      },
+      {
+        cacheKey: ["dense-background", "semantic-foreground", "export.image.resolution"],
+        id: "export-composite",
+        inputs: ["dense-background", "semantic-foreground", "export.image.resolution"],
+        invalidatedBy: ["dense-background", "semantic-foreground", "export.image.resolution"],
+        kind: "composite",
+        output: "export",
+        quality: "export",
+        runsOn: "export-only",
+      },
+    ],
+  } as const;
+}
+
+function createPixelRendererPipeline() {
+  return {
+    interactionInvalidation: [
+      {
+        interaction: "control-drag",
+        invalidates: ["pixel-transform"],
+        targets: ["render.density"],
+      },
+      {
+        interaction: "control-change",
+        invalidates: ["pixel-transform"],
+        targets: ["render.mode"],
+      },
+      {
+        interaction: "viewport-zoom",
+        invalidates: [],
+        mustNotInvalidate: ["pixel-transform"],
+        targets: ["canvas.viewport"],
+      },
+    ],
+    passes: [
+      {
+        cacheKey: ["render.density", "render.mode", "canvas.size", "canvas.renderScale"],
+        id: "pixel-transform",
+        inputs: ["render.density", "render.mode", "canvas.size", "canvas.renderScale"],
+        invalidatedBy: ["render.density", "render.mode", "canvas.size", "canvas.renderScale"],
+        kind: "pixel-transform",
+        output: "preview",
+        quality: "retina",
+        runsOn: "worker",
+      },
+    ],
+  } as const;
+}
+
+function createMediaRendererPipeline() {
+  return {
+    interactionInvalidation: [
+      {
+        interaction: "media-import",
+        invalidates: ["source-decode", "media-preprocess"],
+        targets: ["source.image"],
+      },
+      {
+        interaction: "control-drag",
+        invalidates: ["effect-composite"],
+        mustNotInvalidate: ["source-decode", "media-preprocess"],
+        targets: ["render.density"],
+      },
+      {
+        interaction: "viewport-zoom",
+        invalidates: [],
+        mustNotInvalidate: ["source-decode", "media-preprocess", "effect-composite"],
+        targets: ["canvas.viewport"],
+      },
+    ],
+    passes: [
+      {
+        cacheKey: ["source.image.id", "source.image.width", "source.image.height"],
+        id: "source-decode",
+        inputs: ["source.image"],
+        invalidatedBy: ["source.image"],
+        kind: "decode",
+        output: "source",
+        quality: "full",
+        runsOn: "worker",
+      },
+      {
+        cacheKey: ["source-decode", "source.image.id"],
+        id: "media-preprocess",
+        inputs: ["source-decode"],
+        invalidatedBy: ["source-decode"],
+        kind: "preprocess",
+        output: "intermediate",
+        quality: "full",
+        runsOn: "worker-or-gpu",
+      },
+      {
+        cacheKey: ["media-preprocess", "render.density"],
+        id: "effect-composite",
+        inputs: ["media-preprocess", "render.density"],
+        invalidatedBy: ["media-preprocess", "render.density"],
+        kind: "composite",
+        output: "preview",
+        quality: "retina",
+        runsOn: "gpu",
+      },
+    ],
+  } as const;
+}
+
 function createTextRendererScenarios(
   options: { includeStressPreview?: boolean; includeViewportZoomStress?: boolean } = {},
 ) {
@@ -164,6 +476,9 @@ function createTextRendererScenarios(
       id: "text-preview-render",
       interaction: "preview-render" as const,
       stress: includeStressPreview,
+      ...(includeStressPreview
+        ? { stressFixture: createCombinedRendererStressFixture() }
+        : {}),
       workload: false,
     },
     {
@@ -183,6 +498,7 @@ function createTextRendererScenarios(
       ),
       target: "render.density",
       values: { default: 4, max: 12, min: 1 },
+      workloadFixture: createLargeTextStressFixture(),
       workload: true,
     },
     {
@@ -228,6 +544,10 @@ function createAnimationFrameScenario() {
     id: "animation-frame-loop",
     interaction: "animation-frame" as const,
     stress: true,
+    stressFixture: createCustomStressFixture(
+      { animation: "fastest", density: 12 },
+      "Animation stress must sample the heaviest animated output.",
+    ),
     workload: false,
   };
 }
@@ -244,6 +564,10 @@ function createAnimationViewportDragScenario() {
     id: "animation-viewport-drag",
     interaction: "animation-viewport-drag" as const,
     stress: true,
+    stressFixture: createCustomStressFixture(
+      { animation: "fastest", density: 12 },
+      "Animated viewport drag must run while the heaviest animated output is visible.",
+    ),
     target: "canvas.viewport",
     workload: false,
   };
@@ -264,6 +588,7 @@ function createAnimatedVectorRendererConfig(options: { includeViewportDrag: bool
       whyNotAlternativeStrategies: ["svg preserves semantic vector output for this fixture"],
     },
     rendererWorkload: "vector-output",
+    rendererPipeline: createAnimatedVectorRendererPipeline(),
     scenarios: [
       ...createTextRendererScenarios(),
       createAnimationFrameScenario(),
@@ -570,6 +895,132 @@ describe("Toolcraft template performance contract", () => {
     );
   });
 
+  it("requires stress scenarios to declare an exact stress fixture value", () => {
+    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 heavy renderer fixture",
+          id: "preview-render",
+          interaction: "preview-render",
+          stress: true,
+          workload: false,
+        },
+      ],
+      usesCustomRenderer: false,
+      workloadTargets: [],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(ordinarySliderSchema, config)).toContain(
+      "preview-render stress scenario must declare stressFixture with the real heaviest state used by browser performance tests.",
+    );
+  });
+
+  it("rejects stress fixtures without a browser-applicable value", () => {
+    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 heavy renderer fixture",
+          id: "preview-render",
+          interaction: "preview-render",
+          stress: true,
+          stressFixture: {
+            kind: "custom",
+            reason: "Combined renderer stress state.",
+          },
+          workload: false,
+        },
+      ],
+      usesCustomRenderer: false,
+      workloadTargets: [],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(ordinarySliderSchema, config)).toContain(
+      "preview-render stressFixture must include value so browser tests can apply the exact heavy state.",
+    );
+  });
+
+  it("requires custom stress fixtures to be object-shaped heavy states", () => {
+    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 heavy renderer fixture",
+          id: "preview-render",
+          interaction: "preview-render",
+          stress: true,
+          stressFixture: {
+            kind: "custom",
+            reason: "Combined renderer stress state.",
+            value: 12,
+          },
+          workload: false,
+        },
+      ],
+      usesCustomRenderer: false,
+      workloadTargets: [],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(ordinarySliderSchema, config)).toContain(
+      "preview-render custom stressFixture.value must be an object with one key per heavy state part so browser tests can apply every key.",
+    );
+  });
+
+  it("rejects empty custom stress fixture objects", () => {
+    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 heavy renderer fixture",
+          id: "preview-render",
+          interaction: "preview-render",
+          stress: true,
+          stressFixture: {
+            kind: "custom",
+            reason: "Combined renderer stress state.",
+            value: {},
+          },
+          workload: false,
+        },
+      ],
+      usesCustomRenderer: false,
+      workloadTargets: [],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(ordinarySliderSchema, config)).toContain(
+      "preview-render custom stressFixture.value must include at least one heavy state key.",
+    );
+  });
+
   it("rejects short stress fixtures for large text workload scenarios", () => {
     const config = defineToolcraftPerformance({
       rendererStrategy: "none",
@@ -639,10 +1090,10 @@ describe("Toolcraft template performance contract", () => {
     expect(validateToolcraftPerformanceCoverage(largeTextSchema, config)).toEqual([]);
   });
 
-  it("rejects visible controls without performance scenarios", () => {
+  it("requires workload controls in custom renderers to declare an independent workload fixture", () => {
     const config = defineToolcraftPerformance({
-      rendererStrategy: "none",
-      rendererWorkload: "none",
+      rendererStrategy: "canvas-2d",
+      rendererWorkload: "text-output",
       scenarios: [
         {
           automated: true,
@@ -651,95 +1102,287 @@ describe("Toolcraft template performance contract", () => {
           browserTestName: "browser perf: density drag stays responsive",
           budget: { maxFrameGapMs: 80, maxInteractionMs: 500 },
           controlLabel: "Density",
-          expectedObservable: "Dragging Density updates the product without blocking the UI.",
+          expectedObservable: "Dragging Density updates text output without blocking the UI.",
           fixture: "runtime density fixture",
           id: "density-drag",
           interaction: "control-drag",
+          stressFixture: createMaxValueStressFixture(
+            12,
+            "Density max is the heaviest control value.",
+          ),
           target: "render.density",
           values: { default: 4, max: 12, min: 1 },
           workload: true,
         },
       ],
-      usesCustomRenderer: false,
+      usesCustomRenderer: true,
       workloadTargets: ["render.density"],
     });
 
     expect(validateToolcraftPerformanceCoverage(testSchema, config)).toContain(
-      "render.mode must have a performance scenario because every visible control can affect app responsiveness.",
+      "density-drag workload control scenario must declare workloadFixture for the app's heavy baseline state; stressFixture covers the control value only.",
     );
   });
 
-  it("allows text-output renderers without forcing a GPU strategy", () => {
+  it("rejects toy media workload fixtures for control-drag baselines", () => {
     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(),
+      rendererStrategy: "webgl",
+      rendererWorkload: "pixel-output",
+      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 source media output without blocking the UI.",
+          fixture: "runtime density fixture",
+          id: "density-drag",
+          interaction: "control-drag",
+          stressFixture: createMaxValueStressFixture(
+            12,
+            "Density max is the heaviest control value.",
+          ),
+          target: "render.density",
+          values: { default: 4, max: 12, min: 1 },
+          workloadFixture: createMediaStressFixture(
+            { height: 480, width: 640 },
+            "This small source should be rejected as too light.",
+          ),
+          workload: true,
+        },
+      ],
       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.",
+      "density-drag media workloadFixture.value must be at least 1920x1080-equivalent; received 640x480.",
     );
   });
 
-  it("requires detail-heavy custom renderers to test real viewport zoom stress", () => {
+  it("accepts workload controls with separate control stress and app baseline fixtures", () => {
     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"],
+        fidelityRisks: ["text output must stay crisp"],
+        performanceRisks: ["density changes can relayout text"],
         previewRenderer: "canvas-2d",
         productRepresentation: "text",
         rendererStrategy: "canvas-2d",
         rendererWorkload: "text-output",
         sourceRepresentation: "dom-text",
-        whyNotAlternativeStrategies: ["webgl texture output would rasterize text too early"],
+        whyNotAlternativeStrategies: ["dom output cannot preserve export composition"],
       },
       rendererWorkload: "text-output",
-      scenarios: createTextRendererScenarios({ includeViewportZoomStress: false }),
+      rendererPipeline: createTextRendererPipeline(),
+      scenarios: createTextRendererScenarios(),
       usesCustomRenderer: true,
       workloadTargets: ["render.density"],
     });
 
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toEqual([]);
+  });
+
+  it("rejects workload fixtures that are not paired with scenario stress fixtures", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "none",
+      rendererWorkload: "none",
+      scenarios: [
+        {
+          automated: true,
+          automatedTestName: "perf: preview baseline stays responsive",
+          browser: true,
+          browserTestName: "browser perf: preview baseline stays responsive",
+          budget: { maxPreviewMs: 1000 },
+          expectedObservable: "Preview renders inside a heavy baseline.",
+          fixture: "baseline fixture",
+          id: "preview-heavy-baseline",
+          interaction: "preview-render",
+          workload: false,
+          workloadFixture: createLargeTextStressFixture(),
+        },
+      ],
+      usesCustomRenderer: false,
+      workloadTargets: [],
+    });
+
     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.",
+      "preview-heavy-baseline workloadFixture must be paired with stressFixture so tests apply a heavy baseline and then the measured scenario value.",
     );
   });
 
-  it("requires detail-heavy custom renderers to prove worst-case preview or animation stress", () => {
+  it("rejects media-import scenarios that use toy source dimensions", () => {
     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"]',
+      rendererStrategy: "none",
+      rendererWorkload: "none",
+      scenarios: [
+        {
+          automated: true,
+          automatedTestName: "perf: source image import stays responsive",
+          browser: true,
+          browserTestName: "browser perf: source image import stays responsive",
+          budget: { maxFrameGapMs: 80, maxInteractionMs: 500 },
+          expectedObservable: "Importing source media does not block the app.",
+          fixture: "large source image fixture",
+          id: "source-media-import",
+          interaction: "media-import",
+          stressFixture: createMediaStressFixture(
+            { height: 480, width: 640 },
+            "This small fixture should be rejected as too light.",
+          ),
+          target: "source.image",
+          workload: true,
+        },
+      ],
+      usesCustomRenderer: false,
+      workloadTargets: [],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(mediaUploadSchema, config)).toContain(
+      "source-media-import media stressFixture.value must be at least 1920x1080-equivalent; received 640x480.",
+    );
+  });
+
+  it("requires media-import scenarios to be workload media fixtures", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "none",
+      rendererWorkload: "none",
+      scenarios: [
+        {
+          automated: true,
+          automatedTestName: "perf: source image import stays responsive",
+          browser: true,
+          browserTestName: "browser perf: source image import stays responsive",
+          budget: { maxFrameGapMs: 80, maxInteractionMs: 500 },
+          expectedObservable: "Importing source media does not block the app.",
+          fixture: "large source image fixture",
+          id: "source-media-import",
+          interaction: "media-import",
+          stressFixture: createCustomStressFixture(
+            { height: 1080, width: 1920 },
+            "Wrong fixture kind for media import.",
+          ),
+          target: "source.image",
+          workload: false,
+        },
+      ],
+      usesCustomRenderer: false,
+      workloadTargets: [],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(mediaUploadSchema, config)).toEqual(
+      expect.arrayContaining([
+        "source-media-import media-import scenario must set workload true because decoded source size changes renderer workload.",
+        'source-media-import media-import scenario must use stressFixture.kind "media" with a realistic uploaded source size.',
+      ]),
+    );
+  });
+
+  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",
+      rendererPipeline: createTextRendererPipeline(),
+      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"],
@@ -812,6 +1455,73 @@ describe("Toolcraft template performance contract", () => {
     );
   });
 
+  it("requires detail-heavy Canvas 2D renderers to document measured WebGL/WebGPU evaluation", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "canvas-2d",
+      rendererTechnique: {
+        exportRenderer: "canvas-2d",
+        fidelityRisks: ["dense texture output must match source media colors"],
+        layers: [
+          {
+            content: ["bitmap-media", "noise"],
+            exportMode: "included",
+            id: "media-effect",
+            kind: "product-foreground",
+            primitiveCount: "high",
+            renderer: "canvas-2d",
+            uiSelector: '[data-toolcraft-renderer-layer="media-effect"]',
+          },
+        ],
+        performanceRisks: ["large uploaded media can require millions of pixel operations"],
+        previewRenderer: "canvas-2d",
+        productRepresentation: "pixel",
+        rendererStrategy: "canvas-2d",
+        rendererWorkload: "pixel-output",
+        sourceRepresentation: "image-media",
+        whyNotAlternativeStrategies: ["canvas is convenient"],
+      },
+      rendererWorkload: "pixel-output",
+      scenarios: createTextRendererScenarios(),
+      usesCustomRenderer: true,
+      workloadTargets: ["render.density"],
+    });
+
+    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.",
+    );
+    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.',
+    );
+  });
+
+  it("allows pixel-output Canvas 2D only with measured WebGL/WebGPU evidence", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "canvas-2d",
+      rendererTechnique: {
+        exportRenderer: "canvas-2d",
+        fidelityRisks: ["pixel output must preserve exact color stops"],
+        performanceRisks: [
+          "Measured WebGL stress evidence showed setup overhead exceeded cached Canvas 2D worker output for this static fixture.",
+        ],
+        previewRenderer: "canvas-2d",
+        productRepresentation: "pixel",
+        rendererStrategy: "canvas-2d",
+        rendererWorkload: "pixel-output",
+        sourceRepresentation: "procedural-data",
+        whyNotAlternativeStrategies: [
+          "WebGL measured stress evidence stayed within budget but did not improve interaction latency for this renderer.",
+        ],
+      },
+      rendererWorkload: "pixel-output",
+      rendererPipeline: createPixelRendererPipeline(),
+      scenarios: createTextRendererScenarios(),
+      usesCustomRenderer: true,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toEqual([]);
+  });
+
   it("accepts animated custom renderers with stress coverage while dragging the viewport", () => {
     const config = createAnimatedVectorRendererConfig({ includeViewportDrag: true });
 
@@ -834,6 +1544,528 @@ describe("Toolcraft template performance contract", () => {
     );
   });
 
+  it("requires custom renderers to declare a render pipeline inventory", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "canvas-2d",
+      rendererTechnique: {
+        exportRenderer: "canvas-2d",
+        fidelityRisks: ["canvas output can soften edges"],
+        performanceRisks: ["dense output can jank during drag"],
+        previewRenderer: "canvas-2d",
+        productRepresentation: "mixed",
+        rendererStrategy: "canvas-2d",
+        rendererWorkload: "simple-composition",
+        sourceRepresentation: "procedural-data",
+        whyNotAlternativeStrategies: [
+          "svg cannot preserve dense procedural background output",
+        ],
+      },
+      rendererWorkload: "simple-composition",
+      scenarios: createTextRendererScenarios(),
+      usesCustomRenderer: true,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toContain(
+      "Custom renderers must declare rendererPipeline so render passes, cache keys, and invalidation are machine-checkable.",
+    );
+  });
+
+  it("rejects vague renderer pipeline pass dependencies", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "canvas-2d",
+      rendererTechnique: {
+        exportRenderer: "canvas-2d",
+        fidelityRisks: ["dense text output can soften at small sizes"],
+        performanceRisks: ["text layout can be expensive"],
+        previewRenderer: "canvas-2d",
+        productRepresentation: "text",
+        rendererStrategy: "canvas-2d",
+        rendererWorkload: "text-output",
+        sourceRepresentation: "dom-text",
+        whyNotAlternativeStrategies: ["dom output cannot preserve export composition"],
+      },
+      rendererWorkload: "text-output",
+      rendererPipeline: {
+        interactionInvalidation: [
+          {
+            interaction: "control-drag",
+            invalidates: ["text-layout"],
+            targets: ["render.density"],
+          },
+        ],
+        passes: [
+          {
+            cacheKey: ["state"],
+            id: "text-layout",
+            inputs: ["state"],
+            invalidatedBy: ["all values"],
+            kind: "text-layout",
+            output: "preview",
+            quality: "full",
+            runsOn: "main",
+          },
+        ],
+      },
+      scenarios: createTextRendererScenarios(),
+      usesCustomRenderer: true,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toEqual(
+      expect.arrayContaining([
+        'rendererPipeline pass "text-layout" inputs entry "state" is too vague. Name the concrete runtime target, source key, resource key, or cache key part.',
+        'rendererPipeline pass "text-layout" invalidatedBy entry "all values" is too vague. Name the concrete runtime target, source key, resource key, or cache key part.',
+        'rendererPipeline pass "text-layout" cacheKey entry "state" is too vague. Name the concrete runtime target, source key, resource key, or cache key part.',
+      ]),
+    );
+  });
+
+  it("requires cache-sensitive renderer pipeline passes to declare cache keys", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "canvas-2d",
+      rendererTechnique: {
+        exportRenderer: "canvas-2d",
+        fidelityRisks: ["source pixels must stay crisp"],
+        performanceRisks: ["pixel transforms can block the main thread"],
+        previewRenderer: "canvas-2d",
+        productRepresentation: "pixel",
+        rendererStrategy: "canvas-2d",
+        rendererWorkload: "pixel-output",
+        sourceRepresentation: "image-media",
+        whyNotAlternativeStrategies: [
+          "WebGL/WebGPU measured performance evidence showed no improvement for this fixture",
+        ],
+      },
+      rendererWorkload: "pixel-output",
+      rendererPipeline: {
+        interactionInvalidation: [
+          {
+            interaction: "control-drag",
+            invalidates: ["pixel-pass"],
+            targets: ["render.density"],
+          },
+        ],
+        passes: [
+          {
+            id: "pixel-pass",
+            inputs: ["source.image", "render.density"],
+            invalidatedBy: ["source.image", "render.density"],
+            kind: "pixel-transform",
+            output: "preview",
+            quality: "retina",
+            runsOn: "worker",
+          },
+        ],
+      },
+      scenarios: createTextRendererScenarios(),
+      usesCustomRenderer: true,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toContain(
+      'rendererPipeline pass "pixel-pass" is a cache-sensitive pixel-transform pass and must declare cacheKey so tests can reject full recomputation on every control change.',
+    );
+  });
+
+  it("requires composite renderer pipeline passes to declare cache keys", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "svg",
+      rendererTechnique: {
+        exportRenderer: "svg",
+        fidelityRisks: ["animated composite must preserve vector output"],
+        performanceRisks: ["compositing can be rebuilt too often"],
+        previewRenderer: "svg",
+        productRepresentation: "vector",
+        rendererStrategy: "svg",
+        rendererWorkload: "vector-output",
+        sourceRepresentation: "procedural-data",
+        whyNotAlternativeStrategies: ["svg preserves semantic vector output"],
+      },
+      rendererWorkload: "vector-output",
+      rendererPipeline: {
+        ...createAnimatedVectorRendererPipeline(),
+        passes: createAnimatedVectorRendererPipeline().passes.map((pass) =>
+          pass.id === "animation-composite"
+            ? {
+                id: pass.id,
+                inputs: pass.inputs,
+                invalidatedBy: pass.invalidatedBy,
+                kind: pass.kind,
+                output: pass.output,
+                quality: pass.quality,
+                runsOn: pass.runsOn,
+              }
+            : pass,
+        ),
+      },
+      scenarios: createTextRendererScenarios(),
+      usesCustomRenderer: true,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toContain(
+      'rendererPipeline pass "animation-composite" is a cache-sensitive composite pass and must declare cacheKey so tests can reject full recomputation on every control change.',
+    );
+  });
+
+  it("rejects high-frequency viewport interactions that invalidate expensive passes", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "canvas-2d",
+      rendererTechnique: {
+        exportRenderer: "canvas-2d",
+        fidelityRisks: ["dense background must stay stable while zooming"],
+        layers: [
+          {
+            content: ["dense-pattern"],
+            exportMode: "included",
+            id: "dense-pattern",
+            kind: "background",
+            primitiveCount: "high",
+            renderer: "canvas-2d",
+          },
+        ],
+        performanceRisks: [
+          "WebGL measured stress evidence was reviewed before keeping dense background on Canvas 2D",
+        ],
+        previewRenderer: "canvas-2d",
+        productRepresentation: "pixel",
+        rendererStrategy: "canvas-2d",
+        rendererWorkload: "pixel-output",
+        sourceRepresentation: "procedural-data",
+        whyNotAlternativeStrategies: [
+          "WebGL stress evidence showed shader setup overhead exceeded static cache reuse",
+        ],
+      },
+      rendererWorkload: "pixel-output",
+      rendererPipeline: {
+        interactionInvalidation: [
+          {
+            interaction: "viewport-zoom",
+            invalidates: ["dense-background"],
+            mustNotInvalidate: ["dense-background"],
+            targets: ["canvas.viewport"],
+          },
+          {
+            interaction: "control-drag",
+            invalidates: ["dense-background"],
+            targets: ["render.density"],
+          },
+        ],
+        passes: [
+          {
+            cacheKey: ["render.density", "canvas.size", "canvas.renderScale"],
+            id: "dense-background",
+            inputs: ["render.density", "canvas.size", "canvas.renderScale"],
+            invalidatedBy: ["render.density", "canvas.size", "canvas.renderScale"],
+            kind: "rasterize",
+            output: "preview",
+            quality: "retina",
+            runsOn: "worker",
+          },
+        ],
+      },
+      scenarios: createTextRendererScenarios(),
+      usesCustomRenderer: true,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toEqual(
+      expect.arrayContaining([
+        'rendererPipeline viewport-zoom cannot both invalidate and mustNotInvalidate pass "dense-background".',
+        'rendererPipeline viewport-zoom must not invalidate expensive pass "dense-background" (rasterize). Move viewport work to transforms/uniforms or explain it through a cheaper pass.',
+      ]),
+    );
+  });
+
+  it("requires media decoding pipelines to include media-import coverage", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "webgl",
+      rendererTechnique: {
+        exportRenderer: "webgl",
+        fidelityRisks: ["large source media must preserve color"],
+        performanceRisks: ["source decode can be expensive"],
+        previewRenderer: "webgl",
+        productRepresentation: "pixel",
+        rendererStrategy: "webgl",
+        rendererWorkload: "pixel-output",
+        sourceRepresentation: "image-media",
+        whyNotAlternativeStrategies: ["canvas-2d would run per-pixel work on the main thread"],
+      },
+      rendererWorkload: "pixel-output",
+      rendererPipeline: createMediaRendererPipeline(),
+      scenarios: createTextRendererScenarios(),
+      usesCustomRenderer: true,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toContain(
+      'rendererPipeline pass "source-decode" decodes media, so performance scenarios must include media-import coverage.',
+    );
+  });
+
+  it("requires workload targets to appear in renderer pipeline invalidation targets", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "canvas-2d",
+      rendererTechnique: {
+        exportRenderer: "canvas-2d",
+        fidelityRisks: ["text output must stay crisp"],
+        performanceRisks: ["density changes can relayout text"],
+        previewRenderer: "canvas-2d",
+        productRepresentation: "text",
+        rendererStrategy: "canvas-2d",
+        rendererWorkload: "text-output",
+        sourceRepresentation: "dom-text",
+        whyNotAlternativeStrategies: ["dom output cannot preserve export composition"],
+      },
+      rendererWorkload: "text-output",
+      rendererPipeline: {
+        ...createTextRendererPipeline(),
+        interactionInvalidation: [
+          {
+            interaction: "control-change",
+            invalidates: ["text-layout"],
+            targets: ["render.mode"],
+          },
+        ],
+      },
+      scenarios: createTextRendererScenarios(),
+      usesCustomRenderer: true,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toContain(
+      "Performance workload target render.density must appear in rendererPipeline interactionInvalidation targets.",
+    );
+  });
+
+  it("requires performance scenario interactions to appear in renderer pipeline invalidation", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "canvas-2d",
+      rendererTechnique: {
+        exportRenderer: "canvas-2d",
+        fidelityRisks: ["text output must stay crisp"],
+        performanceRisks: ["density changes can relayout text"],
+        previewRenderer: "canvas-2d",
+        productRepresentation: "text",
+        rendererStrategy: "canvas-2d",
+        rendererWorkload: "text-output",
+        sourceRepresentation: "dom-text",
+        whyNotAlternativeStrategies: ["dom output cannot preserve export composition"],
+      },
+      rendererWorkload: "text-output",
+      rendererPipeline: {
+        ...createTextRendererPipeline(),
+        interactionInvalidation: [
+          {
+            interaction: "control-drag",
+            invalidates: ["text-layout"],
+            targets: ["render.density"],
+          },
+          {
+            interaction: "control-change",
+            invalidates: ["text-layout"],
+            targets: ["render.mode"],
+          },
+        ],
+      },
+      scenarios: createTextRendererScenarios(),
+      usesCustomRenderer: true,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toContain(
+      "Performance scenario viewport-zoom-stress exercises viewport-zoom, so rendererPipeline.interactionInvalidation must declare that interaction.",
+    );
+  });
+
+  it("requires timeline playback scenarios to appear in renderer pipeline invalidation", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "svg",
+      rendererTechnique: {
+        exportRenderer: "svg",
+        fidelityRisks: ["timeline playback must preserve vector motion"],
+        performanceRisks: ["timeline playback can jank at high density"],
+        previewRenderer: "svg",
+        productRepresentation: "vector",
+        rendererStrategy: "svg",
+        rendererWorkload: "vector-output",
+        sourceRepresentation: "procedural-data",
+        whyNotAlternativeStrategies: ["svg preserves semantic vector output"],
+      },
+      rendererWorkload: "vector-output",
+      rendererPipeline: {
+        ...createAnimatedVectorRendererPipeline(),
+        interactionInvalidation: createAnimatedVectorRendererPipeline().interactionInvalidation.filter(
+          (entry) => entry.interaction !== "timeline-playback",
+        ),
+      },
+      scenarios: [
+        ...createTextRendererScenarios(),
+        {
+          automated: true,
+          automatedTestName: "perf: timeline playback stays smooth",
+          browser: true,
+          browserTestName: "browser perf: timeline playback stays smooth",
+          budget: { maxFrameGapMs: 80, maxLongTaskMs: 80 },
+          expectedObservable: "Timeline playback advances without blocking frames.",
+          fixture: "timeline playback fixture",
+          id: "timeline-playback",
+          interaction: "timeline-playback",
+          stress: true,
+          stressFixture: createCombinedRendererStressFixture(),
+          target: "timeline.currentTime",
+          uiSelector: '[data-slot="timeline-playback-handle"]',
+          workload: false,
+        },
+      ],
+      usesCustomRenderer: true,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toContain(
+      "Performance scenario timeline-playback exercises timeline-playback, so rendererPipeline.interactionInvalidation must declare that interaction.",
+    );
+  });
+
+  it("validates timeline scrub scenarios through renderer pipeline invalidation", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "svg",
+      rendererTechnique: {
+        exportRenderer: "svg",
+        fidelityRisks: ["timeline scrub must preserve vector motion"],
+        performanceRisks: ["timeline scrub can jank at high density"],
+        previewRenderer: "svg",
+        productRepresentation: "vector",
+        rendererStrategy: "svg",
+        rendererWorkload: "vector-output",
+        sourceRepresentation: "procedural-data",
+        whyNotAlternativeStrategies: ["svg preserves semantic vector output"],
+      },
+      rendererWorkload: "vector-output",
+      rendererPipeline: createAnimatedVectorRendererPipeline(),
+      scenarios: [
+        ...createTextRendererScenarios(),
+        {
+          automated: true,
+          automatedTestName: "perf: timeline scrub stays responsive",
+          browser: true,
+          browserTestName: "browser perf: timeline scrub stays responsive",
+          budget: { maxFrameGapMs: 80, maxInteractionMs: 500, maxLongTaskMs: 80 },
+          expectedObservable: "Timeline scrub updates output without blocking frames.",
+          fixture: "timeline scrub fixture",
+          id: "timeline-scrub",
+          interaction: "timeline-scrub",
+          stress: true,
+          stressFixture: createCombinedRendererStressFixture(),
+          target: "timeline.currentTime",
+          uiSelector: '[data-slot="timeline-playback-handle"]',
+          workload: false,
+        },
+      ],
+      usesCustomRenderer: true,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toEqual([]);
+  });
+
+  it("requires timeline performance scenarios to name the real timeline UI", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "svg",
+      rendererTechnique: {
+        exportRenderer: "svg",
+        fidelityRisks: ["timeline scrub must preserve vector motion"],
+        performanceRisks: ["timeline scrub can jank at high density"],
+        previewRenderer: "svg",
+        productRepresentation: "vector",
+        rendererStrategy: "svg",
+        rendererWorkload: "vector-output",
+        sourceRepresentation: "procedural-data",
+        whyNotAlternativeStrategies: ["svg preserves semantic vector output"],
+      },
+      rendererWorkload: "vector-output",
+      rendererPipeline: createAnimatedVectorRendererPipeline(),
+      scenarios: [
+        ...createTextRendererScenarios(),
+        {
+          automated: true,
+          automatedTestName: "perf: timeline scrub stays responsive",
+          browser: true,
+          browserTestName: "browser perf: timeline scrub stays responsive",
+          budget: { maxFrameGapMs: 80, maxInteractionMs: 500, maxLongTaskMs: 80 },
+          expectedObservable: "Timeline scrub updates output without blocking frames.",
+          fixture: "timeline scrub fixture",
+          id: "timeline-scrub",
+          interaction: "timeline-scrub",
+          stress: true,
+          stressFixture: createCombinedRendererStressFixture(),
+          target: "timeline.currentTime",
+          workload: false,
+        },
+      ],
+      usesCustomRenderer: true,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toContain(
+      "timeline-scrub timeline-scrub scenario must declare controlLabel or uiSelector for its real browser interaction.",
+    );
+  });
+
+  it("validates mask drag scenarios through renderer pipeline invalidation", () => {
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "svg",
+      rendererTechnique: {
+        exportRenderer: "svg",
+        fidelityRisks: ["mask handles must stay aligned with vector output"],
+        performanceRisks: ["dragging a mask handle can rebuild output too often"],
+        previewRenderer: "svg",
+        productRepresentation: "vector",
+        rendererStrategy: "svg",
+        rendererWorkload: "vector-output",
+        sourceRepresentation: "procedural-data",
+        whyNotAlternativeStrategies: ["svg preserves semantic handle geometry"],
+      },
+      rendererWorkload: "vector-output",
+      rendererPipeline: {
+        ...createAnimatedVectorRendererPipeline(),
+        interactionInvalidation: [
+          ...createAnimatedVectorRendererPipeline().interactionInvalidation,
+          {
+            interaction: "mask-drag",
+            invalidates: ["animation-composite"],
+            mustNotInvalidate: ["vector-build"],
+            targets: ["mask.anchor"],
+          },
+        ],
+      },
+      scenarios: [
+        ...createTextRendererScenarios(),
+        {
+          automated: true,
+          automatedTestName: "perf: mask drag stays responsive",
+          browser: true,
+          browserTestName: "browser perf: mask drag stays responsive",
+          budget: { maxFrameGapMs: 80, maxInteractionMs: 500, maxLongTaskMs: 80 },
+          expectedObservable: "Dragging the mask handle updates output without blocking frames.",
+          fixture: "mask drag fixture",
+          id: "mask-drag",
+          interaction: "mask-drag",
+          stress: true,
+          stressFixture: createCombinedRendererStressFixture(),
+          target: "mask.anchor",
+          uiSelector: '[data-toolcraft-canvas-handle][data-testid="mask-anchor"]',
+          workload: false,
+        },
+      ],
+      usesCustomRenderer: true,
+      workloadTargets: ["render.density"],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(testSchema, config)).toEqual([]);
+  });
+
   it("rejects renderer technique mismatches and missing explanations", () => {
     const config = defineToolcraftPerformance({
       rendererStrategy: "canvas-2d",
@@ -909,9 +2141,11 @@ describe("Toolcraft template performance contract", () => {
         sourceRepresentation: "procedural-data",
         whyNotAlternativeStrategies: [
           "rendering thousands of background dots as DOM nodes would be expensive",
+          "WebGL/WebGPU stress evidence is not needed yet because measured canvas-2d preview budgets pass for this dense static background.",
         ],
       },
       rendererWorkload: "simple-composition",
+      rendererPipeline: createDenseCanvasPipeline(),
       scenarios: createTextRendererScenarios(),
       usesCustomRenderer: true,
       workloadTargets: ["render.density"],