@pixel-point/toolcraft 0.0.15 → 0.0.17

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-model-appearance-evidence-helpers.ts

@@ -0,0 +1,65 @@
+import { attachToolcraftBrowserRuntimeEvidence } from "./browser-runtime-evidence";
+import {
+  createToolcraftSemanticTransitionOptions,
+  expectToolcraftExpectedOutcomeAfterAction,
+} from "./browser-acceptance-transition-helpers";
+import type {
+  ToolcraftBrowserAction,
+  ToolcraftBrowserObservation,
+} from "./browser-proof-session";
+import {
+  assertToolcraftModelAppearanceCoverage,
+  type ToolcraftModelAppearanceCoverage,
+} from "./browser-model-appearance-evidence";
+import {
+  validateToolcraftModelImportObservation,
+  type ToolcraftModelImportBrowserObservation,
+  type ToolcraftModelImportEvidenceOptions,
+} from "./browser-model-import-evidence-helpers";
+
+const evidenceTypeByCoverage = {
+  "appearance-preservation": "model-appearance-preservation",
+  "deterministic-root-selection": "model-deterministic-root-selection",
+  "fallback-appearance": "model-fallback-appearance",
+  "package-extraction": "model-package-extraction",
+  "pixel-output": "model-pixel-output",
+  "presentation-consumer-readiness": "model-presentation-consumer-readiness",
+} as const;
+
+function message(
+  coverage: ToolcraftModelAppearanceCoverage,
+  requirementId: string,
+): string {
+  return `Model import ${coverage} "${requirementId}" must prove package, presentation, and rendered appearance before evidence is attached.`;
+}
+
+export async function expectToolcraftModelAppearanceCoverage(
+  observation: ToolcraftBrowserObservation<ToolcraftModelImportBrowserObservation>,
+  action: ToolcraftBrowserAction,
+  expected: ToolcraftModelImportBrowserObservation,
+  coverage: ToolcraftModelAppearanceCoverage,
+  options: ToolcraftModelImportEvidenceOptions,
+) {
+  validateToolcraftModelImportObservation(expected, options);
+  const result = await expectToolcraftExpectedOutcomeAfterAction(
+    observation,
+    action,
+    expected,
+    createToolcraftSemanticTransitionOptions(
+      message(coverage, options.requirementId),
+      options,
+    ),
+  );
+  validateToolcraftModelImportObservation(result.before, options);
+  assertToolcraftModelAppearanceCoverage(
+    result.after,
+    coverage,
+    message(coverage, options.requirementId),
+  );
+  await attachToolcraftBrowserRuntimeEvidence({
+    evidenceType: evidenceTypeByCoverage[coverage],
+    requirementId: `${options.requirementId}#${coverage}`,
+    target: options.target,
+  });
+  return result.after;
+}

package/templates/starter/e2e/browser-model-appearance-evidence.ts

