@pixel-point/toolcraft 0.0.15 → 0.0.16

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

@@ -1,6 +1,6 @@
 import type {
   ResolvedToolcraftAppSchema,
-  ToolcraftPerformanceScenario,
+  ToolcraftPerformancePath,
 } from "@repo/toolcraft-runtime";
 
 import type { ToolcraftBrowserRuntimeRequirement } from "../src/app/test-evidence/browser-runtime-contract";
@@ -10,8 +10,14 @@ import {
   type ToolcraftBackgroundOutputCoverage,
   type ToolcraftComponentAcceptance,
   type ToolcraftConditionalVisibilityCoverage,
+  type ToolcraftInfinityCanvasCoverage,
+  type ToolcraftModelImportCoverage,
+  type ToolcraftOrientationGizmoCoverage,
   type ToolcraftTimelinePlaybackCoverage,
+  TOOLCRAFT_REQUIRED_MODEL_IMPORT_COVERAGE,
 } from "../src/app/starter-acceptance";
+import { isToolcraftRenderScalePerformancePath } from "./browser-render-scale-evidence";
+import { getToolcraftPerformancePathTestName } from "./performance-path-helpers";
 
 type BrowserAcceptanceRequirementSource = Pick<
   ToolcraftComponentAcceptance,
@@ -22,9 +28,13 @@ type BrowserAcceptanceRequirementSource = Pick<
   | "controlPartCoverage"
   | "evidence"
   | "id"
+  | "infinityCanvasCoverage"
   | "layerCoverage"
+  | "modelImportCoverage"
+  | "orientationGizmoCoverage"
   | "referenceCoverage"
   | "referenceTimelineCoverage"
+  | "renderScaleCoverage"
   | "target"
   | "timelineCoverage"
   | "timelinePlaybackCoverage"
