@vgai/engine 0.2.0 → 0.3.0

package/src/input/schema.ts

@@ -3,22 +3,36 @@
 // Was TS-types-only (`input-types.ts`) until T4.6 authored this Zod schema —
 // see docs/BACKBONE-TASKS.md T4.6. `InputManager.loadMap` (input-manager.ts)
 // is this schema's runtime reader: it parses via this schema, then copies
-// each action's `bindings` array straight into `this.actions`.
+// each action's `bindings` array (and its declared `valueType`, F1) straight
+// into `this.actions`/`this.actionValueTypes`.
 //
 // Every field has a `.describe()` (repo policy — powers
 // `scripts/generate-schema.ts` and the T4.1/T4.6 schema-walk coverage test).
 // No runtime dependency beyond `zod`, matching the `scene/schema/` and
 // `manifest/schema.ts` precedent.
 //
-// T4.1 inheritance: `input-manager.ts`'s `isPressed`/`isJustPressed`/
-// `isJustReleased` switch on `binding.type` and only ever handle `key`,
-// `mouse_button`, `gamepad_button`, and `gamepad_axis` — `mouse_move` and
-// `gamepad_axis_pair` are authored-but-unhandled binding kinds (mouse look is
-// read via a free-standing `mouseDelta`/`lookStick` accumulator that no
-// binding gates, and there is no code path that reads `xAxis`/`yAxis` as a
-// pair). Authoring either kind is a confirmed dead stub — REJECTED at parse,
-// mirroring the `scene/schema/ui.ts` dead-field mechanism (a `.superRefine`
-// that throws naming the field).
+// T4.1 history (now closed by F2): `mouse_move` and `gamepad_axis_pair` were
+// authored-but-unhandled binding kinds — REJECTED at parse via a `.superRefine`
+// that threw naming the field, mirroring the `scene/schema/ui.ts` dead-field
+// mechanism. F2 (spec §12 "Complete Device Backends") un-rejects both: real
+// `InputManager` readers now exist for them (`collectPointerDeltaContributions`/
+// `collectVector2Contributions` — `mouse_move` feeds pointerDelta/vector2 from
+// the existing mouseDelta accumulator; `gamepad_axis_pair` feeds vector2 from
+// the coupled `xAxis`/`yAxis` gamepad reading). F2 also adds two new LIVE
+// binding kinds, `touch_button`/`touch_stick` (the touch/virtual-control
+// backend — see `InputManager.setTouchButton`/`setTouchStick`).
+//
+// F1 (spec §12 "Define Typed Action Values") adds:
+//  - `InputAction.valueType` — an action now DECLARES its value shape
+//    (`digital`/`scalar`/`vector2`/`pointerDelta`/`pointerPosition`),
+//    defaulted to `digital` so every pre-F1 action stays valid unchanged.
+//  - four new, LIVE (not dead-rejected) binding kinds — `test_axis`,
+//    `test_vector2`, `test_pointer_delta`, `test_pointer_position` — the
+//    "injected test input" backend F2's acceptance criteria names as a
+//    peer of keyboard/mouse/gamepad/touch. They read back a caller-injected
+//    raw value (InputManager.injectAxis/injectVector2/injectPointerDelta/
+//    injectPointerPosition) through the SAME deadzone/normalize/combine path
+//    real device bindings use.
 
 import { z } from 'zod';
 import type { InputAction, InputBinding, InputMapFile } from './input-types';
@@ -37,8 +51,18 @@ const MouseMoveBindingSchema = z.object({
   type: z
     .literal('mouse_move')
     .describe(
-      'Binding kind: raw mouse movement. REJECTED at parse (T4.1/T4.6): declared but has no ' +
-        'runtime reader — authoring this binding throws. Do not author.',
+      'Binding kind: raw mouse movement (F2, spec §12 "Complete Device Backends"). Feeds a ' +
+        "'pointerDelta'-valueType action with the raw accumulated mouse delta (no deadzone), and " +
+        "can also feed a 'vector2'-valueType action (the same delta, radial-deadzoned + unit-" +
+        'circle-clamped via `deadzone`).',
+    ),
+  deadzone: z
+    .number()
+    .optional()
+    .describe(
+      "Radial deadzone magnitude applied only when this binding feeds a 'vector2'-valueType " +
+        "action (default 0 — no deadzone; ignored for 'pointerDelta' reads, which are never " +
+        'deadzoned).',
     ),
 });
 
