@pixel-point/toolcraft 0.0.13 → 0.0.15

package/templates/starter/e2e/browser-runtime-evidence-requirements.ts

@@ -0,0 +1,290 @@
+import type {
+  ResolvedToolcraftAppSchema,
+  ToolcraftPerformanceScenario,
+} from "@repo/toolcraft-runtime";
+
+import type { ToolcraftBrowserRuntimeRequirement } from "../src/app/test-evidence/browser-runtime-contract";
+import { schemaHasVideoExportPanelAction } from "../src/app/acceptance/output-export";
+import {
+  getRequiredToolcraftControlPartCoverage,
+  type ToolcraftBackgroundOutputCoverage,
+  type ToolcraftComponentAcceptance,
+  type ToolcraftConditionalVisibilityCoverage,
+  type ToolcraftTimelinePlaybackCoverage,
+} from "../src/app/starter-acceptance";
+
+type BrowserAcceptanceRequirementSource = Pick<
+  ToolcraftComponentAcceptance,
+  | "browser"
+  | "browserTestName"
+  | "backgroundOutputCoverage"
+  | "canvasHandle"
+  | "controlPartCoverage"
+  | "evidence"
+  | "id"
+  | "layerCoverage"
+  | "referenceCoverage"
+  | "referenceTimelineCoverage"
+  | "target"
+  | "timelineCoverage"
+  | "timelinePlaybackCoverage"
+  | "visibilityCoverage"
+>;
+
+type BrowserSchemaRequirementSource = Pick<ResolvedToolcraftAppSchema, "panels">;
+
+function getAcceptanceEvidenceType(
+  evidence: ToolcraftComponentAcceptance["evidence"],
+): ToolcraftBrowserRuntimeRequirement["evidenceType"] | undefined {
+  switch (evidence) {
+    case "product-output":
+    case "rendered-pixels":
+    case "timeline-output":
+      return "product-observable-change";
+    case "exported-bytes":
+      return "exported-artifact";
+    case "command-side-effect":
+    case "media-lifecycle":
+    case "persistence-state":
+    case "viewport-side-effect":
+      return evidence;
+    default:
+      return undefined;
+  }
+}
+
+const layerEvidenceTypeByCoverage = {
+  grouping: "layer-grouping",
+  "media-lifecycle": "layer-media-lifecycle",
+  reorder: "layer-reorder",
+  "selected-layer-controls": "layer-selected-layer-controls",
+  selection: "layer-selection",
+  visibility: "layer-visibility",
+} as const satisfies Record<
+  NonNullable<ToolcraftComponentAcceptance["layerCoverage"]>,
+  ToolcraftBrowserRuntimeRequirement["evidenceType"]
+>;
+
+const timelineEvidenceTypeByCoverage = {
+  duration: "timeline-duration",
+  loop: "timeline-loop",
+  "pause-resume": "timeline-pause-resume",
+  "rendered-frame": "timeline-rendered-frame",
+  scrub: "timeline-scrub",
+} as const satisfies Record<
+  ToolcraftTimelinePlaybackCoverage,
+  ToolcraftBrowserRuntimeRequirement["evidenceType"]
+>;
+
+const timelinePlaybackCoverage = Object.keys(
+  timelineEvidenceTypeByCoverage,
+) as Array<keyof typeof timelineEvidenceTypeByCoverage>;
+
+const conditionalVisibilityEvidenceTypeByCoverage = {
+  hidden: "conditional-control-hidden",
+  visible: "conditional-control-visible",
+} as const satisfies Record<
+  ToolcraftConditionalVisibilityCoverage,
+  ToolcraftBrowserRuntimeRequirement["evidenceType"]
+>;
+
+const conditionalVisibilityCoverage = Object.keys(
+  conditionalVisibilityEvidenceTypeByCoverage,
+) as ToolcraftConditionalVisibilityCoverage[];
+
+const backgroundOutputEvidenceTypeByCoverage = {
+  "image-transparent-when-excluded": "background-image-transparency",
+  "preview-hidden-when-excluded": "background-preview-exclusion",
+  "video-background-preserved": "background-video-preserved",
+} as const satisfies Record<
+  ToolcraftBackgroundOutputCoverage,
+  ToolcraftBrowserRuntimeRequirement["evidenceType"]
+>;
+
+const backgroundOutputCoverage = Object.keys(
+  backgroundOutputEvidenceTypeByCoverage,
+) as ToolcraftBackgroundOutputCoverage[];
+
+export function deriveToolcraftBrowserRuntimeRequirements(
+  acceptance: readonly BrowserAcceptanceRequirementSource[],
+  schema?: BrowserSchemaRequirementSource,
+): ToolcraftBrowserRuntimeRequirement[] {
+  const controlsByTarget = new Map(
+    (schema?.panels.controls?.sections ?? []).flatMap((section) =>
+      Object.values(section.controls).flatMap((control) =>
+        control.target ? [[control.target, control] as const] : [],
+      ),
+    ),
+  );
+
+  return acceptance.flatMap((entry) => {
+    if (!entry.browser) return [];
+
+    const evidenceTypes: ToolcraftBrowserRuntimeRequirement["evidenceType"][] = [];
+    const baseEvidenceType = getAcceptanceEvidenceType(entry.evidence);
+    if (baseEvidenceType) evidenceTypes.push(baseEvidenceType);
+
+    if (entry.canvasHandle) {
+      evidenceTypes.push("canvas-handle-interaction");
+    }
+    if (entry.timelineCoverage === "keyframes") {
+      evidenceTypes.push("timeline-keyframes");
+    }
+    if (entry.timelineCoverage === "playback") {
+      const coverage =
+        entry.timelinePlaybackCoverage === "all-playback-behavior"
+          ? timelinePlaybackCoverage
+          : entry.timelinePlaybackCoverage ?? [];
+      evidenceTypes.push(
+        ...coverage.map((item) => timelineEvidenceTypeByCoverage[item]),
+      );
+    }
+    if (entry.layerCoverage) {
+      evidenceTypes.push(layerEvidenceTypeByCoverage[entry.layerCoverage]);
+    }
+    if (entry.referenceCoverage || entry.referenceTimelineCoverage) {
+      evidenceTypes.push("reference-parity");
+    }
+    const visibilityCoverage =
+      entry.visibilityCoverage === "all-conditional-visibility"
+        ? conditionalVisibilityCoverage
+        : entry.visibilityCoverage ?? [];
+    evidenceTypes.push(
+      ...visibilityCoverage.map(
+        (item) => conditionalVisibilityEvidenceTypeByCoverage[item],
+      ),
+    );
+    const backgroundCoverage =
+      entry.backgroundOutputCoverage === "all-required-background-output"
+        ? backgroundOutputCoverage.filter(
+            (item) =>
+              item !== "video-background-preserved" ||
+              (schema ? schemaHasVideoExportPanelAction(schema) : false),
+          )
+        : entry.backgroundOutputCoverage ?? [];
+    evidenceTypes.push(
+      ...backgroundCoverage.map(
+        (item) => backgroundOutputEvidenceTypeByCoverage[item],
+      ),
+    );
+
+    const control = entry.target ? controlsByTarget.get(entry.target) : undefined;
+    if (control?.type === "segmented") {
+      evidenceTypes.push("segmented-control-layout");
+    }
+    if (
+      (control?.type === "slider" || control?.type === "rangeSlider") &&
+      control.variant === "discrete"
+    ) {
+      evidenceTypes.push("discrete-slider-layout");
+    }
+
+    const requirements = [...new Set(evidenceTypes)].map((evidenceType) => ({
+      evidenceType,
+      requirementId: entry.id,
+      target: entry.target ?? entry.canvasHandle?.writesTarget,
+      testName: entry.browserTestName,
+    }));
+    const controlParts =
+      entry.controlPartCoverage === "all-visible-parts"
+        ? control
+          ? getRequiredToolcraftControlPartCoverage(control)
+          : []
+        : entry.controlPartCoverage ?? [];
+    for (const part of controlParts) {
+      requirements.push({
+        evidenceType: "compound-control-part",
+        requirementId: `${entry.id}#${part}`,
+        target: entry.target,
+        testName: entry.browserTestName,
+      });
+    }
+    if (entry.canvasHandle) {
+      requirements.push({
+        evidenceType: "canvas-export-clean",
+        requirementId: entry.id,
+        target: entry.canvasHandle.writesTarget,
+        testName: entry.canvasHandle.exportCleanTestName,
+      });
+    }
+    return requirements;
+  });
+}
+
+function fixtureUsesRenderScale(value: unknown): boolean {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  return Object.entries(value).some(
+    ([key, nestedValue]) =>
+      /^(?:canvas\.)?renderScale$|(?:^|[._-])resolutionScale$/iu.test(key) ||
+      fixtureUsesRenderScale(nestedValue),
+  );
+}
+
+const productOutcomePerformanceInteractions = new Set([
+  "control-change",
+  "control-drag",
+  "mask-drag",
+  "media-import",
+  "preview-render",
+  "timeline-playback",
+  "timeline-scrub",
+]);
+
+export function deriveToolcraftPerformanceRuntimeRequirements(
+  scenarios: readonly ToolcraftPerformanceScenario[],
+): ToolcraftBrowserRuntimeRequirement[] {
+  return scenarios.flatMap((scenario) => {
+    if (!scenario.browser) return [];
+
+    const evidenceTypes: ToolcraftBrowserRuntimeRequirement["evidenceType"][] = [
+      "performance-measurement",
+      "performance-budget",
+    ];
+    if (productOutcomePerformanceInteractions.has(scenario.interaction)) {
+      evidenceTypes.push("performance-product-outcome");
+    }
+    if (scenario.workload || scenario.stress || scenario.stressFixture) {
+      evidenceTypes.push("performance-stress-fixture");
+    }
+    if (scenario.workloadFixture) {
+      evidenceTypes.push("performance-workload-fixture");
+    }
+    if (scenario.interaction === "export-copy") {
+      evidenceTypes.push("performance-output-completion");
+    }
+    if (
+      scenario.interaction === "control-drag" ||
+      scenario.interaction === "mask-drag"
+    ) {
+      evidenceTypes.push("performance-control-drag");
+    }
+    if (scenario.interaction === "animation-frame") {
+      evidenceTypes.push("performance-animation-frames");
+    }
+    if (
+      [
+        "animation-viewport-drag",
+        "viewport-stability",
+        "viewport-zoom-stress",
+      ].includes(scenario.interaction)
+    ) {
+      evidenceTypes.push("performance-viewport");
+    }
+    if (
+      scenario.target === "canvas.renderScale" ||
+      fixtureUsesRenderScale(scenario.stressFixture?.value) ||
+      fixtureUsesRenderScale(scenario.workloadFixture?.value)
+    ) {
+      evidenceTypes.push("performance-render-scale");
+    }
+
+    return evidenceTypes.map((evidenceType) => ({
+      evidenceType,
+      requirementId: scenario.id,
+      target: scenario.target,
+      testName: scenario.browserTestName,
+    }));
+  });
+}

