@cyberart-io/engine 0.0.4 → 0.0.5

package/README.md

@@ -89,13 +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
 
@@ -244,9 +247,9 @@ CI and agents should drive the **same** `createRuntime({ deterministic })` path.
 - Carts and production hosts: `import { createRuntime } from '@cyberart-io/engine'`
 - 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';
@@ -285,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' } },
 });
@@ -302,6 +305,26 @@ const router = createEventRouter({
 router.attach('presentation', runtime.hostChannel, deriveAttachOptions(contracts, 'cart'));
 ```
 
+## Presentation cue
+
+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';
+
+const timeline = createPresentationTimeline({ originFrame: 0, reducedMotion: false });
+timeline.play({
+  name: 'checkmark',
+  idempotencyKey: 'gold',
+  durationFrames: 90,
+  easing: 'ease-out',
+  onDuplicate: 'replace',
+});
+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.
@@ -313,14 +336,14 @@ import {
 } from '@cyberart-io/engine';
 
 const defined = defineCapabilityManifest({
-  id: 'adventure.presentation',
+  id: 'host.presentation',
   runtime: { minContractVersion: 1, features: ['router'] },
   phases: ['loading', 'ready', 'error', 'unsupported'],
   managers: ['pointer', 'hostChannel'],
-  assets: { kinds: ['image'], declarations: [{ id: 'room-bg', kind: 'image' }] },
-  acceptedEvents: ['adventure.state.*'],
-  emittedEvents: ['adventure.intent.exit-requested'],
-  permissions: { emit: ['adventure.intent.*'], subscribe: ['adventure.state.*'] },
+  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('; '));
@@ -328,8 +351,8 @@ validateCapabilityManifest(defined.manifest, {
   contractVersion: 1,
   features: ['router'],
   integrations: ['tone'],
-  emit: ['adventure.intent.*'],
-  subscribe: ['adventure.state.*'],
+  emit: ['host.intent.*'],
+  subscribe: ['host.state.*'],
 });
 ```
 
@@ -345,17 +368,17 @@ import { createRuntimeGroup } from '@cyberart-io/engine';
 const group = createRuntimeGroup({
   origin: 0,
   participants: [
-    { id: 'effects', cart: effectsCart, emit: ['ambience.intent.*'], subscribe: ['adventure.state.*'] },
+    { id: 'effects', cart: effectsCart, emit: ['ambience.intent.*'], subscribe: ['host.state.*'] },
     { id: 'ambience', cart: ambienceCart, subscribe: ['ambience.intent.*'] },
   ],
 });
-group.publish({ type: 'adventure.state.loon-whistle', kind: 'state', payload: { habitat: 'pond' } });
+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).
+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
 
@@ -400,7 +423,7 @@ const adapter = attachPresentationAdapter(harness);
 adapter.present({
   contractVersion: 1,
   phase: 'ready',
-  view: { title: 'Joiner Brook', regions: [] },
+  view: { title: 'Overlook', regions: [] },
 });
 ```
 
@@ -418,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',
@@ -524,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