@@ -61,57 +85,187 @@ const GamepadAxisPairBindingSchema = z.object({
     .literal('gamepad_axis_pair')
     .describe(
       'Binding kind: a coupled (x, y) gamepad axis pair, e.g. a stick used as a 2D vector ' +
-        '(look/aim). REJECTED at parse (T4.1/T4.6): declared but has no runtime reader — only ' +
-        '`gamepad_axis` (a single thresholded axis) is handled by isPressed/isJustPressed/' +
-        'isJustReleased. Authoring this binding throws. Do not author.',
+        '(look/aim/movement) (F2, spec §12 "Complete Device Backends"). Feeds a ' +
+        "'vector2'-valueType action: (xAxis, yAxis) read together, radial-deadzoned + unit-" +
+        'circle-clamped the same way a real analog stick is.',
     ),
   xAxis: z.number().describe('Standard Gamepad API axis index for the X component'),
   yAxis: z.number().describe('Standard Gamepad API axis index for the Y component'),
   deadzone: z.number().optional().describe('Deadzone magnitude (default 0.15 if omitted)'),
 });
 
-/**
- * A single input binding. `mouse_move`/`gamepad_axis_pair` are dead-by-decision
- * (see the per-variant `.describe()` above) — the `.superRefine` below is the
- * actual enforcement, mirroring `scene/schema/ui.ts`'s dead-field mechanism.
- */
-export const InputBindingSchema: z.ZodType<InputBinding> = z
-  .discriminatedUnion('type', [
-    KeyBindingSchema,
-    MouseButtonBindingSchema,
-    MouseMoveBindingSchema,
-    GamepadButtonBindingSchema,
-    GamepadAxisBindingSchema,
-    GamepadAxisPairBindingSchema,
-  ])
-  .superRefine((binding, ctx) => {
-    if (binding.type === 'mouse_move') {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message:
-          '`mouse_move` binding kind is authored but not implemented — InputManager.isPressed/' +
-          'isJustPressed/isJustReleased never handle it (mouse look is read via a free-standing ' +
-          'mouseDelta/lookStick accumulator, not gated by any action binding). See T4.1/T4.6.',
-        path: ['type'],
-      });
-    }
-    if (binding.type === 'gamepad_axis_pair') {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message:
-          '`gamepad_axis_pair` binding kind is authored but not implemented — no reader consumes ' +
-          '`xAxis`/`yAxis` as a coupled pair (only `gamepad_axis`, a single thresholded axis, is ' +
-          'handled by isPressed/isJustPressed/isJustReleased). See T4.1/T4.6.',
-        path: ['type'],
-      });
-    }
-  }) as z.ZodType<InputBinding>;
+// ---------------------------------------------------------------------------
+// F1 (spec §12) — injected test input bindings. LIVE (real runtime readers in
+// InputManager's getScalar/getVector2/getPointerDelta/getPointerPosition),
+// unlike the two dead stubs above. Foreshadows F2's "injected test input"
+// backend: real device kinds F2 adds later feed the same typed-value
+// aggregation path these exercise today.
+// ---------------------------------------------------------------------------
+
+const TestAxisBindingSchema = z.object({
+  type: z
+    .literal('test_axis')
+    .describe(
+      "Binding kind: an injected synthetic scalar value for a 'scalar'-valueType action " +
+        '(InputManager.injectAxis/getScalar) — the "injected test input" backend named in F2, ' +
+        "built in F1 as the typed scalar value model's testable source.",
+    ),
+  sourceId: z
+    .string()
+    .describe('Names the injected test source this binding reads (InputManager.injectAxis).'),
+  deadzone: z
+    .number()
+    .optional()
+    .describe(
+      '1D deadzone magnitude applied to the injected raw value before combine (default 0 — no ' +
+        'deadzone). Values below it read as 0; values at/above it rescale from 0 (at the ' +
+        'deadzone edge) to ±1 (at |raw| = 1), sign preserved.',
+    ),
+});
+
+const TestVector2BindingSchema = z.object({
+  type: z
+    .literal('test_vector2')
+    .describe(
+      "Binding kind: an injected synthetic {x,y} value for a 'vector2'-valueType action " +
+        '(InputManager.injectVector2/getVector2) — the "injected test input" backend named in ' +
+        "F2, built in F1 as the typed Vector2 value model's testable source.",
+    ),
+  sourceId: z
+    .string()
+    .describe('Names the injected test source this binding reads (InputManager.injectVector2).'),
+  deadzone: z
+    .number()
+    .optional()
+    .describe(
+      'Radial deadzone magnitude applied to the injected raw {x,y} before combine (default 0 ' +
+        '— no deadzone). Vectors whose magnitude is below it read as {0,0}; at/above it, ' +
+        'direction is preserved and magnitude rescales the same way the scalar deadzone does, ' +
+        'then the result is clamped to the unit circle (magnitude <= 1).',
+    ),
+});
+
+const TestPointerDeltaBindingSchema = z.object({
+  type: z
+    .literal('test_pointer_delta')
+    .describe(
+      "Binding kind: an injected synthetic per-frame {x,y} delta for a 'pointerDelta'-" +
+        'valueType action (InputManager.injectPointerDelta/getPointerDelta) — the "injected ' +
+        'test input" backend named in F2. No deadzone (deltas are not deadzoned).',
+    ),
+  sourceId: z
+    .string()
+    .describe(
+      'Names the injected test source this binding reads (InputManager.injectPointerDelta).',
+    ),
+});
+
+const TestPointerPositionBindingSchema = z.object({
+  type: z
+    .literal('test_pointer_position')
+    .describe(
+      "Binding kind: an injected synthetic absolute {x,y} position for a 'pointerPosition'-" +
+        'valueType action (InputManager.injectPointerPosition/getPointerPosition) — the ' +
+        '"injected test input" backend named in F2.',
+    ),
+  sourceId: z
+    .string()
+    .describe(
+      'Names the injected test source this binding reads (InputManager.injectPointerPosition).',
+    ),
+});
+
+// ---------------------------------------------------------------------------
+// F2 (spec §12 "Complete Device Backends") — touch/virtual-control bindings.
+// LIVE (real runtime readers in InputManager's isPressed/isJustPressed/
+// isJustReleased/getDigitalSource and getVector2), driven by
+// InputManager.setTouchButton/setTouchStick — the headless-testable
+// injectable entry points a real on-screen touch-control UI's own
+// touchstart/touchmove/touchend handlers would call (that DOM wiring is a
+// thin adapter at the edge, out of scope here — see input-manager.ts).
+// ---------------------------------------------------------------------------
+
+const TouchButtonBindingSchema = z.object({
+  type: z
+    .literal('touch_button')
+    .describe(
+      "Binding kind: a virtual on-screen button for a 'digital' action " +
+        '(InputManager.setTouchButton/isPressed) — edge-tracked (isJustPressed/isJustReleased) ' +
+        'the same way a real mouse/keyboard button is.',
+    ),
+  sourceId: z
+    .string()
+    .describe(
+      'Names the virtual control zone this binding reads (InputManager.setTouchButton) — a ' +
+        'touch-UI-chosen id, not a real device index.',
+    ),
+});
+
+const TouchStickBindingSchema = z.object({
+  type: z
+    .literal('touch_stick')
+    .describe(
+      "Binding kind: a virtual on-screen analog stick for a 'vector2' action " +
+        '(InputManager.setTouchStick/getVector2) — radial-deadzoned + unit-circle-clamped the ' +
+        'same way a real gamepad stick is.',
+    ),
+  sourceId: z
+    .string()
+    .describe(
+      'Names the virtual control zone this binding reads (InputManager.setTouchStick) — a ' +
+        'touch-UI-chosen id, not a real device index.',
+    ),
+  deadzone: z
+    .number()
+    .optional()
+    .describe(
+      'Radial deadzone magnitude applied to the raw {x,y} before combine (default 0 — no ' +
+        'deadzone).',
+    ),
+});
+
+/** A single input binding. Every kind listed here is LIVE — F2 (spec §12) closed the last two
+ *  dead stubs (`mouse_move`/`gamepad_axis_pair`) by giving both real `InputManager` readers. */
+export const InputBindingSchema: z.ZodType<InputBinding> = z.discriminatedUnion('type', [
+  KeyBindingSchema,
+  MouseButtonBindingSchema,
+  MouseMoveBindingSchema,
+  GamepadButtonBindingSchema,
+  GamepadAxisBindingSchema,
+  GamepadAxisPairBindingSchema,
+  TestAxisBindingSchema,
+  TestVector2BindingSchema,
+  TestPointerDeltaBindingSchema,
+  TestPointerPositionBindingSchema,
+  TouchButtonBindingSchema,
+  TouchStickBindingSchema,
+]) as z.ZodType<InputBinding>;
 
 /** An action has a name (the record key) and one or more bindings. */
 export const InputActionSchema: z.ZodType<InputAction> = z.object({
+  valueType: z
+    .enum(['digital', 'scalar', 'vector2', 'pointerDelta', 'pointerPosition'])
+    .default('digital')
+    .describe(
+      "This action's declared value shape (F1, spec §12). 'digital' (boolean, with " +
+        'pressed/justPressed/justReleased edges) is the default when omitted, matching every ' +
+        "action authored before F1. 'scalar' is a single deadzone-rescaled float axis. " +
+        "'vector2' is a radial-deadzoned, unit-circle-normalized {x,y}. 'pointerDelta' is a " +
+        "per-frame {x,y} movement delta, summed across sources. 'pointerPosition' is an " +
+        'absolute {x,y}, last-write-wins across sources. InputManager enforces this at read ' +
+        'time: reading an action through the wrong typed getter (e.g. getScalar on a ' +
+        "'digital' action) throws.",
+    ),
   bindings: z
     .array(InputBindingSchema)
-    .describe('Bindings that all trigger this action (any one firing is enough)'),
+    .describe(
+      'Bindings that all trigger/feed this action. Digital actions combine via OR (any one ' +
+        'binding satisfied is enough). Scalar actions combine via max-magnitude across ' +
+        'contributing bindings (ties keep the first-listed binding). Vector2 actions combine ' +
+        'by summing contributing {x,y} values then clamping to the unit circle. PointerDelta ' +
+        'actions sum contributing deltas. PointerPosition actions use the most-recently-' +
+        'written contributing source (last-write-wins).',
+    ),
 });
 
 /**

package/src/react/use-data.ts

@@ -0,0 +1,114 @@
+/**
+ * React hooks for data assets — the tool-hooks half of
+ * `docs/DATA-TOOLS-DESIGN.md` §3.3, shipped with W4 (dock tools).
+ *
+ * Lives under `packages/engine/src/react/` deliberately: this is the ONE
+ * directory of the engine allowed to value-import react (colocated with
+ * `game-state.tsx` per the react-free-core rule proved by
+ * `test/react-core-import-ban.test.ts`). Game worlds that aren't react keep
+ * using `DataHandle.get()`/`subscribe()` directly (§2.3).
+ *
+ * - {@link useData} — subscribe a component to any W1 `DataHandle`; works in
+ *   project tools, react worlds, and HUD overlays alike.
+ * - {@link writeData} — EDITOR-TOOL plumbing: write a whole `.data.json`
+ *   back through the editor dev server, closing the live-tuning loop
+ *   (widget → file write → Vite HMR → `hotSwap` → {@link useData} re-render
+ *   → the running game reads the new value). Not for game code.
+ */
+
+import { useSyncExternalStore } from 'react';
+import type { DataHandle } from '../data/data-asset';
+
+/**
+ * Read a data asset's current values and re-render whenever a hot edit lands
+ * (§3.3). A thin `useSyncExternalStore` over the handle's
+ * `subscribe`/`get` — any `defineData` handle works, no provider needed:
+ *
+ * ```tsx
+ * import { tuning } from '../data/tuning';
+ * const values = useData(tuning);   // fresh parsed object after every hotSwap
+ * ```
+ *
+ * `get()` returns the same reference between successful hot swaps, so this
+ * re-renders exactly once per accepted edit and never in between.
+ */
+export function useData<T>(handle: DataHandle<T>): T {
+  return useSyncExternalStore(
+    (onStoreChange) => handle.subscribe(() => onStoreChange()),
+    () => handle.get(),
+  );
+}
+
+/**
+ * Write a data asset's ENTIRE new value back to its `.data.json` — the write
+ * half of a project tool's live-tuning loop (§3.3, D1: writes are file
+ * writes, always). POSTs to the editor dev server's `/__editor/data-file`
+ * route (see its doc comment in `packages/editor/server/editor-server.ts`),
+ * which accepts only `src/data/**\/*.data.json` and writes immediately; the
+ * running game then receives the change through the normal `.data.json` HMR
+ * path, exactly as if VS Code had saved the file.
+ *
+ * ```tsx
+ * // inside a tool's onChange — spread the live values, replace one field:
+ * void writeData('src/data/tuning.data.json', { ...tuning.get(), gravity: v });
+ * ```
+ *
+ * FOR TOOLS, NOT GAME CODE: data assets are immutable at runtime (§2.1) —
+ * runtime state belongs in your game's own store, never written back into
+ * data files. Outside a running editor there is no `/__editor` server, so
+ * this rejects with a teaching error (a shipped game could never reach the
+ * route anyway — builds strip `src/tools/` entirely, §4).
+ *
+ * Serialization matches the editor Data panel's diff-minimal contract:
+ * `"$schema"` first, 2-space indent, trailing newline. When `value` carries
+ * no `"$schema"` key (the common case — `DataHandle.get()` strips it), the
+ * conventional sibling reference (`./<name>.schema.json`, §2.1) is restored
+ * so a tool write never silently drops VS Code validation from the file.
+ */
+export async function writeData(
+  projectRelativePath: string,
+  value: Record<string, unknown>,
+): Promise<void> {
+  if (!projectRelativePath.startsWith('src/data/') || !projectRelativePath.endsWith('.data.json')) {
+    throw new Error(
+      `writeData: invalid path ${JSON.stringify(projectRelativePath)} — data assets live at ` +
+        'src/data/**/*.data.json, addressed project-relative (docs/DATA-TOOLS-DESIGN.md §2.1), ' +
+        "e.g. writeData('src/data/tuning.data.json', next).",
+    );
+  }
+
+  // "$schema" first for minimal diffs; restore the conventional sibling
+  // reference when the caller's object (typically `{ ...handle.get() }`,
+  // which never carries it) omits the line.
+  const { $schema, ...rest } = value;
+  const schemaRef =
+    $schema ??
+    `./${projectRelativePath
+      .split('/')
+      .pop()
+      ?.replace(/\.data\.json$/, '')}.schema.json`;
+  const content = `${JSON.stringify({ $schema: schemaRef, ...rest }, null, 2)}\n`;
+
+  let res: Response;
+  try {
+    res = await fetch('/__editor/data-file', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ path: projectRelativePath, content }),
+    });
+  } catch (err) {
+    throw new Error(
+      'writeData: could not reach the editor dev server (/__editor/data-file) — this helper is ' +
+        'editor-tool plumbing (docs/DATA-TOOLS-DESIGN.md §3.3) and only works inside the running ' +
+        'editor. Game code must not write data assets: they are immutable at runtime (§2.1) — ' +
+        `keep runtime state in your game's own store. (${String(err)})`,
+    );
+  }
+  if (!res.ok) {
+    const detail = await res.text().catch(() => '');
+    throw new Error(
+      `writeData: the editor rejected the write to "${projectRelativePath}" ` +
+        `(HTTP ${res.status}${detail ? `: ${detail}` : ''}).`,
+    );
+  }
+}

