@pixel-point/toolcraft 0.0.16 → 0.0.18

package/templates/starter/e2e/browser-infinity-canvas-unavailable-image-evidence.ts

@@ -0,0 +1,370 @@
+import { expect } from "@playwright/test";
+
+import { attachToolcraftBrowserRuntimeEvidence } from "./browser-runtime-evidence";
+import {
+  assertToolcraftBrowserProofSession,
+  getToolcraftBrowserActionTarget,
+  readToolcraftBrowserObservation,
+  runToolcraftBrowserAction,
+  runToolcraftBrowserValueAction,
+  type ToolcraftBrowserAction,
+  type ToolcraftBrowserObservation,
+  type ToolcraftBrowserProofSession,
+} from "./browser-proof-session";
+import {
+  assertToolcraftProducedArtifact,
+  validateToolcraftExportArtifactInspection,
+  type ToolcraftExportArtifactInspection,
+} from "./export-artifact-helpers";
+
+declare const toolcraftUnavailableImageResourceFixtureBrand: unique symbol;
+
+export type ToolcraftUnavailableImageResourceObservation = Readonly<{
+  assetId?: string;
+  fileName?: string;
+  lifecycle?: "ready" | "unavailable";
+  message?: string;
+  requestId?: string;
+  resolverAvailable?: boolean;
+  status: "active" | "cleaned" | "error" | "missing";
+}>;
+
+export type ToolcraftUnavailableImageResourceFixture = Readonly<{
+  readonly [toolcraftUnavailableImageResourceFixtureBrand]: true;
+}>;
+
+type ToolcraftUnavailableImageResourceFixtureRecord = Readonly<{
+  activate: ToolcraftBrowserAction;
+  cleanup: ToolcraftBrowserAction;
+  fileName: string;
+  observe: ToolcraftBrowserObservation<string | null>;
+  requestId: string;
+  target: string;
+}>;
+
+const unavailableImageResourceFixtureRecords = new WeakMap<
+  object,
+  ToolcraftUnavailableImageResourceFixtureRecord
+>();
+const malformedUnavailableImageResourceObservation = Object.freeze({
+  message: "Unavailable-resource proof published malformed state.",
+  status: "error" as const,
+});
+let unavailableImageResourceFixtureSequence = 0;
+
+function requireUnavailableImageResourceFixture(
+  fixture: ToolcraftUnavailableImageResourceFixture,
+): ToolcraftUnavailableImageResourceFixtureRecord {
+  const record =
+    typeof fixture === "object" && fixture !== null
+      ? unavailableImageResourceFixtureRecords.get(fixture)
+      : undefined;
+  if (!record) {
+    throw new Error(
+      "Unavailable-image export evidence requires the protected Toolcraft unavailable-resource fixture facade.",
+    );
+  }
+  return record;
+}
+
+function parseUnavailableImageResourceObservation(
+  raw: string | null,
+): ToolcraftUnavailableImageResourceObservation {
+  if (!raw) return { status: "missing" };
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    return malformedUnavailableImageResourceObservation;
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return malformedUnavailableImageResourceObservation;
+  }
+  const observation = value as Record<string, unknown>;
+  const optionalStringsAreValid = [
+    "assetId",
+    "fileName",
+    "message",
+    "requestId",
+  ].every(
+    (field) =>
+      observation[field] === undefined ||
+      typeof observation[field] === "string",
+  );
+  const valid =
+    typeof observation.status === "string" &&
+    ["active", "cleaned", "error", "missing"].includes(observation.status) &&
+    optionalStringsAreValid &&
+    (
+      observation.resolverAvailable === undefined ||
+      typeof observation.resolverAvailable === "boolean"
+    ) &&
+    (
+      observation.lifecycle === undefined ||
+      observation.lifecycle === "ready" ||
+      observation.lifecycle === "unavailable"
+    );
+  return valid
+    ? observation as ToolcraftUnavailableImageResourceObservation
+    : malformedUnavailableImageResourceObservation;
+}
+
+async function readUnavailableImageResourceObservation(
+  observation: ToolcraftBrowserObservation<string | null>,
+): Promise<ToolcraftUnavailableImageResourceObservation> {
+  const raw = await readToolcraftBrowserObservation(observation);
+  return parseUnavailableImageResourceObservation(raw);
+}
+
+function validateUnavailableImageResourceObservation(
+  observation: ToolcraftUnavailableImageResourceObservation,
+  expected: Readonly<{
+    fileName: string;
+    requestId: string;
+    status: "active" | "cleaned";
+  }>,
+): void {
+  if (observation.status === "error") {
+    throw new Error(
+      observation.message ??
+        "The Toolcraft unavailable-resource proof fixture failed.",
+    );
+  }
+  expect(
+    observation,
+    `Unavailable-resource proof "${expected.requestId}" must publish its exact typed state.`,
+  ).toMatchObject(
+    expected.status === "active"
+      ? {
+          fileName: expected.fileName,
+          lifecycle: "unavailable",
+          requestId: expected.requestId,
+          resolverAvailable: false,
+          status: "active",
+        }
+      : {
+          fileName: expected.fileName,
+          lifecycle: "ready",
+          requestId: expected.requestId,
+          resolverAvailable: true,
+          status: "cleaned",
+        },
+  );
+  expect(
+    observation.assetId?.trim(),
+    "Unavailable-resource proof must identify the exact affected runtime asset.",
+  ).toBeTruthy();
+}
+
+export function createToolcraftUnavailableImageResourceFixture(
+  session: ToolcraftBrowserProofSession,
+  {
+    fileName,
+    sourceTarget,
+    target,
+  }: Readonly<{
+    fileName: string;
+    sourceTarget?: string;
+    target: string;
+  }>,
+): ToolcraftUnavailableImageResourceFixture {
+  const normalizedFileName = fileName.trim();
+  const normalizedSourceTarget = sourceTarget?.trim();
+  const normalizedTarget = target.trim();
+  expect(
+    normalizedFileName,
+    "Unavailable-resource proof requires an exact non-empty image file name.",
+  ).not.toBe("");
+  expect(
+    normalizedTarget,
+    "Unavailable-resource proof requires an exact semantic acceptance target.",
+  ).not.toBe("");
+  if (sourceTarget !== undefined) {
+    expect(
+      normalizedSourceTarget,
+      "Unavailable-resource proof sourceTarget must be non-empty when provided.",
+    ).not.toBe("");
+  }
+
+  const requestId =
+    `unavailable-image-${++unavailableImageResourceFixtureSequence}`;
+  const request = {
+    fileName: normalizedFileName,
+    requestId,
+    ...(normalizedSourceTarget
+      ? { sourceTarget: normalizedSourceTarget }
+      : {}),
+  };
+  const runRequest = (
+    action: "activate" | "cleanup",
+    expectedStatus: "active" | "cleaned",
+  ) =>
+    session.targetAction(normalizedTarget, async (page) => {
+      await page.evaluate(
+        ({ detail, eventName }) => {
+          document.dispatchEvent(
+            new CustomEvent(eventName, {
+              detail,
+            }),
+          );
+        },
+        {
+          detail: { ...request, action },
+          eventName:
+            "toolcraft.browser-proof.unavailable-resource-request",
+        },
+      );
+      await expect
+        .poll(
+          async () => {
+            const raw = await page
+              .locator('[data-slot="toolcraft-runtime-app"]')
+              .getAttribute(
+                "data-toolcraft-unavailable-resource-evidence",
+              );
+            const observation =
+              parseUnavailableImageResourceObservation(raw);
+            if (
+              observation.status === "error" &&
+              (
+                observation.requestId === undefined ||
+                observation.requestId === requestId
+              )
+            ) {
+              throw new Error(
+                observation.message ??
+                  "The Toolcraft unavailable-resource proof fixture failed.",
+              );
+            }
+            return observation.requestId === requestId
+              ? observation.status
+              : "other-request";
+          },
+          {
+            message:
+              `Unavailable-resource proof "${requestId}" should reach ${expectedStatus}.`,
+          },
+        )
+        .toBe(expectedStatus);
+    });
+  const activate = runRequest("activate", "active");
+  const cleanup = runRequest("cleanup", "cleaned");
+  const observe = session.observe((root) =>
+    root.getAttribute("data-toolcraft-unavailable-resource-evidence"),
+  );
+  const fixture = Object.freeze({}) as ToolcraftUnavailableImageResourceFixture;
+  unavailableImageResourceFixtureRecords.set(fixture, {
+    activate,
+    cleanup,
+    fileName: normalizedFileName,
+    observe,
+    requestId,
+    target: normalizedTarget,
+  });
+  return fixture;
+}
+
+export async function expectToolcraftInfinityCanvasUnavailableImageExportEvidence<
+  TArtifact,
+>(
+  fixture: ToolcraftUnavailableImageResourceFixture,
+  produceArtifact: ToolcraftBrowserAction<"interaction", TArtifact>,
+  inspectArtifact: (
+    artifact: TArtifact,
+  ) => Promise<ToolcraftExportArtifactInspection> | ToolcraftExportArtifactInspection,
+  {
+    expectedSize,
+    requirementId,
+  }: Readonly<{
+    expectedSize: Readonly<{ height: number; width: number }>;
+    requirementId: string;
+  }>,
+): Promise<ToolcraftExportArtifactInspection> {
+  const record = requireUnavailableImageResourceFixture(fixture);
+  assertToolcraftBrowserProofSession(
+    record.observe,
+    record.activate,
+    record.cleanup,
+    produceArtifact,
+  );
+  const exportTarget = getToolcraftBrowserActionTarget(produceArtifact)?.trim();
+  expect(
+    exportTarget,
+    "Unavailable-image export evidence requires a target-scoped artifact action.",
+  ).toBe(record.target);
+
+  let activationAttempted = false;
+  let cleanupSucceeded = false;
+  let inspection: ToolcraftExportArtifactInspection | null = null;
+  let outputVerified = false;
+  try {
+    activationAttempted = true;
+    await runToolcraftBrowserAction(record.activate);
+    validateUnavailableImageResourceObservation(
+      await readUnavailableImageResourceObservation(record.observe),
+      {
+        fileName: record.fileName,
+        requestId: record.requestId,
+        status: "active",
+      },
+    );
+
+    const artifact = await runToolcraftBrowserValueAction(produceArtifact);
+    assertToolcraftProducedArtifact(artifact, requirementId);
+    inspection = await inspectArtifact(artifact);
+    validateToolcraftExportArtifactInspection(inspection, requirementId);
+    expect(
+      inspection,
+      `Unavailable-image export "${requirementId}" must decode to the expected visible scene bounds.`,
+    ).toMatchObject(expectedSize);
+    validateUnavailableImageResourceObservation(
+      await readUnavailableImageResourceObservation(record.observe),
+      {
+        fileName: record.fileName,
+        requestId: record.requestId,
+        status: "active",
+      },
+    );
+    outputVerified = true;
+  } finally {
+    const current = activationAttempted
+      ? await readUnavailableImageResourceObservation(record.observe)
+      : null;
+    if (
+      current?.requestId === record.requestId &&
+      current.status === "active"
+    ) {
+      await runToolcraftBrowserAction(record.cleanup);
+      validateUnavailableImageResourceObservation(
+        await readUnavailableImageResourceObservation(record.observe),
+        {
+          fileName: record.fileName,
+          requestId: record.requestId,
+          status: "cleaned",
+        },
+      );
+      cleanupSucceeded = true;
+    } else if (outputVerified) {
+      throw new Error(
+        "Unavailable-image export evidence requires the exact active fixture to remain available for deterministic cleanup.",
+      );
+    }
+  }
+
+  if (!cleanupSucceeded || !inspection) {
+    throw new Error(
+      "Unavailable-image export evidence requires successful fixture cleanup before publication.",
+    );
+  }
+  await attachToolcraftBrowserRuntimeEvidence({
+    evidenceType: "exported-artifact",
+    requirementId,
+    target: exportTarget,
+  });
+  await attachToolcraftBrowserRuntimeEvidence({
+    evidenceType: "infinity-scene-bounds-image-export",
+    requirementId,
+    target: exportTarget,
+  });
+  return inspection;
+}