@@ -0,0 +1,171 @@
+import { expect } from "@playwright/test";
+
+export const TOOLCRAFT_FALLBACK_MATERIAL_SIGNATURE =
+  "fallback:base-linear(0.8,0.8,0.8):metallic(0):roughness(0.5):emissive(0,0,0):alpha(1)";
+
+export type ToolcraftModelAppearanceCoverage =
+  | "appearance-preservation"
+  | "deterministic-root-selection"
+  | "fallback-appearance"
+  | "package-extraction"
+  | "pixel-output"
+  | "presentation-consumer-readiness";
+
+export type ToolcraftModelOutputObservation = Readonly<{
+  appearanceSource: "authored" | "fallback";
+  documentId: string;
+  editorChrome: "excluded" | "included";
+  materialSignature: string;
+  modelSignature: string;
+  opacity: number;
+  outputSignature: string;
+  pixelSamples: readonly (readonly [number, number, number, number])[];
+  pixelSignature: string;
+  presentationCacheKey: string;
+}>;
+
+export type ToolcraftModelPackageObservation = Readonly<{
+  candidateRootPaths: readonly string[];
+  extractedFileCount: number;
+  kind: "folder" | "standalone" | "zip";
+  selectedRootPath: string;
+}>;
+
+export type ToolcraftModelPresentationObservation = Readonly<{
+  consumerId: string | null;
+  mode: "custom" | "runtime";
+  status: "error" | "ready";
+}>;
+
+export type ToolcraftModelResourceDisposalObservation = Readonly<{
+  acquired: number;
+  active: number;
+  cacheHits: number;
+  disposed: number;
+  released: number;
+}>;
+
+export type ToolcraftModelAppearanceObservation = Readonly<{
+  package: ToolcraftModelPackageObservation | null;
+  presentation: ToolcraftModelPresentationObservation | null;
+  previewOutput: ToolcraftModelOutputObservation | null;
+  resources: ToolcraftModelResourceDisposalObservation;
+}>;
+
+function expectNonEmpty(value: string, description: string): void {
+  expect(value.trim(), description).not.toBe("");
+}
+
+export function validateToolcraftModelOutputObservation(
+  output: ToolcraftModelOutputObservation,
+  description: string,
+): void {
+  expectNonEmpty(output.documentId, `${description} must identify its document.`);
+  expectNonEmpty(output.materialSignature, `${description} must identify its material.`);
+  expectNonEmpty(output.modelSignature, `${description} must identify the rendered model.`);
+  expectNonEmpty(output.outputSignature, `${description} must report an output signature.`);
+  expectNonEmpty(output.pixelSignature, `${description} must report a pixel signature.`);
+  expectNonEmpty(
+    output.presentationCacheKey,
+    `${description} must identify the shared appearance cache entry.`,
+  );
+  expect(/^(?:blank|empty|transparent|none)$/iu.test(output.pixelSignature.trim())).toBe(false);
+  expect(
+    output.editorChrome,
+    `${description} must sample product output without editor gizmos or handles.`,
+  ).toBe("excluded");
+  expect(output.pixelSamples.length, `${description} must sample rendered RGBA pixels.`)
+    .toBeGreaterThan(0);
+  for (const sample of output.pixelSamples) {
+    expect(sample).toHaveLength(4);
+    expect(sample.every((channel) => Number.isInteger(channel) && channel >= 0 && channel <= 255))
+      .toBe(true);
+  }
+  expect(Number.isFinite(output.opacity), `${description} opacity must be finite.`).toBe(true);
+  expect(output.opacity, `${description} opacity must be within 0..1.`).toBeGreaterThanOrEqual(0);
+  expect(output.opacity, `${description} opacity must be within 0..1.`).toBeLessThanOrEqual(1);
+}
+
+export function validateToolcraftModelAppearanceObservation(
+  observation: ToolcraftModelAppearanceObservation,
+  description: string,
+): void {
+  if (observation.package) {
+    const packageObservation = observation.package;
+    expect(packageObservation.extractedFileCount).toBeGreaterThan(0);
+    expect(packageObservation.candidateRootPaths.length).toBeGreaterThan(0);
+    expect(new Set(packageObservation.candidateRootPaths).size)
+      .toBe(packageObservation.candidateRootPaths.length);
+    for (const rootPath of packageObservation.candidateRootPaths) {
+      expectNonEmpty(rootPath, `${description} package roots must be non-empty.`);
+    }
+    expect(packageObservation.candidateRootPaths)
+      .toContain(packageObservation.selectedRootPath);
+  }
+  if (observation.presentation) {
+    const presentation = observation.presentation;
+    if (presentation.mode === "custom") {
+      expectNonEmpty(
+        presentation.consumerId ?? "",
+        `${description} custom presentation must identify its checked consumer.`,
+      );
+    } else {
+      expect(presentation.consumerId).toBeNull();
+    }
+  }
+  const resources = observation.resources;
+  for (const count of Object.values(resources)) {
+    expect(Number.isInteger(count) && count >= 0).toBe(true);
+  }
+  expect(resources.active).toBe(resources.acquired - resources.released);
+  expect(resources.cacheHits).toBeLessThanOrEqual(resources.acquired);
+  expect(resources.disposed).toBeLessThanOrEqual(resources.released);
+}
+
+function requirePreview(
+  observation: ToolcraftModelAppearanceObservation,
+  description: string,
+): ToolcraftModelOutputObservation {
+  expect(observation.previewOutput, `${description} requires visible model output.`)
+    .not.toBeNull();
+  return observation.previewOutput!;
+}
+
+export function assertToolcraftModelAppearanceCoverage(
+  observation: ToolcraftModelAppearanceObservation,
+  coverage: ToolcraftModelAppearanceCoverage,
+  description: string,
+): void {
+  if (coverage === "package-extraction") {
+    expect(observation.package, `${description} requires package provenance.`).not.toBeNull();
+    expect(["folder", "zip"]).toContain(observation.package!.kind);
+    expect(observation.package!.extractedFileCount).toBeGreaterThan(1);
+    return;
+  }
+  if (coverage === "deterministic-root-selection") {
+    expect(observation.package, `${description} requires package provenance.`).not.toBeNull();
+    expect(observation.package!.selectedRootPath)
+      .toBe([...observation.package!.candidateRootPaths].sort()[0]);
+    return;
+  }
+  const output = requirePreview(observation, description);
+  if (coverage === "appearance-preservation") {
+    expect(output.appearanceSource).toBe("authored");
+    expectNonEmpty(output.materialSignature, `${description} must preserve authored appearance.`);
+    return;
+  }
+  if (coverage === "fallback-appearance") {
+    expect(output.appearanceSource).toBe("fallback");
+    expect(output.materialSignature).toBe(TOOLCRAFT_FALLBACK_MATERIAL_SIGNATURE);
+    return;
+  }
+  if (coverage === "presentation-consumer-readiness") {
+    expect(observation.presentation, `${description} requires presentation status.`).not.toBeNull();
+    expect(observation.presentation!.status).toBe("ready");
+    return;
+  }
+  expect(
+    output.pixelSamples.some((sample) => sample[3] > 0),
+    `${description} must include nontransparent sampled output pixels.`,
+  ).toBe(true);
+}