@cyberart-io/engine 0.0.4 → 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

@@ -39,14 +39,14 @@ import {
 } from '@cyberart-io/engine';
 
 const defined = defineCapabilityManifest({
-  id: 'adventure.presentation',
+  id: 'host.presentation',
   runtime: { minContractVersion: 1, features: ['router'] },
   phases: ['loading', 'ready', 'error', 'unsupported'],
   managers: ['pointer', 'hostChannel'],
-  assets: { kinds: ['image'], declarations: [{ id: 'room-bg', kind: 'image' }] },
-  acceptedEvents: ['adventure.state.*'],
-  emittedEvents: ['adventure.intent.exit-requested'],
-  permissions: { emit: ['adventure.intent.*'], subscribe: ['adventure.state.*'] },
+  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('; '));
@@ -55,8 +55,8 @@ const host = {
   contractVersion: 1,
   features: ['router'],
   integrations: ['tone'] as const,
-  emit: ['adventure.intent.*'],
-  subscribe: ['adventure.state.*'],
+  emit: ['host.intent.*'],
+  subscribe: ['host.state.*'],
 };
 
 const check = validateCapabilityManifest(defined.manifest, host);
@@ -82,3 +82,14 @@ const parsed = parseCapabilityManifest(JSON.stringify(defined.manifest));
 | `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/deterministic-mode.md

@@ -2,7 +2,7 @@
 
 Host-controlled time, input, and asset completion so two runs with the same seed, actions, and `step` count match. Production kaleidoscope / Art Blocks **leave `deterministic` unset** (rAF, `performance.now()`, token hash).
 
-CI should use the [headless harness](headless-harness.md) on this path, not a mock engine. Router hosts: [events](events.md).
+CI should use the [headless harness](headless-harness.md) on this path, not a mock engine. Router hosts: [events](events.md). Frame-local effects: [presentation cue](presentation-cue.md) (`timeline.step` beside `cart.step`).
 
 Back to the [package README](../README.md).
 

package/docs/events.md

@@ -1,6 +1,6 @@
 # Events and router
 
-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`), [runtime group](runtime-group.md), [capability manifest](capability-manifest.md).
+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).
 
@@ -16,7 +16,7 @@ pnpm exec vitest run packages/engine/src/canvas/cyb-59-event-contract.repro.spec
 | 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, 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.
@@ -53,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`). |
@@ -68,13 +68,69 @@ 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.
-
-Typed contracts (`defineIntent`, `defineStateEvent`, `defineDiagnostic`) fail at definition time with structured `{ ok: false, errors }` instead of throwing. `createContractRegistry` produces manifest JSON and a `validate` hook for `createEventRouter`. `deriveAttachOptions` / `verifyAttachOptions` keep non-authoritative carts from emitting `state` / `diagnostic` contracts. Payload schema versioning: adding optional fields with a version bump is backward-compatible; removals, type changes, and version downgrades are breaking.
+- 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`.
 
+## Typed contracts
+
+Define each routed type once. That object is the TypeScript payload shape (`InferredPayload`), the runtime validator, the router permission source, and the JSON manifest row.
+
+```ts
+import {
+  defineIntent,
+  defineStateEvent,
+  createContractRegistry,
+  deriveAttachOptions,
+  createEventRouter,
+} from '@cyberart-io/engine';
+
+const exit = defineIntent('host.intent.exit-requested', {
+  version: 1,
+  fields: { exitId: { type: 'string' } },
+});
+const room = defineStateEvent('host.state.room-changed', {
+  version: 1,
+  fields: { roomId: { type: 'string' } },
+});
+if (!exit.ok || !room.ok) {
+  // structured errors — these helpers do not throw
+}
+const contracts = [exit.contract, room.contract];
+const registry = createContractRegistry(contracts);
+const router = createEventRouter({ validate: registry.asRouterValidate });
+router.attach('presentation', runtime.hostChannel, deriveAttachOptions(contracts, 'cart'));
+```
+
+`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 |
+|---|---|---|
+| `defineIntent(type, schema)` | `intent` | `type` must contain an `intent` dotted segment |
+| `defineStateEvent(type, schema)` | `state` | `type` must contain a `state` dotted segment |
+| `defineDiagnostic(type, schema)` | `diagnostic` | `type` must contain a `diagnostic` dotted segment |
+
+`schema` is `{ version: integer >= 1, fields: { name: { type: 'string' \| 'number' \| 'boolean' \| 'object' \| 'array', optional?: true } } }`. Extra payload keys are allowed. Missing required fields and wrong JSON types return `{ ok: false, errors: ContractDiagnostic[] }` (`code`, `detail`, optional `path`). Invalid definitions return the same shape; they never throw.
+
+| Export | Role |
+|---|---|
+| `createContractRegistry(contracts)` | `get`, `manifest()` (JSON-serializable), `validateEnvelope`, `asRouterValidate` (safe to pass as `EventRouterOptions.validate`; does not rely on `this`) |
+| `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 (`host.presentation.intent.*`) |
+
+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`)
+
+| Change | Result |
+|---|---|
+| Same version, same fields | `identical` |
+| Version bump, only new **optional** fields (or unchanged fields) | `backward-compatible` |
+| Removed field, type change, optional → required, version downgrade, optional add **without** a version bump | `breaking` |
+
 ## `createEventRouter(options?)`
 
 ```ts
