@pixel-point/toolcraft 0.0.17 → 0.0.19

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

@@ -0,0 +1,79 @@
+import { expect, test } from "@playwright/test";
+
+import { expectToolcraftSvgExportArtifact } from "./browser-svg-export-evidence";
+import { createToolcraftSvgFixtureDownload } from "./svg-download-test-fixtures";
+
+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("protected SVG evidence attaches only after exact product semantics pass", async ({
+  page,
+}) => {
+  await page.goto("/");
+
+  const inspected = await expectToolcraftSvgExportArtifact(
+    async () => createToolcraftSvgFixtureDownload(page, validSvg),
+    {
+      expectedElements: [
+        {
+          attributes: {
+            fill: "#52AAFF",
+            height: "32",
+            width: "16",
+          },
+          selector: 'rect[data-column-track="true"]',
+        },
+      ],
+      expectedBackgroundColor: null,
+      expectedHeight: 48,
+      expectedWidth: 64,
+      page,
+      requirementId: "fixture.svg",
+    },
+  );
+
+  expect(inspected.inspection.contentHash).not.toHaveLength(0);
+  expect(
+    test.info().attachments.some(
+      ({ name }) => name === "toolcraft.browser-runtime-evidence",
+    ),
+  ).toBe(true);
+});
+
+test("protected SVG evidence rejects empty or mismatched product expectations", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await expect(
+    expectToolcraftSvgExportArtifact(
+      async () => createToolcraftSvgFixtureDownload(page, validSvg),
+      {
+        expectedElements: [],
+        expectedBackgroundColor: null,
+        expectedHeight: 48,
+        expectedWidth: 64,
+        page,
+        requirementId: "fixture.svg.empty",
+      },
+    ),
+  ).rejects.toThrow("requires product vector expectations");
+
+  await expect(
+    expectToolcraftSvgExportArtifact(
+      async () => createToolcraftSvgFixtureDownload(page, validSvg),
+      {
+        expectedElements: [
+          {
+            attributes: { fill: "#FF0000" },
+            selector: 'rect[data-column-track="true"]',
+          },
+        ],
+        expectedBackgroundColor: null,
+        expectedHeight: 48,
+        expectedWidth: 64,
+        page,
+        requirementId: "fixture.svg.color",
+      },
+    ),
+  ).rejects.toThrow("needs fill=#FF0000");
+});

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

