@cyberart-io/engine 0.0.8 → 0.0.9

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to `@cyberart-io/engine`. Each entry links the guide in `docs/` and the pull request on [cyberart-io/cyberart.io](https://github.com/cyberart-io/cyberart.io). Versions before 0.0.9 predate this file.
+
+## 0.0.9 — 2026-09-05
+
+Eleven Animation Framework modules. All are additive: no existing export changed signature, and the `@cyberart-io/engine` / `@cyberart-io/engine/headless` entries export the same new API. Every module ships a `snapshot()` / `restore()` pair that validates JSON before mutating, and typed `*.state.*` / `*.diagnostic.*` event contracts for the router.
+
+### Added
+
+- **Semantic layers** — `createSemanticLayerController`. Cart-published named regions (mask / polygon / rect / depth) in normalized coordinates; host-driven hover / focus / selected, a11y names and roles, hit-test policies `pass-through` / `absorb` / `exclusive` / `depth-ordered`; `inspectPublished()` for segmentation clients. [docs/semantic-layers.md](docs/semantic-layers.md) · [#30](https://github.com/cyberart-io/cyberart.io/pull/30)
+- **Remote cart manifests** — `signRemoteCartManifest`, `loadRemoteCart`, `createRemoteCartRegistry`, `createRemoteCartSandbox`, `createHostGrantSet`, `createDeclaredAssetResolver`. HMAC-signed versioned catalogs, declared asset hashes, deny-by-default host grants, no ambient network. [docs/remote-cart-manifest.md](docs/remote-cart-manifest.md) · [#31](https://github.com/cyberart-io/cyberart.io/pull/31)
+- **Portal lifecycle** — `createPortalLifecycle`, `cabinetPortal`, `paintingPortal`. One enter / exit / abort contract for inhabiting another cart exclusively; parent suspend in the runtime group, exclusive grant transfer, nested stack, versioned outcome. [docs/portal-lifecycle.md](docs/portal-lifecycle.md) · [#33](https://github.com/cyberart-io/cyberart.io/pull/33)
+- **Job orchestration** — `createJobCoordinator`, `createMemoryJobPersistence`; `createHeadlessJobWorker` on the headless entry. Durable queued → claimed → awaiting-evaluation → ready → applied lifecycle with retries, leases, evaluator feedback, and host-owned `accept`. Results are refs, not payloads. [docs/job-orchestration.md](docs/job-orchestration.md) · [#34](https://github.com/cyberart-io/cyberart.io/pull/34)
+- **World graph** — `createWorldGraph`, `worldGraphEventContracts`. Optional spatial graph with stable ids, canonical vs per-observer known projections, locked / disabled edges with opaque host policy, semantic-time transit, atomic `applyPatch`. [docs/world-graph.md](docs/world-graph.md) · [#35](https://github.com/cyberart-io/cyberart.io/pull/35)
+- **Presentation sequences** — `definePresentationSequence`, `createPresentationSequencePlayer`; `createHeadlessAudioAdapter` on the headless entry. One frame-stepped clock across audio, captions, semantic focus, visual layers, and cues; skip / replay / replace / queue; declared capability fallbacks (text-only when audio fails). [docs/presentation-sequences.md](docs/presentation-sequences.md) · [#36](https://github.com/cyberart-io/cyberart.io/pull/36)
+- **Content revision** — `createContentRevisionActivator`, `createStaticContentAdapter`, `createRemoteContentAdapter`, `contentRevisionEventContracts`. Atomic staging and commit of an external content revision; last-known-good rollback, supersede, pin, exact revisions only. [docs/content-revision.md](docs/content-revision.md) · [#37](https://github.com/cyberart-io/cyberart.io/pull/37)
+- **Presentation bindings** — `definePresentationBindings`, `createPresentationBindingRuntime`. Versioned manifest projecting host state onto visual versions, presence, props, semantic regions, hotspots, and sequences; fail-closed defaults, priority conflict resolution, explanation of winners and rejected alternatives. [docs/presentation-bindings.md](docs/presentation-bindings.md) · [#39](https://github.com/cyberart-io/cyberart.io/pull/39)
+- **World patch** — `createWorldPatchApplier`, `createMemoryWorldPersistence`, `worldPatchEventContracts`. Transactional dry-run and atomic commit of a generated world patch as one revision; `stale-base` rejection, idempotent `patchId`, optional world-graph composition, host-injected persistence. [docs/world-patch.md](docs/world-patch.md) · [#40](https://github.com/cyberart-io/cyberart.io/pull/40)
+- **Production scenario** — `defineProductionScenario`, `createProductionScenarioRunner`, `localizeProductionScenarioFailure`, `productionScenarioEventContracts`. One JSON scenario drives the real browser harness / runtime group / compositor / layers / bindings / sequences / audio / snapshot / replay chain; required participants and layers fail closed; `ProductionScenarioEvidenceBundle` with hashes and `firstBrokenBoundary`. [docs/production-scenario.md](docs/production-scenario.md) · [#41](https://github.com/cyberart-io/cyberart.io/pull/41)
+- **Selection trace** — `createSelectionTrace`, `attachSelectionTrace`. Why a binding, revision, asset, sequence, or fallback won; distinct reason codes for binding conflict, asset failure, revision rollback, sequence interruption, and text-only fallback; whitelist-based projection redaction and signed-URL scrubbing; correlates with replay-inspector records and attaches to a production-scenario evidence bundle. [docs/selection-trace.md](docs/selection-trace.md) · [#42](https://github.com/cyberart-io/cyberart.io/pull/42)
+
+### Docs
+
+- README sections and cross-links for every module above; `docs/` is included in the tarball and verified by `pnpm run pack:engine`. [#43](https://github.com/cyberart-io/cyberart.io/pull/43)
+
+## 0.0.8 — 2026-08-23
+
+- Frame benchmarking: `benchmarkCartFrames` (headless) and `onFrameTiming` (live). [docs/frame-benchmark.md](docs/frame-benchmark.md)
+
+## 0.0.7 — 2026-08-23
+
+- Calculation carts and versioned visual layers. [docs/calculation-carts.md](docs/calculation-carts.md), [docs/visual-layers.md](docs/visual-layers.md)
+
+## 0.0.6 — 2026-08-23
+
+- MIDI, executable modules, snapshots, and the audio broker. [docs/midi.md](docs/midi.md), [docs/executable-modules.md](docs/executable-modules.md), [docs/snapshots.md](docs/snapshots.md), [docs/audio.md](docs/audio.md)

package/README.md

@@ -96,13 +96,24 @@ Full API for the event router, deterministic replay, and CI harness (so agents c
 - [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
 - [Executable modules](docs/executable-modules.md) — trusted versioned factories, host allowlists, isolation, per-module failures
+- [Remote cart manifests](docs/remote-cart-manifest.md) — signed catalogs, declared asset hashes, inspectable host grants
 - [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`
 - [Calculation carts](docs/calculation-carts.md) — `kind: 'calculation'`, update + events without paint; sibling render carts still paint
 - [Compositor](docs/compositor.md) — `createCompositor`, transparent stacking, `screen` blend, `writeComposedFrame`
 - [Visual layers](docs/visual-layers.md) — `createVisualLayerController`, versioned overlay `v1`/`v2`, deterministic swaps, `hostState` JSON
+- [Semantic layers](docs/semantic-layers.md) — `createSemanticLayerController`, named mask/polygon/depth regions, host a11y and hover/focus/selected
+- [Presentation sequences](docs/presentation-sequences.md) — `definePresentationSequence`, shared clock for audio / caption / focus / visual, skip / fallback / restore
+- [Presentation bindings](docs/presentation-bindings.md) — `definePresentationBindings`, host state projection to visual / presence / regions / sequences, fail-closed defaults
+- [Portal lifecycle](docs/portal-lifecycle.md) — `createPortalLifecycle`, enter/exit/abort, grant transfer, nested stack restore
+- [Job orchestration](docs/job-orchestration.md) — `createJobCoordinator`, durable jobs, headless fake worker, host-owned apply
+- [World graph](docs/world-graph.md) — `createWorldGraph`, known vs canonical projections, host path policy, semantic-time transit
+- [World patch](docs/world-patch.md) — `createWorldPatchApplier`, transactional validation, atomic world revision, host persistence adapter
+- [Content revision](docs/content-revision.md) — `createContentRevisionActivator`, atomic remote/static bundle swap, last-known-good rollback
 - [Browser harness](docs/browser-harness.md) — `createBrowserHarness`, DOM clicks, viewport/DPR, composed screenshots
+- [Production scenario](docs/production-scenario.md) — `defineProductionScenario` / `createProductionScenarioRunner`, full host/runtime/cart composition, evidence bundles
 - [Replay inspector](docs/replay-inspector.md) — `createReplayInspector`, causation trees, redacted export/import, headless replay
+- [Selection trace](docs/selection-trace.md) — `createSelectionTrace`, binding/revision/asset/sequence fallback records, secret-safe export, CYB-82 evidence attach
 - [MIDI](docs/midi.md) — host-owned `MidiManager`, note/CC/pitch in and out, `inject` / fake port, structured `requestAccess`
 - [Snapshots](docs/snapshots.md) — versioned envelope, `defineSnapshot` / `applySnapshotMigrations`, host-owned `hostState`
 - [Audio](docs/audio.md) — `createAudioBroker`, `createAudioCueTimeline`, headless cue traces (PCM is not deterministic)
@@ -416,6 +427,38 @@ host.destroy();
 
 Unknown ids, wrong versions, and refs missing from the allowlist fail closed. A throwing module returns `{ ok: false, error }` and the next allowlisted invoke still runs. Isolation is in-process (trusted factories), not a worker or iframe. Carts may declare required refs as optional `modules.refs` on a [capability manifest](docs/capability-manifest.md). Full API and the reproduce command: [executable modules](docs/executable-modules.md).
 
+## Remote cart manifests
+
+Signed, versioned catalogs for third-party carts. HMAC over the canonical body, declared asset hashes, and deny-by-default host grants. Isolation is in-process trusted factories, not `eval`. There is no ambient network: tests inject a registry map or `fetch`.
+
+```ts
+import {
+  createRemoteCartRegistry,
+  createRemoteCartSandbox,
+  loadRemoteCart,
+  signRemoteCartManifest,
+} from '@cyberart-io/engine';
+
+const signed = await signRemoteCartManifest(body, secret, 'key-1');
+if (!signed.ok) throw new Error(signed.errors.map((e) => e.detail).join('; '));
+const loaded = await loadRemoteCart({
+  source: { kind: 'registry', id: 'vendor.remote' },
+  keys: { 'key-1': secret },
+  registry: createRemoteCartRegistry({ 'vendor.remote': signed.manifest }),
+  expectedVersion: '1.0.0',
+});
+if (!loaded.ok) throw new Error(loaded.errors.map((e) => e.detail).join('; '));
+const sandbox = createRemoteCartSandbox({
+  manifest: loaded.manifest,
+  keys: { 'key-1': secret },
+  grants: ['audio'],
+  bytesByUrl,
+});
+await sandbox.loadAssets(); // re-verifies HMAC; hash mismatch refuses load
+```
+
+`createHostGrantSet`, `createDeclaredAssetResolver`, `snapshotProvenance()`, and the diagnostic code table: [remote cart manifests](docs/remote-cart-manifest.md).
+
 ## Runtime group
 
 Several production carts, one router, one lockstep clock. Use this instead of intercepting each `onEvent` and republishing by hand.
@@ -438,6 +481,25 @@ group.destroy();
 
 Headless / CI: `createHeadlessMultiCartHarness` from `@cyberart-io/engine/headless` is the same handle after `installHeadlessCanvas()`. Full options: [runtime group](docs/runtime-group.md). Calculation carts (no canvas / paint): [calculation carts](docs/calculation-carts.md). Causation trees, redaction, and tape replay: [replay inspector](docs/replay-inspector.md).
 
+## Portal lifecycle
+
+One enter / exit / abort contract for leaving a cart, inhabiting another exclusively, and returning a versioned outcome. Cabinet, painting, dream, and nested world are host metaphors over the same primitive. The parent is suspended in the runtime group; exclusive grants (`audio`, `controller`, `fullscreen`) transfer for the child's lifetime.
+
+```ts
+import { cabinetPortal, createPortalLifecycle } from '@cyberart-io/engine';
+
+const portal = createPortalLifecycle({
+  group,
+  grants: { lobby: lobbyGrants, game: gameGrants },
+  rootId: 'lobby',
+  declarations: [{ id: 'lobby', targets: ['game'] }],
+});
+cabinetPortal(portal).enter({ from: 'lobby', to: 'game', seed });
+const outcome = portal.exit({ score: 108 }); // { schemaVersion: 1, kind: 'completed', payload }
+```
+
+Host chrome reads `portal.stack()` / `portal.activeId()`; persist `portal.snapshot()` in envelope `hostState`. Nested stacks, abort, and mid-portal restore: [portal lifecycle](docs/portal-lifecycle.md).
+
 ## Visual layers
 
 Durable overlay / mask / sprite versions (`v1`, `v2`) with deterministic show, hide, replace, and crossfade. An accepted `host.state.accepted` (`sceneId: 'alpha'`) runs a presentation cue; the compositor reveals a **preloaded** alternate source in one `setLayer`. Failed assets keep the prior valid frame and emit `visual.layer.failed`. Persist `controller.snapshot()` in envelope `hostState` — do not put pixels in the envelope.
@@ -478,6 +540,248 @@ layers.step(2);
 
 Headless capture: `captureVisualLayers(layers)` from `@cyberart-io/engine` or `@cyberart-io/engine/headless`. Full API: [visual layers](docs/visual-layers.md).
 
+## Semantic layers
+
+Named regions the cart publishes as mask, polygon, rect, and/or depth in normalized coordinates. The host drives hover / focus / selected and supplies a11y names and roles; geometry, blend, and hit-test policy (`pass-through`, `absorb`, `exclusive`, `depth-ordered`) stay with the cart.
+
+```ts
+import { createSemanticLayerController } from '@cyberart-io/engine';
+
+const regions = createSemanticLayerController({
+  compositor,
+  visualLayers,
+  regions: [
+    {
+      id: 'cabinet',
+      hitTest: 'absorb',
+      compositorLayerId: 'hotspot',
+      visualLayerId: 'hotspot',
+      geometry: { rect: { x: 0.2, y: 0.2, width: 0.3, height: 0.3 }, depth: 0.4 },
+      visuals: { idle: { version: 'idle' }, hover: { version: 'hover', blend: 'screen' } },
+    },
+  ],
+});
+regions.setRegionA11y('cabinet', { name: 'Arcade cabinet', role: 'button' });
+regions.setRegionState('cabinet', { hover: true });
+const hit = regions.hitTest({ x: 0.3, y: 0.3 });
+```
+
+`inspectPublished()` returns `{ id, geometryKinds, a11y }` for segmentation clients. Snapshot / restore validate the whole region set before mutating: [semantic layers](docs/semantic-layers.md).
+
+## Presentation sequences
+
+One frame-stepped clock for a semantic beat across audio, captions, semantic-region focus, visual layers, and typed cues. Hosts pass bindings; the engine does not own dialogue graphs.
+
+```ts
+import {
+  createPresentationSequencePlayer,
+  definePresentationSequence,
+} from '@cyberart-io/engine';
+import { createHeadlessAudioAdapter } from '@cyberart-io/engine/headless';
+
+const defined = definePresentationSequence({
+  id: 'spoken-line',
+  interruptionPolicy: 'replace',
+  tracks: [
+    {
+      id: 'caption',
+      kind: 'caption',
+      steps: [
+        {
+          id: 'line-1',
+          timing: { kind: 'absolute', atFrame: 0 },
+          durationFrames: 6,
+          effect: { kind: 'caption', textBinding: 'line', visible: true },
+          restoreOnComplete: true,
+        },
+      ],
+    },
+  ],
+  fallbacks: [
+    { id: 'text-only', when: { capability: 'audio', status: 'failed' }, omitTrackIds: ['audio'] },
+  ],
+});
+const player = createPresentationSequencePlayer({
+  originFrame: 0,
+  audio: createHeadlessAudioAdapter({ originFrame: 0 }),
+  sequences: [defined.sequence],
+});
+player.playSequence('spoken-line', {
+  invocationId: 'inv-1',
+  bindings: { captions: { line: 'spoken line' } },
+});
+player.step(6);
+```
+
+Skip, replay, pause/resume, replace/queue, failed-audio fallback, and mid-line restore: [presentation sequences](docs/presentation-sequences.md).
+
+## Presentation bindings
+
+Host-authoritative state stays on the host. A versioned binding manifest projects a JSON snapshot onto visual versions, presence, props, semantic regions, hotspots, and sequences. Invalid or missing state applies the declared defaults as one complete set.
+
+```ts
+import {
+  createPresentationBindingRuntime,
+  definePresentationBindings,
+} from '@cyberart-io/engine';
+
+const defined = definePresentationBindings({
+  id: 'lobby-room',
+  schemaVersion: 1,
+  bindings: [
+    {
+      id: 'night-room',
+      priority: 30,
+      when: { path: 'timeOfDay', eq: 'night' },
+      targets: [{ kind: 'visual-layer', layerId: 'room', version: 'night' }],
+    },
+  ],
+  defaults: [{ kind: 'visual-layer', layerId: 'room', version: 'day' }],
+});
+if (!defined.ok) throw new Error(defined.errors.map((e) => e.detail).join('; '));
+const runtime = createPresentationBindingRuntime({
+  manifest: defined.manifest,
+  visual,
+  semantic,
+  sequences,
+});
+runtime.apply({ timeOfDay: 'night' }, { revision: 83 });
+```
+
+Fail-closed validation, conflict priority, snapshot restore, and host a11y overrides: [presentation bindings](docs/presentation-bindings.md).
+
+## Production scenario
+
+One scenario definition drives the real production chain: browser harness, runtime group, compositor, visual/semantic layers, bindings, sequences, headless audio, snapshots, and replay. Required carts and layers are declared so an isolated effect test cannot go green while the shipped composition omits them.
+
+```ts
+import {
+  createProductionScenarioRunner,
+  defineProductionScenario,
+} from '@cyberart-io/engine';
+
+const defined = defineProductionScenario({
+  id: 'room-whistle',
+  schemaVersion: 1,
+  seed: `0x${'82'.repeat(32)}`,
+  required: { participants: ['room', 'ripple'], layers: ['room', 'ripple'] },
+});
+const runner = createProductionScenarioRunner({
+  scenario: defined.scenario,
+  participants,
+  compositorLayers,
+  host,
+});
+const evidence = await runner.run([{ type: 'click', selector: '#whistle' }, { type: 'step', frames: 2 }]);
+```
+
+CI and local Vitest execute that same definition. Full contract, matrix axes, and one-command reproduce: [production scenario](docs/production-scenario.md).
+
+## Selection trace
+
+Why this binding, revision, asset, or caption won — not a second debugger. Same query/export API in the browser package and headless. There is no Player UI.
+
+```ts
+import { createSelectionTrace, attachSelectionTrace } from '@cyberart-io/engine';
+
+const trace = createSelectionTrace({
+  projectionWhitelist: ['inventory', 'roomId'],
+});
+trace.recordSelectionDecision({
+  kind: 'asset',
+  reason: 'text-only-fallback',
+  summary: 'npc audio not ready; caption selected',
+  correlationId,
+  asset: { logicalRef: 'npc.line.audio', ready: false, fallback: 'npc.line.caption' },
+});
+const exported = trace.exportTrace({ correlationId });
+const evidence = attachSelectionTrace(bundle, exported);
+```
+
+Reason codes, redaction, and one-command reproduce: [selection trace](docs/selection-trace.md).
+
+## Job orchestration
+
+Durable lifecycle for long-running generated work: queued → claimed → awaiting-evaluation → ready → applied, plus retry / failed / canceled / superseded. Results are refs (`uri` + `kind`), not embedded media. Wall-clock completion never mutates authoritative host state; the host calls `accept(jobId)` on `ready` under its own policy.
+
+```ts
+import { createHeadlessJobWorker, createJobCoordinator } from '@cyberart-io/engine/headless';
+
+const worker = createHeadlessJobWorker();
+const jobs = createJobCoordinator({ definitions: [frontierDefinition], worker, now: () => clock });
+const submitted = jobs.submit({
+  definitionId: 'frontier-generate',
+  idempotencyKey: 'frontier:day-1',
+  request: { prompt: '...', seed },
+  correlationId: playerIntentId,
+});
+if (!submitted.ok) throw new Error(submitted.errors.map((e) => e.detail).join('; '));
+const jobId = submitted.job.id;
+jobs.claim('worker-1');
+worker.complete(jobId, { schemaVersion: 1, kind: 'world-chunk', uri: 'ref://...' });
+jobs.evaluate(jobId, 'accept');
+jobs.accept(jobId); // host policy decides when
+```
+
+Production hosts import `createJobCoordinator` from `@cyberart-io/engine` and persist `snapshot()` in envelope `hostState`. Leases, evaluator revisions, and redacted trace export: [job orchestration](docs/job-orchestration.md).
+
+## World graph
+
+Optional spatial graph for rooms, regions, frontiers, discovery, and entity transit. Stable host-authored ids, canonical vs per-observer known projections, `open` / `locked` / `disabled` edges with opaque lock JSON, and host-supplied semantic time. It does not render maps or encode quest rules.
+
+```ts
+import { createWorldGraph } from '@cyberart-io/engine';
+
+const graph = createWorldGraph({ graphId: 'adventure' });
+graph.applyPatch({ nodes, edges }); // atomic; failure rolls back
+graph.discover('walker', { nodeIds: ['lodge', 'room-1'], edgeIds: ['lodge-room-1'] });
+const minimap = graph.projectLocal('walker', 'room-1');
+const path = graph.findPath('lodge', 'station', hostPolicy, { semanticTime: day });
+```
+
+Transit, migrations, `world.graph.*` contracts: [world graph](docs/world-graph.md).
+
+## World patch
+
+Transactional validation and atomic application of a generated world patch. Rooms, exits, characters, assets, dialogue, graph edges, and presentation bindings become one world revision or none. Stale `baseRevision` is rejected (no silent rebase); re-submitting an accepted `patchId` is idempotent.
+
+```ts
+import { createMemoryWorldPersistence, createWorldPatchApplier } from '@cyberart-io/engine';
+
+const world = createWorldPatchApplier({
+  persistence: createMemoryWorldPersistence(),
+  content: { available: [{ revision: '8' }] },
+  bindings: { listedIds: ['lobby-room'] },
+  now: () => hostClock,
+});
+world.dryRun(patch); // diagnostics only, inspect() unchanged
+world.commit(patch); // one revision, or the previous world unchanged
+```
+
+Hosts inject their own `begin` / `applyWorldRevision` / `commit` / `rollback` persistence. Exactly one `world.patch.state.accepted` per revision: [world patch](docs/world-patch.md).
+
+## Content revision
+
+Atomic staging and commit of an external content revision (room art, masks, portraits, line audio). Every declared asset is resolved and validated before `activeBundle()` changes; consumers see the last known good revision or the new one, never a mix. Snapshots store exact revisions, never `"latest"`.
+
+```ts
+import {
+  createContentRevisionActivator,
+  createHostGrantSet,
+  createStaticContentAdapter,
+} from '@cyberart-io/engine';
+
+const activator = createContentRevisionActivator({
+  adapters: [createStaticContentAdapter({ revisions: catalogs })],
+  grants: createHostGrantSet(['audio']),
+});
+await activator.activate({ contentId: 'room-overlook', revision: '8' });
+activator.activeBundle(); // complete revision 8, or null
+activator.rollback();     // idempotent; last known good
+```
+
+`createRemoteContentAdapter({ fetch })` reads signed remote catalogs. Supersede, pin, health checks, and `content.revision.*` contracts: [content revision](docs/content-revision.md).
+
 ## Normalized geometry
 
 Shared 0–1 content-box coordinates, landmarks, and hit regions. Pixel `PresentationRegion` on the presentation adapter is unchanged.
@@ -653,7 +957,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/` (including compositor, visual layers, browser harness, replay inspector, MIDI, executable modules, snapshots, audio, and calculation carts), 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`, `CHANGELOG.md`, `docs/` (every guide listed under [Feature guides](#feature-guides)), and `package.json`. Add a `CHANGELOG.md` entry and bump `version` in the same commit; tag it `@cyberart-io/engine@<version>` and publish a GitHub release with the same notes. Site code that still imports `src/ui/lib/...` hits thin re-export shims so those paths keep working.
 
 ```bash
 pnpm run pack:engine