@pixel-point/toolcraft 0.0.7 → 0.0.8

package/templates/runtime/testing/performance.ts

@@ -9,8 +9,11 @@ export type ToolcraftPerformanceInteraction =
   | "control-change"
   | "control-drag"
   | "export-copy"
+  | "mask-drag"
   | "media-import"
   | "preview-render"
+  | "timeline-playback"
+  | "timeline-scrub"
   | "viewport-zoom-stress"
   | "viewport-stability";
 
@@ -36,7 +39,7 @@ export type ToolcraftPerformanceValueSet = {
   min?: unknown;
 };
 
-export type ToolcraftPerformanceStressFixtureKind =
+export type ToolcraftPerformanceFixtureKind =
   | "custom"
   | "high-density"
   | "large-canvas"
@@ -45,8 +48,8 @@ export type ToolcraftPerformanceStressFixtureKind =
   | "max-value"
   | "media";
 
-export type ToolcraftPerformanceStressFixture = {
-  kind: ToolcraftPerformanceStressFixtureKind;
+export type ToolcraftPerformanceFixture = {
+  kind: ToolcraftPerformanceFixtureKind;
   minChars?: number;
   minCount?: number;
   minLines?: number;
@@ -54,6 +57,10 @@ export type ToolcraftPerformanceStressFixture = {
   value?: unknown;
 };
 
+export type ToolcraftPerformanceStressFixtureKind = ToolcraftPerformanceFixtureKind;
+export type ToolcraftPerformanceStressFixture = ToolcraftPerformanceFixture;
+export type ToolcraftPerformanceWorkloadFixture = ToolcraftPerformanceFixture;
+
 export type ToolcraftPerformanceScenario = ToolcraftPerformanceCoverage & {
   budget: ToolcraftPerformanceBudget;
   controlLabel?: string;
@@ -64,6 +71,7 @@ export type ToolcraftPerformanceScenario = ToolcraftPerformanceCoverage & {
   target?: string;
   stress?: boolean;
   stressFixture?: ToolcraftPerformanceStressFixture;
+  workloadFixture?: ToolcraftPerformanceWorkloadFixture;
   uiSelector?: string;
   values?: ToolcraftPerformanceValueSet;
   workload: boolean;
@@ -170,7 +178,70 @@ export type ToolcraftRendererTechnique = {
   whyNotAlternativeStrategies: readonly string[];
 };
 
+export type ToolcraftRenderPassKind =
+  | "decode"
+  | "preprocess"
+  | "pixel-transform"
+  | "vector-build"
+  | "text-layout"
+  | "rasterize"
+  | "composite"
+  | "handles"
+  | "export";
+
+export type ToolcraftRenderPassRunLocation =
+  | "main"
+  | "worker"
+  | "gpu"
+  | "worker-or-gpu"
+  | "export-only";
+
+export type ToolcraftRenderPassOutput =
+  | "source"
+  | "intermediate"
+  | "preview"
+  | "overlay"
+  | "export";
+
+export type ToolcraftRenderPassQuality = "preview" | "full" | "retina" | "export";
+
+export type ToolcraftRenderPass = {
+  cacheKey?: readonly string[];
+  id: string;
+  inputs: readonly string[];
+  invalidatedBy: readonly string[];
+  kind: ToolcraftRenderPassKind;
+  output: ToolcraftRenderPassOutput;
+  quality: ToolcraftRenderPassQuality;
+  runsOn: ToolcraftRenderPassRunLocation;
+};
+
+export type ToolcraftPipelineInteraction =
+  | "animation-frame"
+  | "control-change"
+  | "control-drag"
+  | "media-import"
+  | "mask-drag"
+  | "viewport-drag"
+  | "viewport-zoom"
+  | "timeline-playback"
+  | "timeline-scrub"
+  | "export";
+
+export type ToolcraftInteractionInvalidation = {
+  interaction: ToolcraftPipelineInteraction;
+  invalidates: readonly string[];
+  mustNotInvalidate?: readonly string[];
+  targets: readonly string[];
+};
+
+export type ToolcraftRendererPipeline = {
+  interactionInvalidation: readonly ToolcraftInteractionInvalidation[];
+  passes: readonly ToolcraftRenderPass[];
+};
+
 export type ToolcraftPerformanceConfig = {
+  rendererPipeline?: ToolcraftRendererPipeline;
   rendererStrategy: ToolcraftRendererStrategy;
   rendererTechnique?: ToolcraftRendererTechnique;
   rendererWorkload: ToolcraftRendererWorkload;
@@ -213,8 +284,10 @@ const heavyTextInputPattern = /code|css|instruction|json|prompt|script|shader|te
 
 const largeTextStressMinChars = 50_000;
 const largeTextStressMinLines = 1_000;
+const mediaStressMinArea = 1920 * 1080;
+const mediaStressMinLongEdge = 1920;
 
-const stressFixtureKinds = new Set<ToolcraftPerformanceStressFixtureKind>([
+const performanceFixtureKinds = new Set<ToolcraftPerformanceFixtureKind>([
   "custom",
   "high-density",
   "large-canvas",
@@ -224,6 +297,79 @@ const stressFixtureKinds = new Set<ToolcraftPerformanceStressFixtureKind>([
   "media",
 ]);
 
+const renderPassKinds = new Set<ToolcraftRenderPassKind>([
+  "decode",
+  "preprocess",
+  "pixel-transform",
+  "vector-build",
+  "text-layout",
+  "rasterize",
+  "composite",
+  "handles",
+  "export",
+]);
+
+const renderPassRunLocations = new Set<ToolcraftRenderPassRunLocation>([
+  "main",
+  "worker",
+  "gpu",
+  "worker-or-gpu",
+  "export-only",
+]);
+
+const renderPassOutputs = new Set<ToolcraftRenderPassOutput>([
+  "source",
+  "intermediate",
+  "preview",
+  "overlay",
+  "export",
+]);
+
+const renderPassQualities = new Set<ToolcraftRenderPassQuality>([
+  "preview",
+  "full",
+  "retina",
+  "export",
+]);
+
+const pipelineInteractions = new Set<ToolcraftPipelineInteraction>([
+  "animation-frame",
+  "control-change",
+  "control-drag",
+  "media-import",
+  "mask-drag",
+  "viewport-drag",
+  "viewport-zoom",
+  "timeline-playback",
+  "timeline-scrub",
+  "export",
+]);
+
+const expensiveRenderPassKinds = new Set<ToolcraftRenderPassKind>([
+  "decode",
+  "preprocess",
+  "pixel-transform",
+  "text-layout",
+  "rasterize",
+]);
+
+const cacheRequiredRenderPassKinds = new Set<ToolcraftRenderPassKind>([
+  ...expensiveRenderPassKinds,
+  "composite",
+]);
+
+const highFrequencyViewportInteractions = new Set<ToolcraftPipelineInteraction>([
+  "animation-frame",
+  "mask-drag",
+  "timeline-playback",
+  "timeline-scrub",
+  "viewport-drag",
+  "viewport-zoom",
+]);
+
+const vaguePipelineReferencePattern =
+  /^(?:all|all values|everything|props|runtime|settings|state|values)$/i;
+
 function getControlSemanticText(control: ToolcraftControlSchema): string {
   return [
     control.target,
@@ -309,12 +455,33 @@ function hasMinDefaultMax(values: ToolcraftPerformanceScenario["values"]): boole
   return values !== undefined && "default" in values && "min" in values && "max" in values;
 }
 
-function hasStressFixtureValue(
-  fixture: ToolcraftPerformanceStressFixture,
-): fixture is ToolcraftPerformanceStressFixture & { value: unknown } {
+function hasPerformanceFixtureValue(
+  fixture: ToolcraftPerformanceFixture,
+): fixture is ToolcraftPerformanceFixture & { value: unknown } {
   return Object.prototype.hasOwnProperty.call(fixture, "value");
 }
 
+function isPerformanceFixtureObjectValue(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function getMediaStressFixtureDimensions(
+  value: unknown,
+): { height: number; width: number } | null {
+  if (!isPerformanceFixtureObjectValue(value)) {
+    return null;
+  }
+
+  const width = Number(value.width);
+  const height = Number(value.height);
+
+  if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+    return null;
+  }
+
+  return { height, width };
+}
+
 function getTextLineCount(value: string): number {
   if (value.length === 0) {
     return 0;
@@ -340,50 +507,79 @@ function isLargeTextWorkloadControl(
   );
 }
 
-function getStressFixtureErrors(
-  scenario: ToolcraftPerformanceScenario,
-  control: ToolcraftControlSchema | undefined,
+function getPerformanceFixtureShapeErrors(
+  scenarioId: string,
+  fieldName: "stressFixture" | "workloadFixture",
+  fixture: ToolcraftPerformanceFixture,
+  options: {
+    requireLargeText?: boolean;
+    requireMedia?: boolean;
+  } = {},
 ): string[] {
-  if (!scenario.workload) {
-    return [];
-  }
-
   const errors: string[] = [];
-  const fixture = scenario.stressFixture;
 
-  if (!fixture) {
-    return [
-      `${scenario.id} workload scenario must declare stressFixture with the real heaviest value used by browser performance tests.`,
-    ];
+  if (!performanceFixtureKinds.has(fixture.kind)) {
+    errors.push(`${scenarioId} ${fieldName}.kind "${fixture.kind}" is not supported.`);
   }
 
-  if (!stressFixtureKinds.has(fixture.kind)) {
-    errors.push(`${scenario.id} stressFixture.kind "${fixture.kind}" is not supported.`);
+  if (options.requireMedia) {
+    if (fixture.kind !== "media") {
+      errors.push(
+        `${scenarioId} media-import scenario must use ${fieldName}.kind "media" with a realistic uploaded source size.`,
+      );
+    }
   }
 
   if (!fixture.reason.trim()) {
     errors.push(
-      `${scenario.id} stressFixture must explain why this is the heaviest useful fixture.`,
+      `${scenarioId} ${fieldName} must explain why this is the heaviest useful fixture.`,
     );
   }
 
-  if (fixture.kind !== "custom" && !hasStressFixtureValue(fixture)) {
-    errors.push(`${scenario.id} stressFixture must include value so browser tests can use it.`);
+  if (!hasPerformanceFixtureValue(fixture)) {
+    errors.push(
+      `${scenarioId} ${fieldName} must include value so browser tests can apply the exact heavy state.`,
+    );
+  } else if (fixture.kind === "custom") {
+    if (!isPerformanceFixtureObjectValue(fixture.value)) {
+      errors.push(
+        `${scenarioId} custom ${fieldName}.value must be an object with one key per heavy state part so browser tests can apply every key.`,
+      );
+    } else if (Object.keys(fixture.value).length === 0) {
+      errors.push(
+        `${scenarioId} custom ${fieldName}.value must include at least one heavy state key.`,
+      );
+    }
+  } else if (fixture.kind === "media") {
+    const dimensions = getMediaStressFixtureDimensions(fixture.value);
+
+    if (!dimensions) {
+      errors.push(
+        `${scenarioId} media ${fieldName}.value must be an object with numeric width and height so browser tests can generate or load a realistic source image.`,
+      );
+    } else if (
+      Math.max(dimensions.width, dimensions.height) < mediaStressMinLongEdge ||
+      dimensions.width * dimensions.height < mediaStressMinArea
+    ) {
+      errors.push(
+        `${scenarioId} media ${fieldName}.value must be at least 1920x1080-equivalent; received ${dimensions.width}x${dimensions.height}.`,
+      );
+    }
   }
 
-  if (!isLargeTextWorkloadControl(control) && fixture.kind !== "large-text") {
+  if (!options.requireLargeText && fixture.kind !== "large-text") {
     return errors;
   }
 
   if (fixture.kind !== "large-text") {
     errors.push(
-      `${scenario.id} text workload scenario must use stressFixture.kind "large-text" with a real long text value.`,
+      `${scenarioId} text workload scenario must use ${fieldName}.kind "large-text" with a real long text value.`,
     );
     return errors;
   }
 
   if (typeof fixture.value !== "string") {
-    errors.push(`${scenario.id} large-text stressFixture.value must be a string.`);
+    errors.push(`${scenarioId} large-text ${fieldName}.value must be a string.`);
     return errors;
   }
 
@@ -392,31 +588,148 @@ function getStressFixtureErrors(
 
   if (minChars < largeTextStressMinChars) {
     errors.push(
-      `${scenario.id} large-text stressFixture.minChars must be >= ${largeTextStressMinChars}.`,
+      `${scenarioId} large-text ${fieldName}.minChars must be >= ${largeTextStressMinChars}.`,
     );
   }
 
   if (minLines < largeTextStressMinLines) {
     errors.push(
-      `${scenario.id} large-text stressFixture.minLines must be >= ${largeTextStressMinLines}.`,
+      `${scenarioId} large-text ${fieldName}.minLines must be >= ${largeTextStressMinLines}.`,
     );
   }
 
   if (fixture.value.length < minChars) {
     errors.push(
-      `${scenario.id} large-text stressFixture.value must contain at least ${minChars} characters.`,
+      `${scenarioId} large-text ${fieldName}.value must contain at least ${minChars} characters.`,
     );
   }
 
   if (getTextLineCount(fixture.value) < minLines) {
     errors.push(
-      `${scenario.id} large-text stressFixture.value must contain at least ${minLines} lines.`,
+      `${scenarioId} large-text ${fieldName}.value must contain at least ${minLines} lines.`,
     );
   }
 
   return errors;
 }
 
+function getStressFixtureErrors(
+  scenario: ToolcraftPerformanceScenario,
+  control: ToolcraftControlSchema | undefined,
+): string[] {
+  const isMediaImport = scenario.interaction === "media-import";
+
+  if (!scenario.workload && scenario.stress !== true && !scenario.stressFixture && !isMediaImport) {
+    return [];
+  }
+
+  const fixture = scenario.stressFixture;
+
+  if (!fixture) {
+    if (isMediaImport) {
+      return [
+        `${scenario.id} media-import scenario must declare stressFixture.kind "media" with a realistic uploaded source size.`,
+      ];
+    }
+
+    return scenario.workload
+      ? [
+          `${scenario.id} workload scenario must declare stressFixture with the real heaviest value used by browser performance tests.`,
+        ]
+      : [
+          `${scenario.id} stress scenario must declare stressFixture with the real heaviest state used by browser performance tests.`,
+        ];
+  }
+
+  const errors: string[] = [];
+
+  if (isMediaImport && !scenario.workload) {
+    errors.push(
+      `${scenario.id} media-import scenario must set workload true because decoded source size changes renderer workload.`,
+    );
+  }
+
+  errors.push(
+    ...getPerformanceFixtureShapeErrors(scenario.id, "stressFixture", fixture, {
+      requireLargeText: isLargeTextWorkloadControl(control),
+      requireMedia: isMediaImport,
+    }),
+  );
+
+  return errors;
+}
+
+function stressFixtureAlreadyDefinesIndependentWorkload(
+  scenario: ToolcraftPerformanceScenario,
+  control: ToolcraftControlSchema | undefined,
+): boolean {
+  return (
+    scenario.stressFixture?.kind === "large-text" &&
+    isLargeTextWorkloadControl(control)
+  );
+}
+
+function isWorkloadBaselineSensitiveScenario(
+  config: ToolcraftPerformanceConfig,
+  scenario: ToolcraftPerformanceScenario,
+  control: ToolcraftControlSchema | undefined,
+): boolean {
+  if (
+    !scenario.workload ||
+    (scenario.interaction !== "control-change" && scenario.interaction !== "control-drag")
+  ) {
+    return false;
+  }
+
+  if (!config.usesCustomRenderer) {
+    return false;
+  }
+
+  if (config.rendererWorkload === "none" || config.rendererWorkload === "simple-composition") {
+    return false;
+  }
+
+  return !stressFixtureAlreadyDefinesIndependentWorkload(scenario, control);
+}
+
+function getWorkloadFixtureErrors(
+  config: ToolcraftPerformanceConfig,
+  scenario: ToolcraftPerformanceScenario,
+  control: ToolcraftControlSchema | undefined,
+): string[] {
+  const requiresBaseline = isWorkloadBaselineSensitiveScenario(config, scenario, control);
+  const errors: string[] = [];
+
+  if (scenario.workloadFixture && !scenario.stressFixture) {
+    errors.push(
+      `${scenario.id} workloadFixture must be paired with stressFixture so tests apply a heavy baseline and then the measured scenario value.`,
+    );
+  }
+
+  if (!requiresBaseline && !scenario.workloadFixture) {
+    return errors;
+  }
+
+  const fixture = scenario.workloadFixture;
+
+  if (!fixture) {
+    errors.push(
+      `${scenario.id} workload control scenario must declare workloadFixture for the app's heavy baseline state; stressFixture covers the control value only.`,
+    );
+    return errors;
+  }
+
+  errors.push(
+    ...getPerformanceFixtureShapeErrors(
+      scenario.id,
+      "workloadFixture",
+      fixture,
+    ),
+  );
+
+  return errors;
+}
+
 function hasPositiveBudgetField(
   budget: ToolcraftPerformanceBudget,
   field: keyof ToolcraftPerformanceBudget,
@@ -438,6 +751,7 @@ function getMissingInteractionBudgetFields(
           ? ["maxFrameGapMs"]
           : ["maxFrameGapMs", "maxLongTaskMs"];
     case "animation-viewport-drag":
+    case "mask-drag":
     case "viewport-zoom-stress":
       return (["maxInteractionMs", "maxFrameGapMs", "maxLongTaskMs"] as const).filter(
         (field) => !hasPositiveBudgetField(scenario.budget, field),
@@ -459,6 +773,14 @@ function getMissingInteractionBudgetFields(
         hasPositiveBudgetField(scenario.budget, "maxRenderMs")
         ? []
         : ["maxPreviewMs or maxRenderMs"];
+    case "timeline-playback":
+      return (["maxFrameGapMs", "maxLongTaskMs"] as const).filter(
+        (field) => !hasPositiveBudgetField(scenario.budget, field),
+      );
+    case "timeline-scrub":
+      return (["maxInteractionMs", "maxFrameGapMs", "maxLongTaskMs"] as const).filter(
+        (field) => !hasPositiveBudgetField(scenario.budget, field),
+      );
   }
 }
 
@@ -476,7 +798,13 @@ function getBudgetCapErrors(scenario: ToolcraftPerformanceScenario): string[] {
 }
 
 function requiresConcreteUiTarget(interaction: ToolcraftPerformanceInteraction): boolean {
-  return interaction === "control-change" || interaction === "control-drag";
+  return (
+    interaction === "control-change" ||
+    interaction === "control-drag" ||
+    interaction === "mask-drag" ||
+    interaction === "timeline-playback" ||
+    interaction === "timeline-scrub"
+  );
 }
 
 function getAllSchemaControls(
@@ -588,6 +916,32 @@ function hasHighCountCanvas2DRendererLayer(
   );
 }
 
+function hasDetailHeavyCanvas2DRendererLayer(
+  technique: ToolcraftRendererTechnique | undefined,
+): boolean {
+  return (technique?.layers ?? []).some(
+    (layer) =>
+      layer.renderer === "canvas-2d" &&
+      layer.content.some((content) => detailHeavyRendererContent.has(content)),
+  );
+}
+
+function hasMeasuredGpuAlternativeEvidence(
+  technique: ToolcraftRendererTechnique,
+): boolean {
+  const evidenceText = [
+    ...technique.whyNotAlternativeStrategies,
+    ...technique.performanceRisks,
+  ].join(" ");
+
+  return (
+    /\b(?:webgl|webgpu|gpu)\b/i.test(evidenceText) &&
+    /\b(?:budget|evidence|frame|long task|measure|measured|perf|performance|stress)\b/i.test(
+      evidenceText,
+    )
+  );
+}
+
 function hasStressPreviewOrAnimationScenario(config: ToolcraftPerformanceConfig): boolean {
   return config.scenarios.some(
     (scenario) =>
@@ -767,6 +1121,267 @@ function getRendererTechniqueErrors(config: ToolcraftPerformanceConfig): string[
 
   errors.push(...getRendererLayerErrors(technique));
 
+  if (
+    config.usesCustomRenderer &&
+    technique.rendererStrategy === "canvas-2d" &&
+    hasDetailHeavyCanvas2DRendererLayer(technique) &&
+    !hasMeasuredGpuAlternativeEvidence(technique)
+  ) {
+    errors.push(
+      "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.",
+    );
+  }
+
+  return errors;
+}
+
+function getPassById(
+  pipeline: ToolcraftRendererPipeline,
+): Map<string, ToolcraftRenderPass> {
+  return new Map(pipeline.passes.map((pass) => [pass.id, pass]));
+}
+
+function hasPipelineReference(value: string): boolean {
+  return value.trim().length > 0 && !vaguePipelineReferencePattern.test(value.trim());
+}
+
+function getPipelineReferenceErrors(
+  passId: string,
+  field: string,
+  references: readonly string[] | undefined,
+): string[] {
+  if (!references || references.length === 0) {
+    return [`rendererPipeline pass "${passId}" must list ${field}.`];
+  }
+
+  return references.flatMap((reference) =>
+    hasPipelineReference(reference)
+      ? []
+      : [
+          `rendererPipeline pass "${passId}" ${field} entry "${reference}" is too vague. Name the concrete runtime target, source key, resource key, or cache key part.`,
+        ],
+  );
+}
+
+function getPipelineInteractionForScenario(
+  interaction: ToolcraftPerformanceInteraction,
+): ToolcraftPipelineInteraction | null {
+  switch (interaction) {
+    case "animation-frame":
+      return "animation-frame";
+    case "animation-viewport-drag":
+      return "viewport-drag";
+    case "control-change":
+      return "control-change";
+    case "control-drag":
+      return "control-drag";
+    case "export-copy":
+      return "export";
+    case "mask-drag":
+      return "mask-drag";
+    case "media-import":
+      return "media-import";
+    case "preview-render":
+      return null;
+    case "timeline-playback":
+      return "timeline-playback";
+    case "timeline-scrub":
+      return "timeline-scrub";
+    case "viewport-zoom-stress":
+      return "viewport-zoom";
+    case "viewport-stability":
+      return null;
+  }
+}
+
+function getRendererPipelineErrors(
+  _schema: ResolvedToolcraftAppSchema,
+  config: ToolcraftPerformanceConfig,
+): string[] {
+  const errors: string[] = [];
+  const pipeline = config.rendererPipeline;
+
+  if (config.usesCustomRenderer && !pipeline) {
+    return [
+      "Custom renderers must declare rendererPipeline so render passes, cache keys, and invalidation are machine-checkable.",
+    ];
+  }
+
+  if (!config.usesCustomRenderer && pipeline) {
+    return ["Non-custom renderer configs must omit rendererPipeline."];
+  }
+
+  if (!pipeline) {
+    return errors;
+  }
+
+  if (pipeline.passes.length === 0) {
+    errors.push("rendererPipeline must declare at least one render pass.");
+  }
+
+  if (pipeline.interactionInvalidation.length === 0) {
+    errors.push(
+      "rendererPipeline must declare interactionInvalidation so high-frequency UI work cannot accidentally invalidate expensive passes.",
+    );
+  }
+
+  const passIds = new Set<string>();
+
+  for (const pass of pipeline.passes) {
+    const passId = pass.id.trim();
+
+    if (!passId) {
+      errors.push("rendererPipeline passes must have non-empty ids.");
+    } else if (passIds.has(passId)) {
+      errors.push(`rendererPipeline pass id "${passId}" must be unique.`);
+    } else {
+      passIds.add(passId);
+    }
+
+    if (!renderPassKinds.has(pass.kind)) {
+      errors.push(`rendererPipeline pass "${pass.id}" kind "${pass.kind}" is not supported.`);
+    }
+
+    if (!renderPassRunLocations.has(pass.runsOn)) {
+      errors.push(
+        `rendererPipeline pass "${pass.id}" runsOn "${pass.runsOn}" is not supported.`,
+      );
+    }
+
+    if (!renderPassOutputs.has(pass.output)) {
+      errors.push(
+        `rendererPipeline pass "${pass.id}" output "${pass.output}" is not supported.`,
+      );
+    }
+
+    if (!renderPassQualities.has(pass.quality)) {
+      errors.push(
+        `rendererPipeline pass "${pass.id}" quality "${pass.quality}" is not supported.`,
+      );
+    }
+
+    errors.push(...getPipelineReferenceErrors(pass.id, "inputs", pass.inputs));
+    errors.push(...getPipelineReferenceErrors(pass.id, "invalidatedBy", pass.invalidatedBy));
+
+    if (pass.cacheKey) {
+      errors.push(...getPipelineReferenceErrors(pass.id, "cacheKey", pass.cacheKey));
+    }
+
+    if (
+      cacheRequiredRenderPassKinds.has(pass.kind) &&
+      (!pass.cacheKey || pass.cacheKey.length === 0)
+    ) {
+      errors.push(
+        `rendererPipeline pass "${pass.id}" is a cache-sensitive ${pass.kind} pass and must declare cacheKey so tests can reject full recomputation on every control change.`,
+      );
+    }
+
+    if (pass.kind === "decode") {
+      const hasMediaImportScenario = config.scenarios.some(
+        (scenario) => scenario.interaction === "media-import",
+      );
+
+      if (!hasMediaImportScenario) {
+        errors.push(
+          `rendererPipeline pass "${pass.id}" decodes media, so performance scenarios must include media-import coverage.`,
+        );
+      }
+    }
+  }
+
+  const passesById = getPassById(pipeline);
+  const invalidationTargets = new Set<string>();
+  const pipelineInteractionSet = new Set(
+    pipeline.interactionInvalidation.map((invalidation) => invalidation.interaction),
+  );
+
+  for (const invalidation of pipeline.interactionInvalidation) {
+    if (!pipelineInteractions.has(invalidation.interaction)) {
+      errors.push(
+        `rendererPipeline interaction "${invalidation.interaction}" is not supported.`,
+      );
+    }
+
+    errors.push(
+      ...getPipelineReferenceErrors(
+        invalidation.interaction,
+        "targets",
+        invalidation.targets,
+      ),
+    );
+
+    for (const target of invalidation.targets) {
+      if (hasPipelineReference(target)) {
+        invalidationTargets.add(target);
+      }
+    }
+
+    const mustNotInvalidate = new Set(invalidation.mustNotInvalidate ?? []);
+
+    for (const passId of invalidation.invalidates) {
+      if (!passId.trim()) {
+        errors.push(
+          `rendererPipeline ${invalidation.interaction} invalidates contains an empty pass id.`,
+        );
+        continue;
+      }
+
+      const pass = passesById.get(passId);
+
+      if (!pass) {
+        errors.push(
+          `rendererPipeline ${invalidation.interaction} invalidates unknown pass "${passId}".`,
+        );
+        continue;
+      }
+
+      if (mustNotInvalidate.has(passId)) {
+        errors.push(
+          `rendererPipeline ${invalidation.interaction} cannot both invalidate and mustNotInvalidate pass "${passId}".`,
+        );
+      }
+
+      if (
+        highFrequencyViewportInteractions.has(invalidation.interaction) &&
+        expensiveRenderPassKinds.has(pass.kind)
+      ) {
+        errors.push(
+          `rendererPipeline ${invalidation.interaction} must not invalidate expensive pass "${passId}" (${pass.kind}). Move viewport work to transforms/uniforms or explain it through a cheaper pass.`,
+        );
+      }
+    }
+
+    for (const passId of invalidation.mustNotInvalidate ?? []) {
+      if (!passId.trim()) {
+        errors.push(
+          `rendererPipeline ${invalidation.interaction} mustNotInvalidate contains an empty pass id.`,
+        );
+      } else if (!passesById.has(passId)) {
+        errors.push(
+          `rendererPipeline ${invalidation.interaction} mustNotInvalidate unknown pass "${passId}".`,
+        );
+      }
+    }
+  }
+
+  for (const scenario of config.scenarios) {
+    const pipelineInteraction = getPipelineInteractionForScenario(scenario.interaction);
+
+    if (pipelineInteraction && !pipelineInteractionSet.has(pipelineInteraction)) {
+      errors.push(
+        `Performance scenario ${scenario.id} exercises ${pipelineInteraction}, so rendererPipeline.interactionInvalidation must declare that interaction.`,
+      );
+    }
+  }
+
+  for (const target of config.workloadTargets) {
+    if (!invalidationTargets.has(target)) {
+      errors.push(
+        `Performance workload target ${target} must appear in rendererPipeline interactionInvalidation targets.`,
+      );
+    }
+  }
+
   return errors;
 }
 
@@ -790,6 +1405,7 @@ export function validateToolcraftPerformanceCoverage(
   );
 
   errors.push(...getRendererTechniqueErrors(config));
+  errors.push(...getRendererPipelineErrors(schema, config));
 
   if (config.usesCustomRenderer && !customRendererStrategies.has(config.rendererStrategy)) {
     errors.push(
@@ -817,10 +1433,11 @@ export function validateToolcraftPerformanceCoverage(
 
   if (
     config.rendererWorkload === "pixel-output" &&
-    !gpuRendererStrategies.has(config.rendererStrategy)
+    !gpuRendererStrategies.has(config.rendererStrategy) &&
+    (!config.rendererTechnique || !hasMeasuredGpuAlternativeEvidence(config.rendererTechnique))
   ) {
     errors.push(
-      `rendererWorkload "pixel-output" must use rendererStrategy "webgl" or "webgpu", received "${config.rendererStrategy}".`,
+      `rendererWorkload "pixel-output" should use rendererStrategy "webgl" or "webgpu", received "${config.rendererStrategy}". Keeping a CPU renderer requires measured WebGL/WebGPU evidence in rendererTechnique.whyNotAlternativeStrategies or performanceRisks.`,
     );
   }
 
@@ -910,11 +1527,17 @@ export function validateToolcraftPerformanceCoverage(
       }
     }
 
-    if (scenario.workload && !hasMinDefaultMax(scenario.values)) {
+    if (
+      scenario.workload &&
+      scenario.interaction !== "media-import" &&
+      !hasMinDefaultMax(scenario.values)
+    ) {
       errors.push(`${scenario.id} workload scenario must include min/default/max values.`);
     }
 
-    errors.push(...getStressFixtureErrors(scenario, controlsByTarget.get(scenario.target ?? "")));
+    const scenarioControl = controlsByTarget.get(scenario.target ?? "");
+    errors.push(...getStressFixtureErrors(scenario, scenarioControl));
+    errors.push(...getWorkloadFixtureErrors(config, scenario, scenarioControl));
 
     if (
       requiresConcreteUiTarget(scenario.interaction) &&
@@ -1039,10 +1662,24 @@ export function validateToolcraftPerformanceCoverage(
       }
     }
 
-    if (schema.canvas.upload && !interactions.has("media-import")) {
-      errors.push(
-        "Custom renderers with canvas upload must include a media-import performance scenario.",
+    if (schema.canvas.upload) {
+      const mediaImportScenarios = config.scenarios.filter(
+        (scenario) => scenario.interaction === "media-import",
       );
+
+      if (mediaImportScenarios.length === 0) {
+        errors.push(
+          "Custom renderers with canvas upload must include a media-import performance scenario.",
+        );
+      } else if (
+        !mediaImportScenarios.some(
+          (scenario) => scenario.workload && scenario.stressFixture?.kind === "media",
+        )
+      ) {
+        errors.push(
+          'Custom renderers with canvas upload must include a workload media-import performance scenario with stressFixture.kind "media".',
+        );
+      }
     }
 
     if (hasKeyframeTimeline(schema)) {