@pixel-point/toolcraft 0.0.18 → 0.0.19

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

@@ -43,9 +43,22 @@ export type ToolcraftVideoArtifactInspection = Readonly<{
   width: number;
 }>;
 
+export type ToolcraftSvgArtifactInspection = Readonly<{
+  backgroundColor: string | null;
+  byteLength: number;
+  contentHash: string;
+  height: number;
+  kind: "svg";
+  mediaType: "image/svg+xml";
+  vectorElementCount: number;
+  viewBox: readonly [number, number, number, number];
+  width: number;
+}>;
+
 export type ToolcraftExportArtifactInspection =
   | ToolcraftBinaryArtifactInspection
   | ToolcraftImageArtifactInspection
+  | ToolcraftSvgArtifactInspection
   | ToolcraftVideoArtifactInspection;
 
 export type ToolcraftExportArtifactInspectionResult =
@@ -244,6 +257,52 @@ function validateInspection(
     return;
   }
 
+  if (inspection.kind === "svg") {
+    assertPositiveInteger(inspection.width, "width", requirementId);
+    assertPositiveInteger(inspection.height, "height", requirementId);
+    assertPositiveInteger(
+      inspection.vectorElementCount,
+      "vectorElementCount",
+      requirementId,
+    );
+    if (inspection.mediaType !== "image/svg+xml") {
+      throw new Error(
+        `Export requirement "${requirementId}" must report SVG mediaType.`,
+      );
+    }
+    if (
+      inspection.backgroundColor !== null &&
+      (typeof inspection.backgroundColor !== "string" ||
+        !inspection.backgroundColor.trim())
+    ) {
+      throw new Error(
+        `Export requirement "${requirementId}" must report an SVG background color or null.`,
+      );
+    }
+    if (
+      typeof inspection.contentHash !== "string" ||
+      !inspection.contentHash.trim()
+    ) {
+      throw new Error(
+        `Export requirement "${requirementId}" must hash exact SVG bytes.`,
+      );
+    }
+    if (
+      !Array.isArray(inspection.viewBox) ||
+      inspection.viewBox.length !== 4 ||
+      inspection.viewBox.some(
+        (value) => typeof value !== "number" || !Number.isFinite(value),
+      ) ||
+      Number(inspection.viewBox[2]) <= 0 ||
+      Number(inspection.viewBox[3]) <= 0
+    ) {
+      throw new Error(
+        `Export requirement "${requirementId}" must report a finite positive SVG viewBox.`,
+      );
+    }
+    return;
+  }
+
   throw new Error(
     `Export requirement "${requirementId}" returned an unknown artifact inspection kind.`,
   );