@@ -94,6 +104,7 @@ const conditionalVisibilityCoverage = Object.keys(
 
 const backgroundOutputEvidenceTypeByCoverage = {
   "image-transparent-when-excluded": "background-image-transparency",
+  "infinity-viewport-color-and-dependency": "background-infinity-viewport",
   "preview-hidden-when-excluded": "background-preview-exclusion",
   "video-background-preserved": "background-video-preserved",
 } as const satisfies Record<
@@ -105,6 +116,57 @@ const backgroundOutputCoverage = Object.keys(
   backgroundOutputEvidenceTypeByCoverage,
 ) as ToolcraftBackgroundOutputCoverage[];
 
+const orientationEvidenceTypeByCoverage = {
+  "axis-drag": "orientation-axis-drag",
+  "axis-snap": "orientation-axis-snap",
+  "canvas-miss-pan": "orientation-canvas-miss-pan",
+  "export-clean": "canvas-export-clean",
+  "model-drag": "orientation-model-drag",
+  "shared-pose-output": "orientation-shared-pose-output",
+  "undo-reset": "orientation-undo-reset",
+} as const satisfies Record<
+  ToolcraftOrientationGizmoCoverage,
+  ToolcraftBrowserRuntimeRequirement["evidenceType"]
+>;
+
+const orientationGizmoCoverage = Object.keys(
+  orientationEvidenceTypeByCoverage,
+) as ToolcraftOrientationGizmoCoverage[];
+
+const infinityCanvasEvidenceTypeByCoverage = {
+  "mode-and-restoration": "infinity-mode-restoration",
+  "scene-bounds-image-export": "infinity-scene-bounds-image-export",
+  "scene-bounds-video-export": "infinity-scene-bounds-video-export",
+} as const satisfies Record<
+  ToolcraftInfinityCanvasCoverage,
+  ToolcraftBrowserRuntimeRequirement["evidenceType"]
+>;
+
+const modelImportEvidenceTypeByCoverage = {
+  "advertised-format-import": "model-advertised-format-import",
+  "appearance-preservation": "model-appearance-preservation",
+  "clean-commit": "model-clean-commit",
+  "deterministic-root-selection": "model-deterministic-root-selection",
+  "export-output": "model-export-output",
+  "fallback-appearance": "model-fallback-appearance",
+  "fatal-rejection": "model-fatal-rejection",
+  "history-reset": "model-history-reset",
+  "package-extraction": "model-package-extraction",
+  "persistence-restore": "model-persistence-restore",
+  "pixel-output": "model-pixel-output",
+  "presentation-consumer-readiness": "model-presentation-consumer-readiness",
+  "preview-output": "model-preview-output",
+  "repair-action": "model-repair-action",
+  "repair-progress": "model-repair-progress",
+  "repairable-diagnosis": "model-repairable-diagnosis",
+  "resource-unavailable": "model-resource-unavailable",
+  "staged-preview": "model-staged-preview",
+  "verified-repair": "model-verified-repair",
+} as const satisfies Record<
+  ToolcraftModelImportCoverage,
+  ToolcraftBrowserRuntimeRequirement["evidenceType"]
+>;
+
 export function deriveToolcraftBrowserRuntimeRequirements(
   acceptance: readonly BrowserAcceptanceRequirementSource[],
   schema?: BrowserSchemaRequirementSource,
@@ -120,11 +182,15 @@ export function deriveToolcraftBrowserRuntimeRequirements(
   return acceptance.flatMap((entry) => {
     if (!entry.browser) return [];
 
+    const target = entry.target ?? entry.canvasHandle?.writesTarget;
+    const control = target ? controlsByTarget.get(target) : undefined;
+    const hasOrientationCoverage =
+      entry.orientationGizmoCoverage !== undefined;
     const evidenceTypes: ToolcraftBrowserRuntimeRequirement["evidenceType"][] = [];
     const baseEvidenceType = getAcceptanceEvidenceType(entry.evidence);
     if (baseEvidenceType) evidenceTypes.push(baseEvidenceType);
 
-    if (entry.canvasHandle) {
+    if (entry.canvasHandle && !hasOrientationCoverage) {
       evidenceTypes.push("canvas-handle-interaction");
     }
     if (entry.timelineCoverage === "keyframes") {
@@ -142,6 +208,11 @@ export function deriveToolcraftBrowserRuntimeRequirements(
     if (entry.layerCoverage) {
       evidenceTypes.push(layerEvidenceTypeByCoverage[entry.layerCoverage]);
     }
+    if (entry.infinityCanvasCoverage) {
+      evidenceTypes.push(
+        infinityCanvasEvidenceTypeByCoverage[entry.infinityCanvasCoverage],
+      );
+    }
     if (entry.referenceCoverage || entry.referenceTimelineCoverage) {
       evidenceTypes.push("reference-parity");
     }
@@ -158,8 +229,10 @@ export function deriveToolcraftBrowserRuntimeRequirements(
       entry.backgroundOutputCoverage === "all-required-background-output"
         ? backgroundOutputCoverage.filter(
             (item) =>
-              item !== "video-background-preserved" ||
-              (schema ? schemaHasVideoExportPanelAction(schema) : false),
+              (item !== "video-background-preserved" ||
+                (schema ? schemaHasVideoExportPanelAction(schema) : false)) &&
+              (item !== "infinity-viewport-color-and-dependency" ||
+                schema?.canvas.sizing.mode === "editable-output"),
           )
         : entry.backgroundOutputCoverage ?? [];
     evidenceTypes.push(
@@ -168,7 +241,6 @@ export function deriveToolcraftBrowserRuntimeRequirements(
       ),
     );
 
-    const control = entry.target ? controlsByTarget.get(entry.target) : undefined;
     if (control?.type === "segmented") {
       evidenceTypes.push("segmented-control-layout");
     }
@@ -182,9 +254,47 @@ export function deriveToolcraftBrowserRuntimeRequirements(
     const requirements = [...new Set(evidenceTypes)].map((evidenceType) => ({
       evidenceType,
       requirementId: entry.id,
-      target: entry.target ?? entry.canvasHandle?.writesTarget,
+      target,
       testName: entry.browserTestName,
     }));
+
+    for (const state of entry.renderScaleCoverage?.states ?? []) {
+      requirements.push({
+        evidenceType: "canvas-render-scale-backing",
+        requirementId: `${entry.id}#${state}`,
+        target,
+        testName: entry.browserTestName,
+      });
+    }
+
+    const orientationCoverage =
+      entry.orientationGizmoCoverage ===
+      "all-required-orientation-gizmo-behavior"
+        ? orientationGizmoCoverage
+        : entry.orientationGizmoCoverage ?? [];
+    for (const item of orientationCoverage) {
+      requirements.push({
+        evidenceType: orientationEvidenceTypeByCoverage[item],
+        requirementId: `${entry.id}#${item}`,
+        target,
+        testName:
+          item === "export-clean"
+            ? (entry.canvasHandle?.exportCleanTestName ?? entry.browserTestName)
+            : entry.browserTestName,
+      });
+    }
+    const modelImportCoverage =
+      entry.modelImportCoverage === "all-required-model-import-behavior"
+        ? TOOLCRAFT_REQUIRED_MODEL_IMPORT_COVERAGE
+        : entry.modelImportCoverage ?? [];
+    for (const item of modelImportCoverage) {
+      requirements.push({
+        evidenceType: modelImportEvidenceTypeByCoverage[item],
+        requirementId: `${entry.id}#${item}`,
+        target,
+        testName: entry.browserTestName,
+      });
+    }
     const controlParts =
       entry.controlPartCoverage === "all-visible-parts"
         ? control
@@ -199,7 +309,7 @@ export function deriveToolcraftBrowserRuntimeRequirements(
         testName: entry.browserTestName,
       });
     }
-    if (entry.canvasHandle) {
+    if (entry.canvasHandle && !hasOrientationCoverage) {
       requirements.push({
         evidenceType: "canvas-export-clean",
         requirementId: entry.id,
@@ -211,80 +321,51 @@ export function deriveToolcraftBrowserRuntimeRequirements(
   });
 }
 
-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([
+const pathProductOutcomeInteractions = new Set<ToolcraftPerformancePath["interaction"]>([
   "control-change",
   "control-drag",
   "mask-drag",
   "media-import",
-  "preview-render",
   "timeline-playback",
   "timeline-scrub",
 ]);
 
-export function deriveToolcraftPerformanceRuntimeRequirements(
-  scenarios: readonly ToolcraftPerformanceScenario[],
+export function deriveToolcraftPerformancePathRuntimeRequirements(
+  paths: readonly ToolcraftPerformancePath[],
 ): ToolcraftBrowserRuntimeRequirement[] {
-  return scenarios.flatMap((scenario) => {
-    if (!scenario.browser) return [];
-
+  return paths.flatMap((path) => {
     const evidenceTypes: ToolcraftBrowserRuntimeRequirement["evidenceType"][] = [
       "performance-measurement",
       "performance-budget",
     ];
-    if (productOutcomePerformanceInteractions.has(scenario.interaction)) {
+    if (pathProductOutcomeInteractions.has(path.interaction)) {
       evidenceTypes.push("performance-product-outcome");
     }
-    if (scenario.workload || scenario.stress || scenario.stressFixture) {
-      evidenceTypes.push("performance-stress-fixture");
+    if (path.workloadDimensions.length > 0) {
+      evidenceTypes.push("performance-compiled-fixture");
     }
-    if (scenario.workloadFixture) {
-      evidenceTypes.push("performance-workload-fixture");
-    }
-    if (scenario.interaction === "export-copy") {
+    if (path.interaction === "export") {
       evidenceTypes.push("performance-output-completion");
     }
-    if (
-      scenario.interaction === "control-drag" ||
-      scenario.interaction === "mask-drag"
-    ) {
+    if (path.interaction === "control-drag" || path.interaction === "mask-drag") {
       evidenceTypes.push("performance-control-drag");
     }
-    if (scenario.interaction === "animation-frame") {
+    if (path.interaction === "animation-frame") {
       evidenceTypes.push("performance-animation-frames");
     }
-    if (
-      [
-        "animation-viewport-drag",
-        "viewport-stability",
-        "viewport-zoom-stress",
-      ].includes(scenario.interaction)
-    ) {
+    if (path.interaction === "viewport-drag" || path.interaction === "viewport-zoom") {
       evidenceTypes.push("performance-viewport");
     }
-    if (
-      scenario.target === "canvas.renderScale" ||
-      fixtureUsesRenderScale(scenario.stressFixture?.value) ||
-      fixtureUsesRenderScale(scenario.workloadFixture?.value)
-    ) {
+    if (isToolcraftRenderScalePerformancePath(path)) {
       evidenceTypes.push("performance-render-scale");
     }
 
+    const target = path.targets.length === 1 ? path.targets[0] : undefined;
     return evidenceTypes.map((evidenceType) => ({
       evidenceType,
-      requirementId: scenario.id,
-      target: scenario.target,
-      testName: scenario.browserTestName,
+      requirementId: path.id,
+      target,
+      testName: getToolcraftPerformancePathTestName(path),
     }));
   });
 }

package/templates/starter/e2e/browser-semantic-evidence-test-helpers.ts

@@ -0,0 +1,57 @@
+import type { Page, TestInfo } from "@playwright/test";
+
+import { parseToolcraftBrowserRuntimeEvidence } from "../src/app/test-evidence/browser-runtime-contract";
+
+const rootSelector = '[data-slot="toolcraft-runtime-app"]';
+
+export function attachedEvidenceTypes(
+  testInfo: TestInfo,
+  startIndex: number,
+): Array<string | undefined> {
+  return testInfo.attachments
+    .slice(startIndex)
+    .map(
+      (attachment) =>
+        parseToolcraftBrowserRuntimeEvidence(attachment)?.evidenceType,
+    );
+}
+
+export async function setProofState(
+  page: Page,
+  key: string,
+  value: unknown,
+): Promise<void> {
+  await page.locator(rootSelector).evaluate(
+    (root, entry) => {
+      root.setAttribute(`data-proof-${entry.key}`, JSON.stringify(entry.value));
+    },
+    { key, value },
+  );
+}
+
+export async function setSyntheticControlOwner(
+  page: Page,
+  target: string,
+  visible: boolean,
+): Promise<void> {
+  await page.locator(rootSelector).evaluate(
+    (root, entry) => {
+      const selector = `[data-synthetic-target="${CSS.escape(entry.target)}"]`;
+      root.querySelector(selector)?.remove();
+      if (!entry.visible) return;
+
+      const owner = document.createElement("div");
+      owner.dataset.syntheticTarget = entry.target;
+      owner.dataset.toolcraftControlTarget = entry.target;
+      const field = document.createElement("div");
+      field.dataset.slot = "field";
+      const button = document.createElement("button");
+      button.type = "button";
+      button.textContent = entry.target;
+      field.append(button);
+      owner.append(field);
+      root.append(owner);
+    },
+    { target, visible },
+  );
+}

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

@@ -24,6 +24,11 @@ export type ToolcraftMediaLifecycleObservation = {
   outputSignature: string;
 };
 
+export type ToolcraftPersistenceEvidenceOptions =
+  ToolcraftSemanticEvidenceOptions & {
+    assertRestoredOutput?: () => Promise<void>;
+  };
+
 export type ToolcraftViewportObservation = {
   offsetX: number;
   offsetY: number;
@@ -82,7 +87,7 @@ export async function expectToolcraftPersistenceState<T>(
   mutateThroughUi: ToolcraftBrowserAction,
   reloadPage: ToolcraftBrowserAction<"reload">,
   expectedAfterReload: T,
-  options: ToolcraftSemanticEvidenceOptions,
+  options: ToolcraftPersistenceEvidenceOptions,
 ): Promise<T> {
   assertToolcraftBrowserProofSession(
     observePersistedOutcome,
@@ -112,6 +117,7 @@ export async function expectToolcraftPersistenceState<T>(
     expected,
     createToolcraftSemanticTransitionOptions(message, options),
   );
+  await options.assertRestoredOutput?.();
   await attachToolcraftBrowserRuntimeEvidence({
     evidenceType: "persistence-state",
     requirementId: options.requirementId,

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

@@ -138,6 +138,10 @@ export async function expectToolcraftTimelineRenderedFrame<T>(
     evidenceType: "timeline-rendered-frame",
     requirementId: options.requirementId,
   });
+  await attachToolcraftBrowserRuntimeEvidence({
+    evidenceType: "product-observable-change",
+    requirementId: options.requirementId,
+  });
   return after;
 }
 

package/templates/starter/e2e/canvas-handle-helpers.ts

@@ -15,7 +15,7 @@ export async function dragCanvasHandle(
   page: Page,
   testId: string,
   delta: { x: number; y: number },
-  options: { requirementId?: string; scenarioId?: string; target?: string } = {},
+  options: { pathId?: string; requirementId?: string; target?: string } = {},
 ): Promise<void> {
   const handle = getCanvasHandle(page, testId);
   await expect(handle, `Canvas handle "${testId}" should be visible`).toBeVisible();
@@ -32,10 +32,10 @@ export async function dragCanvasHandle(
   await page.mouse.down();
   await page.mouse.move(startX + delta.x, startY + delta.y, { steps: 8 });
   await page.mouse.up();
-  if (options.scenarioId) {
+  if (options.pathId) {
     await attachToolcraftBrowserRuntimeEvidence({
       evidenceType: "performance-control-drag",
-      requirementId: options.scenarioId,
+      requirementId: options.pathId,
       target: options.target,
     });
   }

package/templates/starter/e2e/kernel-benchmark-contract.ts

@@ -0,0 +1,19 @@
+import type { Page } from "@playwright/test";
+import type { ToolcraftRendererStrategy } from "@repo/toolcraft-runtime";
+
+export type ToolcraftKernelCandidateHarness = Readonly<{
+  iterations: number;
+  run: (context: Readonly<{
+    page: Page;
+    workload: Readonly<Record<string, number>>;
+  }>) => Promise<string | Uint8Array>;
+}>;
+
+export type ToolcraftKernelBenchmarkHarnessRegistry = Readonly<
+  Record<
+    string,
+    Readonly<
+      Partial<Record<ToolcraftRendererStrategy, ToolcraftKernelCandidateHarness>>
+    >
+  >
+>;

package/templates/starter/e2e/model-import-evidence-test-support.ts

@@ -0,0 +1,125 @@
+import type { TestInfo } from "@playwright/test";
+
+import { parseToolcraftBrowserRuntimeEvidence } from "../src/app/test-evidence/browser-runtime-contract";
+import type {
+  ToolcraftModelIdentityObservation,
+  ToolcraftModelImportBrowserObservation,
+  ToolcraftModelOutputObservation,
+} from "./browser-model-import-evidence-helpers";
+import { TOOLCRAFT_FALLBACK_MATERIAL_SIGNATURE } from "./browser-model-appearance-evidence";
+
+export const advertisedFormats = ["glb", "gltf", "fbx", "obj", "stl", "ply"];
+export const cleanIdentity = {
+  assetId: "model-clean",
+  documentId: "document-clean",
+};
+export const repairedIdentity = {
+  assetId: "model-repaired",
+  documentId: "document-repaired",
+};
+export const emptyRepair = {
+  available: false,
+  diagnosisSignature: null,
+  geometrySignature: null,
+  progress: null,
+  verification: null,
+} as const;
+export const emptyModelResources = {
+  acquired: 0,
+  active: 0,
+  cacheHits: 0,
+  disposed: 0,
+  released: 0,
+} as const;
+export const readyModelResources = {
+  acquired: 2,
+  active: 1,
+  cacheHits: 1,
+  disposed: 0,
+  released: 1,
+} as const;
+export const runtimePresentation = {
+  consumerId: null,
+  mode: "runtime" as const,
+  status: "ready" as const,
+};
+export const zipPackage = {
+  candidateRootPaths: ["models/a.glb", "models/z.glb"],
+  extractedFileCount: 3,
+  kind: "zip" as const,
+  selectedRootPath: "models/a.glb",
+};
+
+export function output(
+  identity: ToolcraftModelIdentityObservation,
+  suffix: string,
+  opacity: number,
+  options: Readonly<{
+    appearanceSource?: "authored" | "fallback";
+    materialSignature?: string;
+    pixelSamples?: readonly (readonly [number, number, number, number])[];
+  }> = {},
+): ToolcraftModelOutputObservation {
+  const sampleBase = 32 + [...suffix].reduce(
+    (total, character) => (total + character.charCodeAt(0)) % 192,
+    0,
+  );
+  return {
+    appearanceSource: options.appearanceSource ?? "authored",
+    documentId: identity.documentId,
+    editorChrome: "excluded",
+    materialSignature:
+      options.materialSignature ?? `material:${identity.documentId}`,
+    modelSignature: identity.assetId,
+    opacity,
+    outputSignature: `output-${suffix}`,
+    pixelSamples: options.pixelSamples ?? [
+      [sampleBase, 64, 96, 255],
+      [48, sampleBase, 112, 255],
+      [80, 104, sampleBase, 255],
+    ],
+    pixelSignature: `pixels-${suffix}`,
+    presentationCacheKey: `appearance:${identity.documentId}:v2`,
+  };
+}
+
+export function fallbackOutput(
+  identity: ToolcraftModelIdentityObservation,
+  suffix: string,
+  opacity: number,
+): ToolcraftModelOutputObservation {
+  return output(identity, suffix, opacity, {
+    appearanceSource: "fallback",
+    materialSignature: TOOLCRAFT_FALLBACK_MATERIAL_SIGNATURE,
+    pixelSamples: [[204, 204, 204, 255], [196, 196, 196, 255]],
+  });
+}
+
+export function state(
+  overrides: Partial<ToolcraftModelImportBrowserObservation> = {},
+): ToolcraftModelImportBrowserObservation {
+  return {
+    active: null,
+    advertisedFormats,
+    attemptFormat: null,
+    draft: null,
+    exportOutput: null,
+    lifecycle: "empty",
+    package: null,
+    persistenceState: "none",
+    presentation: null,
+    previewOutput: null,
+    rejection: null,
+    repair: emptyRepair,
+    resources: emptyModelResources,
+    unavailableReason: null,
+    ...overrides,
+  };
+}
+
+export function modelEvidence(testInfo: TestInfo, startIndex: number) {
+  return testInfo.attachments
+    .slice(startIndex)
+    .map((attachment) => parseToolcraftBrowserRuntimeEvidence(attachment))
+    .filter((entry) => entry?.evidenceType.startsWith("model-"));
+}