@cyberart-io/engine 0.0.7 → 0.0.9

package/docs/asset-resolver.md

@@ -2,7 +2,7 @@
 
 Host-owned URL policy. The engine caches, dedupes, tracks progress, applies timeouts and fallbacks, and (in live mode) dispatches `ASSET_READY_EVENT` / `ASSET_FAILED_EVENT`. Authored carts keep logical refs (`moltazine:post/<id>#primary-image`, `world:asset/…`, `library:…`, or ordinary URLs). the host, Cyberart, and a local preview each supply a different `AssetResolver`.
 
-Deterministic timing: [deterministic mode](deterministic-mode.md). CI: [headless harness](headless-harness.md). Event mailbox: [events](events.md).
+Deterministic timing: [deterministic mode](deterministic-mode.md). CI: [headless harness](headless-harness.md). Event mailbox: [events](events.md). Built on this: [remote cart manifests](remote-cart-manifest.md) (`createDeclaredAssetResolver`, declared URLs and hashes only), [content revision](content-revision.md) (resolves every declared asset before one atomic bundle swap), [selection trace](selection-trace.md) (records which logical ref, hash, and fallback won).
 
 Back to the [package README](../README.md).
 

package/docs/browser-harness.md

@@ -4,7 +4,7 @@ Opt-in harness that mounts a caller-supplied host into a real viewport, optional
 
 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).
+Related: [normalized geometry](normalized-geometry.md), [presentation adapter](presentation-adapter.md), [compositor](compositor.md), [headless harness](headless-harness.md). Built on this: [production scenario](production-scenario.md) (mounts the full host/runtime/cart composition through this harness), [semantic layers](semantic-layers.md) (`semanticLayers` option, a11y snapshot).
 
 Back to the [package README](../README.md).
 

package/docs/capability-manifest.md

@@ -1,6 +1,6 @@
 # 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), [calculation carts](calculation-carts.md) (`kind`).
+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), [calculation carts](calculation-carts.md) (`kind`). Built on this: [remote cart manifests](remote-cart-manifest.md) (signed catalog with optional nested `capabilities` + host `grants`), [content revision](content-revision.md) (required grants checked before activation).
 
 Back to the [package README](../README.md).
 

package/docs/content-revision.md

