@vgai/engine 0.2.0

package/src/runtime/mount-manifest.ts

@@ -0,0 +1,361 @@
+// D-Z2 (docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md) — the standalone manifest-mount
+// helper: an ENGINE-side generalization of `examples/tri-world/src/main.ts`'s
+// hand-built `WorldMountSpec[]`.
+//
+// `resolveAllWorlds`/`resolveWorldAdapter` (`packages/editor/src/
+// adapter-resolver.ts`) already do this translation for the EDITOR, but they
+// are Vite-coupled by construction (`/@fs/` dynamic imports of project files
+// through the dev server, §0.1/§0.5 of the design doc) — unusable from a
+// plain static build. This module mirrors their per-kind dispatch
+// (`default-three`/`default-pixi`/`default-react`, `{ module }`, `{ ingest }`)
+// but never imports a project file itself: the caller's OWN bundler already
+// resolved whatever module graph the manifest's worlds need, and hands the
+// already-built pieces in via `entries` (keyed by world id) — no `/@fs/`, no
+// dev server, no editor import.
+//
+// Engine-core react/pixi-free discipline (§0.6, mirrored from
+// `create-runtime.ts`'s own documented rule for its `Pixi2DGameAdapter`/
+// `ReactWorldAdapter` type-only imports): this file never value-imports
+// `pixi.js`, `world2d/pixi-game-adapter.ts`, `react`, or `react-dom` — a
+// pixijs or react world's adapter is ALWAYS supplied already-constructed via
+// `entries[id].adapter` (the caller's own module graph built it, exactly like
+// `tri-world`'s original hand-mount built `new PixiSceneGameAdapter(...)` and
+// a hand-rolled `ReactWorldAdapter` itself). Threejs is different: `three`/
+// `VgaiSceneGameAdapter` are already unconditional dependencies of every
+// caller of `createGameRuntime`'s legacy path (this same file's sibling,
+// immediately below in this directory), so building a `VgaiSceneGameAdapter`
+// here for the common scene-driven/`setup`-driven cases adds no NEW bundle
+// weight — only pixi/react are avoided.
+
+import { fromSetup, VgaiSceneGameAdapter } from '../adapter';
+import type { GameAdapter } from '../adapter/game-adapter';
+import { assertNever } from '../adapter/world-kind';
+import {
+  loadGameManifest,
+  type ResolvedGameManifest,
+  type ResolvedWorldEntry,
+} from '../manifest/load';
+import type { ComponentRegistry } from '../scene/component-registry';
+import {
+  createGameRuntime,
+  type GameSession,
+  type Pixi2DGameAdapter,
+  type ReactWorldAdapter,
+  type WorldMountSpec,
+} from './create-runtime';
+import type { GameSetupFn } from './types';
+
+// ---------------------------------------------------------------------------
+// The `entries` contract
+// ---------------------------------------------------------------------------
+
+/**
+ * A caller-supplied entry for a `kind: 'threejs'` world — three ways to
+ * satisfy it, matching exactly what `tri-world`'s manifest actually declares
+ * (a scene-driven world with a project component registry) plus the two
+ * other shapes `resolveDefaultThreeAdapter` supports (an `entry`-module
+ * `setup`, or full caller control via a pre-built adapter):
+ *
+ *  - `{ adapter }` — a fully-constructed {@link GameAdapter} (first-party or
+ *    not). Always wins if present, regardless of the world's `scene`/`entry`
+ *    fields — full caller control, including for a `{ module }`-adapter world
+ *    (mountManifestWorlds cannot import an arbitrary module path itself).
+ *  - `{ setup }` — for an `entry`-declaring world: the project's own
+ *    `entry` module's exported `setup` function (the same `GameSetupFn`
+ *    shape `loadProjectScripts` extracts editor-side). Wrapped in a
+ *    `VgaiSceneGameAdapter` here, mirroring `resolveDefaultThreeAdapter`'s
+ *    entry branch exactly.
+ *  - `{ componentRegistry }` (or nothing at all) — for a `scene`-declaring
+ *    world: mirrors `resolveDefaultThreeAdapter`'s scene branch, fetching
+ *    `world.scene` itself via `VgaiSceneGameAdapter`'s own `scenePath`
+ *    support. `componentRegistry` is optional — omit it if the scene
+ *    authors no named `components:` entries.
+ */
+export interface ThreeMountEntry {
+  readonly kind: 'threejs';
+  readonly adapter?: GameAdapter | undefined;
+  readonly setup?: GameSetupFn | undefined;
+  readonly componentRegistry?: ComponentRegistry | undefined;
+}
+
+/**
+ * A caller-supplied entry for a `kind: 'pixijs'` world — ALWAYS a
+ * fully-constructed {@link Pixi2DGameAdapter} (e.g. `new
+ * PixiSceneGameAdapter({ id, sceneData })`, built exactly like `tri-world`'s
+ * original hand-mount built it — fetch+parse the `.scn2d.json` yourself,
+ * mirroring `resolveDefaultPixiAdapter`'s `fetchScene2DFile` helper, if the
+ * world declares `scene`). There is no "mountManifestWorlds builds it for
+ * you" branch here — doing so would require this file to value-import
+ * `pixi.js`, which it deliberately never does (see this file's header
+ * comment).
+ */
+export interface PixiMountEntry {
+  readonly kind: 'pixijs';
+  readonly adapter: Pixi2DGameAdapter;
+}
+
+/**
+ * A caller-supplied entry for a `kind: 'react'` world — ALWAYS a
+ * fully-constructed {@link ReactWorldAdapter} (the caller's own module graph
+ * calls `createRoot(host.container).render(<GameProvider game={host.game}>
+ * <Entry/></GameProvider>)` itself, exactly like `tri-world`'s original
+ * hand-mount did). A standalone build has ONE module graph, so there is no
+ * context-identity hazard the editor's per-project `GameProvider`
+ * indirection exists to solve (`docs/REACT-STATE-BRIDGE.md` §2) — the
+ * caller's own `<GameProvider>` import is already the single canonical
+ * instance its `Entry` component's own hooks resolve against. This file
+ * never value-imports `react`/`react-dom` itself (see this file's header
+ * comment) — building the adapter is entirely the caller's job.
+ */
+export interface ReactMountEntry {
+  readonly kind: 'react';
+  readonly adapter: ReactWorldAdapter;
+}
+
+export type MountEntry = ThreeMountEntry | PixiMountEntry | ReactMountEntry;
+
+// ---------------------------------------------------------------------------
+// Options / return shape
+// ---------------------------------------------------------------------------
+
+export interface MountManifestOptions {
+  /**
+   * A raw (unparsed) manifest value OR an already-`loadGameManifest`d
+   * {@link ResolvedGameManifest}. `mountManifestWorlds` NEVER fetches or
+   * fs-reads the manifest itself (stays environment-neutral — Node CLI,
+   * browser, or headless test alike): the caller owns getting the JSON off
+   * disk/network (`loadGameManifestFile` for Node, a plain `fetch()` for a
+   * browser build) and may pass either the raw parsed JSON (run through the
+   * pure `loadGameManifest` here) or its own already-resolved manifest.
+   */
+  readonly manifest: unknown;
+  /** The host creates one absolutely-positioned surface per world inside
+   *  this element — see `WorldsRuntimeConfig.container`. */
+  readonly container: HTMLElement;
+  /** Caller-supplied, already-imported entries keyed by manifest world id.
+   *  Optional overall — a manifest whose every world is scene-driven
+   *  threejs with no custom component registry needs none at all. */
+  readonly entries?: Readonly<Record<string, MountEntry>> | undefined;
+  /** Defaults to the manifest's own `resolution` field if declared, else
+   *  the container's own size (`WorldsRuntimeConfig`'s existing default). */
+  readonly width?: number | undefined;
+  readonly height?: number | undefined;
+  /** Forwarded to `createGameRuntime` — Node/headless test harnesses only,
+   *  never a real host. See `WorldsRuntimeConfig.headless`. */
+  readonly headless?: boolean | undefined;
+}
+
+// `mountManifestWorlds` returns the SAME `GameSession` shape
+// `createGameRuntime` returns (D-Z2: "the same session shape... or a thin
+// superset") — callers keep exactly one teardown path (`session.stop()`)
+// whether they mounted through `createGameRuntime` directly or through this
+// helper.
+export type MountedManifestSession = GameSession;
+
+// ---------------------------------------------------------------------------
+// Raw-vs-resolved manifest detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Distinguish an already-`loadGameManifest`d {@link ResolvedGameManifest}
+ * from a raw (pre-Zod-parse) manifest value. The two shapes differ in
+ * exactly one load-bearing way for this check: a `ResolvedWorldEntry.adapter`
+ * is `{ type: 'default' | 'module' | 'ingest', identity, ... }`, while a raw
+ * `WorldEntry.adapter` is the literal string `'default'` or a bare `{module}`/
+ * `{ingest}` object with NO `type`/`identity` fields (`schema.ts`'s
+ * `WorldAdapterSchema`). An empty `worlds` array is treated as "not resolved"
+ * (falls through to `loadGameManifest`, whose own Zod validation reports the
+ * empty-array error, if any, more precisely than a guess here could).
+ */
+function looksAlreadyResolved(value: unknown): value is ResolvedGameManifest {
+  if (typeof value !== 'object' || value === null) return false;
+  const worlds = (value as { worlds?: unknown }).worlds;
+  if (!Array.isArray(worlds) || worlds.length === 0) return false;
+  return worlds.every((world) => {
+    if (typeof world !== 'object' || world === null) return false;
+    const adapter = (world as { adapter?: unknown }).adapter;
+    if (typeof adapter !== 'object' || adapter === null) return false;
+    const type = (adapter as { type?: unknown }).type;
+    return type === 'default' || type === 'module' || type === 'ingest';
+  });
+}
+
+/**
+ * Exported (E4, docs/unified-world-editor/27-visual-react-editing.md §7) so
+ * `mount-game.ts`'s `mountGameFromManifest` composer can share this exact
+ * raw-vs-resolved detection instead of re-implementing it — the two modules
+ * must always agree on what "already resolved" means.
+ */
+export function resolveManifest(raw: unknown): ResolvedGameManifest {
+  if (looksAlreadyResolved(raw)) return raw;
+  return loadGameManifest(raw);
+}
+
+// ---------------------------------------------------------------------------
+// Per-kind entry -> adapter resolution (mirrors `resolveWorldAdapter`'s
+// per-identity dispatch, `packages/editor/src/adapter-resolver.ts`)
+// ---------------------------------------------------------------------------
+
+function resolveThreeAdapter(
+  world: ResolvedWorldEntry,
+  entry: ThreeMountEntry | undefined,
+): GameAdapter {
+  if (entry?.adapter) return entry.adapter;
+
+  if (world.adapter.type === 'module') {
+    throw new Error(
+      `mountManifestWorlds: world "${world.id}" (threejs) declares a { module } adapter ` +
+        `("${world.adapter.module}") — mountManifestWorlds never imports an arbitrary module ` +
+        'path itself (no `/@fs/`, no dev server). Import the module yourself and supply the ' +
+        `constructed adapter via entries["${world.id}"] = { kind: 'threejs', adapter }.`,
+    );
+  }
+  if (world.adapter.type === 'ingest') {
+    throw new Error(
+      `mountManifestWorlds: world "${world.id}" (threejs) declares an { ingest } adapter — ` +
+        "ingest worlds require the editor's dev-server-backed mount machinery (an EditorStore " +
+        "plus iframe/DOM capture, see adapter-resolver.ts's resolveIngestThreeAdapter) and are " +
+        'not supported by mountManifestWorlds (docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md D-Z7 — no ' +
+        'porting aids, no hosted ingest routes).',
+    );
+  }
+
+  // type === 'default'
+  if (world.entry !== undefined) {
+    if (!entry?.setup) {
+      throw new Error(
+        `mountManifestWorlds: world "${world.id}" (threejs) declares \`entry\` "${world.entry}" ` +
+          `— supply entries["${world.id}"] = { kind: 'threejs', setup } (the entry module's ` +
+          "exported `setup` function) or { kind: 'threejs', adapter } for full control. Got " +
+          `${entry === undefined ? 'no entry at all' : 'an entry with neither `setup` nor `adapter`'}.`,
+      );
+    }
+    return fromSetup(world.id, entry.setup);
+  }
+  if (world.scene !== undefined) {
+    return new VgaiSceneGameAdapter({
+      id: world.id,
+      scenePath: world.scene,
+      componentRegistry: entry?.componentRegistry,
+    });
+  }
+  // Unreachable in practice: `load.ts`'s `checkAdapterSceneEntryRules`
+  // requires `scene` or `entry` for every 'default' adapter world at
+  // manifest-load time — see `resolveDefaultThreeAdapter`'s identical guard.
+  throw new Error(
+    `mountManifestWorlds: world "${world.id}" is default-three with neither \`scene\` nor ` +
+      '`entry` — this should have been rejected by manifest validation.',
+  );
+}
+
+function resolvePixiAdapter(
+  world: ResolvedWorldEntry,
+  entry: PixiMountEntry | undefined,
+): Pixi2DGameAdapter {
+  if (entry?.adapter) return entry.adapter;
+  throw new Error(
+    `mountManifestWorlds: world "${world.id}" (pixijs) has no entries["${world.id}"] — a pixijs ` +
+      'world always needs a caller-supplied, already-constructed adapter ' +
+      `(entries["${world.id}"] = { kind: 'pixijs', adapter }, e.g. \`new PixiSceneGameAdapter(...)\` ` +
+      "built from your own already-imported '@engine/world2d') — mountManifestWorlds never " +
+      "value-imports pixi.js (mirrors create-runtime.ts's own pixi-free-core discipline).",
+  );
+}
+
+function resolveReactAdapter(
+  world: ResolvedWorldEntry,
+  entry: ReactMountEntry | undefined,
+): ReactWorldAdapter {
+  if (entry?.adapter) return entry.adapter;
+  throw new Error(
+    `mountManifestWorlds: world "${world.id}" (react) has no entries["${world.id}"] — a react ` +
+      'world always needs a caller-supplied, already-constructed `ReactWorldAdapter` ' +
+      `(entries["${world.id}"] = { kind: 'react', adapter }, mounting via your own already-imported ` +
+      'react-dom `createRoot` + your own `<GameProvider>`) — mountManifestWorlds never ' +
+      "value-imports react/react-dom (mirrors create-runtime.ts's own react-free-core discipline; " +
+      'see docs/REACT-STATE-BRIDGE.md §2-3).',
+  );
+}
+
+function buildWorldMountSpec(
+  world: ResolvedWorldEntry,
+  entry: MountEntry | undefined,
+): WorldMountSpec {
+  if (entry !== undefined && entry.kind !== world.kind) {
+    throw new Error(
+      `mountManifestWorlds: entries["${world.id}"] declares kind "${entry.kind}" but the ` +
+        `manifest's world "${world.id}" is kind "${world.kind}" — fix the entries key (or the ` +
+        'manifest) so the two agree.',
+    );
+  }
+
+  const base = {
+    id: world.id,
+    zOrder: world.zOrder,
+    pausable: world.pausable,
+    loop: world.loop,
+  };
+
+  // `entry`'s `kind` is guaranteed to agree with `world.kind` past the guard
+  // above (or `entry` is `undefined`) — TS can't narrow a `Record` lookup
+  // through that runtime check, so each branch casts to its own entry shape;
+  // the actual safety comes from the mismatch guard, not from the cast.
+  if (world.kind === 'threejs') {
+    const threeEntry = entry as ThreeMountEntry | undefined;
+    return { ...base, kind: 'threejs', adapter: resolveThreeAdapter(world, threeEntry) };
+  }
+  if (world.kind === 'pixijs') {
+    const pixiEntry = entry as PixiMountEntry | undefined;
+    return { ...base, kind: 'pixijs', adapter: resolvePixiAdapter(world, pixiEntry) };
+  }
+  if (world.kind === 'react') {
+    const reactEntry = entry as ReactMountEntry | undefined;
+    return { ...base, kind: 'react', adapter: resolveReactAdapter(world, reactEntry) };
+  }
+  // Exhaustiveness guard (§7.4-2, same idiom as `resolveAllWorlds`'s own
+  // dispatch loop): `world.kind` is the closed `WorldEntry['kind']` union
+  // (`z.enum(['threejs','pixijs','react'])`), so a hypothetical 4th kind
+  // must fail to compile here, not silently fall through.
+  return assertNever(world.kind, 'mountManifestWorlds');
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Mount every world declared by a `vgai.game.json` manifest onto `container`,
+ * standalone — no editor, no dev server. The generalization of
+ * `examples/tri-world/src/main.ts`'s hand-built `WorldMountSpec[]` (D-Z2,
+ * docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md). Reuses the pure `loadGameManifest`
+ * + `createGameRuntime({ worlds })` and mirrors `resolveAllWorlds`'s per-kind
+ * dispatch — but every entry the manifest needs beyond what a `default`-
+ * adapter scene/entry can express on its own comes from the caller's OWN
+ * already-imported module graph (`opts.entries`), never a dynamic import
+ * this file performs itself.
+ *
+ * Degrades loudly (docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md D-Z2): a missing
+ * entry, a kind/shape mismatch, a `{ module }`/`{ ingest }` adapter with no
+ * caller-supplied adapter, or an empty manifest all throw a named `Error`
+ * identifying the world id, its kind, and what was expected — never a silent
+ * skip or a partially-mounted session.
+ */
+export async function mountManifestWorlds(opts: MountManifestOptions): Promise<GameSession> {
+  const manifest = resolveManifest(opts.manifest);
+  if (manifest.worlds.length === 0) {
+    throw new Error('mountManifestWorlds: manifest declares no worlds — nothing to mount.');
+  }
+  const entries = opts.entries ?? {};
+
+  const worlds: WorldMountSpec[] = manifest.worlds.map((world) =>
+    buildWorldMountSpec(world, entries[world.id]),
+  );
+
+  return createGameRuntime({
+    container: opts.container,
+    worlds,
+    width: opts.width ?? manifest.resolution?.width,
+    height: opts.height ?? manifest.resolution?.height,
+    headless: opts.headless,
+  });
+}

