@pixel-point/toolcraft 0.0.16 → 0.0.18

package/templates/starter/e2e/decoded-pixel-observation.spec.ts

@@ -0,0 +1,74 @@
+import { expect, test } from "@playwright/test";
+
+import {
+  assertToolcraftExpectedDecodedPixels,
+  observeToolcraftDecodedPixels,
+  validateToolcraftExpectedDecodedPixels,
+} from "./decoded-pixel-observation";
+
+function createCenteredFixture(): Uint8ClampedArray {
+  const pixels = new Uint8ClampedArray(64 * 64 * 4);
+  for (let y = 0; y < 64; y += 1) {
+    for (let x = 0; x < 64; x += 1) {
+      const offset = (y * 64 + x) * 4;
+      const product = x >= 16 && x < 48 && y >= 16 && y < 48;
+      pixels.set(product ? [255, 0, 0, 255] : [0, 0, 0, 255], offset);
+    }
+  }
+  return pixels;
+}
+
+test("decoded pixels produce stable semantic bounds and hash", async () => {
+  const observation = await observeToolcraftDecodedPixels({
+    backgroundRgba: [0, 0, 0, 255],
+    pixels: createCenteredFixture(),
+    sourceHeight: 64,
+    sourceWidth: 64,
+  });
+
+  expect(observation.decodedPixelHash).toMatch(/^[a-f0-9]{64}$/u);
+  expect(observation.nonBackgroundBounds).toEqual({
+    height: 0.5,
+    width: 0.5,
+    x: 0.25,
+    y: 0.25,
+  });
+  expect(observation.centroid).toEqual({ x: 0.5, y: 0.5 });
+  expect(observation.occupiedAreaRatio).toBe(0.25);
+  expect(() =>
+    assertToolcraftExpectedDecodedPixels({
+      expectedPixels: [
+        { rgba: [255, 0, 0, 255], xRatio: 0.5, yRatio: 0.5 },
+      ],
+      mediaType: "image/png",
+      observation,
+    }),
+  ).not.toThrow();
+});
+
+test("decoded pixel expectations cannot provide empty, invalid, or loosened checks", async () => {
+  const observation = await observeToolcraftDecodedPixels({
+    backgroundRgba: [0, 0, 0, 255],
+    pixels: createCenteredFixture(),
+    sourceHeight: 64,
+    sourceWidth: 64,
+  });
+
+  expect(() => validateToolcraftExpectedDecodedPixels([])).toThrow(
+    "at least one exact pixel sample",
+  );
+  expect(() =>
+    validateToolcraftExpectedDecodedPixels([
+      { rgba: [256, 0, 0, 255], xRatio: 2, yRatio: 0 } as never,
+    ]),
+  ).toThrow();
+  expect(() =>
+    assertToolcraftExpectedDecodedPixels({
+      expectedPixels: [
+        { rgba: [0, 255, 0, 255], xRatio: 0.5, yRatio: 0.5 },
+      ],
+      mediaType: "image/png",
+      observation,
+    }),
+  ).toThrow("fixed tolerance is 0");
+});

package/templates/starter/e2e/decoded-pixel-observation.ts

