@pixel-point/toolcraft 0.0.16 → 0.0.17

package/templates/starter/e2e/export-artifact-helpers.ts

@@ -1,12 +1,52 @@
-export type ToolcraftExportArtifactInspection = {
+export type ToolcraftNormalizedPixelBounds = Readonly<{
+  height: number;
+  width: number;
+  x: number;
+  y: number;
+}>;
+
+export type ToolcraftBinaryArtifactInspection = Readonly<{
   byteLength: number;
   contentHash?: string;
   durationMs?: number;
   frameCount?: number;
   height?: number;
+  kind?: "binary";
   mediaType?: string;
   width?: number;
-};
+}>;
+
+export type ToolcraftImageArtifactInspection = Readonly<{
+  byteLength: number;
+  decodedPixelHash: string;
+  height: number;
+  kind: "image";
+  mediaType: "image/jpeg" | "image/png";
+  nonBackgroundBounds: ToolcraftNormalizedPixelBounds | null;
+  width: number;
+}>;
+
+export type ToolcraftVideoPacketTiming = Readonly<{
+  durationSeconds: number;
+  timeSeconds: number;
+}>;
+
+export type ToolcraftVideoArtifactInspection = Readonly<{
+  byteLength: number;
+  durationMs: number;
+  frameCount: number;
+  height: number;
+  kind: "video";
+  mediaType: "video/mp4" | "video/webm";
+  packetTimings: readonly ToolcraftVideoPacketTiming[];
+  samplePixelHashes: readonly string[];
+  width: number;
+}>;
+
+export type ToolcraftExportArtifactInspection =
+  | ToolcraftBinaryArtifactInspection
+  | ToolcraftImageArtifactInspection
+  | ToolcraftVideoArtifactInspection;
 
 export type ToolcraftExportArtifactInspectionResult =
   | ToolcraftExportArtifactInspection
@@ -33,13 +73,46 @@ function assertPositiveInteger(
   field: string,
   requirementId: string,
 ): asserts value is number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+    throw new Error(
+      `Export requirement "${requirementId}" must report a positive ${field} integer.`,
+    );
+  }
+}
+
+function validateNormalizedPixelBounds(
+  value: unknown,
+  requirementId: string,
+): void {
+  if (value === null) return;
+  if (!isRecord(value)) {
+    throw new Error(
+      `Export requirement "${requirementId}" must report normalized nonBackgroundBounds or null.`,
+    );
+  }
+  const { height, width, x, y } = value;
+  for (const [field, coordinate] of Object.entries({ height, width, x, y })) {
+    if (
+      typeof coordinate !== "number" ||
+      !Number.isFinite(coordinate) ||
+      coordinate < 0 ||
+      coordinate > 1 ||
+      ((field === "height" || field === "width") && coordinate === 0)
+    ) {
+      throw new Error(
+        `Export requirement "${requirementId}" must report normalized nonBackgroundBounds.${field}.`,
+      );
+    }
+  }
   if (
-    typeof value !== "number" ||
-    !Number.isSafeInteger(value) ||
-    value <= 0
+    typeof x === "number" &&
+    typeof y === "number" &&
+    typeof width === "number" &&
+    typeof height === "number" &&
+    (x + width > 1 || y + height > 1)
   ) {
     throw new Error(
-      `Export requirement "${requirementId}" must report a positive ${field} integer.`,
+      `Export requirement "${requirementId}" nonBackgroundBounds must remain inside the normalized artifact.`,
     );
   }
 }
@@ -64,25 +137,12 @@ export function assertToolcraftProducedArtifact(
   }
 }
 