@@ -87,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 },
   );
 });
@@ -116,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`)
 
@@ -125,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 |
@@ -135,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
 
@@ -148,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',

package/docs/headless-harness.md

@@ -12,7 +12,7 @@ Back to the [package README](../README.md).
 
 | Surface | Import |
 |---|---|
-| Carts, Player, kaleidoscope, `/art` | `@cyberart-io/engine` (`createRuntime`, events, assets, presentation adapter) |
+| 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.

package/docs/presentation-adapter.md

@@ -46,17 +46,17 @@ const model: PresentationModel = {
   reason: undefined, // string when not ready
   view: {
     background: '#1b3a4a',
-    title: 'Joiner Brook',
+    title: 'Overlook',
     regions: [
       {
-        id: 'north-trail',
+        id: 'region-north',
         x: 0,
         y: 0,
         width: 320,
         height: 45,
         intent: {
-          type: 'adventure.intent.exit-requested',
-          payload: { exitId: 'brook' },
+          type: 'host.intent.exit-requested',
+          payload: { exitId: 'beta' },
         },
       },
     ],
@@ -81,9 +81,9 @@ The reference cart never writes the host’s world. An unknown `contractVersion`
 
 ### Intents
 
-Region `intent.type` should be routable: `*.intent.*` (for example `adventure.intent.exit-requested`). The reference cart always sets `kind: 'intent'` on clicks (a hotspot cannot emit `state`).
+Region `intent.type` should be routable: `*.intent.*` (for example `host.intent.exit-requested`). The reference cart always sets `kind: 'intent'` on clicks (a hotspot cannot emit `state`).
 
-Default router `emit` is `['*.intent.*']`, which does **not** match `room.exit.requested`. Prefer `adventure.intent.*`.
+Default router `emit` is `['*.intent.*']`, which does **not** match `room.exit.requested`. Prefer `host.intent.*`.
 
 ## Reference cart + session
 
@@ -121,7 +121,7 @@ const adapter = mountPresentationAdapter(runtime, {
 await adapter.start();
 ```
 
-A host with a custom view shape passes `cart:` into `mountPresentationAdapter` and still `present()`s the same event. Do not import Adventure Kit types into engine carts.
+A host with a custom view shape passes `cart:` into `mountPresentationAdapter` and still `present()`s the same event. Do not import the host types into engine carts.
 
 ## Router
 
@@ -131,7 +131,7 @@ router.attach('presentation', runtime.hostChannel, {
   subscribe: [...PRESENTATION_SUBSCRIBE_PATTERNS],
 });
 
-router.subscribe(['adventure.intent.*', 'presentation.intent.unsupported'], (event) => {
+router.subscribe(['host.intent.*', 'presentation.intent.unsupported'], (event) => {
   const next = reduce(world, event); // host validates; ignore invalid intents
   if (next) {
     // Do not pass `{ cause: event }` — a second `presentation.state.model`

package/docs/presentation-cue.md

@@ -1,8 +1,8 @@
 # Presentation cue / timeline
 
-Deterministic cue/effect primitive. Carts call `step(frames)` with the same clock they use for CYB-23; there are no `setTimeout` / rAF timers. Gold checkmarks, ripples, room transitions, weather pulses, and NPC beats should share this lifecycle instead of ad-hoc frame counters.
+Deterministic cue/effect primitive. Carts call `step(frames)` with the same clock they use for deterministic mode; there are no `setTimeout` / rAF timers. Overlay pulses, scene transitions, and NPC beats should share this lifecycle instead of ad-hoc frame counters.
 
-Back to the [package README](../README.md). Related: [deterministic mode](deterministic-mode.md).
+Back to the [package README](../README.md). Related: [deterministic mode](deterministic-mode.md), [events](events.md) (routed contracts vs local `cue.*` names).
 
 ## One-command reproduce (this repo)