@cyberart-io/engine 0.0.3 → 0.0.4

package/docs/events.md

@@ -1,6 +1,6 @@
 # Events and router
 
-Mailbox (one runtime) and `createEventRouter` (many carts). 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).
+Mailbox (one runtime) and `createEventRouter` (many carts). Prefer `createRuntimeGroup` when several carts should share one router and lockstep clock. Carts never receive the router object or another cart’s `HostChannel`. Related: [deterministic mode](deterministic-mode.md) (`now` / `createId` / `turn` per `step`), [presentation adapter](presentation-adapter.md) (`presentation.state.model`), [runtime group](runtime-group.md), [capability manifest](capability-manifest.md).
 
 Back to the [package README](../README.md).
 
@@ -10,14 +10,16 @@ Back to the [package README](../README.md).
 pnpm exec vitest run packages/engine/src/canvas/cyb-59-event-contract.repro.spec.ts
 ```
 
+
 ## When to use which
 
 | Path | Use |
 |---|---|
 | Mailbox only | One cart, host `dispatch` / cart `emit`. No permissions, hops, or loop checks. |
 | Router | Several carts, host reducer in the middle, Adventure-style intent vs state. |
+| Runtime group | Same router plus lockstep `step`, pause/reset/teardown, and a routed trace. |
 
-`createRuntime` does **not** attach a router. Attach `runtime.hostChannel` yourself. Cart unload clears the inbound queue only; router listeners stay until `runtime.destroy()`. If the channel is attached to a router, use `router.subscribe` for host logic — a second `mount({ onEvent })` will see every cart emit twice.
+`createRuntime` does **not** attach a router. Attach `runtime.hostChannel` yourself, or use `createRuntimeGroup()` which calls `router.attach(id, runtime.hostChannel, options)` for each participant. Cart unload clears the inbound queue only; router listeners stay until `runtime.destroy()` (or `group.destroy()`). If the channel is attached to a router, use `router.subscribe` for host logic — a second `mount({ onEvent })` will see every cart emit twice.
 
 ## Mailbox (`HostChannel`)
 
@@ -69,65 +71,9 @@ Routed events are normalized to `EventEnvelope` (`EVENT_ENVELOPE_VERSION = 1`).
 - Else the first dotted segment of `type` that is `intent`, `state`, or `diagnostic` (not necessarily the second segment — `adventure.presentation.intent.cue-started` is an intent).
 - Else `malformed` (`cannot infer kind`). `adventure.presentation.cue.started` does not infer a kind; define it with `defineIntent` / `defineStateEvent` / `defineDiagnostic` so the kind is in the name.
 
-Only the host (`publish`) or an `authoritative` participant may emit `state` / `diagnostic`. Carts emit allowed `intent` patterns. Domain data belongs in `payload`.
-
-## Typed contracts
-
-Define each routed type once. That object is the TypeScript payload shape (`InferredPayload`), the runtime validator, the router permission source, and the JSON manifest row.
-
-```ts
-import {
-  defineIntent,
-  defineStateEvent,
-  createContractRegistry,
-  deriveAttachOptions,
-  createEventRouter,
-} from '@cyberart-io/engine';
-
-const exit = defineIntent('adventure.intent.exit-requested', {
-  version: 1,
-  fields: { exitId: { type: 'string' } },
-});
-const room = defineStateEvent('adventure.state.room-changed', {
-  version: 1,
-  fields: { roomId: { type: 'string' } },
-});
-if (!exit.ok || !room.ok) {
-  // structured errors — these helpers do not throw
-}
-const contracts = [exit.contract, room.contract];
-const registry = createContractRegistry(contracts);
-const router = createEventRouter({ validate: registry.asRouterValidate });
-router.attach('presentation', runtime.hostChannel, deriveAttachOptions(contracts, 'cart'));
-```
-
-`adventure.presentation.cue.started` has no `intent` / `state` / `diagnostic` segment, so `inferEventKind` returns undefined and `defineIntent` returns `{ ok: false, errors }` with `kind-mismatch`. Use `adventure.presentation.intent.cue-started` (kind anywhere after the namespace, not only the second segment). Cue timeline names (`cue.started`, …) are **not** routed envelopes until you wrap them in a contract.
+Typed contracts (`defineIntent`, `defineStateEvent`, `defineDiagnostic`) fail at definition time with structured `{ ok: false, errors }` instead of throwing. `createContractRegistry` produces manifest JSON and a `validate` hook for `createEventRouter`. `deriveAttachOptions` / `verifyAttachOptions` keep non-authoritative carts from emitting `state` / `diagnostic` contracts. Payload schema versioning: adding optional fields with a version bump is backward-compatible; removals, type changes, and version downgrades are breaking.
 
-| Helper | Kind stamped | Name rule |
-|---|---|---|
-| `defineIntent(type, schema)` | `intent` | `type` must contain an `intent` dotted segment |
-| `defineStateEvent(type, schema)` | `state` | `type` must contain a `state` dotted segment |
-| `defineDiagnostic(type, schema)` | `diagnostic` | `type` must contain a `diagnostic` dotted segment |
-
-`schema` is `{ version: integer >= 1, fields: { name: { type: 'string' \| 'number' \| 'boolean' \| 'object' \| 'array', optional?: true } } }`. Extra payload keys are allowed. Missing required fields and wrong JSON types return `{ ok: false, errors: ContractDiagnostic[] }` (`code`, `detail`, optional `path`). Invalid definitions return the same shape; they never throw.
-
-| Export | Role |
-|---|---|
-| `createContractRegistry(contracts)` | `get`, `manifest()` (JSON-serializable), `validateEnvelope`, `asRouterValidate` (safe to pass as `EventRouterOptions.validate`; does not rely on `this`) |
-| `deriveAttachOptions(contracts, 'cart' \| 'authoritative')` | Cart: emit intent family patterns only. Authoritative: emit every contract family. Subscribe to non-intent families. |
-| `verifyAttachOptions(options, contracts)` | `{ ok: true }` or unauthorized-emit errors when a non-authoritative attach can emit a `state` / `diagnostic` contract |
-| `comparePayloadSchemas(from, to)` | `'identical'` / `'backward-compatible'` / `'breaking'` |
-| `kindSegmentInType(type)` / `familyPatternForType(type)` | First kind segment; last-segment `*` glob (`adventure.presentation.intent.*`) |
-
-Default router `emit: ['*.intent.*']` is **three** segments. Four-segment names such as `adventure.presentation.intent.cue-started` need `deriveAttachOptions` (or an explicit four-segment pattern). Duplicate `type`s in a registry last-win.
-
-### Payload versioning (`comparePayloadSchemas`)
-
-| Change | Result |
-|---|---|
-| Same version, same fields | `identical` |
-| Version bump, only new **optional** fields (or unchanged fields) | `backward-compatible` |
-| Removed field, type change, optional → required, version downgrade, optional add **without** a version bump | `breaking` |
+Only the host (`publish`) or an `authoritative` participant may emit `state` / `diagnostic`. Carts emit allowed `intent` patterns. Domain data belongs in `payload`.
 
 ## `createEventRouter(options?)`
 
@@ -247,14 +193,11 @@ Type `REJECTED_EVENT_TYPE` (`cyberart.diagnostic.rejected`). Payload (`Rejection
 | `EVENT_ENVELOPE_VERSION` | `1`. |
 | `DEFAULT_MAX_HOPS` | `8`. |
 | `REJECTED_EVENT_TYPE` | `'cyberart.diagnostic.rejected'`. |