@@ -0,0 +1,64 @@
+# Content revision activation
+
+Atomic staging and commit for an external content revision (room art, masks, portraits, line audio). Adapters load catalogs; the activator resolves every declared asset and swaps one complete bundle. Consumers see the last known good revision or the new revision — never a mix.
+
+Related: [Asset resolver](asset-resolver.md) (`createDeclaredAssetResolver`), [Remote cart manifests](remote-cart-manifest.md) (`verifyRemoteCartSignature`, grants), [Capability manifest](capability-manifest.md), [Snapshots](snapshots.md). Back to the [package README](../README.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-79-content-revision.repro.spec.ts
+```
+
+## When to use
+
+| Surface | Import | Use |
+|---|---|---|
+| Production host | `createContentRevisionActivator` from `@cyberart-io/engine` | Persist `snapshot()` in envelope `hostState`. Read `activeBundle()` / `inspect()` for presentation. |
+| Vitest / jsdom | same, or `@cyberart-io/engine/headless` | `createStaticContentAdapter` plus in-process `createRemoteContentAdapter({ fetch })`. |
+
+Moltazine World is the first **adapter**, not a hard-coded SDK. Tests inject a fake remote fetch. There is no product UI here.
+
+## Contract
+
+1. **Identity.** A bundle is `contentId` + exact `revision` + `manifestVersion` + asset hashes + publisher/source + adapter id. Snapshots never store `"latest"`.
+2. **Adapters.** `createStaticContentAdapter` (local catalog) and `createRemoteContentAdapter` (injected fetch, signed CYB-74 JSON, optional `{ world, revision, manifest }` envelope) implement the same load/activation contract. Static `discover` picks the numeric-aware newest revision id (`10` beats `9`).
+3. **Staging.** Resolve every declared asset, validate schema, hashes, signatures, and required grants **before** `activeBundle()` changes.
+4. **Commit.** One atomic swap, exactly one `content.revision.state.activated` event per accepted revision. Idempotent activate of the live bundle/revision id does not emit again.
+5. **Visibility.** `inspect()` / `activeBundle()` return a complete revision or `null`. Staging identity may appear on `inspect().staging`; resources stay on the live bundle.
+6. **Rollback.** Last-known-good is retained. Hash/schema/capability/health-check failure keeps or restores that bundle and emits a machine-readable rejection. `rollback()` is idempotent.
+7. **Optional assets** may omit or use a declared hashed fallback. Required assets must all succeed.
+8. **Supersede.** A newer `activate` aborts in-flight staging, emits `superseded`, then stages the new revision. A stale health check after a newer commit returns `stale-health-check`, not `superseded`.
+9. **Pin.** `pin()` freezes live movement after a bundle is active: `activate` of another revision, `rollback`, and `restore` that would change the live bundle all fail with `pinned`. Discover still works. Idempotent activate/rollback of the current bundle is allowed.
+10. **Restore.** Validate the entire snapshot (schema version, exact revisions known to adapters) before mutate. Unknown version or unknown revision leaves the live bundle unchanged.
+11. **Cache.** Byte cache is keyed by digest and re-hashed on reuse.
+
+```ts
+import {
+  createContentRevisionActivator,
+  createRemoteContentAdapter,
+  createStaticContentAdapter,
+} from '@cyberart-io/engine';
+
+const activator = createContentRevisionActivator({
+  adapters: [staticAdapter, remoteAdapter],
+  grants: createHostGrantSet(['audio']),
+});
+
+await activator.activate({ contentId: 'room-overlook', revision: '8' });
+activator.activeBundle(); // complete revision 8, or null
+activator.snapshot();     // exact revision + hashes for hostState
+```
+
+| Event | When |
+|---|---|
+| `content.revision.state.discovered` | Adapter reported an exact revision |
+| `content.revision.state.staging` | Resolve/validate started; presentation unchanged |
+| `content.revision.state.validated` | Declared assets, hashes, and capabilities passed |
+| `content.revision.state.rejected` | Staging or validation failed; live bundle unchanged |
+| `content.revision.state.activated` | Atomic commit of one complete bundle |
+| `content.revision.state.rolled-back` | Health-check/activation failure or host `rollback()` |
+| `content.revision.state.superseded` | Newer revision cancelled this staging attempt |
+| `content.revision.diagnostic.lifecycle` | Machine-readable rejection detail |
+
+Contracts: `contentRevisionEventContracts()`.

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`), [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).
+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). Modules that publish typed `*.state.*` / `*.diagnostic.*` contracts through this router: [content revision](content-revision.md), [job orchestration](job-orchestration.md), [world graph](world-graph.md), [world patch](world-patch.md), [production scenario](production-scenario.md), [presentation bindings](presentation-bindings.md), [presentation sequences](presentation-sequences.md).
 
 Back to the [package README](../README.md).
 

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

@@ -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). Several carts: [runtime group](runtime-group.md) (`createHeadlessMultiCartHarness`).
+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`). Whole production composition in CI: [production scenario](production-scenario.md). Headless fakes for the framework modules also live on this entry: `createHeadlessAudioAdapter` ([presentation sequences](presentation-sequences.md)), `createHeadlessJobWorker` ([job orchestration](job-orchestration.md)).
 
 Back to the [package README](../README.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/docs/job-orchestration.md

@@ -0,0 +1,55 @@
+# Job orchestration
+
+Durable lifecycle for long-running generated work (world chunks, media transforms). The coordinator models queueing, progress, retries, evaluator feedback, leases, and host-owned apply. Workers perform the task; wall-clock completion never mutates authoritative host state.
+
+Related: [Events and router](events.md) (CYB-59 contracts), [Replay inspector](replay-inspector.md) (`DEFAULT_SENSITIVE_KEYS` / `REDACTED_VALUE`), [Snapshots](snapshots.md). Built on this: [World patch](world-patch.md) (a `ready` job result becomes one transactional world revision under host `commit`), [World graph](world-graph.md) (generated frontier work). Back to the [package README](../README.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-80-job-orchestration.repro.spec.ts
+```
+
+## When to use
+
+| Surface | Import | Use |
+|---|---|---|
+| Production host | `createJobCoordinator` from `@cyberart-io/engine` | Persist `snapshot()` in envelope `hostState`. Call `accept(jobId)` only under host policy. |
+| Vitest / jsdom | same, or `@cyberart-io/engine/headless` | `createHeadlessJobWorker` controls complete/fail timing. `createMemoryJobPersistence` is enough for refresh tests. |
+
+## Contract
+
+1. **Definitions** are versioned: request schema, result kind, retry/lease/timeout, declared fallback.
+2. **Submit** with a stable idempotency key and a correlation id for the initiating player intent. Duplicate keys return the same job.
+3. **States:** queued → claimed → awaiting-evaluation → ready → applied, plus retry-scheduled, failed, canceled, superseded.
+4. **Results** are refs (`uri` + `kind`), not embedded media/world payloads.
+5. **Evaluator** may accept, reject, or request a bounded revision.
+6. **Host apply** is `accept(jobId)` on `ready` only. Worker `complete` stops at awaiting-evaluation.
+7. **Restore** validates JSON and schema version before mutate. Tampered snapshots return `{ ok: false }` and leave jobs unchanged.
+8. **Export traces** and replay-inspector payloads redact `JOB_REDACTED_KEYS` / `DEFAULT_SENSITIVE_KEYS` (`prompt`, `credentials`, `credential`, `authorization`, `apiKey`, `secret`) via `REDACTED_VALUE`. `token` is not in that set — pass it in `createReplayInspector({ redactedKeys: ['token'] })` when a cart uses that name. Reason codes stay visible.
+
+```ts
+import {
+  createHeadlessJobWorker,
+  createJobCoordinator,
+} from '@cyberart-io/engine/headless';
+
+const worker = createHeadlessJobWorker();
+const jobs = createJobCoordinator({
+  definitions: [frontierDefinition],
+  worker,
+  now: () => clock,
+});
+
+jobs.submit({
+  definitionId: 'frontier-generate',
+  idempotencyKey: 'frontier:day-1',
+  request: { prompt: '...', seed },
+  correlationId: playerIntentId,
+});
+jobs.claim('worker-1');
+worker.complete(jobId, { schemaVersion: 1, kind: 'world-chunk', uri: 'ref://...' });
+jobs.evaluate(jobId, 'accept');
+// host policy: e.g. only at the day boundary
+jobs.accept(jobId);
+```

