@pixel-point/toolcraft 0.0.18 → 0.0.19

package/templates/starter/e2e/app-browser-selection-scope-evidence.spec.ts

@@ -0,0 +1,137 @@
+import { expect, test } from "@playwright/test";
+
+import { createToolcraftBrowserProofSession } from "./browser-proof-session";
+import { expectToolcraftSelectionScopedControl } from "./browser-selection-scope-evidence";
+import {
+  attachedEvidenceTypes,
+  editSyntheticSelectedEntity,
+  mountSyntheticSelectionScene,
+} from "./browser-semantic-evidence-test-helpers";
+
+const propertyTarget = "selectedShape.fill";
+const selectionTarget = "selection.activeShape";
+const entityA = {
+  entityId: "shape-a",
+  selector: '[data-proof-entity="shape-a"]',
+} as const;
+const entityB = {
+  entityId: "shape-b",
+  selector: '[data-proof-entity="shape-b"]',
+} as const;
+
+async function createSelectionProofFixture(
+  page: Parameters<typeof createToolcraftBrowserProofSession>[0],
+) {
+  await page.goto("/");
+  const session = await createToolcraftBrowserProofSession(page);
+  await mountSyntheticSelectionScene(page, {
+    controlValue: "#371C4D",
+    fills: { "shape-a": "#A65F15", "shape-b": "#371C4D" },
+    selectedEntityId: "shape-b",
+  });
+
+  return {
+    observePropertyValue: session.observe((root) =>
+      JSON.parse(root.getAttribute("data-proof-selection-scope") ?? "null")
+        .controlValue,
+    ),
+    observeSelectedEntityId: session.observe((root) =>
+      String(
+        JSON.parse(root.getAttribute("data-proof-selection-scope") ?? "null")
+          .selectedEntityId,
+      ),
+    ),
+    proofSession: session,
+  };
+}
+
+function createSelectionActions(
+  session: Awaited<
+    ReturnType<typeof createSelectionProofFixture>
+  >["proofSession"],
+) {
+  return {
+    selectEntityA: session.surfaceAction(selectionTarget, {
+      selector: entityA.selector,
+      surface: "canvas",
+    }),
+    selectEntityB: session.surfaceAction(selectionTarget, {
+      selector: entityB.selector,
+      surface: "canvas",
+    }),
+  };
+}
+
+test("selection-scoped control proves two-direction entity isolation", async ({
+  page,
+}, testInfo) => {
+  const fixture = await createSelectionProofFixture(page);
+  const attachmentCount = testInfo.attachments.length;
+
+  await expectToolcraftSelectionScopedControl({
+    ...fixture,
+    ...createSelectionActions(fixture.proofSession),
+    editEntityA: fixture.proofSession.controlAction(
+      propertyTarget,
+      (_control, currentPage) =>
+        editSyntheticSelectedEntity(currentPage, "#00AAFF"),
+    ),
+    editEntityB: fixture.proofSession.controlAction(
+      propertyTarget,
+      (_control, currentPage) =>
+        editSyntheticSelectedEntity(currentPage, "#FF44AA"),
+    ),
+    entityA,
+    entityB,
+    propertySurface: "panel",
+    propertyTarget,
+    requirementId: "shape.selected-fill",
+    selectionSurface: "canvas",
+    selectionTarget,
+    stabilityIntervalMs: 0,
+  });
+
+  expect(attachedEvidenceTypes(testInfo, attachmentCount)).toEqual([
+    "product-observable-change",
+    "selection-scoped-control",
+  ]);
+});
+
+test("selection-scoped control rejects cross-entity mutation without evidence", async ({
+  page,
+}, testInfo) => {
+  const fixture = await createSelectionProofFixture(page);
+  const attachmentCount = testInfo.attachments.length;
+
+  await expect(
+    expectToolcraftSelectionScopedControl({
+      ...fixture,
+      ...createSelectionActions(fixture.proofSession),
+      editEntityA: fixture.proofSession.controlAction(
+        propertyTarget,
+        async (_control, currentPage) => {
+          await editSyntheticSelectedEntity(currentPage, "#00AAFF");
+          await currentPage
+            .locator(entityB.selector)
+            .evaluate((entity) => {
+              (entity as HTMLElement).style.background = "#FFFFFF";
+            });
+        },
+      ),
+      editEntityB: fixture.proofSession.controlAction(
+        propertyTarget,
+        (_control, currentPage) =>
+          editSyntheticSelectedEntity(currentPage, "#FF44AA"),
+      ),
+      entityA,
+      entityB,
+      propertySurface: "panel",
+      propertyTarget,
+      requirementId: "shape.cross-entity-fill",
+      selectionSurface: "canvas",
+      selectionTarget,
+      stabilityIntervalMs: 0,
+    }),
+  ).rejects.toThrow();
+  expect(testInfo.attachments).toHaveLength(attachmentCount);
+});

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

