@cyberart-io/engine 0.0.3 → 0.0.5

package/README.md

@@ -89,10 +89,16 @@ Full API for the event router, deterministic replay, and CI harness (so agents c
 
 - [Events and router](docs/events.md) — mailbox, envelope, typed contracts, `createEventRouter`, hops, idempotency, rejections
 - [Deterministic mode](docs/deterministic-mode.md) — `step` / `schedule`, clocks, `ScriptedAction`, replay diffs
-- [Headless harness](docs/headless-harness.md) — `createHeadlessHarness` from `@cyberart-io/engine/headless`, jsdom canvas, inspect / screenshot
+- [Headless harness](docs/headless-harness.md) — `createHeadlessHarness` from `@cyberart-io/engine/headless`, software Canvas2D, `compareImageData` / `assertPixelsEqual`, inspect / screenshot
 - [Presentation adapter](docs/presentation-adapter.md) — host-owned render model, intents, loading / error / unsupported
 - [Asset resolver](docs/asset-resolver.md) — host-pluggable images/audio/fonts/spritesheets, cache, preload, fallbacks
 - [Presentation cue](docs/presentation-cue.md) — deterministic `createPresentationTimeline`, duplicate policy, reduced-motion, lifecycle events
+- [Capability manifest](docs/capability-manifest.md) — versioned JSON for runtime features, phases, managers, assets, events, permissions, integrations
+- [Normalized geometry](docs/normalized-geometry.md) — coordinate spaces, contain/cover/crop layout, landmarks, hit regions, debug overlay
+- [Runtime group](docs/runtime-group.md) — `createRuntimeGroup`, shared router attach, lockstep clock; `createHeadlessMultiCartHarness` from `@cyberart-io/engine/headless`
+- [Compositor](docs/compositor.md) — `createCompositor`, transparent stacking, `screen` blend, `writeComposedFrame`
+- [Browser harness](docs/browser-harness.md) — `createBrowserHarness`, DOM clicks, viewport/DPR, composed screenshots
+- [Replay inspector](docs/replay-inspector.md) — `createReplayInspector`, causation trees, redacted export/import, headless replay
 
 ## Write a cart
 
@@ -170,7 +176,7 @@ const cart = runtime.mount(artProject, {
 
 `runtime.destroy()` tears down the runtime. `runtime.unlockAudio()` is for an early click before `mount`. `runtime.onError` receives frame errors (`phase`, `consecutive`, `stopped`).
 
-One cart per runtime. A second `mount` unloads the first. Several pieces on a page means several `createRuntime()` calls.
+One cart per runtime. A second `mount` unloads the first. Several pieces on a page means several `createRuntime()` calls, or one `createRuntimeGroup()` that attaches each mailbox to a shared router and locksteps a deterministic clock.
 
 ## Audio
 
@@ -239,11 +245,11 @@ const replay = await cart.getReplayMetadata();
 CI and agents should drive the **same** `createRuntime({ deterministic })` path. Import the harness from **`@cyberart-io/engine/headless`** so browser production builds never walk `node:fs/promises`.
 
 - Carts and production hosts: `import { createRuntime } from '@cyberart-io/engine'`
-- Tests, CI, and frame capture: `import { createHeadlessHarness } from '@cyberart-io/engine/headless'`
+- Tests, CI, and frame capture: `import { createHeadlessHarness, createHeadlessMultiCartHarness } from '@cyberart-io/engine/headless'`
 
-`@cyberart-io/engine` does not re-export the harness. `installHeadlessCanvas` is the documented jsdom install (test-only). `createHeadlessHarness` sizes a container, mounts, and wraps step / input / inspect / snapshot.
+`@cyberart-io/engine` does not re-export the harness. `installHeadlessCanvas` is the documented jsdom install (test-only). It attaches a deterministic software Canvas2D (paths, arcs, atlas text, transforms, clip, alpha, gradients, `drawImage`). Unsupported ops throw `HeadlessUnsupportedOperationError`. `createHeadlessHarness` sizes a container, mounts, and wraps step / input / inspect / snapshot. Pixel compare: `compareImageData`, `assertPixelsEqual`, `writeVisualArtifacts` (`CYBERART_UPDATE_GOLDEN=1` to refresh goldens).
 
-Full options, `click` clock rule, Node-only `captureFrame`, remount, and the reproduce command: [headless harness](docs/headless-harness.md).
+Full options, `click` clock rule, Node-only `captureFrame`, remount, visual asserts, and the reproduce command: [headless harness](docs/headless-harness.md).
 
 ```ts
 import { createHeadlessHarness } from '@cyberart-io/engine/headless';
@@ -258,7 +264,7 @@ harness.destroy();
 
 ## Events
 
-Default path: per-runtime **mailbox** (`dispatch` / `consume` / `emit`). Multi-cart hosts attach each `HostChannel` to `createEventRouter` — carts never see the router.
+Default path: per-runtime **mailbox** (`dispatch` / `consume` / `emit`). Multi-cart hosts should prefer `createRuntimeGroup()` (it calls `router.attach` for each mailbox). You can still attach each `HostChannel` to `createEventRouter` yourself — carts never see the router.
 
 ```ts
 const cart = runtime.mount(artProject, {
@@ -282,11 +288,11 @@ import {
   createEventRouter,
 } from '@cyberart-io/engine';
 
-const exit = defineIntent('adventure.intent.exit-requested', {
+const exit = defineIntent('host.intent.exit-requested', {
   version: 1,
   fields: { exitId: { type: 'string' } },
 });
-const room = defineStateEvent('adventure.state.room-changed', {
+const room = defineStateEvent('host.state.room-changed', {
   version: 1,
   fields: { roomId: { type: 'string' } },
 });
@@ -301,7 +307,7 @@ router.attach('presentation', runtime.hostChannel, deriveAttachOptions(contracts
 
 ## Presentation cue
 
-Frame-stepped effects (checkmarks, ripples, room fades). No `setTimeout` / rAF. Drive `step` from the same clock as deterministic `cart.step`.
+Frame-stepped effects (overlays, pulses, scene fades). No `setTimeout` / rAF. Drive `step` from the same clock as deterministic `cart.step`.
 
 ```ts
 import { createPresentationTimeline } from '@cyberart-io/engine';
@@ -319,6 +325,84 @@ timeline.step(90);
 
 Lifecycle names `cue.started` / `cue.completed` / `cue.cancelled` / `cue.replaced` are local to the timeline. They are not router envelopes unless you define a contract. Duplicate policy, late-play catch-up, and reduced-motion: [presentation cue](docs/presentation-cue.md).
 
+## Capability manifest
+
+JSON for what a cart needs from the host. `validateCapabilityManifest` returns structured diagnostics instead of throwing.
+
+```ts
+import {
+  defineCapabilityManifest,
+  validateCapabilityManifest,
+} from '@cyberart-io/engine';
+
+const defined = defineCapabilityManifest({
+  id: 'host.presentation',
+  runtime: { minContractVersion: 1, features: ['router'] },
+  phases: ['loading', 'ready', 'error', 'unsupported'],
+  managers: ['pointer', 'hostChannel'],
+  assets: { kinds: ['image'], declarations: [{ id: 'backdrop', kind: 'image' }] },
+  acceptedEvents: ['host.state.*'],
+  emittedEvents: ['host.intent.exit-requested'],
+  permissions: { emit: ['host.intent.*'], subscribe: ['host.state.*'] },
+  integrations: ['tone'],
+});
+if (!defined.ok) throw new Error(defined.errors.map((e) => e.detail).join('; '));
+validateCapabilityManifest(defined.manifest, {
+  contractVersion: 1,
+  features: ['router'],
+  integrations: ['tone'],
+  emit: ['host.intent.*'],
+  subscribe: ['host.state.*'],
+});
+```
+
+Fields, host allowlists, and diagnostic codes: [capability manifest](docs/capability-manifest.md).
+
+## Runtime group
+
+Several production carts, one router, one lockstep clock. Use this instead of intercepting each `onEvent` and republishing by hand.
+
+```ts
+import { createRuntimeGroup } from '@cyberart-io/engine';
+
+const group = createRuntimeGroup({
+  origin: 0,
+  participants: [
+    { id: 'effects', cart: effectsCart, emit: ['ambience.intent.*'], subscribe: ['host.state.*'] },
+    { id: 'ambience', cart: ambienceCart, subscribe: ['ambience.intent.*'] },
+  ],
+});
+group.publish({ type: 'host.state.accepted', kind: 'state', payload: { id: 'north' } });
+await group.step(2);
+const { trace } = await group.inspect();
+group.destroy();
+```
+
+Headless / CI: `createHeadlessMultiCartHarness` from `@cyberart-io/engine/headless` is the same handle after `installHeadlessCanvas()`. Full options: [runtime group](docs/runtime-group.md). Causation trees, redaction, and tape replay: [replay inspector](docs/replay-inspector.md).
+
+## Normalized geometry
+
+Shared 0–1 content-box coordinates, landmarks, and hit regions. Pixel `PresentationRegion` on the presentation adapter is unchanged.
+
+```ts
+import {
+  createPresentationLayout,
+  pointerToRegion,
+  ROUND_TRIP_TOLERANCE,
+} from '@cyberart-io/engine';
+
+const layout = createPresentationLayout({
+  contentWidth: 1920,
+  contentHeight: 1080,
+  viewportWidth: 1280,
+  viewportHeight: 800,
+  mode: 'contain',
+});
+const hit = pointerToRegion({ x: canvasX, y: canvasY }, layout, doc);
+```
+
+Spaces, contain/cover/crop, debug overlay, and the reproduce command: [normalized geometry](docs/normalized-geometry.md).
+
 ## Presentation adapter
 
 Host-owned render model in, interaction intents out. Cyberart does not mutate the canonical world. `gameManager` is not this contract.
@@ -339,7 +423,7 @@ const adapter = attachPresentationAdapter(harness);
 adapter.present({
   contractVersion: 1,
   phase: 'ready',
-  view: { title: 'Joiner Brook', regions: [] },
+  view: { title: 'Overlook', regions: [] },
 });
 ```
 
@@ -357,7 +441,7 @@ import {
 } from '@cyberart-io/engine';
 
 const roomAssets = [
-  { id: 'room-bg', ref: 'moltazine:post/porch-1#primary-image', type: 'image' as const },
+  { id: 'backdrop', ref: 'moltazine:post/porch-1#primary-image', type: 'image' as const },
   {
     id: 'ambience',
     ref: 'world:asset/stream-loop',
@@ -463,7 +547,7 @@ A canvas the host adopted is left in place on destroy; a canvas the engine creat
 
 ## Publishing this package (maintainers)
 
-Not part of writing a cart. Engine source lives in `packages/engine/src/` (not mixed into the site). The npm tarball is built from `packages/engine/src/index.ts` and `packages/engine/src/headless.ts` and contains minified `dist/index.js` + `dist/headless.js`, rolled-up `.d.ts` for both, `LICENSE`, `README.md`, `docs/` (event / deterministic / harness / presentation-adapter / asset-resolver / presentation-cue API), and `package.json`. Site code that still imports `src/ui/lib/...` hits thin re-export shims so those paths keep working.
+Not part of writing a cart. Engine source lives in `packages/engine/src/` (not mixed into the site). The npm tarball is built from `packages/engine/src/index.ts` and `packages/engine/src/headless.ts` and contains minified `dist/index.js` + `dist/headless.js`, rolled-up `.d.ts` for both, `LICENSE`, `README.md`, `docs/` (including compositor, browser harness, and replay inspector), and `package.json`. Site code that still imports `src/ui/lib/...` hits thin re-export shims so those paths keep working.
 
 ```bash
 pnpm run pack:engine