@pixel-point/toolcraft 0.0.17 → 0.0.19

package/templates/starter/e2e/app-browser-motion-reference-requirements.spec.ts

@@ -0,0 +1,411 @@
+import { expect, test } from "@playwright/test";
+import type {
+  FullConfig,
+  FullResult,
+  Suite,
+} from "@playwright/test/reporter";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  createMotionReferenceBehavior,
+  motionReferenceAcceptance,
+  createMotionReferenceInput,
+  createTimedMotionReferenceStudy,
+} from "../src/app/starter-acceptance.motion-reference-test-utils";
+import {
+  createToolcraftMotionReferenceId,
+  createToolcraftMotionReferenceStudyId,
+} from "../scripts/toolcraft-motion-reference-artifacts.mjs";
+import {
+  starterAcceptance,
+  starterControlSectionInventory,
+  starterProductReadiness,
+  starterTransferMode,
+  type ToolcraftComponentAcceptance,
+  type ToolcraftMotionReferenceEvidence,
+  type ToolcraftMotionReferenceStudy,
+  type ToolcraftTransferMode,
+} from "../src/app/starter-acceptance";
+import { writeCanonicalToolcraftMotionReferenceEvidence } from "../src/app/acceptance/motion-reference-evidence.mjs";
+import { starterSchema } from "../src/app/starter-schema";
+import { deriveToolcraftBrowserRuntimeRequirements } from "./browser-runtime-evidence-requirements";
+import ToolcraftDeliveryCatalogReporter, {
+  validateToolcraftDeliveryCatalogReferences,
+} from "./toolcraft-delivery-catalog-reporter";
+
+const motionReferenceId =
+  "motion-reference-v1-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" as const;
+
+const invalidReferenceTransferMode: ToolcraftTransferMode = {
+  ...starterTransferMode,
+  referenceInputs: [
+    {
+      behaviors: [],
+      kind: "motion-reference",
+      referenceId: motionReferenceId,
+      studies: [],
+    },
+  ],
+};
+
+const validationFixture = {
+  acceptance: starterAcceptance,
+  productReadiness: starterProductReadiness,
+  rootDir: process.cwd(),
+  schema: starterSchema,
+  sectionInventory: starterControlSectionInventory,
+  transferMode: invalidReferenceTransferMode,
+};
+
+function createCanonicalMotionReferenceFixture() {
+  const authoredStudy = createTimedMotionReferenceStudy();
+  if (authoredStudy.evidence.timingMode !== "seconds") {
+    throw new Error("Timed motion fixture must use seconds timing.");
+  }
+  const frameIdByAuthoredId = new Map(
+    authoredStudy.evidence.reviewedFrames.map((frame) => [
+      frame.frameId,
+      `source-frame:${frame.sourceFrameIndex}`,
+    ]),
+  );
+  const reviewedFrames = authoredStudy.evidence.reviewedFrames.map((frame) => ({
+    ...frame,
+    frameId: frameIdByAuthoredId.get(frame.frameId)!,
+  }));
+  const detectedEvents = authoredStudy.evidence.detectedEvents.map((event) => {
+    const windowFrameIds = event.windowFrameIds.map(
+      (frameId) => frameIdByAuthoredId.get(frameId)!,
+    );
+    return {
+      ...event,
+      afterFrameId: frameIdByAuthoredId.get(event.afterFrameId)!,
+      beforeFrameId: frameIdByAuthoredId.get(event.beforeFrameId)!,
+      eventId: `motion-event:${event.kind}:${windowFrameIds
+        .map((frameId) => frameId.slice("source-frame:".length))
+        .join("-")}`,
+      peakFrameId: frameIdByAuthoredId.get(event.peakFrameId)!,
+      windowFrameIds,
+    };
+  });
+  const evidenceSeed = {
+    ...authoredStudy.evidence,
+    detectedEvents,
+    overviewFrameIds: authoredStudy.evidence.overviewFrameIds.map(
+      (frameId) => frameIdByAuthoredId.get(frameId)!,
+    ),
+    reviewedFrames,
+  };
+  const studyId = createToolcraftMotionReferenceStudyId(evidenceSeed);
+  const evidence: ToolcraftMotionReferenceEvidence = {
+    ...evidenceSeed,
+    contactSheet: {
+      ...evidenceSeed.contactSheet,
+      path: `src/app/reference-studies/${studyId}/contact-sheet.png` as const,
+    },
+    studyId,
+  };
+  const study: ToolcraftMotionReferenceStudy = {
+    ...authoredStudy,
+    evidence,
+    evidencePath: `src/app/reference-studies/${studyId}/evidence.json` as const,
+    events: authoredStudy.events.map((event, index) => ({
+      ...event,
+      evidenceEventId: detectedEvents[index].eventId,
+    })),
+    phases: authoredStudy.phases.map((phase) => ({
+      ...phase,
+      fromFrameId: frameIdByAuthoredId.get(phase.fromFrameId)!,
+      toFrameId: frameIdByAuthoredId.get(phase.toFrameId)!,
+    })),
+    studyId,
+  };
+  const referenceId = createToolcraftMotionReferenceId(evidence);
+  const behavior = createMotionReferenceBehavior({
+    timingClaims: [{ claim: "duration", studyId }],
+  });
+  const input = createMotionReferenceInput({
+    behaviors: [behavior],
+    referenceId,
+    studies: [study],
+  });
+  const acceptance = {
+    ...motionReferenceAcceptance,
+    motionReferenceCoverage: [
+      { behaviorId: behavior.id, referenceId },
+    ],
+  };
+  return { acceptance, input, study };
+}
+
+function createAcceptance(
+  overrides: Partial<ToolcraftComponentAcceptance> = {},
+): ToolcraftComponentAcceptance {
+  return {
+    automated: true,
+    automatedTestName: "matches the reference retarget behavior",
+    browser: true,
+    browserTestName: "browser: matches the reference retarget behavior",
+    componentType: "custom-renderer",
+    evidence: "product-output",
+    expectedObservable: "The renderer preserves the delayed retarget behavior.",
+    fixture: "motion reference behavior",
+    id: "reference.delayed-retarget",
+    kind: "runtime",
+    target: "renderer.anchor-state",
+    userAction: "Compare the running renderer with the inspected reference event.",
+    ...overrides,
+  };
+}
+
+function createReporterFixture(projectRoot: string) {
+  const browserRoot = path.join(projectRoot, "e2e");
+  const fileSuite = {
+    location: { file: path.join(browserRoot, "app-persistence.spec.ts") },
+    parent: undefined,
+    type: "file",
+  };
+  const suite = {
+    allTests: () => [
+      {
+        parent: fileSuite,
+        title: starterAcceptance[0].browserTestName,
+      },
+    ],
+  } as unknown as Suite;
+  const config = {
+    configFile: path.join(projectRoot, "playwright.config.ts"),
+    rootDir: browserRoot,
+  } as FullConfig;
+  const result = { status: "passed" } as FullResult;
+  return { browserRoot, config, result, suite };
+}
+
+test("mapped motion behavior requires output-change and reference-parity evidence", () => {
+  const requirements = deriveToolcraftBrowserRuntimeRequirements([
+    createAcceptance({
+      motionReferenceCoverage: [
+        { behaviorId: "delayed-retarget", referenceId: motionReferenceId },
+      ],
+    }),
+  ]);
+
+  expect(requirements.map(({ evidenceType }) => evidenceType)).toEqual([
+    "product-observable-change",
+    "reference-parity",
+  ]);
+});
+
+test("ordinary output change does not acquire motion reference parity", () => {
+  const requirements = deriveToolcraftBrowserRuntimeRequirements([
+    createAcceptance(),
+  ]);
+
+  expect(requirements.map(({ evidenceType }) => evidenceType)).toEqual([
+    "product-observable-change",
+  ]);
+});
+
+test("delivery catalog validation rejects semantic study errors before catalog work", async () => {
+  await expect(
+    validateToolcraftDeliveryCatalogReferences(validationFixture, async () => []),
+  ).rejects.toThrow(/Toolcraft reference validation failed:[\s\S]*study/iu);
+});
+
+test("delivery catalog validation rejects a tampered contact sheet", async () => {
+  const rootDir = await fs.mkdtemp(
+    path.join(os.tmpdir(), "toolcraft-catalog-tampered-sheet-"),
+  );
+  const { acceptance, input, study } = createCanonicalMotionReferenceFixture();
+  const evidencePath = path.join(rootDir, study.evidencePath);
+  const contactSheetPath = path.join(rootDir, study.evidence.contactSheet.path);
+  await fs.mkdir(path.dirname(evidencePath), { recursive: true });
+  await fs.mkdir(path.join(rootDir, "e2e"));
+  await fs.writeFile(
+    evidencePath,
+    writeCanonicalToolcraftMotionReferenceEvidence(study.evidence),
+  );
+  await fs.writeFile(contactSheetPath, "tampered-contact-sheet");
+
+  try {
+    await expect(
+      validateToolcraftDeliveryCatalogReferences({
+        ...validationFixture,
+        acceptance: [starterAcceptance[0], acceptance],
+        rootDir: path.join(rootDir, "e2e"),
+        transferMode: {
+          ...starterTransferMode,
+          referenceInputs: [input],
+        },
+      }),
+    ).rejects.toThrow(/could not be read/iu);
+    await expect(
+      validateToolcraftDeliveryCatalogReferences({
+        ...validationFixture,
+        acceptance: [starterAcceptance[0], acceptance],
+        rootDir,
+        transferMode: {
+          ...starterTransferMode,
+          referenceInputs: [input],
+        },
+      }),
+    ).rejects.toThrow(/contact sheet[\s\S]*SHA-256/iu);
+  } finally {
+    await fs.rm(rootDir, { force: true, recursive: true });
+  }
+});
+
+test("no-reference reporter lifecycle skips artifact and process-selection work", async () => {
+  const projectRoot = path.join(os.tmpdir(), "toolcraft-reporter-no-reference");
+  const { config, result, suite } = createReporterFixture(projectRoot);
+  let artifactValidationCalls = 0;
+  const reporter = new ToolcraftDeliveryCatalogReporter({
+    createCatalog: () => ({ acceptance: [], performance: [], version: 2 }),
+    validateReferences: (input) =>
+      validateToolcraftDeliveryCatalogReferences(input, async () => {
+        artifactValidationCalls += 1;
+        throw new Error(
+          "Artifact or process selection must not run without references.",
+        );
+      }),
+    writeError: (source) => {
+      throw new Error(`Unexpected reporter error: ${source}`);
+    },
+    writeOutput: () => {},
+  });
+
+  reporter.onBegin(config, suite);
+  await expect(reporter.onEnd(result)).resolves.toBeUndefined();
+  expect(artifactValidationCalls).toBe(0);
+});
+
+test("reporter validates the project root at awaited onEnd before publishing JSON", async () => {
+  const projectRoot = path.join(os.tmpdir(), "toolcraft-reporter-project");
+  const { config, result, suite } = createReporterFixture(projectRoot);
+  const output: string[] = [];
+  const validatedRoots: string[] = [];
+  const lifecycle: string[] = [];
+  const reporter = new ToolcraftDeliveryCatalogReporter({
+    createCatalog: () => {
+      lifecycle.push("catalog");
+      return { acceptance: [], performance: [], version: 2 };
+    },
+    validateReferences: async ({ rootDir }) => {
+      lifecycle.push("validation:start");
+      await Promise.resolve();
+      validatedRoots.push(rootDir);
+      lifecycle.push("validation:end");
+    },
+    writeError: (source) => {
+      throw new Error(`Unexpected reporter error: ${source}`);
+    },
+    writeOutput: (source) => {
+      output.push(source);
+    },
+  });
+
+  expect(reporter.onBegin(config, suite)).toBeUndefined();
+  expect(output).toEqual([]);
+  await expect(reporter.onEnd(result)).resolves.toBeUndefined();
+  expect(validatedRoots).toEqual([projectRoot]);
+  expect(lifecycle).toEqual(["validation:start", "validation:end", "catalog"]);
+  expect(output).toHaveLength(1);
+  expect(JSON.parse(output[0])).toMatchObject({ version: 2 });
+});
+
+test("awaited semantic and artifact failures suppress JSON and fail Playwright", async () => {
+  const projectRoot = path.join(os.tmpdir(), "toolcraft-reporter-invalid");
+  const { config, result, suite } = createReporterFixture(projectRoot);
+  for (const validationError of [
+    "semantic motion reference study is incomplete",
+    "tampered motion reference contact sheet",
+  ]) {
+    const errors: string[] = [];
+    const output: string[] = [];
+    let catalogCalls = 0;
+    const reporter = new ToolcraftDeliveryCatalogReporter({
+      createCatalog: () => {
+        catalogCalls += 1;
+        throw new Error("Catalog creation must not run after reference failure.");
+      },
+      validateReferences: async () => {
+        await Promise.resolve();
+        throw new Error(validationError);
+      },
+      writeError: (source) => {
+        errors.push(source);
+      },
+      writeOutput: (source) => {
+        output.push(source);
+      },
+    });
+
+    expect(reporter.onBegin(config, suite)).toBeUndefined();
+    await expect(reporter.onEnd(result)).resolves.toEqual({ status: "failed" });
+    expect(catalogCalls).toBe(0);
+    expect(output).toEqual([]);
+    expect(errors.join("\n")).toContain(validationError);
+  }
+});
+
+test("atomic preparation failure masks validation and preserves stack plus cause", async () => {
+  const projectRoot = path.join(os.tmpdir(), "toolcraft-reporter-preparation");
+  const { config, result } = createReporterFixture(projectRoot);
+  const cause = new Error("containing suite cause");
+  const preparationError = new Error("containing suite failed", { cause });
+  preparationError.stack = "PREPARATION_STACK_MARKER";
+  cause.stack = "PREPARATION_CAUSE_MARKER";
+  const errors: string[] = [];
+  let catalogCalls = 0;
+  let validationCalls = 0;
+  const reporter = new ToolcraftDeliveryCatalogReporter({
+    createCatalog: () => {
+      catalogCalls += 1;
+      return { acceptance: [], performance: [], version: 2 };
+    },
+    validateReferences: async () => {
+      validationCalls += 1;
+      throw new Error("reference validation must remain hidden");
+    },
+    writeError: (source) => {
+      errors.push(source);
+    },
+    writeOutput: () => {
+      throw new Error("Preparation failure must suppress output.");
+    },
+  });
+  const failingSuite = {
+    allTests: () => {
+      throw preparationError;
+    },
+  } as unknown as Suite;
+
+  reporter.onBegin(config, failingSuite);
+  await expect(reporter.onEnd(result)).resolves.toEqual({ status: "failed" });
+  expect(validationCalls).toBe(0);
+  expect(catalogCalls).toBe(0);
+  expect(errors.join("\n")).toContain("PREPARATION_STACK_MARKER");
+  expect(errors.join("\n")).toContain("PREPARATION_CAUSE_MARKER");
+  expect(errors.join("\n")).not.toContain("reference validation must remain hidden");
+});
+
+test("idle reporter state fails with an explicit lifecycle error", async () => {
+  const errors: string[] = [];
+  let validationCalls = 0;
+  const reporter = new ToolcraftDeliveryCatalogReporter({
+    validateReferences: async () => {
+      validationCalls += 1;
+    },
+    writeError: (source) => {
+      errors.push(source);
+    },
+    writeOutput: () => {},
+  });
+
+  await expect(
+    reporter.onEnd({ status: "passed" } as FullResult),
+  ).resolves.toEqual({ status: "failed" });
+  expect(validationCalls).toBe(0);
+  expect(errors.join("\n")).toMatch(/complete onBegin lifecycle/iu);
+});

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

