@cyberart-io/engine 0.0.8 → 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/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).
 

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.

package/docs/production-scenario.md

@@ -0,0 +1,81 @@
+# Production scenario
+
+End-to-end production composition harness. One scenario definition mounts the real host adapter, reducer, runtime group, production carts, DOM layers, compositor, visual/semantic layers, bindings, sequences, asset path, and headless audio. Isolated effect tests are not a substitute: omitting a required cart or compositor layer fails closed.
+
+Related: [Browser harness](browser-harness.md), [Compositor](compositor.md), [Visual layers](visual-layers.md), [Semantic layers](semantic-layers.md), [Presentation sequences](presentation-sequences.md), [Presentation bindings](presentation-bindings.md), [Audio](audio.md), [Replay inspector](replay-inspector.md), [Snapshots](snapshots.md), [Runtime group](runtime-group.md), [Asset resolver](asset-resolver.md). Back to the [package README](../README.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-82-production-scenario.repro.spec.ts
+```
+
+## When to use
+
+| Surface | Import | Use |
+|---|---|---|
+| Production host | `defineProductionScenario` / `createProductionScenarioRunner` from `@cyberart-io/engine` | Prove the shipped composition, not a second runtime. Persist `save()` envelopes in hostState. |
+| Vitest / jsdom | same, or `@cyberart-io/engine/headless` | `installHeadlessCanvas()` first. CI and local must pass the **same** scenario definition object. |
+
+This module composes existing harnesses. It does not reimplement Canvas2D, routing, or playback. Audio is the headless adapter: invocation and provenance only, never physical speakers.
+
+Generic fixture ids only: `whistle`, `ripple`, `room`, `npc`.
+
+## Contract
+
+1. **Definition.** `schemaVersion` `1`, stable `id`, `seed`, `required.participants`, `required.layers`. JSON only. Callbacks and incomplete steps (a `click` without `selector` or `x`/`y`, a `key` without `key`) fail closed at define time. Invalid sequence or binding manifests throw when the runner is created, never silently dropped.
+2. **Required composition.** After mount, every required participant and compositor layer must be present. Omitting the cart under test is a failure, not a skipped assertion. Missing participant localizes to `routing`; missing layer localizes to `pixels`.
+3. **Input.** Pointer and keyboard go through the browser harness (DOM coordinates and a11y ids), then the host reducer, then the group router.
+4. **Observation.** Evidence records reducer accept/reject, routed envelopes, selected bindings, cue sequences, composed pixels, captions, audio invocation, focus, and cleanup.
+5. **Save / reload / replay.** `save()` writes a snapshot envelope. `reload` restores host + presentation sidecars. `replay` re-runs the inspector tape on a fresh composition and compares traces.
+6. **Matrix.** Desktop/mobile viewport, DPR, reduced-motion, mute, failed-asset ids, and audio fallback are fields on the same definition. Not every cell needs a unique golden.
+7. **Evidence bundle.** `ProductionScenarioEvidenceBundle` carries pixel/semantic/a11y/trace/snapshot/asset hashes, revisions, traces, screenshot metadata, and `firstBrokenBoundary` localization: input → reducer → routing → binding → cue → pixels/caption/audio → save-replay. The optional `selectionTrace` field holds a [selection trace](selection-trace.md) export (`attachSelectionTrace(bundle, exported)`); the runner never populates it itself.
+8. **CI = local.** `run(steps)` executes the definition’s steps (or a shared step list). Do not fork scenario JSON for CI.
+
+```ts
+import {
+  createProductionScenarioRunner,
+  defineProductionScenario,
+} from '@cyberart-io/engine';
+import { installHeadlessCanvas } from '@cyberart-io/engine/headless';
+
+installHeadlessCanvas();
+
+const defined = defineProductionScenario({
+  id: 'room-whistle',
+  schemaVersion: 1,
+  seed: `0x${'82'.repeat(32)}`,
+  required: { participants: ['room', 'ripple'], layers: ['room', 'ripple'] },
+  matrix: { viewport: 'desktop', dpr: 1 },
+  steps: [
+    { type: 'click', selector: '#whistle' },
+    { type: 'step', frames: 2 },
+    { type: 'save' },
+    { type: 'replay' },
+  ],
+});
+if (!defined.ok) throw new Error(defined.errors.map((e) => e.detail).join('; '));
+
+const runner = createProductionScenarioRunner({
+  scenario: defined.scenario,
+  participants,
+  compositorLayers,
+  visualLayers,
+  semanticRegions,
+  sequences,
+  bindings,
+  geometry,
+  host,
+});
+
+const evidence = await runner.run();
+runner.destroy();
+```
+
+| Event | When |
+|---|---|
+| `production.scenario.state.observed` | Evidence captured with no broken boundary |
+| `production.scenario.state.failed` | Required composition missing, or an expectation failed |
+| `production.scenario.diagnostic.lifecycle` | Machine-readable rejection detail (`code`, `boundary`); emitted alongside every `state.failed` |
+
+Contracts: `productionScenarioEventContracts()`.

package/docs/remote-cart-manifest.md

@@ -0,0 +1,66 @@
+# Remote cart manifests
+
+Signed, versioned cart catalogs for third-party worlds. HMAC signatures, declared asset hashes, and deny-by-default host grants. Isolation is in-process (trusted factories), not `eval` / `Function`.
+
+Related: [capability manifest](capability-manifest.md) (optional nested `capabilities` + `grants`), [asset resolver](asset-resolver.md) (`createDeclaredAssetResolver`), [executable modules](executable-modules.md), [snapshots](snapshots.md) (`provenance`). Built on this: [content revision](content-revision.md) (`createRemoteContentAdapter` verifies the same signed JSON), [portal lifecycle](portal-lifecycle.md) (`HostGrantSet` transfer to the child cart). Back to the [package README](../README.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-74-remote-cart-manifest.repro.spec.ts
+```
+
+## Load path
+
+1. Parse a signed JSON envelope `{ body, signature }`.
+2. Verify `hmac-sha256` over the canonical body (sorted keys) with a host key id.
+3. Check `cartVersion` when the host asked for an exact version.
+4. List `requestedGrants` (`audio`, `controller`, `network`, `persistence`, `fullscreen`).
+5. Host applies a subset via `createHostGrantSet` (inspectable, revocable, restore fail-closed).
+6. `createDeclaredAssetResolver` may fetch **only** declared URLs; hash mismatch or missing bytes refuse load.
+7. Capability bag APIs throw `RemoteCartCapabilityError` (`capability-denied`) when ungranted. Granted `network.fetch` still cannot reach undeclared URLs, and returns a copy of signed bytes.
+8. `createRemoteCartSandbox` takes the same `keys` map and re-verifies HMAC on `loadAssets`. Nested `capabilities.grants` are checked against the **host** grant set, not the cart's own list.
+
+Tests inject a registry map or `fetch` adapter. There is no ambient network.
+
+```ts
+import {
+  createRemoteCartRegistry,
+  createRemoteCartSandbox,
+  loadRemoteCart,
+  signRemoteCartManifest,
+} from '@cyberart-io/engine';
+
+const signed = await signRemoteCartManifest(body, secret, 'cyb-74-test');
+if (!signed.ok) throw new Error(signed.errors.map((e) => e.detail).join('; '));
+
+const loaded = await loadRemoteCart({
+  source: { kind: 'registry', id: 'cyb-74.remote' },
+  keys: { 'cyb-74-test': secret },
+  registry: createRemoteCartRegistry({ 'cyb-74.remote': signed.manifest }),
+  expectedVersion: '1.0.0',
+});
+if (!loaded.ok) throw new Error(loaded.errors.map((e) => e.detail).join('; '));
+
+const sandbox = createRemoteCartSandbox({
+  manifest: loaded.manifest,
+  keys: { 'cyb-74-test': secret },
+  grants: ['audio'],
+  bytesByUrl: { 'https://registry.test/cyb-74/sprite.bin': bytes },
+});
+sandbox.listRequestedGrants(); // before run
+await sandbox.loadAssets(); // re-verifies HMAC; forged envelopes refuse here
+sandbox.inspect(); // publisher, version, signature id/alg, grant set
+```
+
+`snapshotProvenance()` fills envelope `provenance` (`publisher`, `version`, `signature`, `grants`) for `defineSnapshot`.
+
+| Diagnostic `code` | When |
+|---|---|
+| `invalid-json` / `invalid-manifest` | Envelope is not parseable JSON or the wrong shape. |
+| `invalid-version` | Body version or expected `cartVersion` mismatch. |
+| `invalid-signature` / `unknown-key` | HMAC missing, wrong, or key id unknown. |
+| `undeclared-asset` | Resolver or granted `network.fetch` used a URL not on the manifest. |
+| `hash-mismatch` / `unsigned-bytes` | Declared hash does not match bytes, or bytes/hash missing. |
+| `capability-denied` | Cart called an API the host did not grant. |
+| `destroyed` | Sandbox was torn down. |

package/docs/replay-inspector.md

@@ -2,7 +2,7 @@
 
 Embeddable debug API for multi-cart routing. It records router decisions, builds a causation tree, redacts configured payload keys, bounds retention, and exports a JSON tape that the headless harness can replay. There is no Player UI.
 
-Related: [events](events.md), [runtime group](runtime-group.md), [headless harness](headless-harness.md), [deterministic mode](deterministic-mode.md).
+Related: [events](events.md), [runtime group](runtime-group.md), [headless harness](headless-harness.md), [deterministic mode](deterministic-mode.md). Built on this: [selection trace](selection-trace.md) (reuses correlation ids, `DEFAULT_SENSITIVE_KEYS` / `REDACTED_VALUE`), [production scenario](production-scenario.md) (inspector records in the evidence bundle), [job orchestration](job-orchestration.md) and [world patch](world-patch.md) (redacted trace export).
 
 Back to the [package README](../README.md).
 

package/docs/runtime-group.md

@@ -4,7 +4,7 @@ Host helper that mounts several production `createRuntime` carts, attaches each
 
 Capability-manifest integration is optional and structural (`capability?: { emit, subscribe, authoritative }`). This module does not import the manifest.
 
-Related: [events](events.md), [headless harness](headless-harness.md), [deterministic mode](deterministic-mode.md), [compositor](compositor.md), [replay inspector](replay-inspector.md), [calculation carts](calculation-carts.md).
+Related: [events](events.md), [headless harness](headless-harness.md), [deterministic mode](deterministic-mode.md), [compositor](compositor.md), [replay inspector](replay-inspector.md), [calculation carts](calculation-carts.md). Built on this: [portal lifecycle](portal-lifecycle.md) (per-participant suspend while a child cart is entered), [production scenario](production-scenario.md) (required participants are checked against this group).
 
 Back to the [package README](../README.md).