package/src/runtime/scene-ui-bridge.ts

@@ -0,0 +1,86 @@
+/**
+ * Scene-UI render bridge (B1, widened design/24-scene-ui.md D3) — the injection
+ * seam that keeps the engine React-free.
+ *
+ * The engine knows the scene carries a `ui` tree (data), but it does NOT know how to
+ * render React. An editor-side module registers a renderer here (a thin wrapper over
+ * the React `mountSceneUI`); the first-party scene adapter calls it at game-time to
+ * mount the scene's UI into `host.ui` and disposes it on teardown. Fully decoupled:
+ * the engine treats `sceneUI` and the handle as opaque. The optional third `services`
+ * argument carries game-sourced data/components/events/projector (D2-D7) — still
+ * opaque to the engine, still zero React import here.
+ */
+
+/**
+ * Structural match for `@vgai/scene-ui`'s `UIDataSource` — engine stays React-free
+ * (this interface is duck-typed against the real one, not imported from it).
+ */
+export interface SceneUIDataSourceLike {
+  get(path: string): unknown;
+  set(path: string, value: unknown): void;
+  subscribe(listener: () => void): () => void;
+  version(): number;
+}
+
+/**
+ * Game-time services fed into a scene's UI mount (D2's "dynamic" layer). Every
+ * field is optional: a renderer falls back to its own registration-time registry
+ * (D2 merge rule) or built-in default when a field is absent. `components`/
+ * `transforms`/`strings` stay `unknown`-valued here — they're React things the
+ * scene-ui renderer casts to its real `UIComponentRegistry`/`TransformRegistry`/
+ * `StringTables`.
+ */
+export interface SceneUIGameServices {
+  /** Reactive game state the UI binds against (D4's `gameStateDataSource`, or a
+   *  game's own bus). Absent -> the renderer falls back to an empty static store. */
+  data?: SceneUIDataSourceLike;
+  /** `kind:"component"` leaf implementations, keyed by the name authored in the scene. */
+  components?: Record<string, unknown>;
+  /** Named binding transforms (`$bind.transform`). */
+  transforms?: Record<string, unknown>;
+  /** Localized string tables, keyed by locale then textKey. */
+  strings?: Record<string, Record<string, string>>;
+  locale?: string;
+  /** Routes a `kind:"button"` (etc.) `events.onClick` handler id to the game.
+   *  Absent -> a loud console.warn per event (D6 — no magic engine event bus). */
+  onEvent?: (handlerId: string, payload?: unknown) => void;
+  /** Projects an entity id to a screen-space point for world-tracked canvases
+   *  (D5). Returns null when the entity is unknown or behind the camera. */
+  worldProjector?: (entityId: string) => { x: number; y: number } | null;
+}
+
+export interface SceneUIHandle {
+  dispose(): void;
+  /** Re-render with new services without a remount (a late `setSceneUIServices`
+   *  call after the initial mount, D7). Optional — a renderer that can't update
+   *  in place may omit it; callers dispose+remount instead. */
+  update?(services: SceneUIGameServices): void;
+}
+
+/**
+ * Renderer signature — `sceneUI` is the scene's `ui` array (opaque to the engine).
+ * `services` is optional so existing 2-arg renderer functions keep working
+ * unchanged (back-compat, D3/D5 §5).
+ */
+export type SceneUIRenderer = (
+  container: HTMLElement,
+  sceneUI: unknown,
+  services?: SceneUIGameServices,
+) => SceneUIHandle;
+
+let _renderer: SceneUIRenderer | null = null;
+
+/** Register the React renderer (called once by the editor/runtime host). */
+export function setSceneUIRenderer(renderer: SceneUIRenderer | null): void {
+  _renderer = renderer;
+}
+
+/** Render a scene's UI into `container` if a renderer is registered, else no-op. */
+export function renderSceneUI(
+  container: HTMLElement,
+  sceneUI: unknown,
+  services?: SceneUIGameServices,
+): SceneUIHandle | null {
+  if (!_renderer || sceneUI == null) return null;
+  return _renderer(container, sceneUI, services);
+}