package/src/react/use-selection.tsx

@@ -0,0 +1,135 @@
+/**
+ * W3.1 of docs/DATA-TOOLS-DESIGN.md §3.3 — `useSelection()`, the third
+ * tool-hooks contract member (alongside `useData`/`writeData` from
+ * `use-data.ts`). Where those two hooks are about DATA ASSETS, this one is
+ * about the currently-selected ENTITY and the components authored on it —
+ * the gap a real consumer (`critter-types-w3b`'s `critter-type.tool.tsx`,
+ * §9.4) hit hard: with no way to read a component's own authored config, it
+ * had to recover species from `node.label` (a display string, not data).
+ *
+ * Scope, v1:
+ *  - INSPECTOR-placement tools only (`placement: 'inspector'`,
+ *    `define-tool.ts`). `EditorSelectionProvider` is host plumbing —
+ *    `InspectorToolSection` wraps every tool render in it; dock tools
+ *    (`ToolHost`/`BottomPanel`) have no adapter/selection in scope and never
+ *    get a provider. Calling `useSelection()` there throws a teaching error,
+ *    contained by the tool's `ToolErrorBoundary` (the editor survives).
+ *  - READ-only. `config` is a shallow copy of the authored record; write
+ *    through `InspectorProvider.set('components.<Type>.<field>', v)` /
+ *    `writeData` (the existing paths), never by mutating what this hook
+ *    returns. Per-entity WRITE-from-tool is deferred with `useTunable` (§10).
+ *  - Honest degrades, not errors, when the adapter is thinner than the vgai
+ *    first-party one: no `components` provider at all ⇒ `components: []`;
+ *    a `components` provider present but with no optional `config()`
+ *    accessor ⇒ each entry still appears (from `list()`) but with
+ *    `config: null`. Both mirror the `AuthoringAdapter` optional-provider
+ *    doctrine (§4) — an ingest/UI adapter that never implements `components`
+ *    was already legal, and stays legal.
+ *
+ * Liveness — two existing paths reused, no new mechanism (§4's "reuse that
+ * path" rule):
+ *  1. Selection changes: `Inspector.tsx`'s own
+ *     `useSyncExternalStore(store.subscribe, store.getSnapshot)` re-renders
+ *     the panel, each matched `Section` gets the new `nodeId` prop, and
+ *     `InspectorToolSection` re-creates this provider's context value.
+ *  2. Config edits while the SAME node stays selected: `adapter.subscribe`
+ *     fires (the vgai adapter's store notifies on every `updateEntity`,
+ *     which is what `InspectorProvider.set` goes through) — this hook keeps
+ *     a local version counter bumped per notification (exactly
+ *     `game-state.tsx`'s `useWorldObservation` pattern: the adapter has no
+ *     snapshot/version of its own, `subscribe` is fire-only) and recomputes.
+ */
+
+import {
+  createContext,
+  type ReactNode,
+  useContext,
+  useMemo,
+  useRef,
+  useSyncExternalStore,
+} from 'react';
+import type { AuthoringAdapter, EditorNode } from '../adapter';
+
+interface SelectionContextValue {
+  adapter: AuthoringAdapter;
+  nodeId: string | null;
+}
+
+const SelectionContext = createContext<SelectionContextValue | null>(null);
+
+/**
+ * EDITOR-side host plumbing: `InspectorToolSection` wraps a tool's rendered
+ * `<Component/>` in this, passing the adapter + nodeId it already holds.
+ * Project tools never render this themselves — it exists so `useSelection()`
+ * has something to read.
+ */
+export function EditorSelectionProvider({
+  adapter,
+  nodeId,
+  children,
+}: {
+  adapter: AuthoringAdapter;
+  nodeId: string | null;
+  children: ReactNode;
+}) {
+  const value = useMemo(() => ({ adapter, nodeId }), [adapter, nodeId]);
+  return <SelectionContext.Provider value={value}>{children}</SelectionContext.Provider>;
+}
+
+/** One component attached to the selected entity, with its authored config
+ *  if the adapter can produce one (see the module doc's degrade rules). */
+export interface SelectedComponent {
+  type: string;
+  config: Record<string, unknown> | null;
+}
+
+export interface EditorSelection {
+  nodeId: string | null;
+  node: EditorNode | null;
+  components: SelectedComponent[];
+}
+
+/**
+ * The selected entity, live: its node, and every component attached to it
+ * with that component's own authored config (read-only — see module doc).
+ *
+ * Throws outside an `EditorSelectionProvider` — inspector tools always render
+ * inside one; a dock tool or game-code caller does not, and the error names
+ * the fix rather than failing silently.
+ */
+export function useSelection(): EditorSelection {
+  const ctx = useContext(SelectionContext);
+  if (!ctx) {
+    throw new Error(
+      'useSelection: no editor selection in context — this hook only works inside an editor-hosted ' +
+        "INSPECTOR tool (placement: 'inspector', docs/DATA-TOOLS-DESIGN.md §3.3/§3.2). Dock tools and " +
+        'game code have no selection to read.',
+    );
+  }
+  const { adapter, nodeId } = ctx;
+
+  // Local version counter bumped per adapter notification — the adapter has
+  // no snapshot/version of its own, `subscribe` is fire-only (same pattern
+  // as `useWorldObservation`'s `versionRef`, game-state.tsx).
+  const versionRef = useRef(0);
+  const version = useSyncExternalStore(
+    (onStoreChange) =>
+      adapter.subscribe?.(() => {
+        versionRef.current++;
+        onStoreChange();
+      }) ?? (() => {}),
+    () => versionRef.current,
+  );
+
+  return useMemo(() => {
+    const node = nodeId ? adapter.hierarchy.node(nodeId) : null;
+    const types = nodeId ? (adapter.components?.list(nodeId) ?? []) : [];
+    const components: SelectedComponent[] = types.map(({ type }) => ({
+      type,
+      config: nodeId ? (adapter.components?.config?.(nodeId, type) ?? null) : null,
+    }));
+    return { nodeId, node, components };
+    // `version` has no value of its own — only its CHANGE matters, as the
+    // liveness signal described above.
+  }, [adapter, nodeId, version]);
+}