@@ -0,0 +1,42 @@
+import { expect } from "@playwright/test";
+
+import { attachToolcraftBrowserRuntimeEvidence } from "./browser-runtime-evidence";
+import type { ToolcraftSvgArtifactInspection } from "./export-artifact-helpers";
+import { assertToolcraftInspectedSvgArtifact } from "./svg-artifact-inspection";
+
+export async function expectToolcraftInfinityCanvasSvgExportEvidence(
+  artifacts: Readonly<{
+    finite: ToolcraftSvgArtifactInspection;
+    infinite: ToolcraftSvgArtifactInspection;
+  }>,
+  options: Readonly<{
+    expectedFiniteSize: Readonly<{ height: number; width: number }>;
+    expectedInfiniteSize: Readonly<{ height: number; width: number }>;
+    requirementId: string;
+    target: string;
+  }>,
+): Promise<void> {
+  assertToolcraftInspectedSvgArtifact(artifacts.finite);
+  assertToolcraftInspectedSvgArtifact(artifacts.infinite);
+  expect(artifacts.finite).toMatchObject(options.expectedFiniteSize);
+  expect(artifacts.infinite).toMatchObject(options.expectedInfiniteSize);
+
+  for (const artifact of [artifacts.finite, artifacts.infinite]) {
+    expect(artifact.byteLength).toBeGreaterThan(100);
+    expect(artifact.contentHash).toMatch(/^[a-f0-9]{64}$/u);
+    expect(artifact.mediaType).toBe("image/svg+xml");
+    expect(artifact.vectorElementCount).toBeGreaterThan(0);
+  }
+
+  expect({ height: artifacts.infinite.height, width: artifacts.infinite.width })
+    .not.toEqual({
+      height: artifacts.finite.height,
+      width: artifacts.finite.width,
+    });
+
+  await attachToolcraftBrowserRuntimeEvidence({
+    evidenceType: "infinity-scene-bounds-svg-export",
+    requirementId: options.requirementId,
+    target: options.target,
+  });
+}

package/templates/starter/e2e/browser-layer-evidence-helpers.ts

@@ -11,6 +11,10 @@ import {
   type ToolcraftBrowserAction,
   type ToolcraftBrowserObservation,
 } from "./browser-proof-session";
+import {
+  expectToolcraftSelectionScopedControl,
+  type ToolcraftSelectionScopedControlOptions,
+} from "./browser-selection-scope-evidence";
 
 export type ToolcraftLayerCollectionObservation = {
   layerIds: readonly string[];
@@ -22,12 +26,6 @@ export type ToolcraftLayerGroupingObservation =
     groupSignature: string;
   };
 
-export type ToolcraftLayerSelectedControlObservation = {
-  controlValue: unknown;
-  outputSignature: string;
-  selectedLayerId: string;
-};
-
 export type ToolcraftLayerSelectionObservation = {
   selectedLayerId: string;
 };
@@ -223,37 +221,18 @@ export async function expectToolcraftLayerGrouping(
   return after;
 }
 