package/src/runtime/scene-ui-data.ts

@@ -0,0 +1,119 @@
+/**
+ * gameStateDataSource (design/24-scene-ui.md D4) — the default scene-UI data
+ * source: binds a scene's authored UI directly against live `GameComponent`
+ * instance fields, with zero game-side wiring.
+ *
+ * Path grammar: `"<ComponentName>.<field.path>"` — the first segment resolves
+ * through the SAME `ComponentRegistry` that resolves a scene's `components:`
+ * entries (name -> class) to `game.queryByComponent(Class)[0]`, the rest walks
+ * the live instance's own fields (components mutate `this` freely — the
+ * state-bridge contract, `runtime/state-bridge.ts`). A text node bound to
+ * `S1Session.wallet.money` just works.
+ *
+ * React-free, plain TS — `SceneUIDataSourceLike` is a structural (duck-typed)
+ * match for `@vgai/scene-ui`'s real `UIDataSource`, so the engine never
+ * imports the runtime that consumes this.
+ */
+import type { GameComponent, GameComponentClass } from '../ecs/game-component';
+import type { ComponentRegistry } from '../scene/component-registry';
+import type { Game } from './game';
+import type { SceneUIDataSourceLike } from './scene-ui-bridge';
+
+function splitRoot(path: string): [root: string, rest: string] {
+  const dot = path.indexOf('.');
+  return dot === -1 ? [path, ''] : [path.slice(0, dot), path.slice(dot + 1)];
+}
+
+function readRest(obj: unknown, rest: string): unknown {
+  if (!rest) return obj;
+  let cur: unknown = obj;
+  for (const key of rest.split('.')) {
+    if (cur == null || typeof cur !== 'object') return undefined;
+    cur = (cur as Record<string, unknown>)[key];
+  }
+  return cur;
+}
+
+/**
+ * Build the default `SceneUIDataSourceLike` over a game's live components.
+ *
+ * `subscribe`/`version` are driven by `game.state` (bumps once per completed
+ * frame, after every world's phases — see `state-bridge.ts`) PLUS a local
+ * bump on `set()`, so a two-way control's own write echoes immediately
+ * instead of waiting for the next frame.
+ */
+export function gameStateDataSource(
+  game: Game,
+  registry: ComponentRegistry,
+): SceneUIDataSourceLike {
+  let version = 0;
+  const listeners = new Set<() => void>();
+  // Warn-once-per-root-segment (D4/§9 review checklist): a scene author
+  // typo'ing a component name in a binding should be loud exactly once, not
+  // on every `get()` (a bound node re-reads its path every render).
+  const warnedRoots = new Set<string>();
+
+  const notify = (): void => {
+    for (const listener of listeners) listener();
+  };
+
+  /** Resolves a root segment to its live component instance, or undefined. */
+  const resolveInstance = (root: string): GameComponent | undefined => {
+    const Klass: GameComponentClass | undefined = registry[root];
+    if (!Klass) {
+      if (!warnedRoots.has(root)) {
+        warnedRoots.add(root);
+        console.warn(
+          `scene-ui: data binding root "${root}" is not a registered component name — ` +
+            'check the binding source against src/scripts/registry.ts.',
+        );
+      }
+      return undefined;
+    }
+    // Registered but zero live instances (e.g. not spawned yet this scene) is
+    // an ordinary, expected transient state — stays undefined, no warning.
+    return game.queryByComponent(Klass)[0];
+  };
+
+  // ONE subscription to the frame-versioned state bridge for this data
+  // source's whole lifetime, fanning out to however many external
+  // subscribers this scene-UI mount has.
+  game.state.subscribe(() => {
+    version++;
+    notify();
+  });
+
+  return {
+    get(path: string): unknown {
+      const [root, rest] = splitRoot(path);
+      const inst = resolveInstance(root);
+      return inst === undefined ? undefined : readRest(inst, rest);
+    },
+    set(path: string, value: unknown): void {
+      const [root, rest] = splitRoot(path);
+      const inst = resolveInstance(root);
+      if (inst === undefined || !rest) return;
+      const keys = rest.split('.');
+      let cur: Record<string, unknown> = inst as unknown as Record<string, unknown>;
+      for (let i = 0; i < keys.length - 1; i++) {
+        const key = keys[i] as string;
+        const next = cur[key];
+        if (next == null || typeof next !== 'object') return; // don't invent nested fields on a live instance
+        cur = next as Record<string, unknown>;
+      }
+      cur[keys[keys.length - 1] as string] = value;
+      // Two-way writes echo immediately, not on the next frame (D4).
+      version++;
+      notify();
+    },
+    subscribe(listener: () => void): () => void {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    version(): number {
+      return version;
+    },
+  };
+}

package/src/runtime/state-bridge.ts

@@ -0,0 +1,79 @@
+/**
+ * Frame-versioned game state bridge (T7.4 slice 1 — `docs/REACT-STATE-BRIDGE.md`
+ * §2, the D7 remainder). Components mutate state on `this` freely during
+ * ticks — there is no proxy, no dirty tracking, no event per mutation (Track
+ * A: no mirror, no sync layer). So the unit of change a subscriber can
+ * observe is the FRAME: `GameInternal.runFrame` bumps `frameVersion` and
+ * notifies subscribers at most once, at its tail, AFTER every phase of every
+ * world and every world's `endFrame` hook has run (see the wiring in
+ * `runtime/game.ts`) — mirroring the D7 "from `gameLogic` onward, every
+ * world's post-step state is readable" guarantee, extended to "after the
+ * frame, ALL state is readable".
+ *
+ * This file is plain, react-free TypeScript any consumer could use — no
+ * react import here, or anywhere under `runtime/` (the react-facing
+ * `useGameState` hook, which DOES import react, is deliberately colocated
+ * with the `mountUI` seam instead — see `packages/editor/template/src/
+ * ui/game-state.tsx`).
+ */
+
+/** Frame-versioned, react-free subscription surface — `docs/REACT-STATE-BRIDGE.md` §2. */
+export interface GameStateBridge {
+  /** Monotonic; bumped once per completed `runFrame`. Starts at 0 before the
+   *  first frame has ever completed. */
+  readonly frameVersion: number;
+  /** Notified at most once per frame, after ALL phases of ALL worlds (and
+   *  their `endFrame` hooks) have run. Returns an unsubscribe function. */
+  subscribe(onFrame: () => void): () => void;
+}
+
+/** Host-internal extension of {@link GameStateBridge}: adds `bump`, the
+ *  method `GameInternal.runFrame` calls at its tail. NOT part of the
+ *  game-facing `Game.state` surface (typed as the narrower
+ *  `GameStateBridge` there) — games/components/hooks never call `bump`
+ *  directly; only the frame executor does. */
+export interface GameStateBridgeInternal extends GameStateBridge {
+  /** Bump `frameVersion` by one and notify every current subscriber, in
+   *  subscription order. Subscriber errors are isolated (per-subscriber
+   *  try/catch, loud `console.error`, never swallowed silently) — mirrors
+   *  the error-isolation idiom in `ecs/component-manager.ts`'s per-component
+   *  `update()` calls: one offending subscriber must not stop its siblings
+   *  from being notified, and must not break the frame loop. */
+  bump(): void;
+}
+
+/**
+ * Construct a fresh bridge. One per `Game` (created alongside the other
+ * game-scoped state in `createGame`, `runtime/game.ts`).
+ */
+export function createStateBridge(): GameStateBridgeInternal {
+  let frameVersion = 0;
+  const subscribers = new Set<() => void>();
+
+  return {
+    get frameVersion() {
+      return frameVersion;
+    },
+    subscribe(onFrame: () => void): () => void {
+      subscribers.add(onFrame);
+      return () => {
+        subscribers.delete(onFrame);
+      };
+    },
+    bump(): void {
+      frameVersion++;
+      // Snapshot before iterating (same idiom as ComponentManager's
+      // per-phase `list = byPhase.get(phase)!.slice()`): a subscriber that
+      // subscribes/unsubscribes from WITHIN a notification must not affect
+      // which of ITS SIBLINGS get notified this same bump.
+      const notified = Array.from(subscribers);
+      for (const onFrame of notified) {
+        try {
+          onFrame();
+        } catch (err) {
+          console.error('[state-bridge] subscriber threw:', err);
+        }
+      }
+    },
+  };
+}