@@ -14,6 +14,81 @@ import {
   setProofState,
 } from "./browser-semantic-evidence-test-helpers";
 
+const orientationBaseline: ToolcraftOrientationBrowserObservation = {
+  outputSignature: "model-front",
+  pixelSignature: "pixels-front",
+  pose: { position: [0, 0, 5], up: [0, 1, 0] },
+  poseTarget: "view.orbit",
+  presentationCacheKey: "appearance:document-model:v2",
+  presentationDocumentId: "document-model",
+  viewportOffsetX: 0,
+  viewportOffsetY: 0,
+};
+
+const orientationDragged: ToolcraftOrientationBrowserObservation = {
+  ...orientationBaseline,
+  outputSignature: "model-dragged",
+  pixelSignature: "pixels-dragged",
+  pose: { position: [1, 1, 4.8], up: [0, 1, 0] },
+};
+
+const orientationOptions = {
+  requirementId: "model.orientation",
+  stabilityIntervalMs: 0,
+  target: "view.orbit",
+} as const;
+
+type OrientationProofUiState = Readonly<{
+  playbackActions?: readonly ("pause" | "play")[];
+  renderScales?: readonly Readonly<{
+    maximum: string;
+    value: string;
+  }>[];
+}>;
+
+async function installOrientationProofUiState(
+  page: Page,
+  state: OrientationProofUiState,
+): Promise<void> {
+  await page.locator('[data-slot="toolcraft-runtime-app"]').evaluate(
+    (root, proofState) => {
+      root.querySelector('[data-orientation-proof-state]')?.remove();
+      const fixture = document.createElement("div");
+      fixture.dataset.orientationProofState = "";
+
+      for (const action of proofState.playbackActions ?? []) {
+        const button = document.createElement("button");
+        const label = action === "play" ? "Play playback" : "Pause playback";
+        button.type = "button";
+        button.textContent = label;
+        button.setAttribute("aria-label", label);
+        fixture.append(button);
+      }
+
+      for (const [index, renderScale] of (
+        proofState.renderScales ?? []
+      ).entries()) {
+        const field = document.createElement("div");
+        field.dataset.toolcraftControlTarget = "canvas.renderScale";
+        field.dataset.orientationProofRenderScale = String(index);
+        const slider = document.createElement("div");
+        slider.dataset.slot = "slider";
+        slider.setAttribute("aria-valuemax", renderScale.maximum);
+        slider.setAttribute("aria-valuemin", "1");
+        slider.setAttribute("aria-valuenow", renderScale.value);
+        slider.setAttribute("role", "slider");
+        Object.assign(slider.style, { height: "20px", width: "120px" });
+        slider.textContent = "Render scale";
+        field.append(slider);
+        fixture.append(field);
+      }
+
+      root.append(fixture);
+    },
+    state,
+  );
+}
+
 async function installOrientationGizmoPointerProbe(
   page: Page,
   initial: ToolcraftOrientationBrowserObservation,
@@ -123,33 +198,107 @@ async function installModelOrbitPointerProbe(
   );
 }
 
