@pixel-point/toolcraft 0.0.16 → 0.0.18

package/templates/starter/e2e/performance-path-helpers.ts

@@ -1,6 +1,7 @@
 import type { Page } from "@playwright/test";
 
 import {
+  TOOLCRAFT_CANVAS_RENDER_SCALE,
   compileToolcraftPerformanceFixturePlan,
   deriveToolcraftPerformancePaths,
   type ResolvedToolcraftAppSchema,
@@ -9,14 +10,11 @@ import {
 } from "@repo/toolcraft-runtime";
 
 import {
-  assertToolcraftRenderScaleBackingProofConfig,
+  expectToolcraftCanvasBackingPixelsForRenderScale,
   expectToolcraftPerformanceRenderScaleBackingEvidence,
-  isToolcraftRenderScalePerformancePath,
 } from "./browser-render-scale-evidence";
 import { attachToolcraftBrowserRuntimeEvidence } from "./browser-runtime-evidence";
-import {
-  expectToolcraftPerformanceBudget,
-} from "./performance-budget-helpers";
+import { expectToolcraftPerformanceBudget } from "./performance-budget-helpers";
 import { applyToolcraftPerformancePathCompiledFixture } from "./performance-fixture-helpers";
 import {
   readToolcraftPerformanceFixtureResolutionMode,
@@ -27,11 +25,15 @@ import {
   measureToolcraftClipboardActionByLabel,
   measureToolcraftDownloadActionByLabel,
 } from "./performance-output-action-helpers";
-import type { ToolcraftPerformancePathAdapter } from "./performance-path-adapter-contract";
-import { expectToolcraftPipelineInvariant } from "./performance-pipeline-evidence";
 import {
-  getToolcraftPerformancePathBudget,
-} from "./performance-profile-helpers";
+  createToolcraftPerformanceCanvasQualityGuard,
+} from "./performance-canvas-quality-guard";
+import type {
+  ToolcraftPerformanceCanvasBacking,
+  ToolcraftPerformancePathAdapter,
+} from "./performance-path-adapter-contract";
+import { expectToolcraftPipelineInvariant } from "./performance-pipeline-evidence";
+import { getToolcraftPerformancePathBudget } from "./performance-profile-helpers";
 import {
   measureToolcraftAnimationFrames,
   measureToolcraftInteraction,
@@ -39,10 +41,81 @@ import {
 
 export type ToolcraftCompiledPerformancePathAdapter = Readonly<{
   adapter: ToolcraftPerformancePathAdapter;
+  canvasBacking: ToolcraftPerformanceCanvasBacking | undefined;
   path: ToolcraftPerformancePath;
   testName: string;
 }>;
 
+type ToolcraftPerformancePathAdapterMatrixInput = Readonly<{
+  adapters: readonly ToolcraftPerformancePathAdapter[];
+  canvasBacking: ToolcraftPerformanceCanvasBacking | undefined;
+  paths: readonly ToolcraftPerformancePath[];
+  schema: ResolvedToolcraftAppSchema;
+}>;
+
+function compileToolcraftPerformanceCanvasBackingConfig(
+  canvasBacking: unknown,
+): ToolcraftPerformanceCanvasBacking {
+  if (
+    typeof canvasBacking !== "object" ||
+    canvasBacking === null ||
+    Array.isArray(canvasBacking)
+  ) {
+    throw new Error(
+      "Toolcraft performance canvas backing must be a non-null object.",
+    );
+  }
+  const keys = Reflect.ownKeys(canvasBacking);
+  if (keys.length !== 1 || keys[0] !== "canvasSelector") {
+    throw new Error(
+      'Toolcraft performance canvas backing must contain exactly one "canvasSelector" field.',
+    );
+  }
+  const descriptor = Object.getOwnPropertyDescriptor(
+    canvasBacking,
+    "canvasSelector",
+  );
+  if (!descriptor || !("value" in descriptor)) {
+    throw new Error(
+      "Toolcraft performance canvas backing canvasSelector must be a data property.",
+    );
+  }
+  const canvasSelector = descriptor.value;
+  if (
+    typeof canvasSelector !== "string" ||
+    canvasSelector.length === 0 ||
+    canvasSelector.trim() !== canvasSelector
+  ) {
+    throw new Error(
+      "Toolcraft performance canvas backing canvasSelector must be a non-empty trimmed string.",
+    );
+  }
+  return Object.freeze({ canvasSelector });
+}
+
+function compilePerformanceCanvasBackingBoundary({
+  canvasBacking,
+  schema,
+}: Pick<
+  ToolcraftPerformancePathAdapterMatrixInput,
+  "canvasBacking" | "schema"
+>): ToolcraftPerformanceCanvasBacking | undefined {
+  if (canvasBacking === undefined) {
+    if (!schema.canvas.renderScale.enabled) {
+      return undefined;
+    }
+    throw new Error(
+      "Toolcraft render-scale-enabled performance catalogs require one product canvas selector for 2x backing proof.",
+    );
+  }
+  if (!schema.canvas.renderScale.enabled) {
+    throw new Error(
+      "Toolcraft performance canvas backing proof must be omitted when canvas render scale is disabled.",
+    );
+  }
+  return compileToolcraftPerformanceCanvasBackingConfig(canvasBacking);
+}
+
 function compareCodeUnits(left: string, right: string): number {
   return left < right ? -1 : left > right ? 1 : 0;
 }
@@ -57,13 +130,17 @@ export function getToolcraftPerformancePathSettleFrames(
   path: Pick<ToolcraftPerformancePath, "interaction">,
 ): number | undefined {
   // A p95 distribution needs at least 20 samples to remain distinct from max.
-  return path.interaction === "initial-render" ? 20 : undefined;
+  return path.interaction === "animation-frame" ||
+    path.interaction === "export"
+    ? undefined
+    : 20;
 }
 
 export function compileToolcraftPerformancePathAdapterMatrix(
-  paths: readonly ToolcraftPerformancePath[],
-  adapters: readonly ToolcraftPerformancePathAdapter[],
+  input: ToolcraftPerformancePathAdapterMatrixInput,
 ): readonly ToolcraftCompiledPerformancePathAdapter[] {
+  const compiledCanvasBacking = compilePerformanceCanvasBackingBoundary(input);
+  const { adapters, paths } = input;
   const canonicalPaths = [...paths].sort((left, right) =>
     compareCodeUnits(left.id, right.id),
   );
@@ -100,17 +177,6 @@ export function compileToolcraftPerformancePathAdapterMatrix(
 
   for (const path of canonicalPaths) {
     const adapter = adaptersByPathId.get(path.id)!;
-    if (
-      isToolcraftRenderScalePerformancePath(path) &&
-      !adapter.renderScaleBacking
-    ) {
-      throw new Error(
-        `Toolcraft render-scale performance path "${path.id}" requires real backing-pixel proof configuration.`,
-      );
-    }
-    if (adapter.renderScaleBacking) {
-      assertToolcraftRenderScaleBackingProofConfig(adapter.renderScaleBacking);
-    }
     if (path.interaction === "export" && !adapter.output) {
       throw new Error(
         `Toolcraft export performance path "${path.id}" requires a protected output completion adapter.`,
@@ -135,6 +201,7 @@ export function compileToolcraftPerformancePathAdapterMatrix(
     canonicalPaths.map((path) =>
       Object.freeze({
         adapter: adaptersByPathId.get(path.id)!,
+        canvasBacking: compiledCanvasBacking,
         path,
         testName: getToolcraftPerformancePathTestName(path),
       }),
@@ -179,7 +246,7 @@ export async function runToolcraftPerformancePath(
 ): Promise<void> {
   const fixtureResolutionMode =
     readToolcraftPerformanceFixtureResolutionMode();
-  const { adapter, path } = entry;
+  const { adapter, canvasBacking, path } = entry;
   const canonicalPath = deriveToolcraftPerformancePaths(schema, config).find(
     (candidate) => candidate.id === path.id,
   );
@@ -216,76 +283,128 @@ export async function runToolcraftPerformancePath(
     );
   }
 
+  const renderScaleEnabled = schema.canvas.renderScale.enabled;
+  if (renderScaleEnabled !== (canvasBacking !== undefined)) {
+    throw new Error(
+      "Toolcraft performance canvas backing presence must match the resolved render-scale schema.",
+    );
+  }
+  const baselineCssSize = renderScaleEnabled
+    ? await expectToolcraftCanvasBackingPixelsForRenderScale(
+        page,
+        canvasBacking!.canvasSelector,
+        TOOLCRAFT_CANVAS_RENDER_SCALE.defaultValue,
+        { state: "performance-baseline" },
+      )
+    : undefined;
+  const canvasQualityGuard = baselineCssSize
+    ? await createToolcraftPerformanceCanvasQualityGuard(page, {
+        baselineCssSize,
+        canvasSelector: canvasBacking!.canvasSelector,
+        cssSizePolicy:
+          path.interaction === "viewport-zoom" ? "viewport-driven" : "fixed",
+        pathId: path.id,
+      })
+    : undefined;
+
   const budget = getToolcraftPerformancePathBudget(path, config.scenarios);
   const target = getPathTarget(path);
-  await expectToolcraftPipelineInvariant(
-    page,
-    config,
-    path.id,
-    async (phase) => {
-      const context = Object.freeze({ page, path, phase });
-      let result;
-      if (adapter.output?.kind === "download") {
-        const measured = await measureToolcraftDownloadActionByLabel(
-          page,
-          adapter.output.label,
-          { pathId: path.id, phase, profile: path.profile, target },
-        );
-        result = measured.result;
-        await adapter.output.verify(measured.completion, page);
-      } else if (adapter.output?.kind === "clipboard") {
-        const measured = await measureToolcraftClipboardActionByLabel(
-          page,
-          adapter.output.label,
-          { pathId: path.id, phase, profile: path.profile, target },
-        );
-        result = measured.result;
-        await adapter.output.verify(measured.completion, page);
-      } else if (path.interaction === "animation-frame") {
-        await adapter.action(context);
-        result = await measureToolcraftAnimationFrames(page, 120, {
-          pathId: path.id,
-          phase,
-          profile: path.profile,
-          target,
-        });
-        await adapter.verifyOutcome?.(context);
-      } else {
-        result = await measureToolcraftInteraction(
-          page,
-          () => adapter.action(context),
-          {
-            ...(adapter.observeOutcome
-              ? { observeOutcome: () => adapter.observeOutcome!(context) }
-              : {}),
+  let hasPrimaryFailure = false;
+  try {
+    await expectToolcraftPipelineInvariant(
+      page,
+      config,
+      path.id,
+      async (phase) => {
+        const context = Object.freeze({ page, path, phase });
+        const measurePhase = async () => {
+          if (adapter.output?.kind === "download") {
+            const measured = await measureToolcraftDownloadActionByLabel(
+              page,
+              adapter.output.label,
+              { pathId: path.id, phase, profile: path.profile, target },
+            );
+            await adapter.output.verify(measured.completion, page);
+            return measured.result;
+          }
+          if (adapter.output?.kind === "clipboard") {
+            const measured = await measureToolcraftClipboardActionByLabel(
+              page,
+              adapter.output.label,
+              { pathId: path.id, phase, profile: path.profile, target },
+            );
+            await adapter.output.verify(measured.completion, page);
+            return measured.result;
+          }
+          if (path.interaction === "animation-frame") {
+            await adapter.action(context);
+            const result = await measureToolcraftAnimationFrames(page, 120, {
+              pathId: path.id,
+              phase,
+              profile: path.profile,
+              target,
+            });
+            await adapter.verifyOutcome?.(context);
+            return result;
+          }
+          const result = await measureToolcraftInteraction(
+            page,
+            () => adapter.action(context),
+            {
+              ...(adapter.observeOutcome
+                ? { observeOutcome: () => adapter.observeOutcome!(context) }
+                : {}),
+              pathId: path.id,
+              phase,
+              profile: path.profile,
+              settleFrames: getToolcraftPerformancePathSettleFrames(path),
+              target,
+            },
+          );
+          await adapter.verifyOutcome?.(context);
+          return result;
+        };
+        const result = canvasQualityGuard
+          ? await canvasQualityGuard.runPhase(phase, measurePhase)
+          : await measurePhase();
+        expectToolcraftPerformanceBudget(result, budget);
+        await attachPathEvidence("performance-budget", path);
+
+        if (
+          path.interaction === "control-drag" ||
+          path.interaction === "mask-drag"
+        ) {
+          await attachPathEvidence("performance-control-drag", path);
+        }
+        if (
+          path.interaction === "viewport-drag" ||
+          path.interaction === "viewport-zoom"
+        ) {
+          await attachPathEvidence("performance-viewport", path);
+        }
+        if (canvasBacking) {
+          await expectToolcraftPerformanceRenderScaleBackingEvidence(page, {
+            baselineCssSize: baselineCssSize!,
+            canvasSelector: canvasBacking.canvasSelector,
+            cssSizePolicy:
+              path.interaction === "viewport-zoom"
+                ? "viewport-driven"
+                : "fixed",
             pathId: path.id,
             phase,
-            profile: path.profile,
-            settleFrames: getToolcraftPerformancePathSettleFrames(path),
             target,
-          },
-        );
-        await adapter.verifyOutcome?.(context);
-      }
-      expectToolcraftPerformanceBudget(result, budget);
-      await attachPathEvidence("performance-budget", path);
-
-      if (path.interaction === "control-drag" || path.interaction === "mask-drag") {
-        await attachPathEvidence("performance-control-drag", path);
-      }
-      if (
-        path.interaction === "viewport-drag" ||
-        path.interaction === "viewport-zoom"
-      ) {
-        await attachPathEvidence("performance-viewport", path);
-      }
-      if (isToolcraftRenderScalePerformancePath(path)) {
-        await expectToolcraftPerformanceRenderScaleBackingEvidence(page, {
-          ...adapter.renderScaleBacking!,
-          pathId: path.id,
-          target,
-        });
-      }
-    },
-  );
+          });
+        }
+      },
+    );
+  } catch (error) {
+    hasPrimaryFailure = true;
+    throw error;
+  } finally {
+    try {
+      await canvasQualityGuard?.dispose();
+    } catch (error) {
+      if (!hasPrimaryFailure) throw error;
+    }
+  }
 }

package/templates/starter/e2e/performance-pipeline-evidence-continuity.spec.ts

@@ -3,6 +3,7 @@ import { expect, test } from "@playwright/test";
 import {
   activePipelineAttachments,
   activePipelinePath,
+  animationPipelinePath,
   evaluatePipelineEvidence,
   initialPipelineAttachments,
   initialPipelinePath,
@@ -76,6 +77,81 @@ test("ordinary paths require exact cross-phase continuity", () => {
   );
 });
 
+test("autonomous animation permits only its invalidated passes to advance between phases", () => {
+  const observation = (
+    phase: "cold" | "warm" | "sustained",
+    beforeExecutions: number,
+    afterExecutions: number,
+  ) =>
+    pipelineEvidenceAttachment(
+      pipelineEvidence(
+        phase,
+        noCacheActivitySnapshot(beforeExecutions),
+        noCacheActivitySnapshot(afterExecutions),
+        animationPipelinePath,
+      ),
+    );
+  const valid = evaluatePipelineEvidence(
+    [
+      observation("cold", 0, 2),
+      observation("warm", 5, 7),
+      observation("sustained", 10, 12),
+    ],
+    [animationPipelinePath.id],
+  );
+  const decodeAdvanced = pipelineSnapshot({
+    composite: {
+      cacheMisses: 5,
+      durationMax: 1,
+      durationTotal: 5,
+      executions: 5,
+    },
+    decode: {
+      activeResources: 1,
+      cacheMisses: 1,
+      durationMax: 1,
+      durationTotal: 1,
+      executions: 1,
+      resourceCreations: 1,
+    },
+  });
+  const invalid = evaluatePipelineEvidence(
+    [
+      observation("cold", 0, 2),
+      pipelineEvidenceAttachment(
+        pipelineEvidence(
+          "warm",
+          decodeAdvanced,
+          pipelineSnapshot({
+            composite: {
+              cacheMisses: 7,
+              durationMax: 1,
+              durationTotal: 7,
+              executions: 7,
+            },
+            decode: {
+              activeResources: 1,
+              cacheMisses: 1,
+              durationMax: 1,
+              durationTotal: 1,
+              executions: 1,
+              resourceCreations: 1,
+            },
+          }),
+          animationPipelinePath,
+        ),
+      ),
+      observation("sustained", 10, 12),
+    ],
+    [animationPipelinePath.id],
+  );
+
+  expect(valid.errors).toEqual([]);
+  expect(invalid.errors).toContainEqual(
+    expect.stringMatching(/cold\.after to warm\.before/i),
+  );
+});
+
 test("initial-render uses fresh canonical zero lifecycle samples without continuity", () => {
   const valid = evaluatePipelineEvidence(initialPipelineAttachments(), [
     initialPipelinePath.id,

package/templates/starter/e2e/performance-pipeline-evidence-test-fixtures.ts

@@ -67,6 +67,12 @@ export const pipelineEvidenceRegistration =
         mustNotInvalidate: ["decode"],
         targets: ["canvas.initial-render"],
       },
+      {
+        interaction: "animation-frame",
+        invalidates: ["composite"],
+        mustNotInvalidate: ["decode"],
+        targets: ["runtime.animation-frame"],
+      },
       {
         interaction: "control-drag",
         invalidates: ["composite"],
@@ -116,8 +122,8 @@ export const pipelineEvidenceRegistration =
           relationship: "constant",
         },
         id: "composite",
-        inputs: ["decode", "effect.strength"],
-        invalidatedBy: ["effect.strength"],
+        inputs: ["decode", "effect.strength", "runtime.animation-frame"],
+        invalidatedBy: ["effect.strength", "runtime.animation-frame"],
         kind: "composite",
         output: "preview",
         quality: "full",
@@ -142,6 +148,9 @@ const performancePaths = deriveToolcraftPerformancePaths(
 export const activePipelinePath = performancePaths.find(
   (path) => path.interaction === "control-drag",
 )!;
+export const animationPipelinePath = performancePaths.find(
+  (path) => path.interaction === "animation-frame",
+)!;
 export const initialPipelinePath = performancePaths.find(
   (path) => path.interaction === "initial-render",
 )!;

package/templates/starter/e2e/performance-pipeline-invariants.ts

@@ -151,6 +151,35 @@ function snapshotsMatch(
   });
 }
 
+function snapshotsPreserveContinuousAnimation(
+  left: ToolcraftPerformancePipelineSnapshot,
+  right: ToolcraftPerformancePipelineSnapshot,
+  invalidatedPassIds: ReadonlySet<string>,
+): boolean {
+  if (
+    left.disposed !== right.disposed ||
+    left.runtimeId !== right.runtimeId ||
+    left.passes.length !== right.passes.length
+  ) {
+    return false;
+  }
+  const rightByPass = pipelinePassMap(right);
+  return left.passes.every((leftPass) => {
+    const rightPass = rightByPass.get(leftPass.passId);
+    if (!rightPass) return false;
+    if (!invalidatedPassIds.has(leftPass.passId)) {
+      return TOOLCRAFT_PERFORMANCE_PIPELINE_METRIC_KEYS.every(
+        (key) => leftPass[key] === rightPass[key],
+      );
+    }
+    return TOOLCRAFT_PERFORMANCE_PIPELINE_METRIC_KEYS.every((key) =>
+      key === "activeResources"
+        ? leftPass[key] === rightPass[key]
+        : leftPass[key] <= rightPass[key],
+    );
+  });
+}
+
 export function getPipelinePhaseContinuityErrors({
   cold,
   path,
@@ -164,15 +193,29 @@ export function getPipelinePhaseContinuityErrors({
 }): string[] {
   if (path.interaction === "initial-render") return [];
 
+  const continuousAnimation = path.interaction === "animation-frame";
+  const invalidatedPassIds = new Set(path.invalidates);
+  const snapshotsPreservePhaseBoundary =
+    continuousAnimation
+      ? (left: ToolcraftPerformancePipelineSnapshot, right: ToolcraftPerformancePipelineSnapshot) =>
+          snapshotsPreserveContinuousAnimation(
+            left,
+            right,
+            invalidatedPassIds,
+          )
+      : snapshotsMatch;
+  const continuityRequirement = continuousAnimation
+    ? "monotonic invalidated-pass and exact non-invalidated-pass"
+    : "exact";
   const errors: string[] = [];
-  if (!snapshotsMatch(cold.after, warm.before)) {
+  if (!snapshotsPreservePhaseBoundary(cold.after, warm.before)) {
     errors.push(
-      `Path "${path.id}" must preserve exact pipeline counters from cold.after to warm.before.`,
+      `Path "${path.id}" must preserve ${continuityRequirement} pipeline counters from cold.after to warm.before.`,
     );
   }
-  if (!snapshotsMatch(warm.after, sustained.before)) {
+  if (!snapshotsPreservePhaseBoundary(warm.after, sustained.before)) {
     errors.push(
-      `Path "${path.id}" must preserve exact pipeline counters from warm.after to sustained.before.`,
+      `Path "${path.id}" must preserve ${continuityRequirement} pipeline counters from warm.after to sustained.before.`,
     );
   }
   return errors;