@cyberart-io/engine 0.0.3 → 0.0.5

package/docs/normalized-geometry.md

@@ -0,0 +1,88 @@
+# Normalized geometry
+
+Shared 0–1 content-box coordinates, anchors, hit regions, and resize-stable
+contain/cover/crop layouts. Pixel `PresentationRegion` on the presentation
+adapter is unchanged; hosts can adopt this contract later.
+
+Back to the [package README](../README.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-60-normalized-geometry.repro.spec.ts
+```
+
+## Contract (`GEOMETRY_CONTRACT_VERSION = 1`)
+
+| Field | Meaning |
+|---|---|
+| `version` | Always `1`. Other versions fail `validateGeometry`. |
+| `landmarks` | Named anchors (`id` + normalized point + optional origin keyword). |
+| `regions` | Hitboxes: axis-aligned `rect` and/or `polygon` in normalized space. |
+| `padding` | Normalized insets `{ top, right, bottom, left }`. |
+| `safeArea` | Same inset shape; authoring hint, not applied by the layout math. |
+
+Documents are JSON-serializable (`JSON.parse(JSON.stringify(doc))` round-trips). Import from **`@cyberart-io/engine`** (`createPresentationLayout`, `pointerToRegion`, `serializeGeometry`, …).
+
+If a region sets both `rect` and `polygon`, hit-testing uses the polygon and overlay/AABB helpers use the rect. Prefer one shape per region.
+
+## Coordinate spaces
+
+Normalized is **0–1 of the content box** (intrinsic artwork), not the letterboxed viewport.
+
+| Space | Unit | Box |
+|---|---|---|
+| `normalized` | 0–1 | Full content (`contentWidth` × `contentHeight`) |
+| `asset` | px | Same content, intrinsic pixels |
+| `css` / `viewport` | CSS px | Layout (`viewportWidth` × `viewportHeight`) |
+| `canvas` | buffer px | `css * devicePixelRatio` (default dpr `1`) |
+
+`pointerToRegion` defaults to **canvas** space (same as `PointerManager` / harness `click`). Pass `{ space: 'css' }` for layout pixels.
+
+## Layout (`createPresentationLayout`)
+
+```ts
+import { createPresentationLayout } from '@cyberart-io/engine';
+
+const layout = createPresentationLayout({
+  contentWidth: 1920,
+  contentHeight: 1080,
+  viewportWidth: 1280,
+  viewportHeight: 800,
+  mode: 'contain', // or 'cover' | 'crop'
+});
+```
+
+| Mode | Scale | Offsets |
+|---|---|---|
+| `contain` | `min(vw/cw, vh/ch)` | Letterbox ≥ 0 |
+| `cover` | `max(vw/cw, vh/ch)` | Crop ≤ 0 (centered) |
+| `crop` | Same as `cover` | Same as `cover` |
+
+Resize-stable under **contain**: a normalized point stays on the same content location when only the viewport changes. Cover/crop keep the content centered and report `visibleNormalizedRect` for the uncropped slice.
+
+## Round-trip tolerance
+
+| Constant | Value | Use |
+|---|---|---|
+| `ROUND_TRIP_TOLERANCE` | `1e-6` | Max \|Δ\| in normalized units after canvas/css round-trip |
+| `ROUND_TRIP_TOLERANCE_CANVAS_PX` | `0.5` | Max \|Δ\| in canvas pixels after normalized round-trip |
+
+## Helpers
+
+| Export | Role |
+|---|---|
+| `normalizedToCanvas` / `canvasToNormalized` | Content box ↔ drawing buffer |
+| `normalizedToCss` / `cssToNormalized` | Content box ↔ layout pixels |
+| `normalizedToAsset` / `assetToNormalized` | Content box ↔ intrinsic pixels |
+| `pointerToRegion(pointer, layout, doc)` | First matching region (document order) |
+| `regionToViewport(region, layout)` | CSS rect (polygon AABB) |
+| `createLandmarkRegistry()` | `register` / `get` / `list`; duplicate ids → `{ ok: false, error: 'duplicate-id' }` |
+| `validateGeometry(doc)` | Overlap, out-of-bounds, duplicate id, invalid shape; diagnostics include region ids |
+| `drawGeometryDebug(ctx, layout, doc, diagnostics)` | Canvas2D `fillRect` / `strokeRect` / `fillText` when present; always returns recorded calls with region ids |
+
+Origin keywords: `center`, `top-left`, `top-right`, `bottom-left`, `bottom-right`, `top`, `bottom`, `left`, `right`. `pointFromOrigin` yields the matching unit-square point.
+
+## Fixture (CYB-60)
+
+Content **1920×1080**. Hotspot point `(0.25, 0.4)` inside region `hotspot` `{ x: 0.2, y: 0.35, width: 0.1, height: 0.1 }`. Contain viewports **1280×800** and **390×844**.

package/docs/presentation-adapter.md

@@ -1,6 +1,6 @@
 # Presentation adapter
 
-Host-owned render models in, interaction intents out. Cyberart is not authoritative for game rules. Depends on [events](events.md). CI: [headless harness](headless-harness.md).
+Host-owned render models in, interaction intents out. Cyberart is not authoritative for game rules. Depends on [events](events.md). CI: [headless harness](headless-harness.md). Normalized 0–1 regions: [normalized geometry](normalized-geometry.md).
 
 Back to the [package README](../README.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' },
         },
       },
     ],
@@ -64,7 +64,7 @@ const model: PresentationModel = {
 };
 ```
 
-`view` is host-owned. The reference cart hit-tests `regions` and paints `background`. `title` is inspectable state, not drawn. Extra fields (characters, exits, inventory) are ignored — map clickable things onto `regions`. Coordinates are drawing-space pixels, the same space as `PointerManager` and harness `click`. A shared normalized space is a later ticket.
+`view` is host-owned. The reference cart hit-tests `regions` and paints `background`. `title` is inspectable state, not drawn. Extra fields (characters, exits, inventory) are ignored — map clickable things onto `regions`. Coordinates on `PresentationRegion` are drawing-space pixels, the same space as `PointerManager` and harness `click`. Convert 0–1 content-box geometry with `createPresentationLayout` / `pointerToRegion` from [normalized geometry](normalized-geometry.md).
 
 `adapter.model` / `adapter.phase` are what this session last presented (or the boot model). The getter returns a **copy**. After `step`, `inspect().state.model` is what the cart applied.
 
@@ -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,6 +1,6 @@
 # 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), [events](events.md) (routed contracts vs local `cue.*` names).
 

package/docs/replay-inspector.md

@@ -0,0 +1,88 @@
+# Replay inspector
+
+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).
+
+Back to the [package README](../README.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-65-replay-inspector.repro.spec.ts
+```
+
+## When to use
+
+| Surface | Import | Use |
+|---|---|---|
+| Production host | `createReplayInspector` from `@cyberart-io/engine` | Attach to `createEventRouter` or `createRuntimeGroup`. |
+| Vitest / CI | same API, or from `@cyberart-io/engine/headless` | `replayExportedTrace` against `createHeadlessMultiCartHarness`. |
+
+Hosts attach this inspector to a router or runtime group. Event types stay host-defined.
+
+## `createReplayInspector(options?)`
+
+```ts
+import { createReplayInspector } from '@cyberart-io/engine';
+import { createHeadlessMultiCartHarness } from '@cyberart-io/engine/headless';
+
+const group = createHeadlessMultiCartHarness({
+  origin: 0,
+  participants: [
+    { id: 'effects', cart: effectsCart, emit: ['overlay.intent.*'], subscribe: ['host.state.*'] },
+    { id: 'ambience', cart: ambienceCart, subscribe: ['overlay.intent.*'] },
+  ],
+});
+
+const inspector = createReplayInspector({
+  redactedKeys: ['token'],
+  maxRecords: 512,
+});
+const session = inspector.bind(group);
+session.publish({ type: 'host.state.accepted', kind: 'state', payload: { token: 'secret' } });
+await session.step(2);
+const exported = await session.exportTrace();
+inspector.destroy();
+group.destroy();
+```
+
+`host.state.accepted` delivered to `effects` causes `overlay.intent.play` for `ambience`. The inspector tree is that chain plus any later rejects.
+
+### Options (`CreateReplayInspectorOptions`)
+
+| Option | Default | Meaning |
+|---|---|---|
+| `redactedKeys` | `[]` | Object keys replaced with `REDACTED_VALUE` in payloads and cart state summaries. |
+| `maxRecords` | `512` | Oldest records drop; `report().dropped` counts them. |
+| `registry` | none | `ContractRegistry.get` annotates `payloadSchemaVersion`. |
+
+### Bind vs watch
+
+| Method | Meaning |
+|---|---|
+| `watchRouter(router)` | Copy existing `inspectDecisions()`, then subscribe. |
+| `bind(group)` | Watch the group router and record a `publish` / `dispatch` / `step` / asset tape. `publish` extras (`cause`) are stored and replayed. `unbind()` drops the decision subscription. |
+| `importTrace(json)` | Load an export for inspection without replaying. |
+| `exportTrace(filter?)` | JSON: participants, tape, redacted records, snapshots. |
+| `report(filter?)` | Machine-readable CI report: participants, records, trees, dropped. |
+| `causationTree(correlationId?)` | Forest of accepted/rejected nodes. Duplicates are omitted. |
+| `replayExportedTrace(export, group)` | Play the tape on a fresh group; compare with `compareReplayTraces`. |
+
+`dispatch` of `cyberart.asset.ready` / `cyberart.asset.failed` is stored as tape `kind: 'asset'`.
+
+Cart summaries include `emit` / `subscribe` / `authoritative`, clock, redacted state, and `errorCount` / `lastError` (message only).
+
+## Router traces
+
+`createEventRouter` now also exposes:
+
+| Method | Meaning |
+|---|---|
+| `inspectParticipants()` | id, emit, subscribe, authoritative. |
+| `inspectDecisions()` | Bounded decision log (`maxDecisions`, default 256). |
+| `subscribeDecision(listener)` | Live accepted / rejected / duplicate records. |
+
+`RuntimeGroup.inspectParticipants()` adds `kind`. Group `inspect()` includes the same attach fields. `maxTrace` bounds the accepted-event envelope log (default 1024).
+
+Duplicate idempotency hits are `outcome: 'duplicate'` / `reason: 'duplicate'` and do not fan out. Permission failures stay `unauthorized`; missing targets `unknown-target`; spent TTL `hop-limit`.

package/docs/runtime-group.md

@@ -0,0 +1,122 @@
+# Runtime group
+
+Host helper that mounts several production `createRuntime` carts, attaches each mailbox with `router.attach(id, runtime.hostChannel, attachOptions)`, and locksteps one shared deterministic clock. Carts never receive the router. Not a second engine. Do not call the headless wrapper from Player or kaleidoscope.
+
+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).
+
+Back to the [package README](../README.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-61-runtime-group.repro.spec.ts
+```
+
+## When to use which
+
+| Surface | Import | Use |
+|---|---|---|
+| Production host | `createRuntimeGroup` from `@cyberart-io/engine` | Several carts in one page; host injects containers or lets the group create them. |
+| Vitest / jsdom | `createHeadlessMultiCartHarness` from `@cyberart-io/engine/headless` | Same group API after `installHeadlessCanvas()`. |
+
+`createRuntime` still does **not** attach a router by itself. The group is the attach + lockstep layer.
+
+## `createRuntimeGroup(options)`
+
+```ts
+import { createRuntimeGroup } from '@cyberart-io/engine';
+
+const group = createRuntimeGroup({
+  origin: 0,
+  createId: (() => {
+    let n = 0;
+    return () => `g-${++n}`;
+  })(),
+  participants: [
+    {
+      id: 'effects',
+      cart: effectsCart,
+      seed: `0x${'61'.repeat(32)}`,
+      emit: ['ambience.intent.*'],
+      subscribe: ['host.state.*'],
+    },
+    {
+      id: 'ambience',
+      cart: ambienceCart,
+      kind: 'render',
+      seed: `0x${'62'.repeat(32)}`,
+      subscribe: ['ambience.intent.*'],
+    },
+  ],
+});
+
+group.publish({
+  type: 'host.state.accepted',
+  kind: 'state',
+  payload: { id: 'north' },
+});
+await group.step(2);
+const { participants, trace, diagnostics } = await group.inspect();
+group.destroy();
+```
+
+Example mapping: an accepted `host.state.accepted` is consumed by the effects cart, which emits `ambience.intent.play`; the router delivers that cue to the ambience cart. No project-specific bridge.
+
+### Options (`CreateRuntimeGroupOptions`)
+
+| Option | Default | Meaning |
+|---|---|---|
+| `participants` | required | One entry per cart. Ids must be unique. Sorted lexicographically for lockstep. |
+| `origin` | `0` | Passed to every `createRuntime({ deterministic: { origin } })`. |
+| `width` / `height` | `320` / `180` | Used when the group creates a container. |
+| `createId` / `now` | `evt-1`… / first cart clock | Injected into the **one** shared router. |
+| `validate` | none | Router `validate` for cart-originated events. |
+| `router` | `{}` | Extra `createEventRouter` options (`maxHops`, `maxPerTurn`, …). |
+| `maxTrace` | `1024` | Bound on the accepted-event inspect trace. |
+
+### Participant config
+
+| Field | Meaning |
+|---|---|
+| `id` | Router participant id. Reserved: `host`, `router`. |
+| `cart` | `AnimationCart` mounted through `createRuntime`. |
+| `kind` | `'render'` (default) or `'calculation'` (no-op/minimal render; still a real cart). |
+| `seed` | `0x` + 64 hex, or any seed `createRuntime` accepts. Default: derived from `id`. |
+| `container` | Injected mount node. If omitted, the group creates and owns a sized `div`. |
+| `emit` / `subscribe` / `authoritative` | Passed to `router.attach`. |
+| `capability` | Structural fallback for those three fields when the explicit ones are omitted. |
+| `initialState` / `gameManager` / `onEvent` | `mount` options. The group still records outbound events. |
+
+### Handle (`RuntimeGroup`)
+
+| Member | Meaning |
+|---|---|
+| `router` | The shared `EventRouter`. Do not create a second one. |
+| `step(n)` | For each frame: `router.turn()` once, then `await cart.step(1)` in sorted id order. No-op while paused. Throws after `destroy()`. |
+| `pause` / `resume` | Group flag plus every cart. `step` does not advance while paused. |
+| `reset` | Remounts every cart to its initial state, clears traces / logs, `router.turn()`. Does not change `paused`; call `resume()` if you need lockstep after a paused reset. |
+| `dispatch(id, event)` | Mailbox inbound on that participant. |
+| `publish(event)` | Host `router.publish`. Unknown `target` → `unknown-target` rejection. |
+| `inspect()` | `{ participants: Record<id, { state, events, errors, kind, clock, emit, subscribe, authoritative }>, trace, diagnostics }`. |
+| `inspectParticipants()` | Sync attach view (`id`, `kind`, `emit`, `subscribe`, `authoritative`). |
+| `destroy()` | Detach router listeners, `runtime.destroy()` each cart, remove owned containers. Idempotent. |
+
+Idempotency, correlation, causation, unauthorized emit, hop/loop checks are the existing router. The group only attaches and locksteps. For “why did this effect not fire?”, attach [`createReplayInspector`](replay-inspector.md).
+
+## `createHeadlessMultiCartHarness(options)`
+
+```ts
+import { createHeadlessMultiCartHarness } from '@cyberart-io/engine/headless';
+
+const harness = createHeadlessMultiCartHarness({
+  participants: [effects, ambience, telemetry],
+});
+await harness.step(2);
+harness.destroy();
+```
+
+Calls `installHeadlessCanvas()` then `createRuntimeGroup`. Same handle. Three-cart CI fixture: effects + ambience + a calculation telemetry cart.
+
+Cleanup: `afterEach(() => group.destroy())` so a failed assertion does not leak nodes. After `destroy`, `step` throws and owned containers are gone from `document.body`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cyberart-io/engine",
-  "version": "0.0.3",
-  "description": "CyberArt host engine: mount a cart, assets, events, deterministic cues, and a Node/jsdom headless entry.",
+  "version": "0.0.5",
+  "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",
   "files": [