+test("orientation axis drag validates paused maximum-quality proof state", async ({
+  page,
+}, testInfo) => {
+  await page.goto("/");
+  const session = await createToolcraftBrowserProofSession(page);
+  const attachmentCount = testInfo.attachments.length;
+  const observation = session.observe((root) =>
+    JSON.parse(root.getAttribute("data-proof-orientation") ?? "null"),
+  );
+  const invalidStateCases: readonly Readonly<{
+    expectedError: RegExp;
+    state: OrientationProofUiState;
+  }>[] = [
+    {
+      expectedError: /must be paused.*Play playback/iu,
+      state: {
+        playbackActions: ["pause"],
+        renderScales: [{ maximum: "2", value: "2" }],
+      },
+    },
+    {
+      expectedError: /exactly one standard playback action/iu,
+      state: { playbackActions: ["play", "pause"] },
+    },
+    {
+      expectedError: /canvas\.renderScale.*maximum/iu,
+      state: {
+        playbackActions: ["play"],
+        renderScales: [{ maximum: "2", value: "1" }],
+      },
+    },
+    {
+      expectedError: /exactly one canvas\.renderScale owner/iu,
+      state: {
+        playbackActions: ["play"],
+        renderScales: [
+          { maximum: "2", value: "2" },
+          { maximum: "2", value: "2" },
+        ],
+      },
+    },
+    {
+      expectedError: /finite aria-valuenow/iu,
+      state: {
+        playbackActions: ["play"],
+        renderScales: [{ maximum: "2", value: "" }],
+      },
+    },
+    {
+      expectedError: /finite aria-valuemax/iu,
+      state: {
+        playbackActions: ["play"],
+        renderScales: [{ maximum: "invalid", value: "2" }],
+      },
+    },
+  ];
+
+  for (const { expectedError, state } of invalidStateCases) {
+    await setProofState(page, "orientation", orientationBaseline);
+    await installOrientationGizmoPointerProbe(page, orientationBaseline, {
+      outcomes: { drag: orientationDragged },
+    });
+    await installOrientationProofUiState(page, state);
+    await expect(
+      expectToolcraftOrientationAxisDrag(observation, session, {
+        ...orientationOptions,
+        dragDelta: { x: 18, y: 12 },
+      }),
+    ).rejects.toThrow(expectedError);
+    expect(testInfo.attachments).toHaveLength(attachmentCount);
+  }
+});
+
+test("orientation axis drag retains proof for products without optional playback or render scale", async ({
+  page,
+}) => {
+  await page.goto("/");
+  const session = await createToolcraftBrowserProofSession(page);
+  await setProofState(page, "orientation", orientationBaseline);
+  const observation = session.observe((root) =>
+    JSON.parse(root.getAttribute("data-proof-orientation") ?? "null"),
+  );
+  await installOrientationGizmoPointerProbe(page, orientationBaseline, {
+    outcomes: { drag: orientationDragged },
+  });
+
+  await expectToolcraftOrientationAxisDrag(observation, session, {
+    ...orientationOptions,
+    dragDelta: { x: 18, y: 12 },
+  });
+});
+
 test("orientation recipes require shared pose/output changes and correct canvas ownership", async ({
   page,
 }, testInfo) => {
   await page.goto("/");
   const session = await createToolcraftBrowserProofSession(page);
   const attachmentCount = testInfo.attachments.length;
-  const baseline: ToolcraftOrientationBrowserObservation = {
-    outputSignature: "model-front",
-    pixelSignature: "pixels-front",
-    pose: { position: [0, 0, 5], up: [0, 1, 0] },
-    poseTarget: "view.orbit",
-    presentationCacheKey: "appearance:document-model:v2",
-    presentationDocumentId: "document-model",
-    viewportOffsetX: 0,
-    viewportOffsetY: 0,
-  };
-  const dragged: ToolcraftOrientationBrowserObservation = {
-    ...baseline,
-    outputSignature: "model-dragged",
-    pixelSignature: "pixels-dragged",
-    pose: { position: [1, 1, 4.8], up: [0, 1, 0] },
-  };
-  const options = {
-    requirementId: "model.orientation",
-    stabilityIntervalMs: 0,
-    target: "view.orbit",
-  } as const;
+  const baseline = orientationBaseline;
+  const dragged = orientationDragged;
+  const options = orientationOptions;
 
   await setProofState(page, "orientation", baseline);
   const observation = session.observe((root) =>
@@ -175,6 +324,10 @@ test("orientation recipes require shared pose/output changes and correct canvas
   expect(testInfo.attachments).toHaveLength(attachmentCount);
 
   await setProofState(page, "orientation", baseline);
+  await installOrientationProofUiState(page, {
+    playbackActions: ["play"],
+    renderScales: [{ maximum: "2", value: "2" }],
+  });
   await installOrientationGizmoPointerProbe(page, baseline, {
     dragCommit: "pointerup",
     outcomes: { drag: dragged },