@pixel-point/toolcraft 0.0.15 → 0.0.16

package/templates/starter/e2e/performance-frame-probe.ts

@@ -1,29 +1,44 @@
 import type { Page } from "@playwright/test";
 
 import type { ToolcraftFrameProbeResult } from "./performance-measurement-evidence";
+import { getToolcraftFrameDistributionMetrics } from "./performance-frame-metrics";
 
 let frameProbeReporterSequence = 0;
 
-function emptyToolcraftFrameProbeResult(): ToolcraftFrameProbeResult {
-  return {
-    longTaskCount: 0,
-    longTaskMaxMs: 0,
-    maxFrameGapMs: 0,
-    sampleCount: 0,
-  };
+type ToolcraftRawFrameProbeResult = {
+  frameGapsMs: number[];
+  longTaskCount: number;
+  longTaskMaxMs: number;
+};
+
+function emptyToolcraftRawFrameProbeResult(): ToolcraftRawFrameProbeResult {
+  return { frameGapsMs: [], longTaskCount: 0, longTaskMaxMs: 0 };
+}
+
+function finalizeToolcraftFrameProbeResult(
+  result: ToolcraftRawFrameProbeResult,
+): ToolcraftFrameProbeResult {
+  const frameGapsMs = Object.freeze([...result.frameGapsMs]);
+  return Object.freeze({
+    ...getToolcraftFrameDistributionMetrics(frameGapsMs),
+    frameGapsMs,
+    longTaskCount: result.longTaskCount,
+    longTaskMaxMs: result.longTaskMaxMs,
+  });
 }
 
 export function mergeToolcraftFrameProbeResults(
   results: readonly ToolcraftFrameProbeResult[],
 ): ToolcraftFrameProbeResult {
-  return results.reduce<ToolcraftFrameProbeResult>(
-    (merged, result) => ({
-      longTaskCount: merged.longTaskCount + result.longTaskCount,
-      longTaskMaxMs: Math.max(merged.longTaskMaxMs, result.longTaskMaxMs),
-      maxFrameGapMs: Math.max(merged.maxFrameGapMs, result.maxFrameGapMs),
-      sampleCount: merged.sampleCount + result.sampleCount,
-    }),
-    emptyToolcraftFrameProbeResult(),
+  return finalizeToolcraftFrameProbeResult(
+    results.reduce<ToolcraftRawFrameProbeResult>(
+      (merged, result) => ({
+        frameGapsMs: [...merged.frameGapsMs, ...result.frameGapsMs],
+        longTaskCount: merged.longTaskCount + result.longTaskCount,
+        longTaskMaxMs: Math.max(merged.longTaskMaxMs, result.longTaskMaxMs),
+      }),
+      emptyToolcraftRawFrameProbeResult(),
+    ),
   );
 }
 
@@ -32,10 +47,10 @@ export async function startToolcraftFrameProbe(
 ): Promise<() => Promise<ToolcraftFrameProbeResult>> {
   type FrameProbeReport = {
     kind: "checkpoint" | "final";
-    result: ToolcraftFrameProbeResult;
+    result: ToolcraftRawFrameProbeResult;
   };
-  let reportedCheckpoint = emptyToolcraftFrameProbeResult();
-  const reportedFinalSegments: ToolcraftFrameProbeResult[] = [];
+  let reportedCheckpoint = emptyToolcraftRawFrameProbeResult();
+  const reportedFinalSegments: ToolcraftRawFrameProbeResult[] = [];
   const reporterName = `__toolcraftReportFrameProbe${++frameProbeReporterSequence}`;
   await page.exposeBinding(
     reporterName,
@@ -45,51 +60,47 @@ export async function startToolcraftFrameProbe(
         return;
       }
       reportedCheckpoint = {
+        frameGapsMs: [
+          ...reportedCheckpoint.frameGapsMs,
+          ...report.result.frameGapsMs,
+        ],
         longTaskCount:
           reportedCheckpoint.longTaskCount + report.result.longTaskCount,
         longTaskMaxMs: Math.max(
           reportedCheckpoint.longTaskMaxMs,
           report.result.longTaskMaxMs,
         ),
-        maxFrameGapMs: Math.max(
-          reportedCheckpoint.maxFrameGapMs,
-          report.result.maxFrameGapMs,
-        ),
-        sampleCount: Math.max(
-          reportedCheckpoint.sampleCount,
-          report.result.sampleCount,
-        ),
       };
     },
   );
   const probeId = await page.evaluate((currentReporterName) => {
     type FrameProbeReport = {
       kind: "checkpoint" | "final";
-      result: ToolcraftFrameProbeResult;
+      result: ToolcraftRawFrameProbeResult;
     };
     type FrameProbe = {
       active: boolean;
       id: number;
+      frameGapsMs: number[];
       longTaskCount: number;
       longTaskMaxMs: number;
       observer?: PerformanceObserver;
-      maxFrameGapMs: number;
       pageHideHandler?: () => void;
+      pendingFrameGapsMs: number[];
+      reportedMaxFrameGapMs: number;
       rafId: number;
-      sampleCount: number;
     };
     const win = window as Window & {
-      __toolcraftCompletedFrameProbes?: Record<number, ToolcraftFrameProbeResult>;
+      __toolcraftCompletedFrameProbes?: Record<number, ToolcraftRawFrameProbeResult>;
       __toolcraftFrameProbe?: FrameProbe;
       __toolcraftFrameProbeSequence?: number;
-      __toolcraftStopFrameProbe?: (probeId: number) => ToolcraftFrameProbeResult;
+      __toolcraftStopFrameProbe?: (probeId: number) => ToolcraftRawFrameProbeResult;
     };
 
-    const emptyResult = (): ToolcraftFrameProbeResult => ({
+    const emptyResult = (): ToolcraftRawFrameProbeResult => ({
+      frameGapsMs: [],
       longTaskCount: 0,
       longTaskMaxMs: 0,
-      maxFrameGapMs: 0,
-      sampleCount: 0,
     });
     const reportProbe = (report: FrameProbeReport) => {
       const reporter = (
@@ -100,7 +111,7 @@ export async function startToolcraftFrameProbe(
       )[currentReporterName];
       void reporter?.(report);
     };
-    const disposeProbe = (probe: FrameProbe): ToolcraftFrameProbeResult => {
+    const disposeProbe = (probe: FrameProbe): ToolcraftRawFrameProbeResult => {
       probe.active = false;
       cancelAnimationFrame(probe.rafId);
       probe.observer?.disconnect();
@@ -108,10 +119,9 @@ export async function startToolcraftFrameProbe(
         window.removeEventListener("pagehide", probe.pageHideHandler);
       }
       return {
+        frameGapsMs: [...probe.frameGapsMs],
         longTaskCount: probe.longTaskCount,
         longTaskMaxMs: probe.longTaskMaxMs,
-        maxFrameGapMs: probe.maxFrameGapMs,
-        sampleCount: probe.sampleCount,
       };
     };
 
@@ -130,12 +140,13 @@ export async function startToolcraftFrameProbe(
     let lastFrame = performance.now();
     win.__toolcraftFrameProbe = {
       active: true,
+      frameGapsMs: [],
       id,
       longTaskCount: 0,
       longTaskMaxMs: 0,
-      maxFrameGapMs: 0,
+      pendingFrameGapsMs: [],
+      reportedMaxFrameGapMs: 0,
       rafId: 0,
-      sampleCount: 0,
     };
 
     try {
@@ -154,7 +165,6 @@ export async function startToolcraftFrameProbe(
               ...emptyResult(),
               longTaskCount: 1,
               longTaskMaxMs: entry.duration,
-              sampleCount: probe.sampleCount,
             },
           });
         }
@@ -170,19 +180,32 @@ export async function startToolcraftFrameProbe(
         return;
       }
 
-      const previousMaxFrameGapMs = probe.maxFrameGapMs;
-      probe.maxFrameGapMs = Math.max(probe.maxFrameGapMs, now - lastFrame);
-      probe.sampleCount += 1;
+      if (document.visibilityState === "hidden") {
+        lastFrame = now;
+        probe.rafId = requestAnimationFrame(tick);
+        return;
+      }
+
+      const frameGapMs = Math.max(0, now - lastFrame);
+      probe.frameGapsMs.push(frameGapMs);
+      probe.pendingFrameGapsMs.push(frameGapMs);
       lastFrame = now;
-      if (probe.maxFrameGapMs > previousMaxFrameGapMs) {
+      const nextMaxFrameGapMs = Math.max(
+        probe.reportedMaxFrameGapMs,
+        frameGapMs,
+      );
+      if (
+        nextMaxFrameGapMs > probe.reportedMaxFrameGapMs ||
+        probe.pendingFrameGapsMs.length >= 30
+      ) {
         reportProbe({
           kind: "checkpoint",
           result: {
             ...emptyResult(),
-            maxFrameGapMs: probe.maxFrameGapMs,
-            sampleCount: probe.sampleCount,
+            frameGapsMs: probe.pendingFrameGapsMs.splice(0),
           },
         });
+        probe.reportedMaxFrameGapMs = nextMaxFrameGapMs;
       }
       probe.rafId = requestAnimationFrame(tick);
     };
@@ -223,11 +246,11 @@ export async function startToolcraftFrameProbe(
   return async () => {
     if (stoppedResult) return stoppedResult;
 
-    let currentSegment: ToolcraftFrameProbeResult | undefined;
+    let currentSegment: ToolcraftRawFrameProbeResult | undefined;
     try {
       currentSegment = await page.evaluate((targetProbeId) => {
         const win = window as Window & {
-          __toolcraftStopFrameProbe?: (probeId: number) => ToolcraftFrameProbeResult;
+          __toolcraftStopFrameProbe?: (probeId: number) => ToolcraftRawFrameProbeResult;
         };
 
         return win.__toolcraftStopFrameProbe?.(targetProbeId);
@@ -241,7 +264,9 @@ export async function startToolcraftFrameProbe(
       : reportedFinalSegments.length > 0
         ? reportedFinalSegments
         : [reportedCheckpoint];
-    stoppedResult = mergeToolcraftFrameProbeResults(preservedSegments);
+    stoppedResult = mergeToolcraftFrameProbeResults(
+      preservedSegments.map(finalizeToolcraftFrameProbeResult),
+    );
     return stoppedResult;
   };
 }

package/templates/starter/e2e/performance-helpers.ts

@@ -3,4 +3,5 @@ export * from "./performance-canvas-helpers";
 export * from "./performance-control-helpers";
 export * from "./performance-output-action-helpers";
 export * from "./performance-fixture-helpers";
+export { expectToolcraftPipelinePassExecutions } from "./performance-pipeline-evidence";
 export * from "./performance-probe-helpers";

package/templates/starter/e2e/performance-interaction-measurement.ts

@@ -31,7 +31,7 @@ export async function measureToolcraftInteraction(
     options,
     "expectedOutcome",
   );
-  const outcomeMessage = `Toolcraft performance outcome "${options.scenarioId ?? "interaction"}" should ${hasExpectedOutcome ? "reach the expected state" : "change"} after the measured action.`;
+  const outcomeMessage = `Toolcraft performance outcome "${options.pathId ?? "interaction"}" should ${hasExpectedOutcome ? "reach the expected state" : "change"} after the measured action.`;
   const outcomeBefore = options.observeOutcome
     ? snapshotToolcraftOutcome(
         await options.observeOutcome(),
@@ -145,10 +145,10 @@ export async function measureToolcraftInteraction(
           stableOutcomeOptions,
         );
       }
-      if (options.scenarioId) {
+      if (options.pathId) {
         await attachToolcraftBrowserRuntimeEvidence({
           evidenceType: "performance-product-outcome",
-          requirementId: options.scenarioId,
+          requirementId: options.pathId,
           target: options.target,
         });
       }
@@ -168,10 +168,7 @@ export async function measureToolcraftInteraction(
 
     return finalizeToolcraftMeasurement({
       durationMs: (measuredEndedAt ?? actionEndedAt) - startedAt,
-      longTaskCount: frameProbe.longTaskCount,
-      longTaskMaxMs: frameProbe.longTaskMaxMs,
-      maxFrameGapMs: frameProbe.maxFrameGapMs,
-      sampleCount: frameProbe.sampleCount,
+      ...frameProbe,
     }, options, "interaction");
   } catch (error) {
     outcomeObservationCancelled = true;
@@ -212,10 +209,7 @@ export async function measureToolcraftAnimationFrames(
 
     return finalizeToolcraftMeasurement({
       durationMs: endedAt - startedAt,
-      longTaskCount: frameProbe.longTaskCount,
-      longTaskMaxMs: frameProbe.longTaskMaxMs,
-      maxFrameGapMs: frameProbe.maxFrameGapMs,
-      sampleCount: frameProbe.sampleCount,
+      ...frameProbe,
     }, options, "animation-frames");
   } catch (error) {
     await stopProbe();

package/templates/starter/e2e/performance-measurement-evidence.ts

@@ -1,6 +1,17 @@
+import type { ToolcraftPerformanceProfileName } from "@repo/toolcraft-runtime";
+
+import { serializeToolcraftPerformanceMeasurement } from "../src/app/test-evidence/browser-performance-measurement-contract";
+import type { ToolcraftPerformancePipelinePhase } from "../src/app/test-evidence/browser-performance-contract";
+import { attachToolcraftPerformanceMeasurementEvidence } from "./browser-performance-measurement-evidence";
 import { attachToolcraftBrowserRuntimeEvidence } from "./browser-runtime-evidence";
 
 export type ToolcraftFrameProbeResult = {
+  droppedFrameCount: number;
+  droppedFrameRatio: number;
+  frameGapP50Ms: number;
+  frameGapP95Ms: number;
+  frameGapP99Ms: number;
+  frameGapsMs: readonly number[];
   longTaskCount: number;
   longTaskMaxMs: number;
   maxFrameGapMs: number;
@@ -18,7 +29,9 @@ export type ToolcraftInteractionOptions = {
   observeOutcome?: () => Promise<unknown>;
   outcomePollIntervalMs?: number;
   outcomeTimeoutMs?: number;
-  scenarioId?: string;
+  phase?: ToolcraftPerformancePipelinePhase;
+  profile?: ToolcraftPerformanceProfileName;
+  pathId?: string;
   settleFrames?: number;
   settleMs?: number;
   stabilityIntervalMs?: number;
@@ -28,7 +41,7 @@ export type ToolcraftInteractionOptions = {
 
 const measurementProvenance = new WeakMap<
   ToolcraftInteractionResult,
-  { kind: "animation-frames" | "interaction"; scenarioId: string; target?: string }
+  { kind: "animation-frames" | "interaction"; pathId: string; target?: string }
 >();
 
 export function getToolcraftMeasurementProvenance(
@@ -36,7 +49,7 @@ export function getToolcraftMeasurementProvenance(
 ):
   | {
       kind: "animation-frames" | "interaction";
-      scenarioId: string;
+      pathId: string;
       target?: string;
     }
   | undefined {
@@ -48,25 +61,56 @@ export async function finalizeToolcraftMeasurement(
   options: ToolcraftInteractionOptions,
   kind: "animation-frames" | "interaction",
 ): Promise<ToolcraftInteractionResult> {
-  const immutableResult = Object.freeze({ ...result });
-  if (options.scenarioId) {
+  const immutableResult = Object.freeze({
+    ...result,
+    frameGapsMs: Object.freeze([...result.frameGapsMs]),
+  });
+  if (options.pathId) {
     measurementProvenance.set(immutableResult, {
       kind,
-      scenarioId: options.scenarioId,
+      pathId: options.pathId,
       target: options.target,
     });
     await attachToolcraftBrowserRuntimeEvidence({
       evidenceType: "performance-measurement",
-      requirementId: options.scenarioId,
+      requirementId: options.pathId,
       target: options.target,
     });
     if (kind === "animation-frames") {
       await attachToolcraftBrowserRuntimeEvidence({
         evidenceType: "performance-animation-frames",
-        requirementId: options.scenarioId,
+        requirementId: options.pathId,
         target: options.target,
       });
     }
+    if ((options.phase === undefined) !== (options.profile === undefined)) {
+      throw new Error(
+        "Protected Toolcraft measurement evidence requires phase and profile together.",
+      );
+    }
+    if (options.phase && options.profile) {
+      await attachToolcraftPerformanceMeasurementEvidence(
+        serializeToolcraftPerformanceMeasurement({
+          evidenceType: "performance-measurement-metrics",
+          kind,
+          metrics: {
+            droppedFrameCount: immutableResult.droppedFrameCount,
+            droppedFrameRatio: immutableResult.droppedFrameRatio,
+            durationMs: immutableResult.durationMs,
+            frameGapP50Ms: immutableResult.frameGapP50Ms,
+            frameGapP95Ms: immutableResult.frameGapP95Ms,
+            frameGapP99Ms: immutableResult.frameGapP99Ms,
+            longTaskCount: immutableResult.longTaskCount,
+            longTaskMaxMs: immutableResult.longTaskMaxMs,
+            maxFrameGapMs: immutableResult.maxFrameGapMs,
+            sampleCount: immutableResult.sampleCount,
+          },
+          pathId: options.pathId,
+          phase: options.phase,
+          profile: options.profile,
+        }),
+      );
+    }
   }
   return immutableResult;
 }

package/templates/starter/e2e/performance-model-appearance-contract.ts

@@ -0,0 +1,11 @@
+export const TOOLCRAFT_MODEL_APPEARANCE_PERFORMANCE_PASSES = Object.freeze([
+  Object.freeze({ execution: "worker", id: "package-extraction" }),
+  Object.freeze({ execution: "worker", id: "canonical-decode" }),
+  Object.freeze({ execution: "main-thread", id: "model-presentation" }),
+  Object.freeze({ execution: "main-thread", id: "canvas-orbit" }),
+  Object.freeze({ execution: "main-thread", id: "export" }),
+  Object.freeze({ execution: "main-thread", id: "resource-cleanup" }),
+] as const);
+
+export type ToolcraftModelAppearancePerformancePassId =
+  typeof TOOLCRAFT_MODEL_APPEARANCE_PERFORMANCE_PASSES[number]["id"];

package/templates/starter/e2e/performance-model-import-appearance-fixture-support.ts

@@ -0,0 +1,32 @@
+import type {
+  ToolcraftModelBrowserFixture,
+  ToolcraftModelBrowserFixtureFile,
+} from "./performance-model-import-fixtures";
+
+export function file(
+  name: string,
+  mimeType: string,
+  bytes: Uint8Array,
+): ToolcraftModelBrowserFixtureFile {
+  return Object.freeze({
+    buffer: Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength),
+    mimeType,
+    name,
+  });
+}
+
+export function fixture(
+  format: ToolcraftModelBrowserFixture["format"],
+  encoding: ToolcraftModelBrowserFixture["encoding"],
+  files: readonly ToolcraftModelBrowserFixtureFile[],
+): ToolcraftModelBrowserFixture {
+  return Object.freeze({
+    encoding,
+    files: Object.freeze([...files]),
+    format,
+    observed: Object.freeze({
+      bundleFiles: files.length,
+      sourceBytes: files.reduce((total, entry) => total + entry.buffer.byteLength, 0),
+    }),
+  });
+}

package/templates/starter/e2e/performance-model-import-appearance-fixtures.spec.ts

@@ -0,0 +1,56 @@
+import { expect, test } from "@playwright/test";
+
+import { createToolcraftModelAppearanceFixtures } from "./performance-model-import-appearance-fixtures";
+import { TOOLCRAFT_MODEL_APPEARANCE_PERFORMANCE_PASSES } from "./performance-model-appearance-contract";
+
+test("toolcraft model appearance fixtures cover authored, fallback, package, warning, and hostile inputs", () => {
+  const cases = createToolcraftModelAppearanceFixtures();
+
+  expect(cases.map(({ id }) => id)).toEqual([
+    "standalone-fallback-glb",
+    "textured-glb",
+    "textured-gltf-folder",
+    "obj-material-folder",
+    "obj-material-zip",
+    "fbx-material",
+    "ply-vertex-colors",
+    "stl-fallback",
+    "missing-texture",
+    "multiple-roots-zip",
+    "hostile-zip",
+  ]);
+  expect(cases.some(({ expected }) => expected.appearance === "authored")).toBe(true);
+  expect(cases.some(({ expected }) => expected.appearance === "fallback")).toBe(true);
+  expect(cases.some(({ expected }) => expected.appearance === "warning")).toBe(true);
+  expect(cases.some(({ expected }) => expected.outcome === "rejected")).toBe(true);
+  expect(new Set(cases.map(({ expected }) => expected.packageKind))).toEqual(
+    new Set(["folder", "standalone", "zip"]),
+  );
+
+  for (const { expected, fixture, id } of cases) {
+    expect(fixture.files.length, `${id} must contain source files.`).toBeGreaterThan(0);
+    expect(fixture.observed.bundleFiles).toBe(fixture.files.length);
+    expect(fixture.observed.sourceBytes).toBe(
+      fixture.files.reduce((total, entry) => total + entry.buffer.byteLength, 0),
+    );
+    expect(fixture.observed.sourceBytes, `${id} must not be an empty placeholder.`)
+      .toBeGreaterThan(0);
+    expect(expected.selectedRootPath).not.toBe("");
+    expect(expected.materialSignature).not.toBe("");
+    if (expected.packageKind === "zip") {
+      expect(fixture.files).toHaveLength(1);
+      expect(fixture.files[0]!.buffer.readUInt32LE(0)).toBe(0x04034b50);
+    }
+  }
+});
+
+test("toolcraft model appearance performance contract assigns every affected pass", () => {
+  expect(TOOLCRAFT_MODEL_APPEARANCE_PERFORMANCE_PASSES).toEqual([
+    { execution: "worker", id: "package-extraction" },
+    { execution: "worker", id: "canonical-decode" },
+    { execution: "main-thread", id: "model-presentation" },
+    { execution: "main-thread", id: "canvas-orbit" },
+    { execution: "main-thread", id: "export" },
+    { execution: "main-thread", id: "resource-cleanup" },
+  ]);
+});