@cyberart-io/engine 0.0.9 → 0.0.10

package/docs/audio.md

@@ -8,6 +8,7 @@ Back to the [package README](../README.md). Related: [presentation cue](presenta
 
 ```bash
 pnpm exec vitest run packages/engine/src/canvas/cyb-67-audio.repro.spec.ts
+pnpm exec vitest run packages/engine/src/canvas/cyb-102-audio-sidecar-restore.repro.spec.ts
 ```
 
 ## Why this exists
@@ -136,6 +137,29 @@ adapter.destroy();
 
 Replay two runs with the same seed/tape and compare `events`. Do not compare speakers, meters, or decoded PCM — those are not deterministic across machines or browsers.
 
+## Snapshot schema (version 1)
+
+`AudioCueTimeline.snapshot()` / `createHeadlessAudioAdapter().snapshot()` write a versioned sidecar. `schemaVersion` is `1` (`AUDIO_CUE_SNAPSHOT_SCHEMA_VERSION`). Restore validates the **entire** payload before mutation. Unknown schema, unknown cue idempotency keys, or malformed JSON return `{ ok: false, errors }` and leave live state unchanged.
+
+```ts
+const snap = adapter.snapshot();
+adapter.play({ /* another cue */ });
+const restored = adapter.restore(JSON.parse(JSON.stringify(snap)));
+if (!restored.ok) throw new Error(restored.errors.map((e) => e.detail).join('; '));
+```
+
+| Field | Meaning |
+|---|---|
+| `schemaVersion` | `1`. Any other value fails closed. |
+| `frame` | Presentation clock at save. |
+| `reducedSensory` | Skip-playback flag. Restored onto the timeline. |
+| `cues` | Live cue views (`scheduled` / `started` / `skipped`; completed and failed rows are event-log only). |
+| `events` | Deterministic cue event log. |
+| `muted` | Headless adapter only. Restored via `broker.mute()` / `unmute()`. |
+| `unlock` | Headless adapter only. **Observation.** Unlock cannot be faithfully restored (it is async and may require a user gesture). Restore applies cue / mute / event log only; `snapshot().unlock` after reload is the live broker status. |
+
+`parseAudioCueSnapshot(input)` is the shared validator. Browser (`@cyberart-io/engine`) and headless (`@cyberart-io/engine/headless`) share the same semantic contract.
+
 ## Host wiring
 
 ```ts

package/docs/browser-harness.md

@@ -76,7 +76,7 @@ The host owns overlay markup, reducer state, and event type names. The harness o
 | `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. |
+| `geometry` | none | Optional geometry document for `placeRegion` / CSS hit-testing. Replace later with `setGeometry`. |
 | `contentWidth` / `contentHeight` / `fit` | viewport / `contain` | Intrinsic box for `createPresentationLayout`. |
 | `mount` | none | Host builds DOM and returns carts / compositor / cleanup. |
 
@@ -86,6 +86,7 @@ The host owns overlay markup, reducer state, and event type names. The harness o
 |---|---|
 | `goto()` | No-op ready check (fixture is already mounted). |
 | `setViewport(width, height, dpr?)` | Resize root, group canvases, compositor; call host `relayout`. |
+| `setGeometry(document?)` | Replace the geometry document used by `placeRegion` and CSS hit-testing; call host `relayout`. Pointer hit-tests only regions in the active document (semantic hits whose ids are not in that document are ignored). |
 | `click(selector)` / `click(x, y)` | Dispatch `pointerdown` / `pointerup` / `click` on DOM. |
 | `key` / `focus` | Keyboard through the focused element. |
 | `step` / `advance` | Deterministic group clock. |

package/docs/production-scenario.md

@@ -8,6 +8,10 @@ Related: [Browser harness](browser-harness.md), [Compositor](compositor.md), [Vi
 
 ```bash
 pnpm exec vitest run packages/engine/src/canvas/cyb-82-production-scenario.repro.spec.ts
+pnpm exec vitest run packages/engine/src/canvas/cyb-101-host-audio-observation.repro.spec.ts
+pnpm exec vitest run packages/engine/src/canvas/cyb-102-audio-sidecar-restore.repro.spec.ts
+pnpm exec vitest run packages/engine/src/canvas/cyb-103-reduced-motion-propagate.repro.spec.ts
+pnpm exec vitest run packages/engine/src/canvas/cyb-104-dynamic-host-geometry.repro.spec.ts
 ```
 
 ## When to use
@@ -17,7 +21,7 @@ pnpm exec vitest run packages/engine/src/canvas/cyb-82-production-scenario.repro
 | 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.
+This module composes existing harnesses. It does not reimplement Canvas2D, routing, or playback. Sequence audio is the headless adapter: invocation and provenance only, never physical speakers. Hosts that already own a production audio controller pass it as `hostAudio` instead of duplicating the beat as a presentation sequence.
 
 Generic fixture ids only: `whistle`, `ripple`, `room`, `npc`.
 
@@ -25,11 +29,11 @@ Generic fixture ids only: `whistle`, `ripple`, `room`, `npc`.
 
 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.
+3. **Input.** Pointer and keyboard go through the browser harness (DOM coordinates and a11y ids), then the host reducer, then the group router. After an accepted reduce, and on reload, the runner syncs the active input surface from `host.projectInputSurface(state)` when provided: visible/focusable controls and the `GeometryDocument` update atomically. Controls the projection omits are removed from the DOM (not clickable, focusable, or hit-testable). Construction-time `geometry` / region ids remain the fallback when the host does not project. Missing, overlapping/duplicate, or stale geometry (a control with no matching region) fails closed at boundary `input` with `invalid-geometry`, `ambiguous-geometry`, or `stale-geometry`. Evidence records `observation.activeControlIds`. The seam is host-generic: it does not encode product room names.
+4. **Observation.** Evidence records reducer accept/reject, routed envelopes, selected bindings, cue sequences, composed pixels, captions, audio invocation, focus, and cleanup. Caption and audio evidence come from the presentation-sequence player **or** an optional host-owned audio observer (`hostAudio` on runner options)—not only from a test sequence.
+5. **Save / reload / replay.** `save()` writes a snapshot envelope. `hostState.audio` is the versioned headless-adapter sidecar (`schemaVersion` `1`; see [Audio](audio.md)). `reload` restores host, then visual / semantic / bindings / sequences, then **audio last** so a sequence reapply cannot double-invoke cues. `applyPresentation()` is not run on reload. The runner does call `syncInputSurface()` so restored `hostState` rebuilds the active controls and geometry without playing sequences. Unlock status is observation-only and is not restored. Tampered or unknown audio sidecars fail closed: live audio (and the rest of the composition) stay unchanged, `observation.audioRestoreOk` is `false`, and `firstBrokenBoundary` is `audio` with code `invalid-audio-sidecar`. Omitting `hostState.audio` declares audio non-restorable (`audioRestoreOk` false, no localization). `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. Construction-time `matrix.reducedMotion` still seeds browser, visual, sequence, and audio policy.
+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. `traces.audio` is the sequence/headless adapter cue log. `traces.hostAudio` is host-owned observer evidence (invocation, completion, failure, skip, fallback, captions, envelope identity). `observation.audioInvoked` / `audioFailed` / `captions` merge both sources. `observation.audioRestoreOk` reports whether reload restored the audio sidecar. `observation.activeControlIds` is the projected input surface. A runtime `reducedMotion` step records `observation.reducedMotion` and `observation.reducedMotionPropagation` (from/to, per-participant applied/reason, active sequence policy). 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
@@ -79,3 +83,85 @@ runner.destroy();
 | `production.scenario.diagnostic.lifecycle` | Machine-readable rejection detail (`code`, `boundary`); emitted alongside every `state.failed` |
 
 Contracts: `productionScenarioEventContracts()`.
+
+## Host-owned audio observation
+
+A production host may already own an audio/presentation controller outside Cyberart sequences. Pass that controller (or a thin snapshot wrapper) as `hostAudio` on `createProductionScenarioRunner`. The runner does not construct a second sequence for the same beat and does not play speakers.
+
+The adapter is generic. It reports `invoked` / `completed` / `failed` / `skipped` / `fallback` plus optional caption text and envelope identity (`id`, `correlationId`, `causationId`). It must not encode product-specific dialogue fields.
+
+```ts
+const hostAudio = {
+  snapshot() {
+    return {
+      events: [
+        {
+          kind: 'invoked',
+          name: 'whistle',
+          caption: 'whistle taken',
+          id: 'env-whistle',
+          correlationId: 'corr-101',
+          causationId: 'cause-click',
+        },
+        { kind: 'completed', name: 'whistle', id: 'env-whistle', correlationId: 'corr-101' },
+      ],
+    };
+  },
+};
+
+const runner = createProductionScenarioRunner({
+  scenario: defined.scenario,
+  participants,
+  compositorLayers,
+  geometry,
+  host, // reduce() invokes the host controller; it does not set playSequence
+  hostAudio,
+});
+```
+
+- Omit `hostAudio` when the host has no controller. Sequence/headless `traces.audio` still works.
+- Supplying a non-object, an object without `snapshot()` or `collect()`, or an adapter whose `inspect` / `snapshot` / `collect` throws fails closed: `firstBrokenBoundary` is `audio`, code `invalid-host-audio`.
+- Browser and headless use the same scenario object and the same observer. Evidence is semantic (invocation, captions, identity), not PCM.
+- `observation.audioInvoked` follows host `invoked` / `completed` (the analogue of sequence `audio.cue.scheduled` / `audio.cue.started`). `failed`, `skipped`, and `fallback` stay in `traces.hostAudio` and can set `audioFailed` or captions; they do not count as invoked.
+
+## Dynamic input surface
+
+Hosts that change visible hotspots after a reducer transition implement `host.projectInputSurface(state)`. The runner rebuilds the control set and geometry document after every accepted (or rejected) reduce and on reload.
+
+```ts
+const host = {
+  initialState: { place: 'a' },
+  reduce(state, intent) {
+    const id = (intent.payload as { id?: string } | undefined)?.id;
+    if (intent.type === 'host.intent.select' && id === 'whistle' && state.place === 'a') {
+      return { accepted: true, state: { ...state, place: 'b' } };
+    }
+    return { accepted: true, state };
+  },
+  projectInputSurface(state) {
+    const place = state.place === 'b' ? 'b' : 'a';
+    const geometry =
+      place === 'a'
+        ? { version: 1, landmarks: [], regions: [{ id: 'whistle', rect: { x: 0.1, y: 0.1, width: 0.3, height: 0.3 } }] }
+        : { version: 1, landmarks: [], regions: [{ id: 'npc', rect: { x: 0.55, y: 0.55, width: 0.3, height: 0.3 } }] };
+    return { controls: geometry.regions.map((row) => ({ id: row.id })), geometry };
+  },
+};
+```
+
+- Place `a` exposes `#whistle`. After the accepted transition, place `b` exposes `#npc` and whistle is gone.
+- `inspect().inputSurface` and `observation.activeControlIds` are the active semantic targets. Browser and headless share the scenario object.
+- Reload calls `syncInputSurface()` only. It does not call `applyPresentation()`, so sequences are not replayed.
+- Invalid documents, overlapping/duplicate ids, or a control without a matching region fail closed at boundary `input`.
+
+## Runtime reduced motion
+
+A `reducedMotion` step (or `runner.setReducedMotion(value)`) is one host-generic fan-out. It does not encode product names.
+
+1. **Browser / a11y.** `BrowserHarness.setReducedMotion` (already present). `matchMedia('(prefers-reduced-motion: reduce)')` and `root.dataset.reducedMotion` match the new value.
+2. **Visual.** `visual.setReducedMotion`. In-flight transitions keep compiled durations; future `play()` uses the new flag.
+3. **Sequence.** `sequences.setReducedMotion`. **Active invocation policy is `continue`:** the current play keeps the durations it was compiled with. Queued plays that have not started, and every later `playSequence`, compile with the new policy. `inspectCueIntent` reports the future policy immediately.
+4. **Audio.** `audio.setReducedSensory(value || muted)`. Already-started cues continue; later starts skip with reason `reduced-sensory` when the flag is on. Matches construction-time `matrix.reducedMotion || matrix.mute`.
+5. **Semantic.** No reduced-motion policy. Evidence records a declared no-op (`applied: false`, `reason: 'no-reduced-motion-policy'`). A missing visual/sequence controller is the same shape (`participant-not-mounted`). A mounted controller without `setReducedMotion` / `setReducedSensory` fails closed at boundary `cue`, code `unsupported-preference`.
+
+Evidence: `observation.reducedMotion` is the current preference. After a runtime change, `observation.reducedMotionPropagation` records `{ from, to, activeSequencePolicy: 'continue', participants }`. Browser and headless fixtures assert that object, plus inspect getters (`sequences.reducedMotion`, `audio.reducedSensory`, harness reproduction). Construction-time `matrix.reducedMotion` is unchanged.

package/package.json

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