@cyberart-io/engine 0.0.7 → 0.0.8

package/README.md

@@ -90,6 +90,7 @@ Full API for the event router, deterministic replay, and CI harness (so agents c
 - [Events and router](docs/events.md) — mailbox, envelope, typed contracts, `createEventRouter`, hops, idempotency, rejections
 - [Deterministic mode](docs/deterministic-mode.md) — `step` / `schedule`, clocks, `ScriptedAction`, replay diffs
 - [Headless harness](docs/headless-harness.md) — `createHeadlessHarness` from `@cyberart-io/engine/headless`, software Canvas2D, `compareImageData` / `assertPixelsEqual`, inspect / screenshot
+- [Frame benchmarking](docs/frame-benchmark.md) — `benchmarkCartFrames` (headless) and optional `onFrameTiming` (live); zero cost when unset
 - [Presentation adapter](docs/presentation-adapter.md) — host-owned render model, intents, loading / error / unsupported
 - [Asset resolver](docs/asset-resolver.md) — host-pluggable images/audio/fonts/spritesheets, cache, preload, fallbacks
 - [Presentation cue](docs/presentation-cue.md) — deterministic `createPresentationTimeline`, duplicate policy, reduced-motion, lifecycle events
@@ -272,6 +273,8 @@ CI and agents should drive the **same** `createRuntime({ deterministic })` path.
 
 Full options, `click` clock rule, Node-only `captureFrame`, remount, visual asserts, and the reproduce command: [headless harness](docs/headless-harness.md).
 
+Hash / trait cost A/B without a browser: `benchmarkCartFrames` / `formatFrameBenchmarkResult` from the same headless entry. Live overlays: `runtime.onFrameTiming`. Details and the zero-overhead-when-off contract: [frame benchmarking](docs/frame-benchmark.md).
+
 ```ts
 import { createHeadlessHarness } from '@cyberart-io/engine/headless';
 

package/dist/headless.d.ts

@@ -333,6 +333,73 @@ type CartStateBundle = {
     state: unknown;
 };
 
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Host-controlled time, input, and asset completion for deterministic replays.
+ * Production kaleidoscope / Art Blocks playback does not enable this mode.
+ * Logical asset URLs are resolved by the host preloader (`assetResolver.ts`);
+ * this module only times `ASSET_READY_EVENT` / `ASSET_FAILED_EVENT` delivery.
+ */
+
+type PointerKind = 'down' | 'move' | 'up';
+type ScriptedAction = {
+    atFrame: number;
+} & ({
+    type: 'pointer';
+    pointer: {
+        kind: PointerKind;
+        x: number;
+        y: number;
+    };
+} | {
+    type: 'key';
+    key: string;
+} | {
+    type: 'event';
+    event: HostEvent;
+} | {
+    type: 'asset';
+    id: string;
+    status: 'ready' | 'failed';
+    /** Optional structured failure or resolved resource. Envelope is unchanged. */
+    detail?: unknown;
+});
+type DeterministicRuntimeOptions = {
+    /** Virtual clock origin in ms. Default 0. */
+    origin?: number;
+    /** Actions applied at the start of `atFrame`, before `update`. */
+    actions?: ScriptedAction[];
+};
+type ClockSnapshot = {
+    now: number;
+    framesElapsed: number;
+    frameRate: number;
+};
+type ReplayMetadata = {
+    seed: string;
+    clock: ClockSnapshot;
+    rng: RandomState;
+    actions: ScriptedAction[];
+    applied: AppliedAction[];
+    events: HostEvent[];
+    state: unknown;
+};
+type AppliedAction = {
+    frame: number;
+    action: ScriptedAction;
+};
+
+type FrameTimingSample = {
+    frame: number;
+    updateMs: number;
+    renderMs: number;
+    drawMs: number;
+    totalMs: number;
+};
+
 /**
  * Copyright (c) 2026 Aaron Boyarsky
  * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
@@ -403,65 +470,6 @@ type ExportSnapshotOptions = {
     runtimeVersion?: string;
 };
 
-/**
- * Copyright (c) 2026 Aaron Boyarsky
- * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
- * See packages/engine/LICENSE
- *
- * Host-controlled time, input, and asset completion for deterministic replays.
- * Production kaleidoscope / Art Blocks playback does not enable this mode.
- * Logical asset URLs are resolved by the host preloader (`assetResolver.ts`);
- * this module only times `ASSET_READY_EVENT` / `ASSET_FAILED_EVENT` delivery.
- */
-
-type PointerKind = 'down' | 'move' | 'up';
-type ScriptedAction = {
-    atFrame: number;
-} & ({
-    type: 'pointer';
-    pointer: {
-        kind: PointerKind;
-        x: number;
-        y: number;
-    };
-} | {
-    type: 'key';
-    key: string;
-} | {
-    type: 'event';
-    event: HostEvent;
-} | {
-    type: 'asset';
-    id: string;
-    status: 'ready' | 'failed';
-    /** Optional structured failure or resolved resource. Envelope is unchanged. */
-    detail?: unknown;
-});
-type DeterministicRuntimeOptions = {
-    /** Virtual clock origin in ms. Default 0. */
-    origin?: number;
-    /** Actions applied at the start of `atFrame`, before `update`. */
-    actions?: ScriptedAction[];
-};
-type ClockSnapshot = {
-    now: number;
-    framesElapsed: number;
-    frameRate: number;
-};
-type ReplayMetadata = {
-    seed: string;
-    clock: ClockSnapshot;
-    rng: RandomState;
-    actions: ScriptedAction[];
-    applied: AppliedAction[];
-    events: HostEvent[];
-    state: unknown;
-};
-type AppliedAction = {
-    frame: number;
-    action: ScriptedAction;
-};
-
 declare const ASSET_KINDS: readonly ["image", "audio", "font", "spritesheet"];
 type AssetKind = (typeof ASSET_KINDS)[number];
 declare const ASSET_FAILURE_CODES: readonly ["timeout", "cors", "not-found", "invalid", "aborted", "resolver"];
@@ -630,6 +638,7 @@ type FrameErrorInfo = {
     consecutive: number;
     stopped: boolean;
 };
+
 type CreateRuntimeOptions = {
     /** Required mount point. The runtime creates or adopts a canvas inside this element. */
     container: HTMLElement;
@@ -679,6 +688,11 @@ type CreateRuntimeOptions = {
      * `update`, and host-channel events still run. Default `'render'`.
      */
     kind?: CartKind;
+    /**
+     * Optional per-frame update/render/draw timings. Can also be assigned later
+     * via `runtime.onFrameTiming`. Unset = no `performance.now` in the draw loop.
+     */
+    onFrameTiming?: (sample: FrameTimingSample) => void;
 };
 type MountOptions<T = unknown> = {
     /** Boot overrides passed as `customState` into `getDefaultState`. Not a live-state replay. */
@@ -760,6 +774,11 @@ type CyberArtRuntime = {
     /** `'render'` (default) or `'calculation'` (no canvas / paint). */
     readonly kind: CartKind;
     onError?: (error: unknown, info: FrameErrorInfo) => void;
+    /**
+     * Optional per-frame update/render/draw timings. Unset = zero overhead in the
+     * draw loop (single null check). Same pattern as `onError`.
+     */
+    onFrameTiming?: (sample: FrameTimingSample) => void;
 };
 
 /**
@@ -1689,6 +1708,53 @@ type VisualLayerCapture = {
 declare function captureVisualLayers(controller: VisualLayerController): VisualLayerCapture;
 declare function createVisualLayerController(options: CreateVisualLayerControllerOptions): VisualLayerController;
 
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Cart-agnostic update/render frame benchmark for CI and agent workflows.
+ * Prefer this over ad-hoc vitest probes when evaluating hash / trait cost.
+ */
+
+type FrameBenchmarkOptions = {
+    /** Measured frames after warmup. Default 30. */
+    frames?: number;
+    /** Discarded frames before measurement. Default 5. */
+    warmupFrames?: number;
+    /** Simulated frame advance in ms. Default 1000/60. */
+    frameStepMs?: number;
+    width?: number;
+    height?: number;
+    tokenId?: string;
+    /**
+     * Mutate state after `getDefaultState` (e.g. skip Tone init in jsdom by
+     * setting `audioContextStarted = true`).
+     */
+    prepareState?: (state: unknown, featureState: unknown) => void;
+    /** Optional stub drawing context; defaults to a no-op `putImageData`. */
+    drawingContext?: CanvasRenderingContext2D;
+};
+type FrameBenchmarkResult = {
+    frames: number;
+    updateAvgMs: number;
+    renderAvgMs: number;
+    totalAvgMs: number;
+    updateMaxMs: number;
+    renderMaxMs: number;
+    estFps: number;
+    updatePct: number;
+    renderPct: number;
+};
+/**
+ * Run a cart's update/render loop headlessly and report average / max phase
+ * timings. Does not start audio or mount a live AnimationManager — suitable
+ * for jsdom vitest and agent hash probes.
+ */
+declare function benchmarkCartFrames<T, TFeatureState = undefined>(cart: AnimationCart<T, TFeatureState>, hash: string, rawParams: number[], options?: FrameBenchmarkOptions): FrameBenchmarkResult;
+/** Round timing fields for stable console / snapshot logging. */
+declare function formatFrameBenchmarkResult(result: FrameBenchmarkResult, digits?: number): Record<string, number>;
+
 /**
  * Copyright (c) 2026 Aaron Boyarsky
  * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
@@ -1709,4 +1775,4 @@ type WriteComposedFrameResult = ComposedFrame & {
  */
 declare function writeComposedFrame(compositor: Compositor, path?: string): Promise<WriteComposedFrameResult>;
 
-export { type BoundReplaySession, type CausationTreeNode, type CreateHeadlessHarnessOptions, type CreateHeadlessMultiCartHarnessOptions, type CreateReplayInspectorOptions, DEFAULT_HEADLESS_HEIGHT, DEFAULT_HEADLESS_WIDTH, type GlyphAtlas, HEADLESS_PNG_DATA_URL, type HeadlessAudioAdapter, type HeadlessCanvas2DSettings, type HeadlessFrameError, type HeadlessHarness, type HeadlessImageFixture, type HeadlessInspect, type HeadlessMultiCartHarness, HeadlessUnsupportedOperationError, type InspectorRecord, type InstallHeadlessCanvasOptions, type ReplayCompareResult, type ReplayInspector, type ReplayInspectorExport, type ReplayInspectorReport, type ReplayParticipantSummary, type ReplayTapeAction, type ReplayTraceFilter, UPDATE_GOLDEN_ENV, type VisualArtifactPaths, type VisualArtifacts, type VisualCompareOptions, type VisualCompareResult, type VisualLayerCapture, type VisualLayerController, type VisualLayerInspect, type WriteComposedFrameResult, assertPixelsEqual, assertPngDataUrlsEqual, attachHeadlessCanvas2D, captureVisualLayers, compareImageData, compareReplayTraces, createDefaultGlyphAtlas, createHeadlessAudioAdapter, createHeadlessHarness, createHeadlessMultiCartHarness, createImageFixture, createReplayInspector, createVisualLayerController, decodePng, encodePng, encodePngDataUrl, getHeadlessSurface, imageDataFromPngDataUrl, installHeadlessCanvas, makeImageData, replayExportedTrace, setDefaultGlyphAtlas, shouldUpdateGolden, writeComposedFrame, writeVisualArtifacts };
+export { type BoundReplaySession, type CausationTreeNode, type CreateHeadlessHarnessOptions, type CreateHeadlessMultiCartHarnessOptions, type CreateReplayInspectorOptions, DEFAULT_HEADLESS_HEIGHT, DEFAULT_HEADLESS_WIDTH, type FrameBenchmarkOptions, type FrameBenchmarkResult, type GlyphAtlas, HEADLESS_PNG_DATA_URL, type HeadlessAudioAdapter, type HeadlessCanvas2DSettings, type HeadlessFrameError, type HeadlessHarness, type HeadlessImageFixture, type HeadlessInspect, type HeadlessMultiCartHarness, HeadlessUnsupportedOperationError, type InspectorRecord, type InstallHeadlessCanvasOptions, type ReplayCompareResult, type ReplayInspector, type ReplayInspectorExport, type ReplayInspectorReport, type ReplayParticipantSummary, type ReplayTapeAction, type ReplayTraceFilter, UPDATE_GOLDEN_ENV, type VisualArtifactPaths, type VisualArtifacts, type VisualCompareOptions, type VisualCompareResult, type VisualLayerCapture, type VisualLayerController, type VisualLayerInspect, type WriteComposedFrameResult, assertPixelsEqual, assertPngDataUrlsEqual, attachHeadlessCanvas2D, benchmarkCartFrames, captureVisualLayers, compareImageData, compareReplayTraces, createDefaultGlyphAtlas, createHeadlessAudioAdapter, createHeadlessHarness, createHeadlessMultiCartHarness, createImageFixture, createReplayInspector, createVisualLayerController, decodePng, encodePng, encodePngDataUrl, formatFrameBenchmarkResult, getHeadlessSurface, imageDataFromPngDataUrl, installHeadlessCanvas, makeImageData, replayExportedTrace, setDefaultGlyphAtlas, shouldUpdateGolden, writeComposedFrame, writeVisualArtifacts };