-| `inferEventKind(input)` | Kind from `kind` or first kind segment in `type`. |
+| `inferEventKind(input)` | Kind from `kind` or type name. |
 | `matchEventPattern(pattern, type)` | One-segment `*` glob. |
 | `normalizeEvent(input, context)` | Build an envelope or `{ ok: false, reason: 'malformed', detail }`. The router calls this; hosts rarely need it. |
-| `defineIntent` / `defineStateEvent` / `defineDiagnostic` | Contract constructors (see Typed contracts). |
-| `createContractRegistry` / `deriveAttachOptions` / `verifyAttachOptions` / `comparePayloadSchemas` | Registry, permissions, schema compatibility. |
-| `kindSegmentInType` / `familyPatternForType` | Name helpers used by contracts. |
 
-Types: `EventEnvelope`, `EventInput`, `EventKind`, `NormalizeContext`, `NormalizeResult`, `RejectionPayload`, `RejectionReason`, `AttachOptions`, `EventRouter`, `EventRouterOptions`, `PublishExtras`, `ValidateResult`, `EventContract`, `EventContractManifest`, `ContractRegistry`, `DefineContractResult`, `PayloadSchema`, `PayloadFieldSpec`, `PayloadValidation`, `ContractDiagnostic`, `ContractFieldType`, `InferredPayload`, `SchemaCompatibility`.
+Types: `EventEnvelope`, `EventInput`, `EventKind`, `NormalizeContext`, `NormalizeResult`, `RejectionPayload`, `RejectionReason`, `AttachOptions`, `EventRouter`, `EventRouterOptions`, `PublishExtras`, `ValidateResult`.
 
 `matchesAnyPattern` / `clonePayload` / `isEventKind` are not on the public package surface.
 

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).
+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`).
 
 Back to the [package README](../README.md).
 
@@ -12,8 +12,8 @@ Back to the [package README](../README.md).
 
 | Surface | Import |
 |---|---|
-| Carts, Player, kaleidoscope, `/art` | `@cyberart-io/engine` (`createRuntime`, events, contracts, assets, presentation adapter, presentation cue) |
-| Vitest / jsdom / CI capture | `@cyberart-io/engine/headless` (`createHeadlessHarness`, `installHeadlessCanvas`, `captureFrame`) |
+| Carts, Player, kaleidoscope, `/art` | `@cyberart-io/engine` (`createRuntime`, events, assets, presentation adapter) |
+| Vitest / jsdom / CI capture | `@cyberart-io/engine/headless` (`createHeadlessHarness`, `createHeadlessMultiCartHarness`, `installHeadlessCanvas`, `captureFrame`) |
 
 The main export does not re-export the harness. A browser bundle that only imports `@cyberart-io/engine` must not warn about `node:fs/promises`.
 

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).
 
@@ -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.
 

package/docs/presentation-cue.md

@@ -2,7 +2,7 @@
 
 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.
 
-Back to the [package README](../README.md). Related: [deterministic mode](deterministic-mode.md), [events](events.md) (routed contracts vs local `cue.*` names).
+Back to the [package README](../README.md). Related: [deterministic mode](deterministic-mode.md).
 
 ## One-command reproduce (this repo)
 

package/docs/runtime-group.md

@@ -0,0 +1,120 @@
+# 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).
+
+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: ['adventure.state.*'],
+    },
+    {
+      id: 'ambience',
+      cart: ambienceCart,
+      kind: 'render',
+      seed: `0x${'62'.repeat(32)}`,
+      subscribe: ['ambience.intent.*'],
+    },
+  ],
+});
+
+group.publish({
+  type: 'adventure.state.loon-whistle',
+  kind: 'state',
+  payload: { habitat: 'pond' },
+});
+await group.step(2);
+const { participants, trace, diagnostics } = await group.inspect();
+group.destroy();
+```
+
+Adventure-style mapping (fixture, not Adventure Kit): an accepted `adventure.state.loon-whistle` 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`, …). |
+
+### 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 }>, trace, diagnostics }`. |
+| `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.
+
+## `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.4",
+  "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": [