@cyberart-io/engine 0.0.7 → 0.0.8

package/docs/frame-benchmark.md

@@ -0,0 +1,107 @@
+# Frame performance benchmarking
+
+Cart-agnostic tools for measuring update vs render cost. Use these for hash / trait investigations instead of one-off vitest probes.
+
+Production kaleidoscope / Art Blocks playback **leave profiling unset**. When `onFrameTiming` is unset, the draw loop only does a single null check — no `performance.now()` calls.
+
+Back to the [package README](../README.md). Related: [headless harness](headless-harness.md), [deterministic mode](deterministic-mode.md).
+
+## Two surfaces
+
+| Surface | Import | When to use |
+|---|---|---|
+| Headless bench | `@cyberart-io/engine/headless` → `benchmarkCartFrames` | CI / agent hash A/B without mounting a live runtime |
+| Live hook | `@cyberart-io/engine` → `runtime.onFrameTiming` | Overlay / collect samples on the real `rAF` or `step` path |
+
+## Headless: `benchmarkCartFrames`
+
+Runs a cart's `update` / `render` loop with a virtual frame clock. Does not start audio or construct `AnimationManager`.
+
+```ts
+import {
+  benchmarkCartFrames,
+  formatFrameBenchmarkResult,
+} from '@cyberart-io/engine/headless';
+
+const result = benchmarkCartFrames(artProject, hash, rawParams, {
+  width: 1920,
+  height: 1080,
+  frames: 30,
+  warmupFrames: 5,
+  prepareState: (state) => {
+    // e.g. skip Tone init in jsdom
+    (state as { audioContextStarted?: boolean }).audioContextStarted = true;
+  },
+});
+
+console.table(formatFrameBenchmarkResult(result));
+```
+
+### Result fields
+
+| Field | Meaning |
+|---|---|
+| `updateAvgMs` / `renderAvgMs` | Mean phase time over measured frames |
+| `updateMaxMs` / `renderMaxMs` | Worst frame in the sample (catches sim hitches) |
+| `totalAvgMs` / `estFps` | Combined average and `1000 / totalAvgMs` |
+| `updatePct` / `renderPct` | Share of measured time |
+
+`formatFrameBenchmarkResult` rounds for stable console / snapshot logs.
+
+### Options
+
+- `frames` (default 30), `warmupFrames` (default 5), `frameStepMs` (default `1000/60`)
+- `width` / `height` (default 1920×1080)
+- `tokenId` for `Random`
+- `prepareState(state, featureState)` after `getDefaultState`
+- `drawingContext` stub (default no-op `putImageData`)
+
+One-command reproduce in this repo:
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/frameBenchmark.spec.ts
+```
+
+## Live: `onFrameTiming`
+
+Optional per-frame sample on the production draw / `step` path.
+
+```ts
+import { createRuntime, type FrameTimingSample } from '@cyberart-io/engine';
+
+const samples: FrameTimingSample[] = [];
+
+const runtime = createRuntime({
+  container,
+  // optional at construction:
+  onFrameTiming: (sample) => samples.push(sample),
+});
+
+// or assign later / clear to restore zero overhead:
+runtime.onFrameTiming = (sample) => {
+  console.log(sample.frame, sample.updateMs, sample.renderMs, sample.drawMs);
+};
+runtime.onFrameTiming = undefined;
+```
+
+### Sample shape
+
+```ts
+type FrameTimingSample = {
+  frame: number;
+  updateMs: number;
+  renderMs: number;
+  drawMs: number;
+  totalMs: number;
+};
+```
+
+### Cost when off
+
+`createRuntime` assigns the handler **directly** to `AnimationManager`. When the host clears `runtime.onFrameTiming`, the manager property is `undefined` again. `processFrame` only calls `performance.now()` inside `if (timingHook)` branches.
+
+Do **not** wrap with an always-on forwarder (`(s) => host?.(s)`): that would keep the hook truthy and force timing every frame.
+
+## Cart-specific helpers
+
+This package stays cart-agnostic. Repos that need trait decode beside the bench (e.g. kautomata `hashPerfProbe`) should wrap `benchmarkCartFrames` in the cart tree — not in the engine.

package/docs/headless-harness.md

@@ -13,10 +13,14 @@ Back to the [package README](../README.md).
 | Surface | Import |
 |---|---|
 | Carts, Player, kaleidoscope, `/art` | `@cyberart-io/engine` (`createRuntime`, events, contracts, assets, presentation adapter, presentation cue, capability manifest, geometry, runtime group) |
-| Vitest / jsdom / CI capture | `@cyberart-io/engine/headless` (`createHeadlessHarness`, `createHeadlessMultiCartHarness`, `installHeadlessCanvas`, `captureFrame`) |
+| Vitest / jsdom / CI capture | `@cyberart-io/engine/headless` (`createHeadlessHarness`, `createHeadlessMultiCartHarness`, `installHeadlessCanvas`, `captureFrame`, `benchmarkCartFrames`) |
 
 The main export does not re-export the harness. A browser bundle that only imports `@cyberart-io/engine` must not warn about `node:fs/promises`.
 
+## Frame performance
+
+For update/render timing without mounting a live runtime, use `benchmarkCartFrames` from this entry. For live `rAF` / `step` samples, use `runtime.onFrameTiming` from `@cyberart-io/engine` (unset = no `performance.now` in the draw loop). Full API: [frame benchmarking](frame-benchmark.md).
+
 ## One-command reproduce (this repo)
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyberart-io/engine",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "CyberArt host engine: mount carts, events, capability manifests, geometry, runtime groups, and a Node/jsdom headless entry.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",