package/templates/starter/e2e/browser-runtime-evidence.ts

@@ -0,0 +1,27 @@
+import { test } from "@playwright/test";
+
+import {
+  TOOLCRAFT_BROWSER_RUNTIME_EVIDENCE_ATTACHMENT_NAME,
+  TOOLCRAFT_BROWSER_RUNTIME_EVIDENCE_CONTENT_TYPE,
+  serializeToolcraftBrowserRuntimeEvidence,
+  type ToolcraftBrowserRuntimeEvidenceType,
+} from "../src/app/test-evidence/browser-runtime-contract";
+
+export async function attachToolcraftBrowserRuntimeEvidence({
+  evidenceType,
+  requirementId,
+  target,
+}: {
+  evidenceType: ToolcraftBrowserRuntimeEvidenceType;
+  requirementId: string;
+  target?: string;
+}): Promise<void> {
+  await test.info().attach(TOOLCRAFT_BROWSER_RUNTIME_EVIDENCE_ATTACHMENT_NAME, {
+    body: serializeToolcraftBrowserRuntimeEvidence({
+      evidenceType,
+      requirementId,
+      target,
+    }),
+    contentType: TOOLCRAFT_BROWSER_RUNTIME_EVIDENCE_CONTENT_TYPE,
+  });
+}

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