package/src/runtime/create-runtime.ts

@@ -474,8 +474,8 @@ export async function createGameRuntime(config: RuntimeConfig): Promise<GameSess
     return createWorldsGameRuntime(config);
   }
   const { canvas, width, height, adapter, ...sceneConfig } = config;
-  const w = width ?? canvas.width;
-  const h = height ?? canvas.height;
+  const w = Math.max(1, width ?? canvas.width);
+  const h = Math.max(1, height ?? canvas.height);
 
   // --- Host primitives (neutral — no first-party assumptions) ---
   const renderer = createHostRenderer(canvas, w, h);
@@ -593,8 +593,10 @@ export async function createGameRuntime(config: RuntimeConfig): Promise<GameSess
       game.play.step();
     },
     resize(rw: number, rh: number) {
-      renderer.setSize(rw, rh);
-      mounted.resize?.(rw, rh);
+      const safeWidth = Math.max(1, rw);
+      const safeHeight = Math.max(1, rh);
+      renderer.setSize(safeWidth, safeHeight);
+      mounted.resize?.(safeWidth, safeHeight);
     },
     get scene() {
       return mounted.scene as THREE.Scene;
@@ -983,8 +985,14 @@ async function createWorldsGameRuntime(config: WorldsRuntimeConfig): Promise<Gam
   }
   const mountSpecs = specs as (ThreeWorldMountSpec | PixiWorldMountSpec | ReactWorldMountSpec)[];
 
