@pixel-point/toolcraft 0.0.16 → 0.0.17

package/templates/starter/e2e/performance-render-scale-runner.spec.ts

@@ -1,12 +1,15 @@
 import { expect, test, type Page, type TestInfo } from "@playwright/test";
 import {
+  defineToolcraft,
   defineToolcraftPerformance,
   deriveToolcraftPerformancePaths,
   registerToolcraftRendererPipeline,
   type ToolcraftRendererPipelinePassContract,
 } from "@repo/toolcraft-runtime";
+import type {
+  ToolcraftPerformancePipelinePhase,
+} from "../src/app/test-evidence/browser-performance-contract";
 
-import { starterSchema } from "../src/app/starter-schema";
 import { attachedEvidenceTypes } from "./browser-semantic-evidence-test-helpers";
 import {
   compileToolcraftPerformancePathAdapterMatrix,
@@ -18,6 +21,54 @@ import {
 } from "./performance-fixture-selection";
 
 const canvasSelector = "[data-render-scale-canvas]";
+const originalFixtureResolutionMode =
+  process.env[TOOLCRAFT_PERFORMANCE_FIXTURE_RESOLUTION_MODE_ENV];
+const originalRequestAuthorityHash =
+  process.env[TOOLCRAFT_PERFORMANCE_REQUEST_AUTHORITY_HASH_ENV];
+
+test.beforeEach(() => {
+  process.env[TOOLCRAFT_PERFORMANCE_FIXTURE_RESOLUTION_MODE_ENV] =
+    "full-certification";
+  delete process.env[TOOLCRAFT_PERFORMANCE_REQUEST_AUTHORITY_HASH_ENV];
+});
+
+test.afterEach(() => {
+  if (originalFixtureResolutionMode === undefined) {
+    delete process.env[TOOLCRAFT_PERFORMANCE_FIXTURE_RESOLUTION_MODE_ENV];
+  } else {
+    process.env[TOOLCRAFT_PERFORMANCE_FIXTURE_RESOLUTION_MODE_ENV] =
+      originalFixtureResolutionMode;
+  }
+  if (originalRequestAuthorityHash === undefined) {
+    delete process.env[TOOLCRAFT_PERFORMANCE_REQUEST_AUTHORITY_HASH_ENV];
+  } else {
+    process.env[TOOLCRAFT_PERFORMANCE_REQUEST_AUTHORITY_HASH_ENV] =
+      originalRequestAuthorityHash;
+  }
+});
+
+const renderScaleSchema = defineToolcraft({
+  canvas: { enabled: true, renderScale: true },
+  panels: {
+    controls: {
+      sections: [
+        {
+          controls: {
+            color: {
+              defaultValue: "#ffffff",
+              label: "Color",
+              performanceRole: "responsiveness",
+              target: "appearance.color",
+              type: "color",
+            },
+          },
+          title: "Appearance",
+        },
+      ],
+      title: "Controls",
+    },
+  },
+});
 
 type RenderScalePipelinePasses = {
   composite: ToolcraftRendererPipelinePassContract<void>;
@@ -27,10 +78,10 @@ const renderScaleRegistration =
   registerToolcraftRendererPipeline<RenderScalePipelinePasses>()({
     interactionInvalidation: [
       {
-        interaction: "control-change",
+        interaction: "control-drag",
         invalidates: ["composite"],
         mustNotInvalidate: [],
-        targets: ["canvas.renderScale"],
+        targets: ["appearance.color"],
       },
     ],
     passes: [
@@ -41,8 +92,8 @@ const renderScaleRegistration =
           relationship: "constant",
         },
         id: "composite",
-        inputs: ["canvas.renderScale"],
-        invalidatedBy: ["canvas.renderScale"],
+        inputs: ["appearance.color"],
+        invalidatedBy: ["appearance.color"],
         kind: "composite",
         output: "preview",
         quality: "full",
@@ -62,7 +113,7 @@ const renderScalePerformance = defineToolcraftPerformance({
 });
 
 const [renderScalePath] = deriveToolcraftPerformancePaths(
-  starterSchema,
+  renderScaleSchema,
   renderScalePerformance,
 );
 
@@ -121,15 +172,17 @@ async function installFixture(page: Page): Promise<void> {
   }, renderScaleRegistration.runtimeId);
 }
 
+type PhaseScale = Readonly<Record<ToolcraftPerformancePipelinePhase, number>>;
+
 function compileRunner(
-  backingScaleAfterAction: number,
+  backingScaleByPhase: PhaseScale,
   prepare: () => Promise<void> = async () => undefined,
+  afterAction?: (page: Page) => Promise<void>,
 ) {
-  return compileToolcraftPerformancePathAdapterMatrix(
-    [renderScalePath!],
-    [
+  return compileToolcraftPerformancePathAdapterMatrix({
+    adapters: [
       {
-        action: async ({ page }) => {
+        action: async ({ page, phase }) => {
           await page.evaluate(({ scale, selector }) => {
             const state = Reflect.get(
               globalThis,
@@ -164,7 +217,8 @@ function compileRunner(
             canvas.height = Math.round(
               rect.height * window.devicePixelRatio * scale,
             );
-          }, { scale: backingScaleAfterAction, selector: canvasSelector });
+          }, { scale: backingScaleByPhase[phase], selector: canvasSelector });
+          await afterAction?.(page);
         },
         observeOutcome: ({ page }) =>
           page.evaluate(
@@ -178,15 +232,54 @@ function compileRunner(
           ),
         pathId: renderScalePath!.id,
         prepare,
-        renderScaleBacking: {
-          canvasSelector,
-          selectedScale: 2,
-        },
       },
     ],
-  )[0]!;
+    canvasBacking: { canvasSelector },
+    paths: [renderScalePath!],
+    schema: renderScaleSchema,
+  })[0]!;
 }
 
+test("runner preserves an undefined phase rejection when guard disposal fails", async ({
+  page,
+}) => {
+  await installFixture(page);
+  const outcome = await runToolcraftPerformancePath(
+    page,
+    renderScaleSchema,
+    renderScalePerformance,
+    compileRunner(
+      { cold: 2, sustained: 2, warm: 2 },
+      async () => undefined,
+      async (currentPage) => {
+        await currentPage.evaluate(() => {
+          const stateKey = Object.getOwnPropertyNames(globalThis).find((key) =>
+            key.startsWith("__toolcraftCanvasQualityObserver"),
+          );
+          if (!stateKey) {
+            throw new Error("Quality guard fixture could not find observer state.");
+          }
+          const state = Reflect.get(globalThis, stateKey) as {
+            flush: () => Promise<void>;
+          };
+          Reflect.set(globalThis, stateKey, {
+            dispose: () => {
+              throw new Error("forced guard disposal failure");
+            },
+            flush: state.flush,
+          });
+        });
+        return Promise.reject(undefined);
+      },
+    ),
+  ).then(
+    () => ({ status: "resolved" as const }),
+    (reason: unknown) => ({ reason, status: "rejected" as const }),
+  );
+
+  expect(outcome).toEqual({ reason: undefined, status: "rejected" });
+});
+
 test("requestless performance runner rejects before adapter operations", async ({
   page,
 }) => {
@@ -202,9 +295,9 @@ test("requestless performance runner rejects before adapter operations", async (
     await expect(
       runToolcraftPerformancePath(
         page,
-        starterSchema,
+        renderScaleSchema,
         renderScalePerformance,
-        compileRunner(2, async () => {
+        compileRunner({ cold: 2, sustained: 2, warm: 2 }, async () => {
           prepareCount += 1;
         }),
       ),
@@ -234,9 +327,9 @@ test("browser perf: runner proves real render-scale backing", async ({
 
   await runToolcraftPerformancePath(
     page,
-    starterSchema,
+    renderScaleSchema,
     renderScalePerformance,
-    compileRunner(2),
+    compileRunner({ cold: 2, sustained: 2, warm: 2 }),
   );
 
   expect(
@@ -246,21 +339,30 @@ test("browser perf: runner proves real render-scale backing", async ({
   ).toHaveLength(3);
 });
 
-test("browser perf: runner rejects a render-scale quality clamp", async ({
-  page,
-}, testInfo: TestInfo) => {
-  await installFixture(page);
-  const attachmentCount = testInfo.attachments.length;
+for (const failedPhase of ["cold", "warm", "sustained"] as const) {
+  test(`browser perf: runner rejects a ${failedPhase} render-scale quality clamp`, async ({
+    page,
+  }, testInfo: TestInfo) => {
+    await installFixture(page);
+    const attachmentCount = testInfo.attachments.length;
+    const scaleByPhase: PhaseScale = { cold: 2, sustained: 2, warm: 2 };
 
-  await expect(
-    runToolcraftPerformancePath(
-      page,
-      starterSchema,
-      renderScalePerformance,
-      compileRunner(1),
-    ),
-  ).rejects.toThrow(/backing width.*Resolution scale 2/iu);
-  expect(attachedEvidenceTypes(testInfo, attachmentCount)).not.toContain(
-    "performance-render-scale",
-  );
-});
+    await expect(
+      runToolcraftPerformancePath(
+        page,
+        renderScaleSchema,
+        renderScalePerformance,
+        compileRunner({ ...scaleByPhase, [failedPhase]: 1 }),
+      ),
+    ).rejects.toThrow(new RegExp(`${failedPhase}.*backing width`, "iu"));
+    const attachedQuality = testInfo.attachments
+      .slice(attachmentCount)
+      .filter((attachment) =>
+        attachment.body?.toString().includes("performance-render-scale"),
+      )
+      .map((attachment) => attachment.body?.toString() ?? "");
+    expect(attachedQuality).not.toContainEqual(
+      expect.stringContaining(`${renderScalePath!.id}#${failedPhase}`),
+    );
+  });
+}

package/templates/starter/e2e/video-artifact-inspection.spec.ts

@@ -0,0 +1,64 @@
+import { expect, test } from "@playwright/test";
+
+import { assertToolcraftVideoPacketSchedule } from "./video-artifact-inspection";
+
+const schedule = Object.freeze([
+  Object.freeze({ durationSeconds: 1 / 30, index: 0, timeSeconds: 0 }),
+  Object.freeze({ durationSeconds: 1 / 30, index: 1, timeSeconds: 1 / 30 }),
+]);
+
+test("accepts real packet timings that match the runtime schedule", () => {
+  expect(() =>
+    assertToolcraftVideoPacketSchedule({
+      packetTimings: schedule,
+      schedule,
+      timeResolution: 90_000,
+    }),
+  ).not.toThrow();
+});
+
+test("rejects synthetic or dropped packet counts", () => {
+  expect(() =>
+    assertToolcraftVideoPacketSchedule({
+      packetTimings: schedule.slice(0, 1),
+      schedule,
+      timeResolution: 90_000,
+    }),
+  ).toThrow("contains 1 packets; runtime scheduled 2");
+});
+
+test("rejects packet timestamps that do not match runtime time", () => {
+  expect(() =>
+    assertToolcraftVideoPacketSchedule({
+      packetTimings: [
+        schedule[0]!,
+        { durationSeconds: 1 / 30, timeSeconds: 2 / 30 },
+      ],
+      schedule,
+      timeResolution: 90_000,
+    }),
+  ).toThrow("packet 1 timestamp");
+});
+
+test("rejects packet durations that do not match runtime cadence", () => {
+  expect(() =>
+    assertToolcraftVideoPacketSchedule({
+      packetTimings: [
+        schedule[0]!,
+        { durationSeconds: 2 / 30, timeSeconds: 1 / 30 },
+      ],
+      schedule,
+      timeResolution: 90_000,
+    }),
+  ).toThrow("packet 1 duration");
+});
+
+test("rejects missing timing authority", () => {
+  expect(() =>
+    assertToolcraftVideoPacketSchedule({
+      packetTimings: schedule,
+      schedule,
+      timeResolution: 0,
+    }),
+  ).toThrow("positive time resolution");
+});

package/templates/starter/e2e/video-artifact-inspection.ts

@@ -0,0 +1,281 @@
+import fs from "node:fs/promises";
+
+import type { Download, Page } from "@playwright/test";
+import {
+  ALL_FORMATS,
+  BlobSource,
+  EncodedPacketSink,
+  Input,
+} from "mediabunny";
+
+import {
+  observeToolcraftDecodedPixels,
+  type ToolcraftDecodedPixelObservation,
+} from "./decoded-pixel-observation";
+import type {
+  ToolcraftVideoArtifactInspection,
+  ToolcraftVideoPacketTiming,
+} from "./export-artifact-helpers";
+
+export type ToolcraftScheduledVideoFrame = Readonly<{
+  durationSeconds: number;
+  index: number;
+  timeSeconds: number;
+}>;
+
+export function assertToolcraftVideoPacketSchedule({
+  packetTimings,
+  schedule,
+  timeResolution,
+}: Readonly<{
+  packetTimings: readonly ToolcraftVideoPacketTiming[];
+  schedule: readonly ToolcraftScheduledVideoFrame[];
+  timeResolution: number;
+}>): void {
+  if (!Number.isFinite(timeResolution) || timeResolution <= 0) {
+    throw new Error("Video packet proof requires a positive time resolution.");
+  }
+  if (packetTimings.length !== schedule.length) {
+    throw new Error(
+      `Encoded video contains ${packetTimings.length} packets; runtime scheduled ${schedule.length}.`,
+    );
+  }
+
+  const toleranceSeconds = 1 / timeResolution;
+  for (const [index, actual] of packetTimings.entries()) {
+    const expected = schedule[index];
+    if (!expected) {
+      throw new Error(`Runtime schedule is missing frame ${index}.`);
+    }
+    if (
+      !Number.isFinite(actual.timeSeconds) ||
+      actual.timeSeconds < 0 ||
+      !Number.isFinite(actual.durationSeconds) ||
+      actual.durationSeconds <= 0
+    ) {
+      throw new Error(`Encoded packet ${index} has invalid timing metadata.`);
+    }
+    if (
+      Math.abs(actual.timeSeconds - expected.timeSeconds) > toleranceSeconds
+    ) {
+      throw new Error(
+        `Encoded packet ${index} timestamp does not match the runtime schedule.`,
+      );
+    }
+    if (
+      Math.abs(actual.durationSeconds - expected.durationSeconds) >
+      toleranceSeconds
+    ) {
+      throw new Error(
+        `Encoded packet ${index} duration does not match the runtime schedule.`,
+      );
+    }
+  }
+}
+
+export type ToolcraftInspectedVideoArtifact = Readonly<{
+  inspection: ToolcraftVideoArtifactInspection;
+  observations: readonly ToolcraftDecodedPixelObservation[];
+  sampleTimes: readonly number[];
+  timeResolution: number;
+}>;
+
+function detectVideoMediaType(bytes: Uint8Array): "video/mp4" | "video/webm" {
+  if (
+    bytes.length >= 8 &&
+    String.fromCharCode(...bytes.subarray(4, 8)) === "ftyp"
+  ) {
+    return "video/mp4";
+  }
+  if (
+    bytes.length >= 4 &&
+    bytes[0] === 0x1a &&
+    bytes[1] === 0x45 &&
+    bytes[2] === 0xdf &&
+    bytes[3] === 0xa3
+  ) {
+    return "video/webm";
+  }
+  throw new Error("Downloaded artifact is not a supported MP4 or WebM video.");
+}
+
+function getSampleTimes(
+  schedule: readonly ToolcraftScheduledVideoFrame[],
+): readonly number[] {
+  if (schedule.length === 0) {
+    throw new Error("Video inspection requires a non-empty runtime frame schedule.");
+  }
+  const indices = [...new Set([0, Math.floor(schedule.length / 2), schedule.length - 1])];
+  return Object.freeze(indices.map((index) => schedule[index]!.timeSeconds));
+}
+
+async function decodeSamplesInPage({
+  bytes,
+  mediaType,
+  page,
+  sampleTimes,
+}: Readonly<{
+  bytes: Uint8Array;
+  mediaType: "video/mp4" | "video/webm";
+  page: Page;
+  sampleTimes: readonly number[];
+}>): Promise<readonly Uint8ClampedArray[]> {
+  const samples = await page.evaluate(
+    async ({ base64, mediaType: decodedMediaType, times }) => {
+      const binary = atob(base64);
+      const data = Uint8Array.from(binary, (character) =>
+        character.charCodeAt(0),
+      );
+      const video = document.createElement("video");
+      video.muted = true;
+      video.playsInline = true;
+      video.preload = "auto";
+      const objectUrl = URL.createObjectURL(
+        new Blob([data], { type: decodedMediaType }),
+      );
+      video.src = objectUrl;
+      try {
+        await new Promise<void>((resolve, reject) => {
+          video.addEventListener("loadeddata", () => resolve(), { once: true });
+          video.addEventListener(
+            "error",
+            () => reject(new Error("Browser could not decode exported video.")),
+            { once: true },
+          );
+          video.load();
+        });
+        const canvas = document.createElement("canvas");
+        canvas.width = 64;
+        canvas.height = 64;
+        const context = canvas.getContext("2d", { willReadFrequently: true });
+        if (!context) throw new Error("Unable to inspect exported video pixels.");
+        const decodedSamples: number[][] = [];
+        for (const timeSeconds of times) {
+          if (Math.abs(video.currentTime - timeSeconds) > 1e-6) {
+            await new Promise<void>((resolve, reject) => {
+              video.addEventListener("seeked", () => resolve(), { once: true });
+              video.addEventListener(
+                "error",
+                () => reject(new Error("Browser could not seek exported video.")),
+                { once: true },
+              );
+              video.currentTime = timeSeconds;
+            });
+          }
+          context.clearRect(0, 0, 64, 64);
+          context.drawImage(video, 0, 0, 64, 64);
+          decodedSamples.push(
+            Array.from(context.getImageData(0, 0, 64, 64).data),
+          );
+        }
+        return decodedSamples;
+      } finally {
+        video.removeAttribute("src");
+        video.load();
+        URL.revokeObjectURL(objectUrl);
+      }
+    },
+    {
+      base64: Buffer.from(bytes).toString("base64"),
+      mediaType,
+      times: sampleTimes,
+    },
+  );
+  return Object.freeze(samples.map((sample) => Uint8ClampedArray.from(sample)));
+}
+
+export async function inspectToolcraftVideoDownload({
+  backgroundRgba,
+  download,
+  page,
+  schedule,
+}: Readonly<{
+  backgroundRgba: readonly [number, number, number, number];
+  download: Download;
+  page: Page;
+  schedule: readonly ToolcraftScheduledVideoFrame[];
+}>): Promise<ToolcraftInspectedVideoArtifact> {
+  const downloadPath = await download.path();
+  if (!downloadPath) {
+    throw new Error("Playwright did not expose the downloaded video path.");
+  }
+  const bytes = await fs.readFile(downloadPath);
+  if (bytes.byteLength === 0) {
+    throw new Error("Downloaded video artifact is empty.");
+  }
+  const mediaType = detectVideoMediaType(bytes);
+  const input = new Input({
+    formats: ALL_FORMATS,
+    source: new BlobSource(new Blob([bytes], { type: mediaType })),
+  });
+
+  let durationSeconds: number;
+  let height: number;
+  let packetTimings: ToolcraftVideoPacketTiming[];
+  let timeResolution: number;
+  let width: number;
+  try {
+    const tracks = await input.getVideoTracks();
+    const track = tracks[0];
+    if (!track) throw new Error("Exported video does not contain a video track.");
+    [durationSeconds, height, timeResolution, width] = await Promise.all([
+      input.computeDuration([track]),
+      track.getCodedHeight(),
+      track.getTimeResolution(),
+      track.getCodedWidth(),
+    ]);
+    packetTimings = [];
+    const sink = new EncodedPacketSink(track);
+    for await (const packet of sink.packets(undefined, undefined, {
+      metadataOnly: true,
+    })) {
+      packetTimings.push(
+        Object.freeze({
+          durationSeconds: packet.duration,
+          timeSeconds: packet.timestamp,
+        }),
+      );
+    }
+  } finally {
+    input.dispose();
+  }
+  packetTimings.sort((left, right) => left.timeSeconds - right.timeSeconds);
+
+  const sampleTimes = getSampleTimes(schedule);
+  const decodedSamples = await decodeSamplesInPage({
+    bytes,
+    mediaType,
+    page,
+    sampleTimes,
+  });
+  const observations = await Promise.all(
+    decodedSamples.map((pixels) =>
+      observeToolcraftDecodedPixels({
+        backgroundRgba,
+        pixels,
+        sourceHeight: 64,
+        sourceWidth: 64,
+      }),
+    ),
+  );
+  const inspection: ToolcraftVideoArtifactInspection = Object.freeze({
+    byteLength: bytes.byteLength,
+    durationMs: durationSeconds * 1000,
+    frameCount: packetTimings.length,
+    height,
+    kind: "video",
+    mediaType,
+    packetTimings: Object.freeze(packetTimings),
+    samplePixelHashes: Object.freeze(
+      observations.map(({ decodedPixelHash }) => decodedPixelHash),
+    ),
+    width,
+  });
+
+  return Object.freeze({
+    inspection,
+    observations: Object.freeze(observations),
+    sampleTimes,
+    timeResolution,
+  });
+}

package/templates/starter/gitignore

@@ -14,6 +14,7 @@ dist-ssr
 coverage
 test-results
 playwright-report
+.playwright-mcp
 
 # Local environment
 .env

package/templates/starter/package.json

@@ -38,6 +38,7 @@
     "cross-spawn": "^7.0.6",
     "fflate": "0.8.3",
     "lucide-react": "^0.511.0",
+    "mediabunny": "1.52.2",
     "meshoptimizer": "1.2.0",
     "motion": "^11.16.3",
     "react": "^19.2.0",

package/templates/starter/scripts/check-toolcraft-docs.mjs

@@ -78,6 +78,15 @@ const forbiddenTextPatterns = [
 const forbiddenModelContractPatterns = [
   /\bgeometry-only (?:3D )?model(?:s| bundle| bundles| app| apps| default)?\b/iu,
 ];
+const forbiddenPerformanceRoutingPatterns = [
+  /for a performance complaint only,\s+an exact request quote and the canonical affected performance path ids/iu,
+  /(?:\*\*)?performance complaint(?::\*\*|\.\*\*)[^\n]*(?:canonical affected path ids|targeted iteration)/iu,
+  /\ba performance complaint records[^\n]*(?:canonical affected path ids|targeted iteration)/iu,
+  /unresolved\s+`?needs-agent-judgment`?[^\n]*(?:creates neither|records neither|no `?performance intent)/iu,
+  /for unresolved\s+`?needs-agent-judgment`?[^\n]*no `?performance intent/iu,
+  /direct reports that the app lags[^\n]*select one performance iteration/iu,
+  /independent complaint still selects an iteration/iu,
+];
 
 async function readText(relativePath) {
   return fs.readFile(path.join(projectRoot, relativePath), "utf8");
@@ -172,6 +181,14 @@ for (const pattern of forbiddenModelContractPatterns) {
   }
 }
 
+for (const pattern of forbiddenPerformanceRoutingPatterns) {
+  if (pattern.test(combinedSource)) {
+    failures.push(
+      `local Toolcraft docs contain unconditional complaint routing ${pattern}`,
+    );
+  }
+}
+
 for (const term of [
   "bounded ZIP",
   "Blender-compatible fallback",