@@ -0,0 +1,227 @@
+import type { ToolcraftNormalizedPixelBounds } from "./export-artifact-helpers";
+
+export const TOOLCRAFT_DECODED_OBSERVATION_SIZE = 64;
+export const TOOLCRAFT_LOSSLESS_PIXEL_DISTANCE_TOLERANCE = 0;
+export const TOOLCRAFT_LOSSY_PIXEL_DISTANCE_TOLERANCE = 48;
+export const TOOLCRAFT_BACKGROUND_PIXEL_DISTANCE_THRESHOLD = 24;
+
+export type ToolcraftExpectedDecodedPixel = Readonly<{
+  rgba: readonly [number, number, number, number];
+  xRatio: number;
+  yRatio: number;
+}>;
+
+export type ToolcraftExpectedDecodedVideoSample = Readonly<{
+  pixels: readonly ToolcraftExpectedDecodedPixel[];
+  timeSeconds: number;
+}>;
+
+export type ToolcraftDecodedPixelObservation = Readonly<{
+  centroid: Readonly<{ x: number; y: number }> | null;
+  decodedPixelHash: string;
+  nonBackgroundBounds: ToolcraftNormalizedPixelBounds | null;
+  normalizedPixels: Uint8ClampedArray;
+  occupiedAreaRatio: number;
+}>;
+
+function assertRgba(
+  rgba: readonly number[],
+  label: string,
+): asserts rgba is readonly [number, number, number, number] {
+  if (
+    rgba.length !== 4 ||
+    rgba.some(
+      (channel) =>
+        !Number.isSafeInteger(channel) || channel < 0 || channel > 255,
+    )
+  ) {
+    throw new Error(`${label} must contain four integer RGBA channels from 0 to 255.`);
+  }
+}
+
+function assertRatio(value: number, label: string): void {
+  if (!Number.isFinite(value) || value < 0 || value > 1) {
+    throw new Error(`${label} must be a finite normalized coordinate from 0 to 1.`);
+  }
+}
+
+export function validateToolcraftExpectedDecodedPixels(
+  pixels: readonly ToolcraftExpectedDecodedPixel[],
+  label = "Decoded pixel expectations",
+): void {
+  if (!Array.isArray(pixels) || pixels.length === 0) {
+    throw new Error(`${label} must contain at least one exact pixel sample.`);
+  }
+  for (const [index, pixel] of pixels.entries()) {
+    assertRatio(pixel.xRatio, `${label}[${index}].xRatio`);
+    assertRatio(pixel.yRatio, `${label}[${index}].yRatio`);
+    assertRgba(pixel.rgba, `${label}[${index}].rgba`);
+  }
+}
+
+export function getToolcraftRgbaDistance(
+  left: readonly number[],
+  right: readonly number[],
+): number {
+  return Math.sqrt(
+    left.reduce((sum, channel, index) => {
+      const delta = channel - (right[index] ?? 0);
+      return sum + delta * delta;
+    }, 0),
+  );
+}
+
+function normalizePixels({
+  pixels,
+  sourceHeight,
+  sourceWidth,
+}: Readonly<{
+  pixels: Uint8ClampedArray;
+  sourceHeight: number;
+  sourceWidth: number;
+}>): Uint8ClampedArray {
+  if (
+    !Number.isSafeInteger(sourceWidth) ||
+    sourceWidth <= 0 ||
+    !Number.isSafeInteger(sourceHeight) ||
+    sourceHeight <= 0 ||
+    pixels.length !== sourceWidth * sourceHeight * 4
+  ) {
+    throw new Error("Decoded pixel input must match positive source dimensions.");
+  }
+  if (
+    sourceWidth === TOOLCRAFT_DECODED_OBSERVATION_SIZE &&
+    sourceHeight === TOOLCRAFT_DECODED_OBSERVATION_SIZE
+  ) {
+    return new Uint8ClampedArray(pixels);
+  }
+
+  const normalized = new Uint8ClampedArray(
+    TOOLCRAFT_DECODED_OBSERVATION_SIZE * TOOLCRAFT_DECODED_OBSERVATION_SIZE * 4,
+  );
+  for (let y = 0; y < TOOLCRAFT_DECODED_OBSERVATION_SIZE; y += 1) {
+    const sourceY = Math.min(
+      sourceHeight - 1,
+      Math.floor(((y + 0.5) / TOOLCRAFT_DECODED_OBSERVATION_SIZE) * sourceHeight),
+    );
+    for (let x = 0; x < TOOLCRAFT_DECODED_OBSERVATION_SIZE; x += 1) {
+      const sourceX = Math.min(
+        sourceWidth - 1,
+        Math.floor(((x + 0.5) / TOOLCRAFT_DECODED_OBSERVATION_SIZE) * sourceWidth),
+      );
+      const sourceOffset = (sourceY * sourceWidth + sourceX) * 4;
+      const outputOffset =
+        (y * TOOLCRAFT_DECODED_OBSERVATION_SIZE + x) * 4;
+      normalized.set(pixels.subarray(sourceOffset, sourceOffset + 4), outputOffset);
+    }
+  }
+  return normalized;
+}
+
+async function hashPixels(pixels: Uint8ClampedArray): Promise<string> {
+  const source = new Uint8Array(
+    pixels.buffer,
+    pixels.byteOffset,
+    pixels.byteLength,
+  );
+  const hash = await crypto.subtle.digest("SHA-256", source);
+  return Array.from(new Uint8Array(hash), (byte) =>
+    byte.toString(16).padStart(2, "0"),
+  ).join("");
+}
+
+export async function observeToolcraftDecodedPixels({
+  backgroundRgba,
+  pixels,
+  sourceHeight,
+  sourceWidth,
+}: Readonly<{
+  backgroundRgba: readonly [number, number, number, number];
+  pixels: Uint8ClampedArray;
+  sourceHeight: number;
+  sourceWidth: number;
+}>): Promise<ToolcraftDecodedPixelObservation> {
+  assertRgba(backgroundRgba, "backgroundRgba");
+  const normalizedPixels = normalizePixels({
+    pixels,
+    sourceHeight,
+    sourceWidth,
+  });
+  let count = 0;
+  let minX = TOOLCRAFT_DECODED_OBSERVATION_SIZE;
+  let minY = TOOLCRAFT_DECODED_OBSERVATION_SIZE;
+  let maxX = -1;
+  let maxY = -1;
+  let sumX = 0;
+  let sumY = 0;
+
+  for (let y = 0; y < TOOLCRAFT_DECODED_OBSERVATION_SIZE; y += 1) {
+    for (let x = 0; x < TOOLCRAFT_DECODED_OBSERVATION_SIZE; x += 1) {
+      const offset = (y * TOOLCRAFT_DECODED_OBSERVATION_SIZE + x) * 4;
+      const pixel = normalizedPixels.subarray(offset, offset + 4);
+      if (
+        getToolcraftRgbaDistance(pixel, backgroundRgba) <=
+        TOOLCRAFT_BACKGROUND_PIXEL_DISTANCE_THRESHOLD
+      ) {
+        continue;
+      }
+      count += 1;
+      minX = Math.min(minX, x);
+      minY = Math.min(minY, y);
+      maxX = Math.max(maxX, x);
+      maxY = Math.max(maxY, y);
+      sumX += x + 0.5;
+      sumY += y + 0.5;
+    }
+  }
+
+  const size = TOOLCRAFT_DECODED_OBSERVATION_SIZE;
+  return Object.freeze({
+    centroid:
+      count === 0
+        ? null
+        : Object.freeze({ x: sumX / count / size, y: sumY / count / size }),
+    decodedPixelHash: await hashPixels(normalizedPixels),
+    nonBackgroundBounds:
+      count === 0
+        ? null
+        : Object.freeze({
+            height: (maxY - minY + 1) / size,
+            width: (maxX - minX + 1) / size,
+            x: minX / size,
+            y: minY / size,
+          }),
+    normalizedPixels,
+    occupiedAreaRatio: count / (size * size),
+  });
+}
+
+export function assertToolcraftExpectedDecodedPixels({
+  expectedPixels,
+  mediaType,
+  observation,
+}: Readonly<{
+  expectedPixels: readonly ToolcraftExpectedDecodedPixel[];
+  mediaType: "image/jpeg" | "image/png" | "video/mp4" | "video/webm";
+  observation: ToolcraftDecodedPixelObservation;
+}>): void {
+  validateToolcraftExpectedDecodedPixels(expectedPixels);
+  const tolerance =
+    mediaType === "image/png"
+      ? TOOLCRAFT_LOSSLESS_PIXEL_DISTANCE_TOLERANCE
+      : TOOLCRAFT_LOSSY_PIXEL_DISTANCE_TOLERANCE;
+  const size = TOOLCRAFT_DECODED_OBSERVATION_SIZE;
+
+  for (const expected of expectedPixels) {
+    const x = Math.min(size - 1, Math.floor(expected.xRatio * size));
+    const y = Math.min(size - 1, Math.floor(expected.yRatio * size));
+    const offset = (y * size + x) * 4;
+    const actual = observation.normalizedPixels.subarray(offset, offset + 4);
+    const distance = getToolcraftRgbaDistance(actual, expected.rgba);
+    if (distance > tolerance) {
+      throw new Error(
+        `Decoded pixel at (${expected.xRatio}, ${expected.yRatio}) differs from expected RGBA by ${distance.toFixed(2)}; fixed tolerance is ${tolerance}.`,
+      );
+    }
+  }
+}

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);
+});