@@ -0,0 +1,205 @@
+import { expect } from "@playwright/test";
+
+import { attachToolcraftBrowserRuntimeEvidence } from "./browser-runtime-evidence";
+import {
+  assertToolcraftBrowserProofSession,
+  getToolcraftBrowserActionTarget,
+  readToolcraftBrowserObservation,
+  runToolcraftBrowserAction,
+  type ToolcraftBrowserAction,
+  type ToolcraftBrowserObservation,
+} from "./browser-proof-session";
+import {
+  createToolcraftSemanticTransitionOptions,
+  expectToolcraftExpectedOutcomeAfterAction,
+  type ToolcraftSemanticEvidenceOptions,
+} from "./browser-acceptance-transition-helpers";
+import {
+  expectToolcraftPersistentExpectedOutcome,
+  snapshotToolcraftOutcome,
+} from "./stable-outcome-helpers";
+
+export type ToolcraftMediaLifecycleObservation = {
+  itemIds: readonly string[];
+  outputSignature: string;
+};
+
+export type ToolcraftViewportObservation = {
+  offsetX: number;
+  offsetY: number;
+  outputHeight: number;
+  outputWidth: number;
+  zoom: number;
+};
+
+function validateMediaLifecycleObservation(
+  observation: ToolcraftMediaLifecycleObservation,
+  requirementId: string,
+): void {
+  expect(
+    new Set(observation.itemIds).size,
+    `Media lifecycle "${requirementId}" must report unique item ids.`,
+  ).toBe(observation.itemIds.length);
+  expect(
+    observation.itemIds.every((itemId) => itemId.trim().length > 0),
+    `Media lifecycle "${requirementId}" must report non-empty item ids.`,
+  ).toBe(true);
+  expect(
+    observation.outputSignature.trim(),
+    `Media lifecycle "${requirementId}" must report a product-output signature.`,
+  ).not.toBe("");
+}
+
+export async function expectToolcraftMediaLifecycle(
+  observeLifecycle: ToolcraftBrowserObservation<ToolcraftMediaLifecycleObservation>,
+  action: ToolcraftBrowserAction,
+  expected: ToolcraftMediaLifecycleObservation,
+  options: ToolcraftSemanticEvidenceOptions,
+): Promise<ToolcraftMediaLifecycleObservation> {
+  validateMediaLifecycleObservation(expected, options.requirementId);
+  const { after, before } = await expectToolcraftExpectedOutcomeAfterAction(
+    observeLifecycle,
+    action,
+    expected,
+    createToolcraftSemanticTransitionOptions(
+      `Media lifecycle "${options.requirementId}" should reach the expected item collection and output.`,
+      options,
+    ),
+  );
+  validateMediaLifecycleObservation(before, options.requirementId);
+  expect(before.itemIds).not.toEqual(after.itemIds);
+  expect(before.outputSignature).not.toBe(after.outputSignature);
+  await attachToolcraftBrowserRuntimeEvidence({
+    evidenceType: "media-lifecycle",
+    requirementId: options.requirementId,
+    target: getToolcraftBrowserActionTarget(action),
+  });
+  return after;
+}
+
+export async function expectToolcraftPersistenceState<T>(
+  observePersistedOutcome: ToolcraftBrowserObservation<T>,
+  mutateThroughUi: ToolcraftBrowserAction,
+  reloadPage: ToolcraftBrowserAction<"reload">,
+  expectedAfterReload: T,
+  options: ToolcraftSemanticEvidenceOptions,
+): Promise<T> {
+  assertToolcraftBrowserProofSession(
+    observePersistedOutcome,
+    mutateThroughUi,
+    reloadPage,
+  );
+  const observe = () => readToolcraftBrowserObservation(observePersistedOutcome);
+  const message = `Persistence "${options.requirementId}" should survive a real page reload.`;
+  const expected = snapshotToolcraftOutcome(expectedAfterReload, message);
+  const before = snapshotToolcraftOutcome(
+    await observe(),
+    message,
+  );
+  expect(before, `${message} The mutation must change the initial state.`).not.toEqual(
+    expected,
+  );
+
+  await runToolcraftBrowserAction(mutateThroughUi);
+  await expectToolcraftPersistentExpectedOutcome(
+    observe,
+    expected,
+    createToolcraftSemanticTransitionOptions(message, options),
+  );
+  await runToolcraftBrowserAction(reloadPage, "reload");
+  const restored = await expectToolcraftPersistentExpectedOutcome(
+    observe,
+    expected,
+    createToolcraftSemanticTransitionOptions(message, options),
+  );
+  await attachToolcraftBrowserRuntimeEvidence({
+    evidenceType: "persistence-state",
+    requirementId: options.requirementId,
+    target: getToolcraftBrowserActionTarget(mutateThroughUi),
+  });
+  return restored;
+}
+
+function validateViewportObservation(
+  observation: ToolcraftViewportObservation,
+  requirementId: string,
+): void {
+  for (const [name, value] of Object.entries(observation)) {
+    expect(
+      Number.isFinite(value),
+      `Viewport "${requirementId}" must report a finite ${name}.`,
+    ).toBe(true);
+  }
+  expect(observation.zoom).toBeGreaterThan(0);
+  expect(observation.outputWidth).toBeGreaterThan(0);
+  expect(observation.outputHeight).toBeGreaterThan(0);
+}
+
+export async function expectToolcraftViewportSideEffect(
+  observeViewport: ToolcraftBrowserObservation<ToolcraftViewportObservation>,
+  action: ToolcraftBrowserAction,
+  expected: ToolcraftViewportObservation,
+  options: ToolcraftSemanticEvidenceOptions,
+): Promise<ToolcraftViewportObservation> {
+  validateViewportObservation(expected, options.requirementId);
+  const { after, before } = await expectToolcraftExpectedOutcomeAfterAction(
+    observeViewport,
+    action,
+    expected,
+    createToolcraftSemanticTransitionOptions(
+      `Viewport "${options.requirementId}" should reach the expected offset and zoom.`,
+      options,
+    ),
+  );
+  validateViewportObservation(before, options.requirementId);
+  expect({
+    offsetX: before.offsetX,
+    offsetY: before.offsetY,
+    zoom: before.zoom,
+  }).not.toEqual({
+    offsetX: after.offsetX,
+    offsetY: after.offsetY,
+    zoom: after.zoom,
+  });
+  expect({
+    outputHeight: after.outputHeight,
+    outputWidth: after.outputWidth,
+  }).toEqual({
+    outputHeight: before.outputHeight,
+    outputWidth: before.outputWidth,
+  });
+  await attachToolcraftBrowserRuntimeEvidence({
+    evidenceType: "viewport-side-effect",
+    requirementId: options.requirementId,
+    target: getToolcraftBrowserActionTarget(action),
+  });
+  return after;
+}
+
+export async function expectToolcraftCompoundControlPartOutcome<T>(
+  observeProductOutcome: ToolcraftBrowserObservation<T>,
+  action: ToolcraftBrowserAction,
+  expected: T,
+  {
+    part,
+    ...options
+  }: ToolcraftSemanticEvidenceOptions & { part: string },
+): Promise<T> {
+  expect(part.trim(), "Compound-control evidence requires a semantic part id.").not.toBe("");
+  const requirementId = `${options.requirementId}#${part}`;
+  const { after } = await expectToolcraftExpectedOutcomeAfterAction(
+    observeProductOutcome,
+    action,
+    expected,
+    createToolcraftSemanticTransitionOptions(
+      `Compound control part "${requirementId}" should change product output to the expected state.`,
+      options,
+    ),
+  );
+  await attachToolcraftBrowserRuntimeEvidence({
+    evidenceType: "compound-control-part",
+    requirementId,
+    target: getToolcraftBrowserActionTarget(action),
+  });
+  return after;
+}