@@ -0,0 +1,152 @@
+import { expect, type Download, type Page } from "@playwright/test";
+import {
+  TOOLCRAFT_SVG_BACKGROUND_ATTRIBUTE,
+  TOOLCRAFT_SVG_NON_RENDERING_CONTAINERS,
+  TOOLCRAFT_SVG_PRODUCT_SCENE_ATTRIBUTE,
+  TOOLCRAFT_SVG_VECTOR_PRIMITIVES,
+} from "@repo/toolcraft-runtime";
+
+import { attachToolcraftBrowserRuntimeEvidence } from "./browser-runtime-evidence";
+import {
+  getToolcraftBrowserActionTarget,
+  isToolcraftBrowserAction,
+  runToolcraftBrowserValueAction,
+  type ToolcraftBrowserAction,
+} from "./browser-proof-session";
+import {
+  inspectToolcraftSvgDownload,
+  type ToolcraftInspectedSvgArtifact,
+} from "./svg-artifact-inspection";
+
+export type ToolcraftSvgElementExpectation = Readonly<{
+  attributes?: Readonly<Record<string, string>>;
+  selector: string;
+  textContent?: string;
+}>;
+
+async function assertProductExpectations(
+  page: Page,
+  source: string,
+  expectations: readonly ToolcraftSvgElementExpectation[],
+): Promise<void> {
+  if (expectations.length === 0) {
+    throw new Error("SVG export evidence requires product vector expectations.");
+  }
+  await page.evaluate(
+    ({
+      backgroundAttribute,
+      expectedElements,
+      nonRenderingNames,
+      productSceneAttribute,
+      svgSource,
+      vectorPrimitiveNames,
+    }) => {
+      const parsed = new DOMParser().parseFromString(
+        svgSource,
+        "image/svg+xml",
+      );
+      const vectorNames = new Set(vectorPrimitiveNames);
+      const nonRendering = new Set(nonRenderingNames);
+      const productScene = parsed.querySelector(
+        `[${productSceneAttribute}="true"]`,
+      );
+      if (!productScene) {
+        throw new Error("SVG product expectations need a product scene.");
+      }
+      for (const expected of expectedElements) {
+        if (
+          !expected.selector.trim() ||
+          (Object.keys(expected.attributes ?? {}).length === 0 &&
+            expected.textContent === undefined)
+        ) {
+          throw new Error(
+            "Each SVG product expectation needs a selector and exact attribute or text semantics.",
+          );
+        }
+        const element = productScene.querySelector(expected.selector);
+        if (!element || !vectorNames.has(element.localName.toLowerCase())) {
+          throw new Error(
+            `SVG product expectation did not match a vector primitive: ${expected.selector}`,
+          );
+        }
+        if (element.hasAttribute(backgroundAttribute)) {
+          throw new Error("SVG product expectations cannot target runtime background.");
+        }
+        let ancestor = element.parentElement;
+        while (ancestor && !ancestor.isSameNode(productScene)) {
+          if (nonRendering.has(ancestor.localName.toLowerCase())) {
+            throw new Error(
+              `SVG product expectation targets non-rendering content: ${expected.selector}`,
+            );
+          }
+          ancestor = ancestor.parentElement;
+        }
+        for (const [name, value] of Object.entries(expected.attributes ?? {})) {
+          if (element.getAttribute(name) !== value) {
+            throw new Error(
+              `SVG product expectation ${expected.selector} needs ${name}=${value}.`,
+            );
+          }
+        }
+        if (
+          expected.textContent !== undefined &&
+          element.textContent !== expected.textContent
+        ) {
+          throw new Error(
+            `SVG product expectation ${expected.selector} has unexpected text.`,
+          );
+        }
+      }
+    },
+    {
+      backgroundAttribute: TOOLCRAFT_SVG_BACKGROUND_ATTRIBUTE,
+      expectedElements: expectations,
+      nonRenderingNames: TOOLCRAFT_SVG_NON_RENDERING_CONTAINERS,
+      productSceneAttribute: TOOLCRAFT_SVG_PRODUCT_SCENE_ATTRIBUTE,
+      svgSource: source,
+      vectorPrimitiveNames: TOOLCRAFT_SVG_VECTOR_PRIMITIVES,
+    },
+  );
+}
+
+export async function expectToolcraftSvgExportArtifact(
+  produceDownload:
+    | (() => Promise<Download>)
+    | ToolcraftBrowserAction<"interaction", Download>,
+  options: Readonly<{
+    expectedElements: readonly ToolcraftSvgElementExpectation[];
+    expectedBackgroundColor: string | null;
+    expectedHeight: number;
+    expectedWidth: number;
+    page: Page;
+    requirementId: string;
+  }>,
+): Promise<ToolcraftInspectedSvgArtifact> {
+  const target = isToolcraftBrowserAction(produceDownload)
+    ? getToolcraftBrowserActionTarget(produceDownload)
+    : undefined;
+  const download = isToolcraftBrowserAction(produceDownload)
+    ? await runToolcraftBrowserValueAction(produceDownload)
+    : await produceDownload();
+  const inspected = await inspectToolcraftSvgDownload({
+    download,
+    page: options.page,
+  });
+  expect(inspected.inspection.width).toBe(options.expectedWidth);
+  expect(inspected.inspection.height).toBe(options.expectedHeight);
+  expect(inspected.inspection.backgroundColor).toBe(
+    options.expectedBackgroundColor,
+  );
+  expect(inspected.inspection.contentHash).not.toHaveLength(0);
+  await assertProductExpectations(
+    options.page,
+    inspected.source,
+    options.expectedElements,
+  );
+  await attachToolcraftBrowserRuntimeEvidence({
+    evidenceType: "svg-export-artifact",
+    requirementId: options.requirementId,
+    target,
+  });
+  return inspected;
+}

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