-  const w = width ?? (container as HTMLElement & { clientWidth?: number }).clientWidth ?? 0;
-  const h = height ?? (container as HTMLElement & { clientHeight?: number }).clientHeight ?? 0;
+  const w = Math.max(
+    1,
+    width ?? (container as HTMLElement & { clientWidth?: number }).clientWidth ?? 0,
+  );
+  const h = Math.max(
+    1,
+    height ?? (container as HTMLElement & { clientHeight?: number }).clientHeight ?? 0,
+  );
   const dpr = headless
     ? 1
     : Math.min(typeof window !== 'undefined' ? window.devicePixelRatio || 1 : 1, 2);
@@ -1031,8 +1039,19 @@ async function createWorldsGameRuntime(config: WorldsRuntimeConfig): Promise<Gam
     surfacesById.set(entry.id, surface);
   });
 
-  // One shared UI overlay, above every canvas.
+  // One shared UI overlay, above every canvas. I8 render-integration seam
+  // (docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §15 I8, C1 review note):
+  // the legacy single-world path (above) reuses/stamps a stable `#example-ui`
+  // id so a capture host has a reliable selector for "the HUD/letterbox
+  // overlay" — this worlds path had no such id at all, so a render-mode page
+  // built on `createWorldsGameRuntime` (multi-world manifests, including a
+  // react-HUD-over-threejs cinematic) had no stable selector to composite-
+  // screenshot. `vgai-ui-overlay` is deliberately a DIFFERENT id than the
+  // legacy path's `example-ui` (not reused/aliased) — the two runtime paths
+  // mount genuinely different DOM subtrees, and collapsing them onto one id
+  // would make a caller's selector ambiguous about which mount produced it.
   const uiContainer = document.createElement('div');
+  uiContainer.id = 'vgai-ui-overlay';
   uiContainer.style.cssText =
     `position:absolute;top:0;left:0;width:100%;height:100%;pointer-events:none;` +
     `z-index:${stacked.length + 1};`;
@@ -1124,9 +1143,11 @@ async function createWorldsGameRuntime(config: WorldsRuntimeConfig): Promise<Gam
       game.play.step();
     },
     resize(rw: number, rh: number) {
+      const safeWidth = Math.max(1, rw);
+      const safeHeight = Math.max(1, rh);
       for (const entry of mountedEntries) {
-        entry.renderer?.setSize(rw, rh, false);
-        entry.mounted.resize?.(rw, rh);
+        entry.renderer?.setSize(safeWidth, safeHeight, false);
+        entry.mounted.resize?.(safeWidth, safeHeight);
       }
     },
     // `GameSession.scene`/`.camera`/`.mounted` alias `Game.defaultWorld` (T6.1