@pixel-point/toolcraft 0.0.16 → 0.0.17

package/templates/starter/e2e/browser-render-scale-evidence.ts

@@ -1,10 +1,11 @@
 import { expect, type Page } from "@playwright/test";
-import type { ToolcraftPerformancePath } from "@repo/toolcraft-runtime";
+import { TOOLCRAFT_CANVAS_RENDER_SCALE } from "@repo/toolcraft-runtime";
 
+import type { ToolcraftPerformancePipelinePhase } from "../src/app/test-evidence/browser-performance-contract";
 import type { ToolcraftRenderScaleState } from "../src/app/starter-acceptance";
 import { attachToolcraftBrowserRuntimeEvidence } from "./browser-runtime-evidence";
 
-type CanvasMetrics = Readonly<{
+export type ToolcraftCanvasBackingMetrics = Readonly<{
   backingHeight: number;
   backingWidth: number;
   cssHeight: number;
@@ -12,6 +13,8 @@ type CanvasMetrics = Readonly<{
   devicePixelRatio: number;
 }>;
 
+export type ToolcraftCanvasVisibleSizePolicy = "fixed" | "viewport-driven";
+
 export type ToolcraftRenderScaleStateTransition = Readonly<{
   run: () => Promise<void>;
   state: ToolcraftRenderScaleState;
@@ -19,20 +22,12 @@ export type ToolcraftRenderScaleStateTransition = Readonly<{
 
 export type ToolcraftRenderScaleBackingOptions = Readonly<{
   baselineCssSize?: Readonly<{ height: number; width: number }>;
-  state?: ToolcraftRenderScaleState | "performance";
+  state?:
+    | ToolcraftRenderScaleState
+    | "performance-baseline"
+    | `performance-${ToolcraftPerformancePipelinePhase}`;
 }>;
 
-export function isToolcraftRenderScalePerformancePath(
-  path: Pick<ToolcraftPerformancePath, "targets" | "workloadDimensions">,
-): boolean {
-  return (
-    path.targets.includes("canvas.renderScale") ||
-    path.workloadDimensions.some((dimension) =>
-      /render[-_.]?scale|resolution[-_.]?scale/iu.test(dimension),
-    )
-  );
-}
-
 function assertPositiveFiniteScale(selectedScale: number): void {
   if (!Number.isFinite(selectedScale) || selectedScale <= 0) {
     throw new Error(
@@ -64,7 +59,7 @@ export function assertToolcraftRenderScaleBackingProofConfig(
 async function readCanvasMetrics(
   page: Page,
   canvasSelector: string,
-): Promise<CanvasMetrics> {
+): Promise<ToolcraftCanvasBackingMetrics> {
   if (!canvasSelector.trim()) {
     throw new Error(
       "Toolcraft canvas backing-pixel checks require a non-empty canvas selector.",
@@ -95,8 +90,8 @@ async function readCanvasMetrics(
   });
 }
 
-function assertBackingMetrics(
-  metrics: CanvasMetrics,
+export function assertToolcraftCanvasBackingMetricsForRenderScale(
+  metrics: ToolcraftCanvasBackingMetrics,
   selectedScale: number,
   options: ToolcraftRenderScaleBackingOptions,
 ): void {
@@ -128,14 +123,16 @@ function assertBackingMetrics(
     metrics.cssWidth * metrics.devicePixelRatio * selectedScale;
   const expectedHeight =
     metrics.cssHeight * metrics.devicePixelRatio * selectedScale;
+  const widthError = Math.abs(metrics.backingWidth - expectedWidth);
+  const heightError = Math.abs(metrics.backingHeight - expectedHeight);
   expect(
-    metrics.backingWidth,
-    `${stateLabel} expected canvas backing width to honor Resolution scale ${selectedScale}.`,
-  ).toBeGreaterThanOrEqual(Math.floor(expectedWidth - 1));
+    widthError,
+    `${stateLabel} expected exact canvas backing width within one physical pixel for Resolution scale ${selectedScale}.`,
+  ).toBeLessThanOrEqual(1);
   expect(
-    metrics.backingHeight,
-    `${stateLabel} expected canvas backing height to honor Resolution scale ${selectedScale}.`,
-  ).toBeGreaterThanOrEqual(Math.floor(expectedHeight - 1));
+    heightError,
+    `${stateLabel} expected exact canvas backing height within one physical pixel for Resolution scale ${selectedScale}.`,
+  ).toBeLessThanOrEqual(1);
 }
 
 export async function expectToolcraftCanvasBackingPixelsForRenderScale(
@@ -146,7 +143,11 @@ export async function expectToolcraftCanvasBackingPixelsForRenderScale(
 ): Promise<Readonly<{ height: number; width: number }>> {
   assertPositiveFiniteScale(selectedScale);
   const metrics = await readCanvasMetrics(page, canvasSelector);
-  assertBackingMetrics(metrics, selectedScale, options);
+  assertToolcraftCanvasBackingMetricsForRenderScale(
+    metrics,
+    selectedScale,
+    options,
+  );
   return { height: metrics.cssHeight, width: metrics.cssWidth };
 }
 
@@ -216,13 +217,17 @@ export async function expectToolcraftPerformanceRenderScaleBackingEvidence(
   page: Page,
   {
     canvasSelector,
+    baselineCssSize,
+    cssSizePolicy,
     pathId,
-    selectedScale,
+    phase,
     target,
   }: Readonly<{
+    baselineCssSize: Readonly<{ height: number; width: number }>;
     canvasSelector: string;
+    cssSizePolicy: ToolcraftCanvasVisibleSizePolicy;
     pathId: string;
-    selectedScale: number;
+    phase: ToolcraftPerformancePipelinePhase;
     target?: string;
   }>,
 ): Promise<void> {
@@ -234,12 +239,15 @@ export async function expectToolcraftPerformanceRenderScaleBackingEvidence(
   await expectToolcraftCanvasBackingPixelsForRenderScale(
     page,
     canvasSelector,
-    selectedScale,
-    { state: "performance" },
+    TOOLCRAFT_CANVAS_RENDER_SCALE.defaultValue,
+    {
+      ...(cssSizePolicy === "fixed" ? { baselineCssSize } : {}),
+      state: `performance-${phase}`,
+    },
   );
   await attachToolcraftBrowserRuntimeEvidence({
     evidenceType: "performance-render-scale",
-    requirementId: pathId,
+    requirementId: `${pathId}#${phase}`,
     target,
   });
 }

package/templates/starter/e2e/browser-runtime-evidence-reporter.ts

@@ -173,7 +173,10 @@ export default class ToolcraftBrowserRuntimeEvidenceReporter implements Reporter
     );
     this.performanceRequirements =
       this.performanceRequirementsOverride ??
-      deriveToolcraftPerformancePathRuntimeRequirements(this.canonicalPaths);
+      deriveToolcraftPerformancePathRuntimeRequirements(
+        this.canonicalPaths,
+        this.performanceSchema,
+      );
   }
 
   onEnd(_result: FullResult): { status: "failed" } | undefined {

package/templates/starter/e2e/browser-runtime-evidence-requirements.ts

@@ -3,6 +3,9 @@ import type {
   ToolcraftPerformancePath,
 } from "@repo/toolcraft-runtime";
 
+import {
+  TOOLCRAFT_PERFORMANCE_PIPELINE_PHASES,
+} from "../src/app/test-evidence/browser-performance-contract";
 import type { ToolcraftBrowserRuntimeRequirement } from "../src/app/test-evidence/browser-runtime-contract";
 import { schemaHasVideoExportPanelAction } from "../src/app/acceptance/output-export";
 import {
@@ -16,7 +19,6 @@ import {
   type ToolcraftTimelinePlaybackCoverage,
   TOOLCRAFT_REQUIRED_MODEL_IMPORT_COVERAGE,
 } from "../src/app/starter-acceptance";
-import { isToolcraftRenderScalePerformancePath } from "./browser-render-scale-evidence";
 import { getToolcraftPerformancePathTestName } from "./performance-path-helpers";
 
 type BrowserAcceptanceRequirementSource = Pick<
@@ -27,6 +29,7 @@ type BrowserAcceptanceRequirementSource = Pick<
   | "canvasHandle"
   | "controlPartCoverage"
   | "evidence"
+  | "exportArtifactCoverage"
   | "id"
   | "infinityCanvasCoverage"
   | "layerCoverage"
@@ -188,7 +191,25 @@ export function deriveToolcraftBrowserRuntimeRequirements(
       entry.orientationGizmoCoverage !== undefined;
     const evidenceTypes: ToolcraftBrowserRuntimeRequirement["evidenceType"][] = [];
     const baseEvidenceType = getAcceptanceEvidenceType(entry.evidence);
-    if (baseEvidenceType) evidenceTypes.push(baseEvidenceType);
+    const exportArtifactCoverage = entry.exportArtifactCoverage
+      ? typeof entry.exportArtifactCoverage === "string"
+        ? [entry.exportArtifactCoverage]
+        : entry.exportArtifactCoverage
+      : [];
+    if (
+      baseEvidenceType &&
+      entry.renderScaleCoverage === undefined &&
+      exportArtifactCoverage.length === 0
+    ) {
+      evidenceTypes.push(baseEvidenceType);
+    }
+    for (const coverage of exportArtifactCoverage) {
+      evidenceTypes.push(
+        coverage === "all-required-image-export-behavior"
+          ? "image-export-artifact"
+          : "video-export-artifact",
+      );
+    }
 
     if (entry.canvasHandle && !hasOrientationCoverage) {
       evidenceTypes.push("canvas-handle-interaction");
@@ -321,7 +342,9 @@ export function deriveToolcraftBrowserRuntimeRequirements(
   });
 }
 
-const pathProductOutcomeInteractions = new Set<ToolcraftPerformancePath["interaction"]>([
+const pathProductOutcomeInteractions = new Set<
+  ToolcraftPerformancePath["interaction"]
+>([
   "control-change",
   "control-drag",
   "mask-drag",
@@ -332,6 +355,7 @@ const pathProductOutcomeInteractions = new Set<ToolcraftPerformancePath["interac
 
 export function deriveToolcraftPerformancePathRuntimeRequirements(
   paths: readonly ToolcraftPerformancePath[],
+  schema: ResolvedToolcraftAppSchema,
 ): ToolcraftBrowserRuntimeRequirement[] {
   return paths.flatMap((path) => {
     const evidenceTypes: ToolcraftBrowserRuntimeRequirement["evidenceType"][] = [
@@ -353,19 +377,29 @@ export function deriveToolcraftPerformancePathRuntimeRequirements(
     if (path.interaction === "animation-frame") {
       evidenceTypes.push("performance-animation-frames");
     }
-    if (path.interaction === "viewport-drag" || path.interaction === "viewport-zoom") {
+    if (
+      path.interaction === "viewport-drag" ||
+      path.interaction === "viewport-zoom"
+    ) {
       evidenceTypes.push("performance-viewport");
     }
-    if (isToolcraftRenderScalePerformancePath(path)) {
-      evidenceTypes.push("performance-render-scale");
-    }
-
     const target = path.targets.length === 1 ? path.targets[0] : undefined;
-    return evidenceTypes.map((evidenceType) => ({
+    const requirements = evidenceTypes.map((evidenceType) => ({
       evidenceType,
       requirementId: path.id,
       target,
       testName: getToolcraftPerformancePathTestName(path),
     }));
+    if (schema.canvas.renderScale.enabled) {
+      for (const phase of TOOLCRAFT_PERFORMANCE_PIPELINE_PHASES) {
+        requirements.push({
+          evidenceType: "performance-render-scale",
+          requirementId: `${path.id}#${phase}`,
+          target,
+          testName: getToolcraftPerformancePathTestName(path),
+        });
+      }
+    }
+    return requirements;
   });
 }

package/templates/starter/e2e/browser-standard-timeline-evidence.ts

@@ -0,0 +1,106 @@
+import { expect } from "@playwright/test";
+
+import { attachToolcraftBrowserRuntimeEvidence } from "./browser-runtime-evidence";
+import {
+  getToolcraftBrowserProofPage,
+  type ToolcraftBrowserProofSession,
+} from "./browser-proof-session";
+
+async function readMarkerSignature(
+  page: Awaited<ReturnType<typeof getToolcraftBrowserProofPage>>,
+  markerSelector: string,
+): Promise<string> {
+  return page.locator(markerSelector).evaluate((element) => {
+    const node = element as HTMLElement;
+    return `${node.dataset.timelineProgress ?? "missing"}:${node.style.transform || node.style.left}`;
+  });
+}
+
+export async function expectToolcraftStandardTimelinePlayback(
+  session: ToolcraftBrowserProofSession,
+  options: Readonly<{
+    markerSelector: string;
+    requirementId: string;
+  }>,
+): Promise<void> {
+  const page = await getToolcraftBrowserProofPage(session);
+  const scrubber = page.getByRole("slider", { name: "Playback position" });
+  if (!(await scrubber.isVisible())) {
+    await page
+      .locator('[data-toolcraft-control-target="panels.timeline.extended"]')
+      .getByRole("switch")
+      .click();
+    await expect(scrubber).toBeVisible();
+  }
+  const pause = page.getByRole("button", { name: "Pause playback" });
+  if (await pause.isVisible()) await pause.click();
+
+  await scrubber.press("Home");
+  await expect(scrubber).toHaveAttribute("aria-valuenow", "0");
+  const initialStart = await readMarkerSignature(page, options.markerSelector);
+  await scrubber.press("End");
+  const initialEnd = await readMarkerSignature(page, options.markerSelector);
+  expect(initialEnd).toBe(initialStart);
+  await scrubber.press("ArrowLeft");
+  const scrubbed = await readMarkerSignature(page, options.markerSelector);
+  expect(scrubbed).not.toBe(initialStart);
+  await attachToolcraftBrowserRuntimeEvidence({
+    evidenceType: "timeline-scrub",
+    requirementId: options.requirementId,
+    target: "timeline.playback",
+  });
+  await attachToolcraftBrowserRuntimeEvidence({
+    evidenceType: "timeline-rendered-frame",
+    requirementId: options.requirementId,
+    target: "timeline.playback",
+  });
+  await attachToolcraftBrowserRuntimeEvidence({
+    evidenceType: "product-observable-change",
+    requirementId: options.requirementId,
+    target: "timeline.playback",
+  });
+
+  await page.getByRole("button", { name: "Edit timeline duration" }).click();
+  const durationEditor = page.getByRole("textbox", { name: "timeline duration" });
+  await durationEditor.fill("2s");
+  await durationEditor.press("Enter");
+  await expect(scrubber).toHaveAttribute("aria-valuemax", "2");
+  await scrubber.press("Home");
+  const resizedStart = await readMarkerSignature(page, options.markerSelector);
+  await scrubber.press("End");
+  const resizedEnd = await readMarkerSignature(page, options.markerSelector);
+  expect(resizedEnd).toBe(resizedStart);
+  await attachToolcraftBrowserRuntimeEvidence({
+    evidenceType: "timeline-duration",
+    requirementId: options.requirementId,
+    target: "timeline.playback",
+  });
+  await attachToolcraftBrowserRuntimeEvidence({
+    evidenceType: "timeline-loop",
+    requirementId: options.requirementId,
+    target: "timeline.playback",
+  });
+
+  await scrubber.press("Home");
+  await page.getByRole("button", { name: "Play playback" }).click();
+  await expect
+    .poll(() => scrubber.getAttribute("aria-valuenow"))
+    .not.toBe("0");
+  await page.getByRole("button", { name: "Pause playback" }).click();
+  const pausedTime = await scrubber.getAttribute("aria-valuenow");
+  const pausedSignature = await readMarkerSignature(page, options.markerSelector);
+  await page.waitForTimeout(100);
+  expect(await scrubber.getAttribute("aria-valuenow")).toBe(pausedTime);
+  expect(await readMarkerSignature(page, options.markerSelector)).toBe(
+    pausedSignature,
+  );
+  await page.getByRole("button", { name: "Play playback" }).click();
+  await expect
+    .poll(() => scrubber.getAttribute("aria-valuenow"))
+    .not.toBe(pausedTime);
+  await attachToolcraftBrowserRuntimeEvidence({
+    evidenceType: "timeline-pause-resume",
+    requirementId: options.requirementId,
+    target: "timeline.playback",
+  });
+}

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