@@ -279,6 +338,7 @@ export function getToolcraftSemanticArtifactSignature(
   validateToolcraftExportArtifactInspection(inspection, requirementId);
   if (inspection.kind === "image") {
     return JSON.stringify({
+      backgroundColor: inspection.backgroundColor,
       decodedPixelHash: inspection.decodedPixelHash,
       height: inspection.height,
       mediaType: inspection.mediaType,
@@ -297,6 +357,16 @@ export function getToolcraftSemanticArtifactSignature(
       width: inspection.width,
     });
   }
+  if (inspection.kind === "svg") {
+    return JSON.stringify({
+      contentHash: inspection.contentHash,
+      height: inspection.height,
+      mediaType: inspection.mediaType,
+      vectorElementCount: inspection.vectorElementCount,
+      viewBox: inspection.viewBox,
+      width: inspection.width,
+    });
+  }
   if (!inspection.contentHash?.trim()) {
     throw new Error(
       `Export requirement "${requirementId}" must report contentHash from decoded product output for semantic comparison.`,

package/templates/starter/e2e/product-observable-helpers.ts

@@ -1,4 +1,4 @@
-import { expect, type Page } from "@playwright/test";
+import type { Page } from "@playwright/test";
 
 import { attachToolcraftBrowserRuntimeEvidence } from "./browser-runtime-evidence";
 import {
@@ -12,6 +12,7 @@ import {
   type ToolcraftBrowserProofSession,
 } from "./browser-proof-session";
 import { expectToolcraftPersistentOutcomeAfterAction } from "./stable-outcome-helpers";
+import { resolveToolcraftProductRasterProbe } from "./browser-product-raster-snapshot";
 
 const defaultProductObservableSelector = [
   "[data-toolcraft-product-output]",
@@ -21,16 +22,6 @@ const defaultProductObservableSelector = [
   "[data-toolcraft-canvas-world] canvas",
   "[data-toolcraft-canvas-world] svg",
 ].join(", ");
-const maxProductObservableDimension = 4096;
-const maxProductObservablePixelArea = 8_388_608;
-const productObservableScreenshotOptions = Object.freeze({
-  animations: "disabled" as const,
-  caret: "hide" as const,
-  scale: "css" as const,
-  type: "png" as const,
-});
-const warmedProductObservableSelectors = new WeakMap<Page, Set<string>>();
-
 export type ToolcraftProductObservableSnapshotOptions = {
   selector?: string;
   timeoutMs?: number;
@@ -51,124 +42,12 @@ export async function getToolcraftProductObservableSnapshot(
   options: ToolcraftProductObservableSnapshotOptions = {},
 ): Promise<string> {
   const selector = options.selector ?? defaultProductObservableSelector;
-  const observable = page.locator(selector).first();
-
-  await expect(
-    observable,
-    `Product observable "${selector}" must exist and be visible.`,
-  ).toBeVisible({
-    timeout: options.timeoutMs ?? 5000,
-  });
-
-  const bounds = await observable.boundingBox();
-
-  if (
-    bounds === null ||
-    !Number.isFinite(bounds.width) ||
-    !Number.isFinite(bounds.height) ||
-    bounds.width <= 0 ||
-    bounds.height <= 0
-  ) {
-    throw new Error(
-      `Product observable "${selector}" must have finite positive visible bounds.`,
-    );
-  }
-
-  const width = Math.ceil(bounds.width);
-  const height = Math.ceil(bounds.height);
-  if (
-    width > maxProductObservableDimension ||
-    height > maxProductObservableDimension ||
-    width * height > maxProductObservablePixelArea
-  ) {
-    throw new Error(
-      `Product observable "${selector}" exceeds the bounded visual proof limit (${width}x${height}; maximum dimension ${maxProductObservableDimension}px and maximum area ${maxProductObservablePixelArea}px). Use a narrower product-observable selector or a fixed semantic proof recipe.`,
-    );
-  }
-
-  const warmedSelectors =
-    warmedProductObservableSelectors.get(page) ?? new Set<string>();
-  if (!warmedSelectors.has(selector)) {
-    await observable.screenshot(productObservableScreenshotOptions);
-    await page.evaluate(
-      () =>
-        new Promise<void>((resolve) => {
-          requestAnimationFrame(() => resolve());
-        }),
-    );
-    warmedSelectors.add(selector);
-    warmedProductObservableSelectors.set(page, warmedSelectors);
-  }
-
-  const raster = await observable.screenshot(productObservableScreenshotOptions);
-  const rasterSnapshot = await page.evaluate(async ({
-    encoded,
-    maxDimension,
-    maxPixelArea,
-    selector: rasterSelector,
-  }) => {
-    const binary = atob(encoded);
-    const bytes = Uint8Array.from(
-      binary,
-      (character) => character.charCodeAt(0),
-    );
-    const bitmap = await createImageBitmap(
-      new Blob([bytes], { type: "image/png" }),
-    );
-
-    try {
-      const rasterWidth = bitmap.width;
-      const rasterHeight = bitmap.height;
-      if (
-        rasterWidth <= 0 ||
-        rasterHeight <= 0 ||
-        rasterWidth > maxDimension ||
-        rasterHeight > maxDimension ||
-        rasterWidth * rasterHeight > maxPixelArea
-      ) {
-        throw new Error(
-          `Product observable "${rasterSelector}" decoded outside the bounded visual proof limit (${rasterWidth}x${rasterHeight}).`,
-        );
-      }
-
-      const canvas = document.createElement("canvas");
-      canvas.width = rasterWidth;
-      canvas.height = rasterHeight;
-      const context = canvas.getContext("2d", { willReadFrequently: true });
-      if (!context) {
-        throw new Error(
-          `Product observable "${rasterSelector}" could not decode its visual pixels.`,
-        );
-      }
-      context.drawImage(bitmap, 0, 0);
-      const pixels = context.getImageData(
-        0,
-        0,
-        rasterWidth,
-        rasterHeight,
-      ).data;
-      let hash = 2166136261;
-      for (const byte of pixels) {
-        hash ^= byte;
-        hash = Math.imul(hash, 16777619);
-      }
-
-      return {
-        height: rasterHeight,
-        rasterHash: (hash >>> 0).toString(16),
-        width: rasterWidth,
-      };
-    } finally {
-      bitmap.close();
-    }
-  }, {
-    encoded: raster.toString("base64"),
-    maxDimension: maxProductObservableDimension,
-    maxPixelArea: maxProductObservablePixelArea,
-    selector,
-  });
-
-  return JSON.stringify(rasterSnapshot);
+  const probe = await resolveToolcraftProductRasterProbe(
+    page,
+    { selector },
+    options.timeoutMs,
+  );
+  return probe.capture();
 }
 
 export async function expectToolcraftProductObservableToChange(

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

@@ -0,0 +1,136 @@
+import { expect, test } from "@playwright/test";
+
+import { createToolcraftSvgFixtureDownload } from "./svg-download-test-fixtures";
+import { inspectToolcraftSvgDownload } from "./svg-artifact-inspection";
+
+const validSvg = `<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="64" height="48" viewBox="0 0 64 48"><g data-toolcraft-product-scene="true"><rect data-column-track="true" x="8" y="8" width="16" height="32" fill="#52AAFF"/></g></svg>`;
+
+test("inspects strict self-contained vector SVG bytes", async ({
+  page,
+}) => {
+  await page.goto("/");
+  const download = await createToolcraftSvgFixtureDownload(page, validSvg);
+
+  const result = await inspectToolcraftSvgDownload({ download, page });
+
+  expect(result.inspection).toMatchObject({
+    backgroundColor: null,
+    height: 48,
+    kind: "svg",
+    mediaType: "image/svg+xml",
+    vectorElementCount: 1,
+    viewBox: [0, 0, 64, 48],
+    width: 64,
+  });
+  expect(result.inspection.byteLength).toBeGreaterThan(0);
+  expect(result.inspection.contentHash).toMatch(/^[a-f0-9]{64}$/u);
+});
+
+test("inspects the exact runtime background before product vectors", async ({
+  page,
+}) => {
+  await page.goto("/");
+  const source = `<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="64" height="48" viewBox="-4 2 64 48"><rect data-toolcraft-background="true" x="-4" y="2" width="64" height="48" fill="#112233"/><g data-toolcraft-product-scene="true"><path data-column-track="true" d="M0 0h1v1z"/></g></svg>`;
+  const download = await createToolcraftSvgFixtureDownload(page, source);
+
+  const result = await inspectToolcraftSvgDownload({ download, page });
+
+  expect(result.inspection.backgroundColor).toBe("#112233");
+  expect(result.inspection.vectorElementCount).toBe(1);
+  expect(result.inspection.viewBox).toEqual([-4, 2, 64, 48]);
+});
+
+const invalidSvgCases = [
+  {
+    message: "not valid XML",
+    name: "valueless XML attribute",
+    source:
+      '<svg xmlns="http://www.w3.org/2000/svg" width="64" height="48" viewBox="0 0 64 48"><rect data-column-graph-background width="1" height="1"/></svg>',
+  },
+  {
+    message: "namespaced <svg> root",
+    name: "missing SVG namespace",
+    source:
+      '<svg width="64" height="48" viewBox="0 0 64 48"><rect width="1" height="1"/></svg>',
+  },
+  {
+    message: "forbidden <image>",
+    name: "raster image",
+    source:
+      '<svg xmlns="http://www.w3.org/2000/svg" width="64" height="48" viewBox="0 0 64 48"><g data-toolcraft-product-scene="true"><image href="data:image/png;base64,AA=="/></g></svg>',
+  },
+  {
+    message: "forbidden <foreignObject>",
+    name: "foreign HTML",
+    source:
+      '<svg xmlns="http://www.w3.org/2000/svg" width="64" height="48" viewBox="0 0 64 48"><g data-toolcraft-product-scene="true"><foreignObject><div xmlns="http://www.w3.org/1999/xhtml">x</div></foreignObject></g></svg>',
+  },
+  {
+    message: "event attribute",
+    name: "event handler",
+    source:
+      '<svg xmlns="http://www.w3.org/2000/svg" width="64" height="48" viewBox="0 0 64 48"><g data-toolcraft-product-scene="true"><rect onclick="alert(1)" width="1" height="1"/></g></svg>',
+  },
+  {
+    message: "only elements and text nodes",
+    name: "processing instruction",
+    source:
+      '<svg xmlns="http://www.w3.org/2000/svg" width="64" height="48" viewBox="0 0 64 48"><g data-toolcraft-product-scene="true"><?xml-stylesheet href="https://example.com/styles.css"?><rect width="1" height="1"/></g></svg>',
+  },
+  {
+    message: "external href",
+    name: "external reference",
+    source:
+      '<svg xmlns="http://www.w3.org/2000/svg" width="64" height="48" viewBox="0 0 64 48"><g data-toolcraft-product-scene="true"><use href="https://example.com/shape.svg#x"/></g></svg>',
+  },
+  {
+    message: "local reference #missing has no target",
+    name: "missing local reference",
+    source:
+      '<svg xmlns="http://www.w3.org/2000/svg" width="64" height="48" viewBox="0 0 64 48"><g data-toolcraft-product-scene="true"><use href="#missing"/></g></svg>',
+  },
+  {
+    message: "positive width",
+    name: "zero dimensions",
+    source:
+      '<svg xmlns="http://www.w3.org/2000/svg" width="0" height="48" viewBox="0 0 0 48"><g data-toolcraft-product-scene="true"><rect width="1" height="1"/></g></svg>',
+  },
+  {
+    message: "no visible vector primitive",
+    name: "empty product vectors",
+    source:
+      '<svg xmlns="http://www.w3.org/2000/svg" width="64" height="48" viewBox="0 0 64 48"><g data-toolcraft-product-scene="true"><defs><path d="M0 0h1v1z"/></defs></g></svg>',
+  },
+  {
+    message: "no visible vector primitive",
+    name: "runtime background without product vectors",
+    source:
+      '<svg xmlns="http://www.w3.org/2000/svg" width="64" height="48" viewBox="0 0 64 48"><rect data-toolcraft-background="true" x="0" y="0" width="64" height="48" fill="#000000"/><g data-toolcraft-product-scene="true"/></svg>',
+  },
+] as const;
+
+for (const { message, name, source } of invalidSvgCases) {
+  test(`rejects ${name}`, async ({ page }) => {
+    await page.goto("/");
+    const download = await createToolcraftSvgFixtureDownload(page, source);
+
+    await expect(
+      inspectToolcraftSvgDownload({ download, page }),
+    ).rejects.toThrow(message);
+  });
+}
+
+test("rejects a non-SVG filename before byte inspection", async ({
+  page,
+}) => {
+  const download = await createToolcraftSvgFixtureDownload(
+    page,
+    validSvg,
+    "column-graph.txt",
+  );
+  await expect(inspectToolcraftSvgDownload({ download, page })).rejects.toThrow(
+    ".svg extension",
+  );
+});