-export function validateToolcraftExportArtifactInspection(
-  observation: unknown,
+function validateInspection(
+  inspection: Record<string, unknown>,
   requirementId: string,
-): ToolcraftExportArtifactInspectionResult {
-  const observations = Array.isArray(observation) ? observation : [observation];
-  if (observations.length === 0) {
-    throw new Error(
-      `Export requirement "${requirementId}" must inspect at least one artifact.`,
-    );
-  }
-
-  for (const inspection of observations) {
-    if (!isRecord(inspection) || !("byteLength" in inspection)) {
-      throw new Error(
-        `Export requirement "${requirementId}" must return a typed artifact inspection with byteLength.`,
-      );
-    }
-
-    assertPositiveInteger(inspection.byteLength, "byteLength", requirementId);
+): void {
+  assertPositiveInteger(inspection.byteLength, "byteLength", requirementId);
+  if (inspection.kind === undefined || inspection.kind === "binary") {
     if (inspection.durationMs !== undefined) {
       assertPositiveFiniteNumber(
         inspection.durationMs,
@@ -105,6 +165,108 @@ export function validateToolcraftExportArtifactInspection(
         );
       }
     }
+    return;
+  }
+
+  if (inspection.kind === "image") {
+    assertPositiveInteger(inspection.width, "width", requirementId);
+    assertPositiveInteger(inspection.height, "height", requirementId);
+    if (
+      inspection.mediaType !== "image/png" &&
+      inspection.mediaType !== "image/jpeg"
+    ) {
+      throw new Error(
+        `Export requirement "${requirementId}" must report a supported image mediaType.`,
+      );
+    }
+    if (
+      typeof inspection.decodedPixelHash !== "string" ||
+      !inspection.decodedPixelHash.trim()
+    ) {
+      throw new Error(
+        `Export requirement "${requirementId}" must hash decoded image pixels.`,
+      );
+    }
+    validateNormalizedPixelBounds(
+      inspection.nonBackgroundBounds,
+      requirementId,
+    );
+    return;
+  }
+
+  if (inspection.kind === "video") {
+    assertPositiveInteger(inspection.width, "width", requirementId);
+    assertPositiveInteger(inspection.height, "height", requirementId);
+    assertPositiveInteger(inspection.frameCount, "frameCount", requirementId);
+    assertPositiveFiniteNumber(inspection.durationMs, "durationMs", requirementId);
+    if (
+      inspection.mediaType !== "video/mp4" &&
+      inspection.mediaType !== "video/webm"
+    ) {
+      throw new Error(
+        `Export requirement "${requirementId}" must report a supported video mediaType.`,
+      );
+    }
+    if (
+      !Array.isArray(inspection.packetTimings) ||
+      inspection.packetTimings.length !== inspection.frameCount
+    ) {
+      throw new Error(
+        `Export requirement "${requirementId}" must report every real encoded packet timing.`,
+      );
+    }
+    for (const [index, timing] of inspection.packetTimings.entries()) {
+      if (
+        !isRecord(timing) ||
+        typeof timing.timeSeconds !== "number" ||
+        !Number.isFinite(timing.timeSeconds) ||
+        timing.timeSeconds < 0 ||
+        typeof timing.durationSeconds !== "number" ||
+        !Number.isFinite(timing.durationSeconds) ||
+        timing.durationSeconds <= 0
+      ) {
+        throw new Error(
+          `Export requirement "${requirementId}" must report valid timing for encoded packet ${index}.`,
+        );
+      }
+    }
+    if (
+      !Array.isArray(inspection.samplePixelHashes) ||
+      inspection.samplePixelHashes.length === 0 ||
+      inspection.samplePixelHashes.some(
+        (hash) => typeof hash !== "string" || !hash.trim(),
+      )
+    ) {
+      throw new Error(
+        `Export requirement "${requirementId}" must hash decoded video samples.`,
+      );
+    }
+    return;
+  }
+
+  throw new Error(
+    `Export requirement "${requirementId}" returned an unknown artifact inspection kind.`,
+  );
+}
+
+export function validateToolcraftExportArtifactInspection(
+  observation: unknown,
+  requirementId: string,
+): ToolcraftExportArtifactInspectionResult {
+  const observations = Array.isArray(observation) ? observation : [observation];
+  if (observations.length === 0) {
+    throw new Error(
+      `Export requirement "${requirementId}" must inspect at least one artifact.`,
+    );
+  }
+
+  for (const inspection of observations) {
+    if (!isRecord(inspection) || !("byteLength" in inspection)) {
+      throw new Error(
+        `Export requirement "${requirementId}" must return a typed artifact inspection with byteLength.`,
+      );
+    }
+    validateInspection(inspection, requirementId);
   }
 
   return observation as ToolcraftExportArtifactInspectionResult;
@@ -115,12 +277,31 @@ export function getToolcraftSemanticArtifactSignature(
   requirementId: string,
 ): string {
   validateToolcraftExportArtifactInspection(inspection, requirementId);
+  if (inspection.kind === "image") {
+    return JSON.stringify({
+      decodedPixelHash: inspection.decodedPixelHash,
+      height: inspection.height,
+      mediaType: inspection.mediaType,
+      nonBackgroundBounds: inspection.nonBackgroundBounds,
+      width: inspection.width,
+    });
+  }
+  if (inspection.kind === "video") {
+    return JSON.stringify({
+      durationMs: inspection.durationMs,
+      frameCount: inspection.frameCount,
+      height: inspection.height,
+      mediaType: inspection.mediaType,
+      packetTimings: inspection.packetTimings,
+      samplePixelHashes: inspection.samplePixelHashes,
+      width: inspection.width,
+    });
+  }
   if (!inspection.contentHash?.trim()) {
     throw new Error(
       `Export requirement "${requirementId}" must report contentHash from decoded product output for semantic comparison.`,
     );
   }
-
   return JSON.stringify({
     contentHash: inspection.contentHash,
     durationMs: inspection.durationMs,

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

@@ -0,0 +1,41 @@
+import fs from "node:fs/promises";
+
+import { expect, test, type Download } from "@playwright/test";
+
+import { inspectToolcraftImageDownload } from "./image-artifact-inspection";
+
+test("image inspection hashes decoded pixels and reports product bounds", async ({
+  page,
+}, testInfo) => {
+  await page.goto("/");
+  const base64 = await page.evaluate(() => {
+    const canvas = document.createElement("canvas");
+    canvas.width = 64;
+    canvas.height = 32;
+    const context = canvas.getContext("2d");
+    if (!context) throw new Error("Missing test canvas context.");
+    context.fillStyle = "#000000";
+    context.fillRect(0, 0, 64, 32);
+    context.fillStyle = "#FF0000";
+    context.fillRect(16, 8, 32, 16);
+    return canvas.toDataURL("image/png").split(",")[1]!;
+  });
+  const artifactPath = testInfo.outputPath("decoded-fixture.png");
+  await fs.writeFile(artifactPath, Buffer.from(base64, "base64"));
+  const download = { path: async () => artifactPath } as Download;
+
+  const result = await inspectToolcraftImageDownload({
+    backgroundRgba: [0, 0, 0, 255],
+    download,
+    page,
+  });
+
+  expect(result.inspection).toMatchObject({
+    height: 32,
+    kind: "image",
+    mediaType: "image/png",
+    nonBackgroundBounds: { height: 0.5, width: 0.5, x: 0.25, y: 0.25 },
+    width: 64,
+  });
+  expect(result.inspection.decodedPixelHash).toMatch(/^[a-f0-9]{64}$/u);
+});

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

@@ -0,0 +1,99 @@
+import fs from "node:fs/promises";
+
+import type { Download, Page } from "@playwright/test";
+
+import {
+  observeToolcraftDecodedPixels,
+  type ToolcraftDecodedPixelObservation,
+} from "./decoded-pixel-observation";
+import type { ToolcraftImageArtifactInspection } from "./export-artifact-helpers";
+
+export type ToolcraftInspectedImageArtifact = Readonly<{
+  inspection: ToolcraftImageArtifactInspection;
+  observation: ToolcraftDecodedPixelObservation;
+}>;
+
+function detectImageMediaType(
+  bytes: Uint8Array,
+): "image/jpeg" | "image/png" {
+  if (
+    bytes.length >= 8 &&
+    bytes[0] === 0x89 &&
+    bytes[1] === 0x50 &&
+    bytes[2] === 0x4e &&
+    bytes[3] === 0x47
+  ) {
+    return "image/png";
+  }
+  if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8) {
+    return "image/jpeg";
+  }
+  throw new Error("Downloaded artifact is not a decodable PNG or JPEG image.");
+}
+
+export async function inspectToolcraftImageDownload({
+  backgroundRgba,
+  download,
+  page,
+}: Readonly<{
+  backgroundRgba: readonly [number, number, number, number];
+  download: Download;
+  page: Page;
+}>): Promise<ToolcraftInspectedImageArtifact> {
+  const downloadPath = await download.path();
+  if (!downloadPath) {
+    throw new Error("Playwright did not expose the downloaded image path.");
+  }
+  const bytes = await fs.readFile(downloadPath);
+  if (bytes.byteLength === 0) {
+    throw new Error("Downloaded image artifact is empty.");
+  }
+  const mediaType = detectImageMediaType(bytes);
+  const decoded = await page.evaluate(
+    async ({ base64, mediaType: decodedMediaType }) => {
+      const binary = atob(base64);
+      const data = Uint8Array.from(binary, (character) =>
+        character.charCodeAt(0),
+      );
+      const bitmap = await createImageBitmap(
+        new Blob([data], { type: decodedMediaType }),
+      );
+      try {
+        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 image pixels.");
+        context.imageSmoothingEnabled = false;
+        context.drawImage(bitmap, 0, 0, 64, 64);
+        return {
+          height: bitmap.height,
+          pixels: Array.from(context.getImageData(0, 0, 64, 64).data),
+          width: bitmap.width,
+        };
+      } finally {
+        bitmap.close();
+      }
+    },
+    { base64: bytes.toString("base64"), mediaType },
+  );
+  const observation = await observeToolcraftDecodedPixels({
+    backgroundRgba,
+    pixels: Uint8ClampedArray.from(decoded.pixels),
+    sourceHeight: 64,
+    sourceWidth: 64,
+  });
+
+  return Object.freeze({
+    inspection: Object.freeze({
+      byteLength: bytes.byteLength,
+      decodedPixelHash: observation.decodedPixelHash,
+      height: decoded.height,
+      kind: "image",
+      mediaType,
+      nonBackgroundBounds: observation.nonBackgroundBounds,
+      width: decoded.width,
+    }),
+    observation,
+  });
+}

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

@@ -38,22 +38,22 @@ export async function dragToolcraftCanvasViewport(
 
 export async function zoomToolcraftCanvasViewport(
   page: Page,
-  repetitions = 2,
-  options: { pathId?: string } = {},
+  options: {
+    direction: "in" | "out";
+    pathId?: string;
+    repetitions?: number;
+  },
 ): Promise<void> {
   const zoomIn = page.getByRole("button", { name: "Zoom in" });
   const zoomOut = page.getByRole("button", { name: "Zoom out" });
+  const control = options.direction === "in" ? zoomIn : zoomOut;
+  await expect(
+    control,
+    `Toolcraft zoom-${options.direction} control should be visible`,
+  ).toBeVisible();
 
-  await expect(zoomIn, "Toolcraft zoom-in control should be visible").toBeVisible();
-  await expect(zoomOut, "Toolcraft zoom-out control should be visible").toBeVisible();
-
-  for (let index = 0; index < repetitions; index += 1) {
-    await zoomIn.click();
-    await waitForToolcraftAnimationFrames(page, 2);
-  }
-
-  for (let index = 0; index < repetitions; index += 1) {
-    await zoomOut.click();
+  for (let index = 0; index < (options.repetitions ?? 1); index += 1) {
+    await control.click();
     await waitForToolcraftAnimationFrames(page, 2);
   }
   if (options.pathId) {
@@ -70,17 +70,18 @@ export async function readToolcraftCanvasViewport(page: Page): Promise<{
   zoom: number;
 }> {
   return page.evaluate(() => {
-    const canvas = document.querySelector("[data-toolcraft-editable-canvas]");
-    const style = canvas ? window.getComputedStyle(canvas) : null;
-    const zoomText =
-      canvas?.getAttribute("data-canvas-zoom") ??
-      style?.getPropertyValue("--canvas-zoom") ??
-      "1";
+    const world = document.querySelector("[data-toolcraft-canvas-world]");
 
     return {
-      offsetX: Number(canvas?.getAttribute("data-canvas-offset-x") ?? 0),
-      offsetY: Number(canvas?.getAttribute("data-canvas-offset-y") ?? 0),
-      zoom: Number.parseFloat(zoomText) || 1,
+      offsetX: Number(
+        world?.getAttribute("data-toolcraft-canvas-offset-x") ?? 0,
+      ),
+      offsetY: Number(
+        world?.getAttribute("data-toolcraft-canvas-offset-y") ?? 0,
+      ),
+      zoom: Number.parseFloat(
+        world?.getAttribute("data-toolcraft-canvas-zoom") ?? "100",
+      ) || 100,
     };
   });
 }