+export type ToolcraftSelectedLayerControlOptions =
+  ToolcraftSelectionScopedControlOptions;
+
 export async function expectToolcraftSelectedLayerControl(
-  observeControl: ToolcraftBrowserObservation<ToolcraftLayerSelectedControlObservation>,
-  action: ToolcraftBrowserAction,
-  expected: ToolcraftLayerSelectedControlObservation,
-  options: ToolcraftSemanticEvidenceOptions,
-): Promise<ToolcraftLayerSelectedControlObservation> {
-  const target = requireLayerActionTarget(action, options.requirementId);
-  validateIdentifier(expected.selectedLayerId, "Selected-layer control requires a layer id.");
-  validateIdentifier(
-    expected.outputSignature,
-    "Selected-layer control requires product-output semantics.",
-  );
-  const { after, before } = await expectToolcraftExpectedOutcomeAfterAction(
-    observeControl,
-    action,
-    expected,
-    createToolcraftSemanticTransitionOptions(
-      `Selected-layer control "${options.requirementId}" should edit the selected layer output.`,
-      options,
-    ),
-  );
-  expect(before.selectedLayerId).toBe(after.selectedLayerId);
-  expect(before.controlValue).not.toEqual(after.controlValue);
-  expect(before.outputSignature).not.toBe(after.outputSignature);
-  await attachLayerEvidence(
-    "media-lifecycle",
-    "layer-selected-layer-controls",
-    options.requirementId,
-    target,
-  );
-  return after;
+  options: ToolcraftSelectedLayerControlOptions,
+): Promise<void> {
+  await expectToolcraftSelectionScopedControl(options);
+  await attachToolcraftBrowserRuntimeEvidence({
+    evidenceType: "layer-selected-layer-controls",
+    requirementId: options.requirementId,
+    target: options.propertyTarget,
+  });
 }
 
 export async function expectToolcraftLayerMediaLifecycle(

package/templates/starter/e2e/browser-product-raster-snapshot.ts

@@ -0,0 +1,213 @@
+import { expect, type Locator, type Page } from "@playwright/test";
+
+const maxRasterDimension = 4096;
+const maxRasterPixelArea = 8_388_608;
+const screenshotOptions = Object.freeze({
+  animations: "disabled" as const,
+  caret: "hide" as const,
+  scale: "css" as const,
+  type: "png" as const,
+});
+const warmedSelectors = new WeakMap<Page, Set<string>>();
+
+export type ToolcraftProductRasterRegion = Readonly<{
+  height: number;
+  width: number;
+  x: number;
+  y: number;
+}>;
+
+export type ToolcraftProductRasterProbe = Readonly<{
+  region?: ToolcraftProductRasterRegion;
+  selector: string;
+}>;
+
+export type ToolcraftResolvedProductRasterProbe = Readonly<{
+  bounds: ToolcraftProductRasterRegion;
+  capture: () => Promise<string>;
+  locator: Locator;
+}>;
+
+function validateRegion(
+  region: ToolcraftProductRasterRegion,
+  ownerWidth: number,
+  ownerHeight: number,
+  label: string,
+): void {
+  if (
+    !Number.isFinite(region.x) ||
+    !Number.isFinite(region.y) ||
+    !Number.isFinite(region.width) ||
+    !Number.isFinite(region.height) ||
+    region.x < 0 ||
+    region.y < 0 ||
+    region.width <= 0 ||
+    region.height <= 0 ||
+    region.x + region.width > ownerWidth ||
+    region.y + region.height > ownerHeight
+  ) {
+    throw new Error(
+      `Raster probe "${label}" requires a finite positive region inside its visible selector.`,
+    );
+  }
+}
+
+async function decodeRasterSnapshot(
+  page: Page,
+  raster: Buffer,
+  region: ToolcraftProductRasterRegion | undefined,
+  selector: string,
+): Promise<string> {
+  const snapshot = await page.evaluate(
+    async ({ encoded, maxDimension, maxPixelArea, probeRegion, selector }) => {
+      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 source = probeRegion ?? {
+          height: bitmap.height,
+          width: bitmap.width,
+          x: 0,
+          y: 0,
+        };
+        if (
+          source.width > maxDimension ||
+          source.height > maxDimension ||
+          source.width * source.height > maxPixelArea
+        ) {
+          throw new Error(
+            `Raster probe "${selector}" exceeds the bounded visual proof limit (${source.width}x${source.height}).`,
+          );
+        }
+
+        const canvas = document.createElement("canvas");
+        canvas.width = Math.ceil(source.width);
+        canvas.height = Math.ceil(source.height);
+        const context = canvas.getContext("2d", { willReadFrequently: true });
+        if (!context) {
+          throw new Error(
+            `Raster probe "${selector}" could not decode its visual pixels.`,
+          );
+        }
+        context.drawImage(
+          bitmap,
+          source.x,
+          source.y,
+          source.width,
+          source.height,
+          0,
+          0,
+          source.width,
+          source.height,
+        );
+        const pixels = context.getImageData(
+          0,
+          0,
+          canvas.width,
+          canvas.height,
+        ).data;
+        const digest = await crypto.subtle.digest(
+          "SHA-256",
+          new Uint8Array(
+            pixels.buffer,
+            pixels.byteOffset,
+            pixels.byteLength,
+          ),
+        );
+        return {
+          height: canvas.height,
+          rasterHash: [...new Uint8Array(digest)]
+            .map((byte) => byte.toString(16).padStart(2, "0"))
+            .join(""),
+          width: canvas.width,
+        };
+      } finally {
+        bitmap.close();
+      }
+    },
+    {
+      encoded: raster.toString("base64"),
+      maxDimension: maxRasterDimension,
+      maxPixelArea: maxRasterPixelArea,
+      probeRegion: region,
+      selector,
+    },
+  );
+
+  return JSON.stringify(snapshot);
+}
+
+export async function resolveToolcraftProductRasterProbe(
+  page: Page,
+  probe: ToolcraftProductRasterProbe,
+  timeoutMs = 5000,
+): Promise<ToolcraftResolvedProductRasterProbe> {
+  if (!probe.selector.trim()) {
+    throw new Error("A raster probe requires a non-empty selector.");
+  }
+
+  const locator = page.locator(probe.selector);
+  await expect(
+    locator,
+    `Raster probe "${probe.selector}" must resolve exactly once.`,
+  ).toHaveCount(1);
+  await expect(locator).toBeVisible({ timeout: timeoutMs });
+  const ownerBounds = await locator.boundingBox();
+  if (
+    ownerBounds === null ||
+    !Number.isFinite(ownerBounds.width) ||
+    !Number.isFinite(ownerBounds.height) ||
+    ownerBounds.width <= 0 ||
+    ownerBounds.height <= 0
+  ) {
+    throw new Error(
+      `Raster probe "${probe.selector}" must have finite positive visible bounds.`,
+    );
+  }
+
+  if (probe.region) {
+    validateRegion(
+      probe.region,
+      ownerBounds.width,
+      ownerBounds.height,
+      probe.selector,
+    );
+  }
+  const localBounds = probe.region ?? {
+    height: ownerBounds.height,
+    width: ownerBounds.width,
+    x: 0,
+    y: 0,
+  };
+  const bounds = {
+    height: localBounds.height,
+    width: localBounds.width,
+    x: ownerBounds.x + localBounds.x,
+    y: ownerBounds.y + localBounds.y,
+  };
+
+  return {
+    bounds,
+    capture: async () => {
+      const pageSelectors = warmedSelectors.get(page) ?? new Set<string>();
+      const key = `${probe.selector}:${JSON.stringify(probe.region ?? null)}`;
+      if (!pageSelectors.has(key)) {
+        await locator.screenshot(screenshotOptions);
+        await page.evaluate(
+          () => new Promise<void>((resolve) => requestAnimationFrame(() => resolve())),
+        );
+        pageSelectors.add(key);
+        warmedSelectors.set(page, pageSelectors);
+      }
+      const raster = await locator.screenshot(screenshotOptions);
+      return decodeRasterSnapshot(page, raster, probe.region, probe.selector);
+    },
+    locator,
+  };
+}