package/templates/starter/e2e/browser-media-export-evidence.spec.ts

@@ -0,0 +1,77 @@
+import fs from "node:fs/promises";
+
+import { expect, test, type Download, type Page } from "@playwright/test";
+
+import { expectToolcraftImageExportArtifact } from "./browser-media-export-evidence";
+
+async function createImageFixture(
+  page: Page,
+): Promise<Buffer> {
+  const base64 = await page.evaluate(() => {
+    const canvas = document.createElement("canvas");
+    canvas.width = 64;
+    canvas.height = 64;
+    const context = canvas.getContext("2d");
+    if (!context) throw new Error("Missing test canvas context.");
+    context.fillStyle = "#000000";
+    context.fillRect(0, 0, 64, 64);
+    context.fillStyle = "#FF0000";
+    context.fillRect(16, 16, 32, 32);
+    return canvas.toDataURL("image/png").split(",")[1]!;
+  });
+  return Buffer.from(base64, "base64");
+}
+
+test("protected image evidence attaches only after decoded semantics pass", async ({
+  page,
+}, testInfo) => {
+  await page.goto("/");
+  const artifactPath = testInfo.outputPath("protected-image.png");
+  await fs.writeFile(artifactPath, await createImageFixture(page));
+  const download = { path: async () => artifactPath } as Download;
+
+  await expectToolcraftImageExportArtifact(async () => download, {
+    backgroundRgba: [0, 0, 0, 255],
+    expectedBounds: { height: 0.5, width: 0.5, x: 0.25, y: 0.25 },
+    expectedHeight: 64,
+    expectedMediaType: "image/png",
+    expectedPixels: [
+      { rgba: [0, 0, 0, 255], xRatio: 0.1, yRatio: 0.1 },
+      { rgba: [255, 0, 0, 255], xRatio: 0.5, yRatio: 0.5 },
+    ],
+    expectedWidth: 64,
+    page,
+    requirementId: "fixture.image",
+  });
+
+  expect(
+    test.info().attachments.some(
+      ({ name }) => name === "toolcraft.browser-runtime-evidence",
+    ),
+  ).toBe(true);
+});
+
+test("protected image evidence rejects empty product expectations before download", async ({
+  page,
+}) => {
+  let called = false;
+  await expect(
+    expectToolcraftImageExportArtifact(
+      async () => {
+        called = true;
+        throw new Error("must not run");
+      },
+      {
+        backgroundRgba: [0, 0, 0, 255],
+        expectedBounds: { height: 0.5, width: 0.5, x: 0.25, y: 0.25 },
+        expectedHeight: 64,
+        expectedMediaType: "image/png",
+        expectedPixels: [],
+        expectedWidth: 64,
+        page,
+        requirementId: "fixture.empty",
+      },
+    ),
+  ).rejects.toThrow("at least one exact pixel sample");
+  expect(called).toBe(false);
+});