package/docs/portal-lifecycle.md

@@ -0,0 +1,50 @@
+# Portal lifecycle
+
+One enter / exit / abort contract for leaving a cart, inhabiting another exclusively, and returning a versioned outcome. Arcade cabinet, painting, dream, wormhole, book, and nested world are host metaphors over the same primitive — not separate lifecycles.
+
+Related: [runtime group](runtime-group.md) (per-participant suspend), [remote cart manifests](remote-cart-manifest.md) (`HostGrantSet` transfer), [snapshots](snapshots.md). Back to the [package README](../README.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-75-portal-lifecycle.repro.spec.ts
+```
+
+## When to use
+
+| Surface | Import | Use |
+|---|---|---|
+| Production host | `createPortalLifecycle`, `cabinetPortal`, `paintingPortal` from `@cyberart-io/engine` | Chrome / back-stack / a11y stay on the host. Carts declare portal targets and outcome schema versions. |
+| Vitest / jsdom | same, or from `@cyberart-io/engine/headless` | Pair with `createRuntimeGroup` after `installHeadlessCanvas()`. |
+
+`cabinetPortal` / `paintingPortal` only stamp `metaphor`. They call the same `enter` / `exit` / `abort`.
+
+## Contract
+
+1. **Enter** another cart (exclusive presentation).
+2. Pass seed/clock/state/persistence and transfer exclusive grants (`audio`, `controller`, `fullscreen`) for the child's lifetime.
+3. **Suspend** the parent: group `step` skips it; cart state stays snapshot-safe.
+4. **Exit** with `{ schemaVersion: 1, kind: 'completed' | 'aborted', payload? }`.
+5. Nested enter is stack-ordered. Aborting the top frame does not rewrite ancestor `parentState`.
+6. Restore validates JSON and participant ids before mutate. A mid-portal snapshot restores parent-suspended + child-active, reapplies extra child grants, and transfers audio broker authorization the same way enter does. Tampered or unknown-id JSON returns `{ ok: false }` and leaves suspend flags and broker grants unchanged.
+
+```ts
+import {
+  cabinetPortal,
+  createPortalLifecycle,
+  paintingPortal,
+} from '@cyberart-io/engine';
+
+const portal = createPortalLifecycle({
+  group,
+  grants: { lobby: lobbyGrants, game: gameGrants },
+  rootId: 'lobby',
+  declarations: [{ id: 'lobby', targets: ['game'] }],
+});
+
+cabinetPortal(portal).enter({ from: 'lobby', to: 'game', seed });
+const outcome = portal.exit({ score: 108 });
+paintingPortal(portal).enter({ from: 'lobby', to: 'gallery' });
+```
+
+Host-owned chrome reads `portal.stack()` and `portal.activeId()`. Persist `portal.snapshot()` inside envelope `hostState`.

package/docs/presentation-bindings.md

@@ -0,0 +1,93 @@
+# Presentation bindings
+
+Declarative, versioned mapping from a host-supplied state projection onto presentation resources (visual versions, presence, props, semantic regions, hotspots, sequences, assets). The host reducer stays authoritative. Cyberart evaluates a bounded manifest and applies **one complete presentation revision** — or the declared fail-closed defaults. Never a mixed scene.
+
+Related: [Visual layers](visual-layers.md), [Semantic layers](semantic-layers.md), [Presentation sequences](presentation-sequences.md), [Events](events.md), [Snapshots](snapshots.md). Back to the [package README](../README.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-83-presentation-bindings.repro.spec.ts
+```
+
+## When to use
+
+| Surface | Import | Use |
+|---|---|---|
+| Production host | `definePresentationBindings` / `createPresentationBindingRuntime` from `@cyberart-io/engine` | Pass a JSON projection into `apply`. Persist `snapshot()` in envelope `hostState`. |
+| Vitest / jsdom | same, or `@cyberart-io/engine/headless` | Headless and browser entrypoints evaluate the same winners. |
+
+The framework does not own inventory, doors, or character location. Hosts define typed projections (CYB-59). Generic fixture ids only: `room`, `overlay`, `whistle`, `door`, `npc`, `lobby`, `hotspot-whistle`, `hotspot-door`, `line-enter`.
+
+## Contract
+
+1. **Manifest.** `schemaVersion` `1`, stable binding ids, JSON only. Callbacks and `eval` are rejected at define time.
+2. **Predicates.** Constrained expressions over dotted paths (`eq` / `neq` / `present`) or registered typed selectors. No ambient store access.
+3. **Targets.** Visual-layer versions, presence, props, semantic regions, hotspot enablement, sequences, asset bindings.
+4. **Conflicts.** Higher priority wins. Equal priority on the same target is a define-time error. Defaults must cover every target key bindings can select.
+5. **Atomic apply.** Evaluate the full target set, preflight live resources, then apply. `visual.play` / `sequences.playSequence` results are honored: `{ ok: false, reason: 'duplicate' }` is ignored (`onDuplicate: 'ignore'`); other failures abort as `unknown-resource`. On apply failure, controller snapshots are restored and `liveTargets` is not committed. Invalid/missing projections apply the **complete** default set. Restore applies targets before writing revision / selectedBindingIds / override; a failed apply leaves those fields and live presentation unchanged.
+6. **Change minimization.** Unchanged targets are not replayed or remounted. An already-selected matching sequence is not restarted when unrelated projection fields change.
+7. **Overrides.** `setOverride` can change a11y labels / reduced-sensory presentation without mutating the projection or selected binding ids.
+8. **Snapshot.** Records projection revision + selected binding ids + resolved targets. Restore validates schema before mutate.
+
+```ts
+import {
+  createPresentationBindingRuntime,
+  definePresentationBindings,
+} from '@cyberart-io/engine';
+
+const defined = definePresentationBindings({
+  id: 'lobby-room',
+  schemaVersion: 1,
+  bindings: [
+    {
+      id: 'night-room',
+      priority: 30,
+      when: { path: 'timeOfDay', eq: 'night' },
+      targets: [{ kind: 'visual-layer', layerId: 'room', version: 'night' }],
+    },
+  ],
+  defaults: [{ kind: 'visual-layer', layerId: 'room', version: 'day' }],
+});
+if (!defined.ok) throw new Error(defined.errors.map((e) => e.detail).join('; '));
+
+const runtime = createPresentationBindingRuntime({
+  manifest: defined.manifest,
+  visual,
+  semantic,
+  sequences,
+});
+
+runtime.apply(
+  { timeOfDay: 'night', inventory: { loonWhistle: false } },
+  { revision: 83 },
+);
+runtime.inspect();  // winners + explanation
+runtime.snapshot(); // revision + selectedBindingIds for hostState
+```
+
+`createPresentationBindingRuntime` re-validates the manifest and throws if it is invalid.
+
+## Predicates
+
+| Form | Match |
+|---|---|
+| `{ path: "inventory.loonWhistle", eq: false }` | dotted path equals a JSON primitive |
+| `{ path: "door.roomSeven", neq: "locked" }` | path exists and is not the value, or is missing |
+| `{ path: "timeOfDay", present: true }` | path exists and is not `null` |
+| `{ selector: "isNight" }` | host-registered own-property `(projection) => boolean`. Inherited keys such as `constructor` do not match. |
+| `{ all: [...] }` / `{ any: [...] }` / `{ not: ... }` | boolean combinations |
+
+Unknown fields on the manifest, bindings, predicates, or targets fail closed at define time.
+
+## Apply, explanation, restore
+
+`apply(projection, { revision })` returns `selectedBindingIds`, `explanation` (considered / winners / rejected alternatives / fallback reason), and `inspect()`. Visual swaps use `visual.play` with `durationFrames: 0` so one accepted revision is one coherent layer set. Play results are checked: duplicate-ignore is ok, unknown version / invalid / busy abort and roll the visual / semantic / sequence controllers back. Semantic presence/focus is `setRegionState`. `hitTestEnabled` (and hotspot `enabled` when a `regionId` is set) writes the region's hit-test policy through `semantic.restore`: `false` becomes `pass-through`, `true` restores the region's prior absorbing policy. Sequences use `playSequence` / `skip`. `restore` calls `applyTargets` before committing revision, selected binding ids, or override. `setOverride({ reducedSensory: true })` skips an active bound sequence; clearing the override and reapplying the same projection starts it again.
+
+| Event | When |
+|---|---|
+| `presentation.binding.state.applied` | One complete presentation revision committed |
+| `presentation.binding.state.rejected` | Preflight or apply failed; live presentation unchanged |
+| `presentation.binding.diagnostic.lifecycle` | Machine-readable rejection detail |
+
+Contracts: `presentationBindingEventContracts()`.

package/docs/presentation-sequences.md

@@ -0,0 +1,150 @@
+# Presentation sequences
+
+One frame-stepped clock for a semantic beat that spans audio, captions/text, semantic-region state, visual layers, and typed cues. Hosts pass content through bindings. The engine does not own dialogue graphs, relationship state, inventory, or game rules.
+
+Related: [presentation cue](presentation-cue.md), [audio](audio.md), [semantic layers](semantic-layers.md), [visual layers](visual-layers.md), [events](events.md). Back to the [package README](../README.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-78-presentation-sequence.repro.spec.ts
+```
+
+## When to use
+
+| Surface | Import | Use |
+|---|---|---|
+| Production host | `definePresentationSequence` / `createPresentationSequencePlayer` from `@cyberart-io/engine` | Author JSON sequences; `playSequence` with bindings. |
+| Vitest / jsdom | same, plus `createHeadlessAudioAdapter` from `@cyberart-io/engine/headless` | Silent cue traces; `inspectCueIntent` without audible playback. |
+
+Generic ids only: `speaker`, `caption`, `room-bg`, `line-1`. Drive `step` from the same clock as deterministic `cart.step`. There are no `setTimeout` / rAF timers.
+
+## `definePresentationSequence({ id, tracks, interruptionPolicy, fallbacks })`
+
+Authored content must be JSON-serializable. Callbacks and ambient host access are rejected at define time.
+
+```ts
+import {
+  definePresentationSequence,
+  createPresentationSequencePlayer,
+} from '@cyberart-io/engine';
+
+const defined = definePresentationSequence({
+  id: 'spoken-line',
+  interruptionPolicy: 'replace', // 'replace' | 'queue' | 'reject' | 'ignore'
+  tracks: [
+    {
+      id: 'beat',
+      kind: 'cue',
+      steps: [
+        {
+          id: 'line-1',
+          timing: { kind: 'absolute', atFrame: 0 },
+          durationFrames: 6,
+          effect: { kind: 'cue', name: 'line-1' },
+        },
+      ],
+    },
+    {
+      id: 'audio',
+      kind: 'audio',
+      steps: [
+        {
+          id: 'line-1-audio',
+          timing: { kind: 'simultaneous', withStepId: 'line-1', order: 0 },
+          durationFrames: 6,
+          effect: { kind: 'audio', assetBinding: 'line' },
+        },
+      ],
+    },
+  ],
+  fallbacks: [
+    {
+      id: 'text-only',
+      when: { capability: 'audio', status: 'failed' },
+      omitTrackIds: ['audio'],
+    },
+  ],
+});
+```
+
+Step timing: `absolute` (`atFrame`), `relative` (`afterStepId`, `delayFrames`), or `simultaneous` (`withStepId`, `order`). Completion is `duration` (default) or `immediate`. Simultaneous steps at one frame run in `order`, then `trackId`, then `stepId`. On each `step`, due completions run before new activations so a `relative` follow-up with `delayFrames: 0` does not clobber the finishing step's restore.
+
+## `playSequence(sequenceId, { invocationId, bindings })`
+
+```ts
+const player = createPresentationSequencePlayer({
+  originFrame: 0,
+  audio: headlessAudio, // or createAudioCueTimeline
+  semantic,
+  visual,
+  sequences: [defined.sequence],
+});
+
+player.playSequence('spoken-line', {
+  invocationId: 'inv-1',
+  idempotencyKey: 'inv-1',
+  bindings: {
+    assets: { line: 'line-1' },
+    captions: { line: 'spoken line' },
+    regions: { speaker: 'speaker' },
+    layers: { room: 'room-bg' },
+    versions: { room: 'v1' },
+  },
+});
+player.step(6);
+```
+
+The player steps bound audio and visual controllers with the same delta so one sequence owns the clock. Caption visibility lives on the player. Semantic focus is `setRegionState`. Visual dim/restore is `visual.play({ kind: 'hide' | 'show' })`. Cue tracks use `createPresentationTimeline`.
+
+## Policies
+
+| Policy | Behavior |
+|---|---|
+| `skip()` | Restores caption / audio / focus / visual under one policy, emits `skipped`. A second skip is a no-op. The next `playSequence` is available exactly once. |
+| `replay()` | Restarts the last invocation from playhead 0. |
+| `pause()` / `resume()` | Freeze or continue the shared clock. `step` is ignored while paused. |
+| `replace` (default interruption) | Incoming play interrupts the active invocation (`interrupted`) and starts the new one. |
+| `queue` | Incoming play waits until the active invocation completes, skips, or cancels. |
+| `reject` | Incoming play returns `{ ok: false, reason: 'busy' }`. |
+| `ignore` | Incoming play keeps the active invocation. |
+| `cancel()` | Aborts as `interrupted` without semantic completion. |
+| Same `idempotencyKey` | Idempotent: no second `started`. |
+
+## Fallbacks and reduced sensory
+
+Readiness is probed before `started`. Failed / unavailable / unauthorized / muted audio selects the matching authored fallback (typically `omitTrackIds: ['audio']`) instead of throwing and leaving mixed channels. Semantic steps still complete.
+
+`reducedMotion: true` shortens step duration (`skip` / `complete` → 0, or `{ durationFrames: n }`). `reducedSensory: true` omits audio tracks. Caption, focus, and completion still run.
+
+## Snapshot / mid-line restore
+
+`schemaVersion` is `PRESENTATION_SEQUENCE_SNAPSHOT_SCHEMA_VERSION` (`1`). Restore **fails closed** on unknown version or unknown sequence id and leaves live state unchanged. Unknown queued ids are rejected in that pre-mutation check, before live adapters are released. After mutation, unknown queue rows are skipped rather than failed: `fail()` restores JS backup but does not re-apply adapter effects.
+
+Mid-line policy:
+
+1. Restore the playhead (`frame`, `startedAtFrame`, completed and active step ids, selected fallback, bindings).
+2. Re-apply currently active step effects (caption visibility, speaker focus, visual hide/show, remaining audio/cue duration).
+3. Do not re-run completed steps.
+4. A **skipped** invocation restores as skipped: remaining duration is not played, channels stay released.
+5. Hosts should pass fresh or already-restored audio / semantic / visual adapters; this module does not seek those clocks backward.
+
+## Lifecycle events (CYB-59 contracts)
+
+`presentationSequenceEventContracts()` registers:
+
+| `type` | When |
+|---|---|
+| `presentation.sequence.state.requested` | `playSequence` accepted |
+| `presentation.sequence.state.preloading` | Capability probe |
+| `presentation.sequence.state.ready` | Fallback selected if needed |
+| `presentation.sequence.state.started` | First steps may apply |
+| `presentation.sequence.state.step-started` | Step becomes active |
+| `presentation.sequence.state.step-completed` | Duration elapsed |
+| `presentation.sequence.state.skipped` | `skip()` |
+| `presentation.sequence.state.interrupted` | replace / cancel |
+| `presentation.sequence.state.failed` | Unrecoverable (reserved) |
+| `presentation.sequence.state.completed` | All steps terminal |
+| `presentation.sequence.diagnostic.lifecycle` | Diagnostics |
+
+`inspectCueIntent(sequenceId, { fallbackId })` returns the planned steps without calling the audio adapter.