package/templates/starter/e2e/browser-proof-session.ts

@@ -6,27 +6,27 @@ import {
 } from "@playwright/test";
 
 import { getToolcraftControlFieldByTarget } from "./browser-control-target-helpers";
-
+import {
+  createToolcraftSurfaceActionRunner,
+  normalizeToolcraftSurfaceActionOptions,
+  type ToolcraftBrowserActionSurface,
+  type ToolcraftBrowserSurfaceActionOptions,
+} from "./browser-proof-surface-action";
+import type {
+  ToolcraftBrowserAction,
+  ToolcraftBrowserObservation,
+} from "./browser-proof-types";
 const TOOLCRAFT_APP_ROOT_SELECTOR = '[data-slot="toolcraft-runtime-app"]';
 const TOOLCRAFT_APP_TITLE_SELECTOR = 'meta[name="toolcraft-app-title"]';
 const TOOLCRAFT_SERVER_IDENTITY_PATH = "/.toolcraft/server-identity.json";
 
-declare const toolcraftBrowserActionBrand: unique symbol;
-declare const toolcraftBrowserObservationBrand: unique symbol;
 declare const toolcraftBrowserSessionBrand: unique symbol;
 
-export type ToolcraftBrowserAction<
-  Kind extends string = "interaction",
-  Result = void,
-> = {
-  readonly [toolcraftBrowserActionBrand]: true;
-  readonly kind?: Kind;
-  readonly result?: Result;
-};
-
-export type ToolcraftBrowserObservation<T> = {
-  readonly [toolcraftBrowserObservationBrand]: T;
-};
+export type {
+  ToolcraftBrowserAction,
+  ToolcraftBrowserObservation,
+} from "./browser-proof-types";
+export type { ToolcraftBrowserActionSurface } from "./browser-proof-surface-action";
 
 export type ToolcraftBrowserProofSession = {
   action<Result = void>(
@@ -36,6 +36,10 @@ export type ToolcraftBrowserProofSession = {
     target: string,
     run: (control: Locator, page: Page) => Promise<Result>,
   ): ToolcraftBrowserAction<"interaction", Result>;
+  surfaceAction(
+    target: string,
+    options: ToolcraftBrowserSurfaceActionOptions,
+  ): ToolcraftBrowserAction<"interaction">;
   targetAction<Result = void>(
     target: string,
     run: (page: Page) => Promise<Result>,
@@ -60,6 +64,7 @@ type ActionRecord = {
   kind: "interaction" | "reload";
   run: (page: Page) => Promise<unknown>;
   session: SessionRecord;
+  surface?: ToolcraftBrowserActionSurface;
   target?: string;
 };
 
@@ -289,6 +294,23 @@ export async function createToolcraftBrowserProofSession(
           return run(control, currentPage);
         },
         session: record,
+        surface: "panel",
+        target: normalizedTarget,
+      });
+      return action;
+    },
+    surfaceAction(
+      target: string,
+      rawOptions: ToolcraftBrowserSurfaceActionOptions,
+    ): ToolcraftBrowserAction<"interaction"> {
+      const normalizedTarget = normalizeActionTarget(target);
+      const options = normalizeToolcraftSurfaceActionOptions(rawOptions);
+      const action = Object.freeze({}) as ToolcraftBrowserAction<"interaction">;
+      actionRecords.set(action, {
+        kind: "interaction",
+        run: createToolcraftSurfaceActionRunner(options),
+        session: record,
+        surface: options.surface,
         target: normalizedTarget,
       });
       return action;
@@ -364,6 +386,12 @@ export function getToolcraftBrowserActionTarget(
   return requireAction(action).target;
 }
 
+export function getToolcraftBrowserActionSurface(
+  action: ToolcraftBrowserAction,
+): ToolcraftBrowserActionSurface | undefined {
+  return requireAction(action).surface;
+}
+
 export async function readToolcraftBrowserObservation<T>(
   observation: ToolcraftBrowserObservation<T>,
 ): Promise<T> {

package/templates/starter/e2e/browser-proof-surface-action.ts

@@ -0,0 +1,79 @@
+import { expect, type Page } from "@playwright/test";
+
+export type ToolcraftBrowserActionSurface = "canvas" | "panel";
+
+export type ToolcraftBrowserSurfaceActionOptions = Readonly<{
+  position?: Readonly<{ x: number; y: number }>;
+  selector: string;
+  surface: ToolcraftBrowserActionSurface;
+}>;
+
+export function normalizeToolcraftSurfaceActionOptions(
+  options: ToolcraftBrowserSurfaceActionOptions,
+): ToolcraftBrowserSurfaceActionOptions {
+  if (!options.selector.trim()) {
+    throw new Error("A surface action requires a non-empty selector.");
+  }
+  if (options.surface !== "canvas" && options.surface !== "panel") {
+    throw new Error("A surface action requires canvas or panel ownership.");
+  }
+  if (
+    options.position &&
+    (!Number.isFinite(options.position.x) ||
+      !Number.isFinite(options.position.y) ||
+      options.position.x < 0 ||
+      options.position.y < 0)
+  ) {
+    throw new Error(
+      "A surface action position requires finite nonnegative coordinates.",
+    );
+  }
+  return options;
+}
+
+async function getToolcraftActionSurface(
+  page: Page,
+  options: ToolcraftBrowserSurfaceActionOptions,
+): Promise<ToolcraftBrowserActionSurface | null> {
+  return page.locator(options.selector).evaluate((element) => {
+    if (element.closest('[data-slot="toolcraft-runtime-canvas"]')) {
+      return "canvas";
+    }
+    if (
+      element.closest(
+        "[data-toolcraft-controls-panel-shell], [data-toolcraft-layers-panel]",
+      )
+    ) {
+      return "panel";
+    }
+    return null;
+  });
+}
+
+export function createToolcraftSurfaceActionRunner(
+  options: ToolcraftBrowserSurfaceActionOptions,
+): (page: Page) => Promise<void> {
+  return async (page) => {
+    const locator = page.locator(options.selector);
+    await expect(
+      locator,
+      `Surface action locator "${options.selector}" must resolve exactly once.`,
+    ).toHaveCount(1);
+    await expect(locator).toBeVisible();
+    expect(
+      await getToolcraftActionSurface(page, options),
+      `Surface action locator "${options.selector}" must live inside the declared ${options.surface} runtime surface.`,
+    ).toBe(options.surface);
+
+    if (options.position) {
+      const bounds = await locator.boundingBox();
+      expect(bounds).not.toBeNull();
+      expect(options.position.x).toBeLessThanOrEqual(bounds!.width);
+      expect(options.position.y).toBeLessThanOrEqual(bounds!.height);
+    }
+
+    await locator.click(
+      options.position ? { position: options.position } : undefined,
+    );
+  };
+}

package/templates/starter/e2e/browser-proof-types.ts

@@ -0,0 +1,15 @@
+declare const toolcraftBrowserActionBrand: unique symbol;
+declare const toolcraftBrowserObservationBrand: unique symbol;
+
+export type ToolcraftBrowserAction<
+  Kind extends string = "interaction",
+  Result = void,
+> = {
+  readonly [toolcraftBrowserActionBrand]: true;
+  readonly kind?: Kind;
+  readonly result?: Result;
+};
+
+export type ToolcraftBrowserObservation<T> = {
+  readonly [toolcraftBrowserObservationBrand]: T;
+};