@cyberart-io/engine 0.0.3 → 0.0.5

package/docs/browser-harness.md

@@ -0,0 +1,126 @@
+# Browser / DOM host harness
+
+Opt-in harness that mounts a caller-supplied host into a real viewport, optionally with a runtime group and compositor. It sets viewport / DPR / reduced-motion / input modality, dispatches pointer and keyboard through DOM coordinates, steps a deterministic clock, and captures composed frames plus accessibility HTML.
+
+Import `createBrowserHarness` from **`@cyberart-io/engine`**. It does not load `node:fs`. In Vitest/jsdom, call `installHeadlessCanvas()` from **`@cyberart-io/engine/headless`** first so `Canvas2D` pixels exist. Production Player / kaleidoscope should not call this harness.
+
+Related: [normalized geometry](normalized-geometry.md), [presentation adapter](presentation-adapter.md), [compositor](compositor.md), [headless harness](headless-harness.md).
+
+Back to the [package README](../README.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-63-browser-harness.repro.spec.ts
+```
+
+## Why this exists
+
+`createHeadlessHarness` injects canvas-pixel clicks. It cannot prove a host's DOM overlay, CSS geometry, resize/DPR anchors, focus, or scroll. This harness lets a host mount overlay controls, run its own reducer, route through carts, and compose with `createCompositor` / `captureComposedFrame`. jsdom software Canvas2D is the headless composition path; a Playwright-compatible adapter maps the same scenario API for a later Chromium swap.
+
+Hosts drive the same API with their own overlay markup and event types; those names stay in the host, not in this module.
+
+## `createBrowserHarness(options)`
+
+```ts
+import { createBrowserHarness } from '@cyberart-io/engine';
+import { installHeadlessCanvas } from '@cyberart-io/engine/headless';
+
+installHeadlessCanvas();
+
+const harness = createBrowserHarness({
+  seed: `0x${'00'.repeat(32)}`,
+  viewport: { width: 1280, height: 800, deviceScaleFactor: 1 },
+  geometry,
+  contentWidth: 1920,
+  contentHeight: 1080,
+  mount(ctx) {
+    const hotspot = document.createElement('button');
+    hotspot.id = 'hotspot';
+    ctx.placeRegion('hotspot', hotspot);
+    ctx.root.append(hotspot);
+    return {
+      participants: [overlayA, overlayB],
+      compositor: { layers: [{ id: 'overlay-a', order: 0 }, { id: 'overlay-b', order: 1 }] },
+      ready(runtime) {
+        hotspot.addEventListener('click', () => {
+          runtime.publish({ type: 'host.intent.select', kind: 'intent', payload: { id: 'hotspot' } });
+        });
+      },
+      relayout() {
+        ctx.placeRegion('hotspot', hotspot);
+      },
+      destroy() {
+        hotspot.remove();
+      },
+    };
+  },
+});
+
+harness.goto();
+harness.click('#hotspot');
+await harness.step(1);
+const shot = harness.screenshot();
+const a11y = harness.accessibilitySnapshot();
+const meta = harness.reproduction();
+harness.destroy();
+```
+
+The host owns overlay markup, reducer state, and event type names. The harness owns viewport metrics, DOM input dispatch, the optional group/compositor lifecycle, and cleanup.
+
+### Options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `seed` | `0x00…` | Default participant seed when a cart omits one. |
+| `viewport.width` / `height` / `deviceScaleFactor` | `320` / `180` / `1` | CSS viewport and DPR. |
+| `reducedMotion` | `false` | Stubs `matchMedia('(prefers-reduced-motion: reduce)')`. |
+| `inputModality` | `'pointer'` | Recorded on the root (`data-input-modality`). |
+| `geometry` | none | Optional geometry document for `placeRegion` / CSS hit-testing. |
+| `contentWidth` / `contentHeight` / `fit` | viewport / `contain` | Intrinsic box for `createPresentationLayout`. |
+| `mount` | none | Host builds DOM and returns carts / compositor / cleanup. |
+
+### Handle (Playwright-shaped names)
+
+| Member | Meaning |
+|---|---|
+| `goto()` | No-op ready check (fixture is already mounted). |
+| `setViewport(width, height, dpr?)` | Resize root, group canvases, compositor; call host `relayout`. |
+| `click(selector)` / `click(x, y)` | Dispatch `pointerdown` / `pointerup` / `click` on DOM. |
+| `key` / `focus` | Keyboard through the focused element. |
+| `step` / `advance` | Deterministic group clock. |
+| `screenshot` | `captureComposedFrame()` plus `root.outerHTML` when a compositor is mounted. |
+| `accessibilitySnapshot` | Focus, `aria-live` text, HTML. |
+| `reproduction` | Seed, viewport, DPR, reduced-motion, modality, action tape. |
+| `destroy` | Host cleanup, group, compositor, listeners; blur focus; restore `matchMedia` / DPR. |
+
+## Playwright-compatible adapter (no Playwright dependency)
+
+`@playwright/test` is **not** an engine dependency. CI can wrap the same harness:
+
+```ts
+import { createBrowserHarness, createPlaywrightCompatibleAdapter } from '@cyberart-io/engine';
+
+const harness = createBrowserHarness({ viewport: { width: 390, height: 844 }, mount });
+const page = createPlaywrightCompatibleAdapter(harness);
+
+await page.goto();
+await page.setViewportSize({ width: 390, height: 844, deviceScaleFactor: 2 });
+await page.click('#hotspot');
+const shot = await page.screenshot();
+await page.close();
+```
+
+| Playwright `Page` | This adapter |
+|---|---|
+| `goto(url)` | `harness.goto()` (host already mounted) |
+| `setViewportSize` | `harness.setViewport` |
+| `click(selector)` | DOM click at the element's CSS box |
+| `screenshot()` | Composed `ImageData` + HTML (not a Chromium PNG) |
+| `keyboard.press` | `harness.key` |
+| `locator(sel).click` | Same DOM click |
+| `close()` | `harness.destroy()` |
+
+To run the same scenario in Chromium later, keep these method names and swap the adapter body for `chromium.launch()` + `page.goto(hostUrl)` without changing tests.
+
+Visual diffs stay on `assertPixelsEqual` / `compareImageData`. Do not add a second screenshot library.

package/docs/capability-manifest.md

@@ -0,0 +1,95 @@
+# Capability manifest
+
+Versioned JSON for what a cart needs from the host: runtime contract, lifecycle phases, managers, asset kinds, event patterns, permissions, and integrations. Related: [events](events.md) (emit / subscribe patterns), [asset resolver](asset-resolver.md) (kinds only — this file does not resolve URLs).
+
+Back to the [package README](../README.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-25-capability-manifest.repro.spec.ts
+```
+
+## Shape (`CAPABILITY_MANIFEST_VERSION = 1`)
+
+`defineCapabilityManifest` / `parseCapabilityManifest` return `{ ok: true, manifest }` or `{ ok: false, errors }`. `validateCapabilityManifest(manifest, host)` checks the host can actually run it. The manifest is a plain object: `JSON.parse(JSON.stringify(m))` equals `toJSON(m)`.
+
+| Field | Meaning |
+|---|---|
+| `id` | Cart / module id. |
+| `runtime.minContractVersion` | Lowest host contract version that may load this cart. |
+| `runtime.features` | Feature tags the host must list (e.g. `router`, `assets`). |
+| `phases` | Presentation phases used: `loading` \| `ready` \| `error` \| `unsupported`. |
+| `managers` | Required host managers: `keyboard`, `pointer`, `audio`, `assets`, `hostChannel`. |
+| `assets.kinds` | Asset kinds the cart declares (`image`, `audio`, `font`, `spritesheet`). |
+| `assets.declarations` | `{ id, kind }` summary only — not a resolver. |
+| `acceptedEvents` / `emittedEvents` | Dotted type patterns (`*` = one segment). |
+| `permissions` | `emit` / `subscribe` patterns; optional `authoritative`. |
+| `integrations` | Required host libraries: `tone` \| `midi`. |
+
+Emitted types must be covered by `permissions.emit`; accepted types by `permissions.subscribe`.
+
+## Host check
+
+```ts
+import {
+  defineCapabilityManifest,
+  parseCapabilityManifest,
+  validateCapabilityManifest,
+} from '@cyberart-io/engine';
+
+const defined = defineCapabilityManifest({
+  id: 'host.presentation',
+  runtime: { minContractVersion: 1, features: ['router'] },
+  phases: ['loading', 'ready', 'error', 'unsupported'],
+  managers: ['pointer', 'hostChannel'],
+  assets: { kinds: ['image'], declarations: [{ id: 'backdrop', kind: 'image' }] },
+  acceptedEvents: ['host.state.*'],
+  emittedEvents: ['host.intent.exit-requested'],
+  permissions: { emit: ['host.intent.*'], subscribe: ['host.state.*'] },
+  integrations: ['tone'],
+});
+if (!defined.ok) throw new Error(defined.errors.map((e) => e.detail).join('; '));
+
+const host = {
+  contractVersion: 1,
+  features: ['router'],
+  integrations: ['tone'] as const,
+  emit: ['host.intent.*'],
+  subscribe: ['host.state.*'],
+};
+
+const check = validateCapabilityManifest(defined.manifest, host);
+// check.ok === true
+const parsed = parseCapabilityManifest(JSON.stringify(defined.manifest));
+```
+
+`host.managers`, `host.emit`, and `host.subscribe` are optional. When omitted, `missing-manager` and `unknown-permission` are not checked. Pass them when the host wants to enforce those allowlists.
+
+| Diagnostic `code` | When |
+|---|---|
+| `unknown-field` | Extra key on the manifest or host object. |
+| `invalid-json` | `parseCapabilityManifest` received unparseable text. |
+| `invalid-manifest` / `invalid-host` | Root value is not a JSON object. |
+| `invalid-id` / `invalid-runtime` / `invalid-assets` / `invalid-permissions` | Required object missing or malformed. |
+| `invalid-field` | Array/string field has the wrong shape. |
+| `invalid-phase` | Phase is not loading/ready/error/unsupported. |
+| `invalid-pattern` | Event pattern is empty or malformed. |
+| `invalid-feature` | Feature tag is empty or malformed. |
+| `undeclared-permission` | An accepted/emitted pattern is not covered by cart permissions. |
+| `unsupported-runtime` | Host contract version is below `minContractVersion`. |
+| `unsupported-feature` | A required feature tag is missing on the host. |
+| `missing-integration` | Host does not provide `tone` / `midi` as required. |
+| `missing-manager` | Host listed `managers` but omitted one the cart requires. |
+| `unknown-permission` | Cart emit/subscribe permission is not on the host allowlist (only if host listed `emit` / `subscribe`). |
+| `invalid-surface` / `invalid-clear-policy` / `invalid-blend` | Cart or host `surface` / `layers` values are the wrong shape or not in the allowlist. |
+| `unsupported-surface` / `unsupported-layer` | Host omitted `surface.alpha` / `clearPolicy` or compositor blend modes the cart requires. |
+
+Optional additive keys (omitted on existing carts):
+
+```ts
+surface: { alpha: true, clearPolicy: 'transparent' }
+layers: { compositor: true, blend: ['source-over', 'screen'] }
+```
+
+See [compositor](compositor.md).

package/docs/compositor.md

@@ -0,0 +1,103 @@
+# Compositor
+
+Transparent multi-cart compositor. Reads each runtime-group canvas with `getImageData`, blends onto a host image (or a transparent clear), and records declared layer order for headless capture. Hosts should not invent CSS `screen` hacks for black-backed carts.
+
+Related: [runtime group](runtime-group.md), [headless harness](headless-harness.md), [capability manifest](capability-manifest.md).
+
+Back to the [package README](../README.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-64-compositor.repro.spec.ts
+```
+
+## When to use
+
+| Surface | Import | Use |
+|---|---|---|
+| Production host | `createCompositor` from `@cyberart-io/engine` | Stack a host image under participant canvases (effects, overlays, debug). |
+| Vitest / jsdom | same compositor after `installHeadlessCanvas()` | Headless `captureComposedFrame()` / `writeComposedFrame`. |
+
+Browser vs headless pixel agreement is covered by the [browser harness](browser-harness.md). This module still emits a headless capture that includes `declaredOrder`.
+
+## `createCompositor(options)`
+
+```ts
+import { createCompositor, createRuntimeGroup } from '@cyberart-io/engine';
+
+const group = createRuntimeGroup({
+  participants: [baseCart, overlayCart],
+});
+const compositor = createCompositor({
+  group,
+  width: 320,
+  height: 180,
+  dpr: 1,
+  host: { image: backdropImageData },
+  clearPolicy: 'transparent',
+  layers: [
+    { id: 'overlay-a', order: 0, blend: 'source-over' },
+    { id: 'overlay-b', order: 1, blend: 'screen' },
+  ],
+});
+
+await group.step(1);
+const frame = compositor.captureComposedFrame();
+// frame.declaredOrder is the compose list; frame.imageData is the stack.
+compositor.destroy();
+```
+
+Typical stack: host image, then opaque overlay carts (`source-over`), then additive layers (`screen` so RGB `0,0,0` backing is identity unless `clearPolicy: 'transparent'` knocks it out). Later `order` values draw on top.
+
+### Options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `group` | required | `createRuntimeGroup` handle. |
+| `layers` | required | One entry per participant id. Sorted by `order`, then id. |
+| `width` / `height` / `dpr` | `320` / `180` / `1` | Shared viewport. `resize` updates the group canvases. |
+| `host.image` / `host.color` | none | Back layer. Color is `#rgb` / `#rrggbb`. |
+| `clearPolicy` | `transparent` | Host surface starts clear (never filled black). Per-layer transparent policy knocks out RGB `0,0,0` backing pixels on opaque cart canvases. |
+| `offscreen` | `true` | Compose into a compositor-owned canvas when `target` is omitted. `false` requires `target`. A provided `target` is never destroyed. |
+
+### Layer fields
+
+| Field | Default | Meaning |
+|---|---|---|
+| `id` | required | Runtime-group participant id. |
+| `order` | required | Lower draws first. |
+| `visible` | `true` | Skip compose and pointer hits when false. |
+| `opacity` | `1` | 0..1. |
+| `blend` | `source-over` | Also `screen` (in-engine; same modes as `CAPABILITY_BLEND_MODES`). |
+| `clip` | none | Pixel rect; compose and pointer hits are clipped. |
+| `pointerEvents` | `auto` | `none` skips hit testing and sets `canvas.style.pointerEvents`. |
+| `clearPolicy` | compositor default | `transparent` knocks out black backing. |
+
+### Handle
+
+| Member | Meaning |
+|---|---|
+| `compose()` | Blend host + visible layers; returns `ImageData`. |
+| `captureComposedFrame()` | `{ imageData, pngDataUrl, declaredOrder, width, height }`. |
+| `resize(w, h, dpr?)` | Shared viewport; calls `group.resize` on the buffer size. Order/blend survive `group.step`. Carts that cache `DimensionContext` should `group.reset()` after a size change. |
+| `setLayer` / `layer` / `layers` | Mutate / inspect declarative settings. |
+| `pointerTarget(x, y)` | Top-most visible layer with `pointerEvents: 'auto'` under the pixel. |
+| `unmountLayer(id)` | `group.detach(id)` without clearing sibling canvases. |
+| `inspect()` | Viewport, clear policy, layers, `declaredOrder` ids. |
+| `destroy()` | Drops the host canvas only if the compositor created it. Does not destroy the group. |
+
+`group.step` isolates per-cart update/render throws so a failing layer does not blank siblings.
+
+Node tests that need a PNG file: `writeComposedFrame(compositor, path)` from `@cyberart-io/engine/headless`.
+
+## Capability keys (additive)
+
+Optional manifest fields, omitted on existing carts:
+
+```ts
+surface: { alpha: true, clearPolicy: 'transparent' }
+layers: { compositor: true, blend: ['source-over', 'screen'] }
+```
+
+`validateCapabilityManifest` reports `unsupported-surface` / `unsupported-layer` when the host does not list matching `surface` / `layers`. Carts that omit the keys keep the previous host check.

package/docs/events.md

@@ -1,6 +1,6 @@
 # Events and router
 
-Mailbox (one runtime) and `createEventRouter` (many carts). Carts never receive the router object or another cart’s `HostChannel`. Related: [deterministic mode](deterministic-mode.md) (`now` / `createId` / `turn` per `step`), [presentation adapter](presentation-adapter.md) (`presentation.state.model`), [presentation cue](presentation-cue.md) (frame-local lifecycle, not routed unless you define a contract).
+Mailbox (one runtime) and `createEventRouter` (many carts). Prefer `createRuntimeGroup` when several carts should share one router and lockstep clock. Carts never receive the router object or another cart’s `HostChannel`. Related: [deterministic mode](deterministic-mode.md) (`now` / `createId` / `turn` per `step`), [presentation adapter](presentation-adapter.md) (`presentation.state.model`), [presentation cue](presentation-cue.md) (frame-local lifecycle, not routed unless you define a contract), [runtime group](runtime-group.md), [capability manifest](capability-manifest.md), [replay inspector](replay-inspector.md).
 
 Back to the [package README](../README.md).
 
@@ -10,14 +10,16 @@ Back to the [package README](../README.md).
 pnpm exec vitest run packages/engine/src/canvas/cyb-59-event-contract.repro.spec.ts
 ```
 
+
 ## When to use which
 
 | Path | Use |
 |---|---|
 | Mailbox only | One cart, host `dispatch` / cart `emit`. No permissions, hops, or loop checks. |
-| Router | Several carts, host reducer in the middle, Adventure-style intent vs state. |
+| Router | Several carts, host reducer in the middle, Dotted-name intent vs state. |
+| Runtime group | Same router plus lockstep `step`, pause/reset/teardown, and a routed trace. |
 
-`createRuntime` does **not** attach a router. Attach `runtime.hostChannel` yourself. Cart unload clears the inbound queue only; router listeners stay until `runtime.destroy()`. If the channel is attached to a router, use `router.subscribe` for host logic — a second `mount({ onEvent })` will see every cart emit twice.
+`createRuntime` does **not** attach a router. Attach `runtime.hostChannel` yourself, or use `createRuntimeGroup()` which calls `router.attach(id, runtime.hostChannel, options)` for each participant. Cart unload clears the inbound queue only; router listeners stay until `runtime.destroy()` (or `group.destroy()`). If the channel is attached to a router, use `router.subscribe` for host logic — a second `mount({ onEvent })` will see every cart emit twice.
 
 ## Mailbox (`HostChannel`)
 
@@ -51,7 +53,7 @@ Routed events are normalized to `EventEnvelope` (`EVENT_ENVELOPE_VERSION = 1`).
 | Field | Set by | Meaning |
 |---|---|---|
 | `schemaVersion` | router | Always `1`. Other versions are `malformed`. |
-| `type` | emitter | Dotted name, e.g. `adventure.intent.exit-requested`. |
+| `type` | emitter | Dotted name, e.g. `host.intent.exit-requested`. |
 | `kind` | explicit or inferred | `intent` \| `state` \| `diagnostic`. |
 | `source` | router | Participant id (or `host` / `router`). Claimed `source` is overwritten. |
 | `target` | emitter | Optional **participant id**, not a domain object (put the exit id in `payload`). |
@@ -66,8 +68,8 @@ Routed events are normalized to `EventEnvelope` (`EVENT_ENVELOPE_VERSION = 1`).
 `kind` on the input wins. Otherwise:
 
 - `cyberart.state.save` / `cyberart.state.load` are **intents** (historical names).
-- Else the first dotted segment of `type` that is `intent`, `state`, or `diagnostic` (not necessarily the second segment — `adventure.presentation.intent.cue-started` is an intent).
-- Else `malformed` (`cannot infer kind`). `adventure.presentation.cue.started` does not infer a kind; define it with `defineIntent` / `defineStateEvent` / `defineDiagnostic` so the kind is in the name.
+- Else the first dotted segment of `type` that is `intent`, `state`, or `diagnostic` (not necessarily the second segment — `host.presentation.intent.cue-started` is an intent).
+- Else `malformed` (`cannot infer kind`). `host.presentation.cue.started` does not infer a kind; define it with `defineIntent` / `defineStateEvent` / `defineDiagnostic` so the kind is in the name.
 
 Only the host (`publish`) or an `authoritative` participant may emit `state` / `diagnostic`. Carts emit allowed `intent` patterns. Domain data belongs in `payload`.
 
@@ -84,11 +86,11 @@ import {
   createEventRouter,
 } from '@cyberart-io/engine';
 
-const exit = defineIntent('adventure.intent.exit-requested', {
+const exit = defineIntent('host.intent.exit-requested', {
   version: 1,
   fields: { exitId: { type: 'string' } },
 });
-const room = defineStateEvent('adventure.state.room-changed', {
+const room = defineStateEvent('host.state.room-changed', {
   version: 1,
   fields: { roomId: { type: 'string' } },
 });
@@ -101,7 +103,7 @@ const router = createEventRouter({ validate: registry.asRouterValidate });
 router.attach('presentation', runtime.hostChannel, deriveAttachOptions(contracts, 'cart'));
 ```
 
-`adventure.presentation.cue.started` has no `intent` / `state` / `diagnostic` segment, so `inferEventKind` returns undefined and `defineIntent` returns `{ ok: false, errors }` with `kind-mismatch`. Use `adventure.presentation.intent.cue-started` (kind anywhere after the namespace, not only the second segment). Cue timeline names (`cue.started`, …) are **not** routed envelopes until you wrap them in a contract.
+`host.presentation.cue.started` has no `intent` / `state` / `diagnostic` segment, so `inferEventKind` returns undefined and `defineIntent` returns `{ ok: false, errors }` with `kind-mismatch`. Use `host.presentation.intent.cue-started` (kind anywhere after the namespace, not only the second segment). Cue timeline names (`cue.started`, …) are **not** routed envelopes until you wrap them in a contract.
 
 | Helper | Kind stamped | Name rule |
 |---|---|---|
@@ -117,9 +119,9 @@ router.attach('presentation', runtime.hostChannel, deriveAttachOptions(contracts
 | `deriveAttachOptions(contracts, 'cart' \| 'authoritative')` | Cart: emit intent family patterns only. Authoritative: emit every contract family. Subscribe to non-intent families. |
 | `verifyAttachOptions(options, contracts)` | `{ ok: true }` or unauthorized-emit errors when a non-authoritative attach can emit a `state` / `diagnostic` contract |
 | `comparePayloadSchemas(from, to)` | `'identical'` / `'backward-compatible'` / `'breaking'` |
-| `kindSegmentInType(type)` / `familyPatternForType(type)` | First kind segment; last-segment `*` glob (`adventure.presentation.intent.*`) |
+| `kindSegmentInType(type)` / `familyPatternForType(type)` | First kind segment; last-segment `*` glob (`host.presentation.intent.*`) |
 
-Default router `emit: ['*.intent.*']` is **three** segments. Four-segment names such as `adventure.presentation.intent.cue-started` need `deriveAttachOptions` (or an explicit four-segment pattern). Duplicate `type`s in a registry last-win.
+Default router `emit: ['*.intent.*']` is **three** segments. Four-segment names such as `host.presentation.intent.cue-started` need `deriveAttachOptions` (or an explicit four-segment pattern). Duplicate `type`s in a registry last-win.
 
 ### Payload versioning (`comparePayloadSchemas`)
 
@@ -141,13 +143,13 @@ const router = createEventRouter({
 });
 
 router.attach('presentation', runtime.hostChannel, {
-  emit: ['adventure.intent.*'],
-  subscribe: ['adventure.state.*', 'cyberart.diagnostic.rejected'],
+  emit: ['host.intent.*'],
+  subscribe: ['host.state.*', 'cyberart.diagnostic.rejected'],
 });
 
-router.subscribe(['adventure.intent.*'], (event) => {
+router.subscribe(['host.intent.*'], (event) => {
   router.publish(
-    { type: 'adventure.state.room-changed', kind: 'state', payload: { roomId: 'brook' } },
+    { type: 'host.state.room-changed', kind: 'state', payload: { sceneId: 'beta' } },
     { cause: event },
   );
 });
@@ -170,6 +172,7 @@ router.turn(); // once per step / frame
 | `maxHops` | `DEFAULT_MAX_HOPS` (`8`) | Remaining hops on a new root. A caused follow-up gets `cause.hops - 1`. At 0 → `hop-limit`. |
 | `maxCorrelationPerTurn` | `16` | Events sharing a `correlationId` per turn → `storm-detected`. |
 | `maxIndex` | `256` | Bound on causation / idempotency maps (oldest keys dropped). |
+| `maxDecisions` | `256` | Bound on `inspectDecisions()` (oldest dropped). |
 
 ### Router methods (`EventRouter`)
 
@@ -179,8 +182,13 @@ router.turn(); // once per step / frame
 | `detach(id)` | Unbind. In-flight targeted emits to this id fail `unknown-target`. |
 | `publish(event, extras?)` | Host emit. `extras.cause` sets causation and inherited idempotency/correlation. Returns the envelope, or `undefined` if rejected. |
 | `subscribe(patterns, listener)` | Host listener (not a cart). Returns unsubscribe. |
+| `subscribeDecision(listener)` | Routing decisions: accepted, rejected, duplicate. |
+| `inspectParticipants()` | Attached id / emit / subscribe / authoritative. |
+| `inspectDecisions()` | Copy of the bounded decision log. |
 | `turn()` | Reset per-turn budgets and the auto-link causation cursor. Idempotency records **survive**. Call once per `step`. |
 
+Causation trees and tape replay: [replay inspector](replay-inspector.md).
+
 ### `AttachOptions`
 
 | Option | Default | Meaning |
@@ -189,7 +197,7 @@ router.turn(); // once per step / frame
 | `subscribe` | `[]` | Types delivered to this channel. |
 | `authoritative` | `false` | If true, may emit `state` / `diagnostic` **when those types are also in `emit`**. |
 
-Patterns are dotted segments; `*` matches one segment. `adventure.intent.*` matches `adventure.intent.exit-requested`, not `adventure.intent.exit.requested`.
+Patterns are dotted segments; `*` matches one segment. `host.intent.*` matches `host.intent.exit-requested`, not `host.intent.exit.requested`.
 
 ## Delivery and ordering
 
@@ -202,7 +210,7 @@ Cart-to-cart still goes through the router:
 
 ```ts
 presentationChannel.emit({
-  type: 'adventure.intent.remark',
+  type: 'host.intent.remark',
   target: 'npc',
   payload: { text: 'Anyone there?' },
   idempotencyKey: 'hello-1',
@@ -247,14 +255,11 @@ Type `REJECTED_EVENT_TYPE` (`cyberart.diagnostic.rejected`). Payload (`Rejection
 | `EVENT_ENVELOPE_VERSION` | `1`. |
 | `DEFAULT_MAX_HOPS` | `8`. |
 | `REJECTED_EVENT_TYPE` | `'cyberart.diagnostic.rejected'`. |
-| `inferEventKind(input)` | Kind from `kind` or first kind segment in `type`. |
+| `inferEventKind(input)` | Kind from `kind` or type name. |
 | `matchEventPattern(pattern, type)` | One-segment `*` glob. |
 | `normalizeEvent(input, context)` | Build an envelope or `{ ok: false, reason: 'malformed', detail }`. The router calls this; hosts rarely need it. |
-| `defineIntent` / `defineStateEvent` / `defineDiagnostic` | Contract constructors (see Typed contracts). |
-| `createContractRegistry` / `deriveAttachOptions` / `verifyAttachOptions` / `comparePayloadSchemas` | Registry, permissions, schema compatibility. |
-| `kindSegmentInType` / `familyPatternForType` | Name helpers used by contracts. |
 
-Types: `EventEnvelope`, `EventInput`, `EventKind`, `NormalizeContext`, `NormalizeResult`, `RejectionPayload`, `RejectionReason`, `AttachOptions`, `EventRouter`, `EventRouterOptions`, `PublishExtras`, `ValidateResult`, `EventContract`, `EventContractManifest`, `ContractRegistry`, `DefineContractResult`, `PayloadSchema`, `PayloadFieldSpec`, `PayloadValidation`, `ContractDiagnostic`, `ContractFieldType`, `InferredPayload`, `SchemaCompatibility`.
+Types: `EventEnvelope`, `EventInput`, `EventKind`, `NormalizeContext`, `NormalizeResult`, `RejectionPayload`, `RejectionReason`, `AttachOptions`, `EventRouter`, `EventRouterOptions`, `PublishExtras`, `ValidateResult`.
 
 `matchesAnyPattern` / `clonePayload` / `isEventKind` are not on the public package surface.
 

package/docs/headless-harness.md

@@ -4,7 +4,7 @@ CI / agent wrapper around production `createRuntime({ deterministic })`. Not a s
 
 Import from **`@cyberart-io/engine/headless`**. Production carts and browser hosts keep using `@cyberart-io/engine` so Vite never resolves `node:fs/promises`.
 
-Depends on [deterministic mode](deterministic-mode.md). Host reducers: [events](events.md). Presentation overlay: [presentation adapter](presentation-adapter.md).
+Depends on [deterministic mode](deterministic-mode.md). Host reducers: [events](events.md). Presentation overlay: [presentation adapter](presentation-adapter.md). Several carts: [runtime group](runtime-group.md) (`createHeadlessMultiCartHarness`).
 
 Back to the [package README](../README.md).
 
@@ -12,8 +12,8 @@ Back to the [package README](../README.md).
 
 | Surface | Import |
 |---|---|
-| Carts, Player, kaleidoscope, `/art` | `@cyberart-io/engine` (`createRuntime`, events, contracts, assets, presentation adapter, presentation cue) |
-| Vitest / jsdom / CI capture | `@cyberart-io/engine/headless` (`createHeadlessHarness`, `installHeadlessCanvas`, `captureFrame`) |
+| 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`) |
 
 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`.
 
@@ -38,10 +38,38 @@ import {
 installHeadlessCanvas();
 ```
 
-Mutates `HTMLCanvasElement.prototype`: `ImageData` polyfill (width/height constructor), stub `getContext` (`fillRect`, `putImageData`, `createImageData`), `toDataURL` → `HEADLESS_PNG_DATA_URL` (a real 1×1 PNG, not visual `fillRect` pixels). Idempotent. **Do not call from production playback.**
+Mutates `HTMLCanvasElement.prototype`: `ImageData` polyfill (width/height and `ImageData(data, w, h)`), software `getContext('2d')` (paths, arcs, text via a glyph atlas, transforms, clip, alpha, source-over, linear/radial gradients, `drawImage` from ImageData / headless canvas / `createImageFixture`), `toDataURL` encodes those pixels as PNG. `HEADLESS_PNG_DATA_URL` remains a 1×1 compatibility export for callers that never attached a context. Idempotent. **Do not call from production playback.**
 
 `createHeadlessHarness` calls this for you. Default container size is `DEFAULT_HEADLESS_WIDTH` × `DEFAULT_HEADLESS_HEIGHT` (320×180).
 
+Coverage is binary (pixel-center inside path / nearest-neighbor images). No antialiasing, no `Math.random`. Identical seeded harness runs produce identical `ImageData`. Unsupported operations throw `HeadlessUnsupportedOperationError` with the operation name (never silent no-ops). `createPattern`, non-empty `setLineDash`, `filter`, shadows, HTMLImageElement `drawImage`, and unknown context methods are in that set.
+
+Font/image fixtures: pass `{ glyphAtlas }` to `installHeadlessCanvas`, call `setDefaultGlyphAtlas`, or `ctx.setGlyphAtlas`. `fillText` never loads system fonts. `drawImage` accepts `ImageData`, another headless canvas, or `createImageFixture(width, height, pixels)`.
+
+## Visual assertions
+
+Import `compareImageData`, `assertPixelsEqual`, `assertPngDataUrlsEqual`, and `writeVisualArtifacts` from `@cyberart-io/engine/headless`.
+
+- Exact match: `tolerance` defaults to 0 (every RGBA byte).
+- Perceptual / slack: `tolerance` (max per-channel delta) and/or `perceptualThreshold` (weighted RGB distance with luma weights 0.299 / 0.587 / 0.114).
+- On mismatch the result includes in-memory `expectedPng` / `actualPng` / `diffPng` (magenta where pixels differ) plus data URLs. `writeVisualArtifacts(dir, artifacts)` writes those PNGs (Node `fs` only; same rule as `captureFrame(path)`).
+- Golden update: set `CYBERART_UPDATE_GOLDEN=1` (or `true`) or pass `{ updateGolden: true }`. The compare then treats actual as expected so CI can rewrite goldens. Engine-encoded 8-bit RGBA PNGs round-trip through `decodePng`.
+
+```ts
+import { compareImageData, writeVisualArtifacts } from '@cyberart-io/engine/headless';
+
+const result = compareImageData(actual, expected, { perceptualThreshold: 2 });
+if (!result.match) {
+  await writeVisualArtifacts('/tmp/cyb-62-diff', result.artifacts);
+}
+```
+
+One-command visual reproduce in this repo:
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-62-headless-canvas2d.repro.spec.ts
+```
+
 ## `createHeadlessHarness(options)`
 
 ```ts
@@ -54,7 +82,7 @@ const harness = createHeadlessHarness({
   height: 180,
   origin: 0,
   actions: [{ type: 'asset', atFrame: 0, id: 'room-map', status: 'ready' }],
-  initialState: { room: 'glade' },
+  initialState: { scene: 'alpha' },
   gameManager: hostAdapter, // site injection; presentation overlay is attachPresentationAdapter
   onEvent: (event) => {},
   onError: (error, info) => {},
@@ -92,7 +120,7 @@ Always sets `deterministic: { origin, actions }`.
 | `click(x, y)` | Pointer-**down** at `getClock().framesElapsed` (next tick). Canvas pixels, not CSS. Use `schedule` for `move` / `up`. |
 | `key(key)` | Same next-frame `schedule` for a key. Cart must `registerAction`. |
 | `inspect()` | `{ state, events, errors, replay, clock }`. `state` is **exported**, not live `getCartState()`. |
-| `captureFrame(path?)` | `cart.snapshot()`. Optional `path` writes PNG bytes (Node only). Stub-stable. |
+| `captureFrame(path?)` | `cart.snapshot()` (`canvas.toDataURL('image/png')` on the production buffer). Optional `path` writes PNG bytes (Node only). |
 | `remount(options?)` | `runtime.mount` again while alive. Constructor `actions` replay; prior `click`/`key`/`schedule` dropped. `'onEvent' in options` replaces the listener; `{ onEvent: undefined }` clears it. Invalid after `destroy()`. |
 | `destroy()` | Unload cart, destroy runtime, remove container. Idempotent. Always removes the container even if unload throws. |
 
@@ -118,9 +146,11 @@ First frame throw: `{ phase: 'update', consecutive: 1, stopped: false }`. See [d
 
 Returns `CartSnapshot`: `{ seed, metadata?, pngDataUrl }`.
 
-- Omit `path` for in-memory snapshot (`pngDataUrl` is `HEADLESS_PNG_DATA_URL` under the stub).
+- Omit `path` for in-memory snapshot (`pngDataUrl` is the software Canvas2D frame, not the 1×1 stub).
 - With `path`: Node `fs.promises.writeFile` of decoded PNG bytes. Throws a harness message if not Node, if `node:fs/promises` cannot load, or if the write fails (missing directory, etc.). Write under `os.tmpdir()`, not the repo.
 
+Composed stacks use `createCompositor` plus `writeComposedFrame(compositor, path)` from the same headless entry. See [compositor](compositor.md).
+
 ## Interaction loop (agent recipe)
 
 ```ts
@@ -142,17 +172,17 @@ adapter.present({
   contractVersion: 1,
   phase: 'ready',
   view: {
-    title: 'Glade',
+    title: 'Alpha',
     regions: [
       {
-        id: 'north-trail',
+        id: 'region-north',
         x: 0,
         y: 0,
         width: canvas.width,
         height: canvas.height * 0.25,
         intent: {
-          type: 'adventure.intent.exit-requested',
-          payload: { exitId: 'brook' },
+          type: 'host.intent.exit-requested',
+          payload: { exitId: 'beta' },
         },
       },
     ],
@@ -163,24 +193,24 @@ harness.click(canvas.width / 2, canvas.height * 0.1);
 await harness.step(1);
 
 const { events } = await harness.inspect();
-// assert exactly one adventure.intent.exit-requested; cart state is still Glade
+// assert exactly one host.intent.exit-requested; cart state is still Alpha
 
 adapter.present({
   contractVersion: 1,
   phase: 'ready',
-  view: { title: 'Joiner Brook', regions: [] },
+  view: { title: 'Overlook', regions: [] },
 });
 await harness.step(1);
 
-await harness.captureFrame('/tmp/brook.png');
+await harness.captureFrame('/tmp/alpha.png');
 adapter.destroy();
 harness.destroy();
 ```
 
 Cleanup: cart `teardown` runs on unload; after `destroy`, `step` throws and the container is gone. `afterEach(() => harness.destroy())` so a failed assertion does not leak nodes. `attachPresentationAdapter(harness)` then `adapter.destroy()` tears down the harness too; `attachPresentationAdapter(harness.cart)` only unloads the cart.
 
-Host-owned rooms / hotspots use this adapter (`present` + `adventure.intent.*`). `gameManager` is site multiplayer, not this contract.
+Host-owned scenes / hotspots use this adapter (`present` + `host.intent.*`). `gameManager` is site multiplayer, not this contract.
 
 ## Types
 
-`CreateHeadlessHarnessOptions`, `HeadlessHarness`, `HeadlessInspect`, `HeadlessFrameError`.
+`CreateHeadlessHarnessOptions`, `HeadlessHarness`, `HeadlessInspect`, `HeadlessFrameError`, `InstallHeadlessCanvasOptions`, `HeadlessUnsupportedOperationError`, visual-assert types.