package/templates/starter/e2e/browser-media-export-evidence.ts

@@ -0,0 +1,208 @@
+import { expect, type Download, type Page } from "@playwright/test";
+
+import {
+  assertToolcraftExpectedDecodedPixels,
+  getToolcraftRgbaDistance,
+  TOOLCRAFT_BACKGROUND_PIXEL_DISTANCE_THRESHOLD,
+  validateToolcraftExpectedDecodedPixels,
+  type ToolcraftExpectedDecodedPixel,
+  type ToolcraftExpectedDecodedVideoSample,
+} from "./decoded-pixel-observation";
+import type { ToolcraftNormalizedPixelBounds } from "./export-artifact-helpers";
+import { inspectToolcraftImageDownload } from "./image-artifact-inspection";
+import { attachToolcraftBrowserRuntimeEvidence } from "./browser-runtime-evidence";
+import {
+  assertToolcraftVideoPacketSchedule,
+  inspectToolcraftVideoDownload,
+  type ToolcraftInspectedVideoArtifact,
+  type ToolcraftScheduledVideoFrame,
+} from "./video-artifact-inspection";
+import {
+  getToolcraftBrowserActionTarget,
+  isToolcraftBrowserAction,
+  runToolcraftBrowserValueAction,
+  type ToolcraftBrowserAction,
+} from "./browser-proof-session";
+
+type AdditionalArtifactRequirement = Readonly<{
+  requirementId: string;
+  target: string;
+}>;
+
+async function attachAdditionalArtifactRequirements(
+  requirements: readonly AdditionalArtifactRequirement[] | undefined,
+): Promise<void> {
+  for (const requirement of requirements ?? []) {
+    await attachToolcraftBrowserRuntimeEvidence({
+      evidenceType: "exported-artifact",
+      requirementId: requirement.requirementId,
+      target: requirement.target,
+    });
+  }
+}
+
+const normalizedBoundsTolerance = 2 / 64;
+
+function assertContainsProductExpectation(
+  expectedPixels: readonly ToolcraftExpectedDecodedPixel[],
+  backgroundRgba: readonly [number, number, number, number],
+): void {
+  validateToolcraftExpectedDecodedPixels(expectedPixels);
+  if (
+    !expectedPixels.some(
+      ({ rgba }) =>
+        getToolcraftRgbaDistance(rgba, backgroundRgba) >
+        TOOLCRAFT_BACKGROUND_PIXEL_DISTANCE_THRESHOLD,
+    )
+  ) {
+    throw new Error(
+      "Media export evidence requires at least one non-background product pixel expectation.",
+    );
+  }
+}
+
+function assertExpectedBounds(
+  actual: ToolcraftNormalizedPixelBounds | null,
+  expected: ToolcraftNormalizedPixelBounds,
+): void {
+  expect(actual, "Decoded export must contain product pixels.").not.toBeNull();
+  if (!actual) return;
+  for (const field of ["height", "width", "x", "y"] as const) {
+    expect(
+      Math.abs(actual[field] - expected[field]),
+      `Decoded product ${field} must match the expected normalized bounds.`,
+    ).toBeLessThanOrEqual(normalizedBoundsTolerance);
+  }
+}
+
+export async function expectToolcraftImageExportArtifact(
+  produceDownload:
+    | (() => Promise<Download>)
+    | ToolcraftBrowserAction<"interaction", Download>,
+  options: Readonly<{
+    additionalArtifactRequirements?: readonly AdditionalArtifactRequirement[];
+    backgroundRgba: readonly [number, number, number, number];
+    expectedBounds: ToolcraftNormalizedPixelBounds;
+    expectedHeight: number;
+    expectedMediaType: "image/jpeg" | "image/png";
+    expectedPixels: readonly ToolcraftExpectedDecodedPixel[];
+    expectedWidth: number;
+    page: Page;
+    requirementId: string;
+  }>,
+): Promise<void> {
+  assertContainsProductExpectation(options.expectedPixels, options.backgroundRgba);
+  const target = isToolcraftBrowserAction(produceDownload)
+    ? getToolcraftBrowserActionTarget(produceDownload)
+    : undefined;
+  const download = isToolcraftBrowserAction(produceDownload)
+    ? await runToolcraftBrowserValueAction(produceDownload)
+    : await produceDownload();
+  const inspected = await inspectToolcraftImageDownload({
+    backgroundRgba: options.backgroundRgba,
+    download,
+    page: options.page,
+  });
+  expect(inspected.inspection.byteLength).toBeGreaterThan(0);
+  expect(inspected.inspection.mediaType).toBe(options.expectedMediaType);
+  expect(inspected.inspection.width).toBe(options.expectedWidth);
+  expect(inspected.inspection.height).toBe(options.expectedHeight);
+  expect(inspected.inspection.decodedPixelHash).not.toHaveLength(0);
+  assertExpectedBounds(
+    inspected.inspection.nonBackgroundBounds,
+    options.expectedBounds,
+  );
+  assertToolcraftExpectedDecodedPixels({
+    expectedPixels: options.expectedPixels,
+    mediaType: inspected.inspection.mediaType,
+    observation: inspected.observation,
+  });
+  await attachAdditionalArtifactRequirements(
+    options.additionalArtifactRequirements,
+  );
+  await attachToolcraftBrowserRuntimeEvidence({
+    evidenceType: "image-export-artifact",
+    requirementId: options.requirementId,
+    target,
+  });
+}
+
+export async function expectToolcraftVideoExportArtifact(
+  produceDownload:
+    | (() => Promise<Download>)
+    | ToolcraftBrowserAction<"interaction", Download>,
+  options: Readonly<{
+    additionalArtifactRequirements?: readonly AdditionalArtifactRequirement[];
+    animated: boolean;
+    backgroundRgba: readonly [number, number, number, number];
+    expectedDurationSeconds: number;
+    expectedHeight: number;
+    expectedMediaType: "video/mp4" | "video/webm";
+    expectedSamples: readonly ToolcraftExpectedDecodedVideoSample[];
+    expectedWidth: number;
+    page: Page;
+    requirementId: string;
+    schedule: readonly ToolcraftScheduledVideoFrame[];
+  }>,
+): Promise<ToolcraftInspectedVideoArtifact> {
+  if (options.schedule.length === 0) {
+    throw new Error("Video export evidence requires the runtime frame schedule.");
+  }
+  for (const sample of options.expectedSamples) {
+    assertContainsProductExpectation(sample.pixels, options.backgroundRgba);
+  }
+  const target = isToolcraftBrowserAction(produceDownload)
+    ? getToolcraftBrowserActionTarget(produceDownload)
+    : undefined;
+  const download = isToolcraftBrowserAction(produceDownload)
+    ? await runToolcraftBrowserValueAction(produceDownload)
+    : await produceDownload();
+  const inspected = await inspectToolcraftVideoDownload({
+    backgroundRgba: options.backgroundRgba,
+    download,
+    page: options.page,
+    schedule: options.schedule,
+  });
+  const toleranceSeconds = 1 / inspected.timeResolution;
+  expect(inspected.inspection.byteLength).toBeGreaterThan(0);
+  expect(inspected.inspection.mediaType).toBe(options.expectedMediaType);
+  expect(inspected.inspection.width).toBe(options.expectedWidth);
+  expect(inspected.inspection.height).toBe(options.expectedHeight);
+  expect(inspected.inspection.frameCount).toBe(options.schedule.length);
+  expect(
+    Math.abs(
+      inspected.inspection.durationMs - options.expectedDurationSeconds * 1000,
+    ),
+  ).toBeLessThanOrEqual(toleranceSeconds * 1000);
+  assertToolcraftVideoPacketSchedule({
+    packetTimings: inspected.inspection.packetTimings,
+    schedule: options.schedule,
+    timeResolution: inspected.timeResolution,
+  });
+  expect(inspected.sampleTimes).toEqual(
+    options.expectedSamples.map(({ timeSeconds }) => timeSeconds),
+  );
+  expect(inspected.observations).toHaveLength(options.expectedSamples.length);
+  for (const [index, observation] of inspected.observations.entries()) {
+    const expected = options.expectedSamples[index];
+    if (!expected) throw new Error(`Missing expected decoded sample ${index}.`);
+    expect(observation.nonBackgroundBounds).not.toBeNull();
+    assertToolcraftExpectedDecodedPixels({
+      expectedPixels: expected.pixels,
+      mediaType: inspected.inspection.mediaType,
+      observation,
+    });
+  }
+  if (options.animated) {
+    expect(new Set(inspected.inspection.samplePixelHashes).size).toBeGreaterThan(1);
+  }
+  await attachAdditionalArtifactRequirements(
+    options.additionalArtifactRequirements,
+  );
+  await attachToolcraftBrowserRuntimeEvidence({
+    evidenceType: "video-export-artifact",
+    requirementId: options.requirementId,
+    target,
+  });
+  return inspected;
+}

package/templates/starter/e2e/browser-orientation-gizmo-evidence-helpers.ts

@@ -26,6 +26,9 @@ import {
   getToolcraftOrientationAxisPosition,
   type ToolcraftOrientationAxis,
 } from "./browser-orientation-gizmo-actions";
+import {
+  expectToolcraftOrientationLiveDragPreconditions,
+} from "./browser-orientation-gizmo-live-preconditions";
 
 export type ToolcraftOrientationBrowserObservation = {
   outputSignature: string;
@@ -222,6 +225,7 @@ export async function expectToolcraftOrientationAxisDrag(
     message,
     options,
   );
+  await expectToolcraftOrientationLiveDragPreconditions(session);
   const before = snapshotToolcraftOutcome(await observe(), message);
 
   validateObservation(before, options);