@pixel-point/toolcraft 0.0.17 → 0.0.19

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

@@ -18,6 +18,7 @@ export type InfinityCanvasObservation = Readonly<{
   finiteControlSize: { height: number; width: number } | null;
   finiteControlsPresent: boolean;
   overflow: string;
+  productSceneStatus: "empty" | "ready" | "unavailable" | null;
   sceneRect: { height: number; width: number; x: number; y: number } | null;
   viewportOffset: { x: number; y: number };
 }>;
@@ -91,18 +92,17 @@ export async function observeInfinityCanvasBackground(
 
 export async function observeInfinityCanvas(
   page: Page,
-  sceneSelector?: string,
 ): Promise<InfinityCanvasObservation> {
-  return page.evaluate((selector) => {
+  return page.evaluate(() => {
     const surface = document.querySelector<HTMLElement>(
       "[data-toolcraft-canvas-mode]",
     );
     const world = document.querySelector<HTMLElement>(
       "[data-toolcraft-canvas-world]",
     );
-    const scene = selector
-      ? document.querySelector<HTMLElement>(selector)
-      : null;
+    const productScene = document.querySelector<HTMLElement>(
+      "[data-toolcraft-product-scene]",
+    );
     const finiteControlsPresent = [
       "canvas.aspectRatio",
       "canvas.size.width",
@@ -138,7 +138,7 @@ export async function observeInfinityCanvas(
       const parsed = Number.parseFloat(value ?? "");
       return Number.isFinite(parsed) ? parsed : null;
     };
-    const style = scene?.style;
+    const style = productScene?.style;
     const sceneValues = style
       ? {
           height: read(style.height),
@@ -156,11 +156,11 @@ export async function observeInfinityCanvas(
             y: sceneValues.y!,
           }
         : null;
+    const productSceneStatus =
+      productScene?.dataset.toolcraftProductSceneStatus;
 
     return {
-      artboardPresent: Boolean(
-        editableCanvas,
-      ),
+      artboardPresent: Boolean(editableCanvas),
       canvasMode: surface?.getAttribute("data-toolcraft-canvas-mode") ?? null,
       finiteCanvasSize:
         canvasWidth === null || canvasHeight === null
@@ -172,13 +172,19 @@ export async function observeInfinityCanvas(
           : { height: controlHeight, width: controlWidth },
       finiteControlsPresent,
       overflow: surface ? getComputedStyle(surface).overflow : "missing",
+      productSceneStatus:
+        productSceneStatus === "ready" ||
+        productSceneStatus === "empty" ||
+        productSceneStatus === "unavailable"
+          ? productSceneStatus
+          : null,
       sceneRect,
       viewportOffset: {
         x: Number(world?.dataset.toolcraftCanvasOffsetX ?? 0),
         y: Number(world?.dataset.toolcraftCanvasOffsetY ?? 0),
       },
     };
-  }, sceneSelector);
+  });
 }
 
 export function expectInfiniteCanvasObservation(
@@ -191,7 +197,10 @@ export function expectInfiniteCanvasObservation(
   expect(observation.finiteControlSize).toEqual(null);
   expect(observation.finiteControlsPresent).toBe(false);
   expect(observation.overflow).toBe("visible");
-  if (expectedSceneRect) expect(observation.sceneRect).toEqual(expectedSceneRect);
+  if (expectedSceneRect) {
+    expect(observation.productSceneStatus).toBe("ready");
+    expect(observation.sceneRect).toEqual(expectedSceneRect);
+  }
   expect(Number.isFinite(observation.viewportOffset.x)).toBe(true);
   expect(Number.isFinite(observation.viewportOffset.y)).toBe(true);
 }

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-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);

package/templates/starter/e2e/browser-orientation-gizmo-live-preconditions.ts

@@ -0,0 +1,86 @@
+import { expect, type Locator, type Page } from "@playwright/test";
+
+import {
+  countToolcraftControlOwnersByTarget,
+  getToolcraftControlFieldByTarget,
+} from "./browser-control-target-helpers";
+import {
+  getToolcraftBrowserProofPage,
+  type ToolcraftBrowserProofSession,
+} from "./browser-proof-session";
+
+const TOOLCRAFT_APP_ROOT_SELECTOR = '[data-slot="toolcraft-runtime-app"]';
+const RENDER_SCALE_TARGET = "canvas.renderScale";
+
+async function expectPausedPlaybackWhenPresent(page: Page): Promise<void> {
+  const root = page.locator(TOOLCRAFT_APP_ROOT_SELECTOR);
+  const play = root.getByRole("button", { name: "Play playback" });
+  const pause = root.getByRole("button", { name: "Pause playback" });
+  const playCount = await play.count();
+  const actionCount = playCount + (await pause.count());
+
+  if (actionCount === 0) return;
+
+  expect(
+    actionCount,
+    "Orientation axis-drag proof requires exactly one standard playback action.",
+  ).toBe(1);
+  expect(
+    playCount,
+    "Orientation axis-drag proof must be paused; Play playback must be visible before its baseline.",
+  ).toBe(1);
+  await expect(play).toBeVisible();
+}
+
+async function readFiniteAriaNumber(
+  slider: Locator,
+  name: "aria-valuemax" | "aria-valuenow",
+): Promise<number> {
+  const raw = await slider.getAttribute(name);
+  const value = raw === null || raw.trim() === "" ? Number.NaN : Number(raw);
+
+  expect(
+    Number.isFinite(value),
+    `Orientation axis-drag proof requires a finite ${name} on canvas.renderScale.`,
+  ).toBe(true);
+  return value;
+}
+
+async function expectMaximumRenderScaleWhenPresent(page: Page): Promise<void> {
+  const ownerCount = await countToolcraftControlOwnersByTarget(
+    page,
+    RENDER_SCALE_TARGET,
+  );
+
+  if (ownerCount === 0) return;
+
+  expect(
+    ownerCount,
+    "Orientation axis-drag proof requires exactly one canvas.renderScale owner.",
+  ).toBe(1);
+  const field = await getToolcraftControlFieldByTarget(
+    page,
+    RENDER_SCALE_TARGET,
+  );
+  const slider = field.getByRole("slider");
+  await expect(
+    slider,
+    "Orientation axis-drag proof requires one canvas.renderScale slider.",
+  ).toHaveCount(1);
+  await expect(slider).toBeVisible();
+
+  const value = await readFiniteAriaNumber(slider, "aria-valuenow");
+  const maximum = await readFiniteAriaNumber(slider, "aria-valuemax");
+  expect(
+    value,
+    "Orientation axis-drag proof requires canvas.renderScale at maximum quality before its baseline.",
+  ).toBe(maximum);
+}
+
+export async function expectToolcraftOrientationLiveDragPreconditions(
+  session: ToolcraftBrowserProofSession,
+): Promise<void> {
+  const page = await getToolcraftBrowserProofPage(session);
+  await expectPausedPlaybackWhenPresent(page);
+  await expectMaximumRenderScaleWhenPresent(page);
+}

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