@vgai/engine 0.2.0 → 0.4.0-canary.20260715.0

package/src/react/game-state.tsx

@@ -1,8 +1,9 @@
 /**
- * Engine-PUBLISHED `GameProvider`/`useGame`/`useGameState`/`useWorldObservation`
- * (D-Z5, `docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md` §D-Z5) — the canonical,
- * opt-in react entry for the T7.4 state bridge (`docs/REACT-STATE-BRIDGE.md`
- * §3). This is a SEPARATE, react-value-importing module under
+ * Canonical `GameProvider`/`useGame`/`useGameState`/`useWorldObservation`
+ * entry for React adapter roots. Also home to `useDebugProvider` and
+ * `useDebugCommand`/`useDebugEmit`, the React-facing debug seam.
+ *
+ * This is a SEPARATE, react-value-importing module under
  * `packages/engine/src/react/` — colocated per REACT-STATE-BRIDGE §3's own
  * "colocate the react-facing hooks with the HUD seam, not the react-free
  * core" rule, just now living IN the engine package rather than only in the
@@ -11,34 +12,26 @@
  * invariant is proved by `packages/engine/test/react-core-import-ban.test.ts`
  * (AC-F1).
  *
- * This module is the SPEC others port faithfully: it was originally authored
- * as `packages/editor/template/src/ui/game-state.tsx` (T7.4); that file is
- * now a thin re-export of this one (D-Z5 step 3) so every NEW scaffolded
- * project gets ONE canonical context, while existing projects with their own
- * full copy (their own `createContext`) keep working untouched — adoption of
- * THIS module is an option, never a forced migration (D-Z5).
- *
- * Context-identity landmine (unchanged from the template file's own history,
- * still the reason `loadProjectGameProvider`/the virtual-module plugin exist
- * in `packages/editor/src/adapter-resolver.ts` /
- * `packages/editor/vite-plugin-react-world-provider.ts`): `<GameProvider>`
- * and `useGame()` must resolve against the SAME `createContext()` call. A
- * project that ships its OWN `src/ui/game-state.tsx` (its own
- * `createContext`) must be wrapped by ITS OWN `GameProvider` — wrapping it
- * with THIS module's `GameProvider` instead would split context and
- * `useGame()` would throw "no Game in context" even though a `<GameProvider>`
- * genuinely wraps the tree (proved by
- * `packages/editor/test/game-state-context-split.test.tsx`, AC-F1). This is
- * exactly why the engine-published fallback (`resolveIngestReactAdapter`'s
- * D-Y3 upgrade, `default-react`'s optional fallback) only ever fires when the
- * project's OWN `src/ui/game-state.tsx` is ABSENT — an unmodified foreign
- * entry that imports no vgai hooks has no context to split.
+ * Every host and game imports this one module, so provider and hooks share
+ * one `createContext()` identity. The engine core outside `src/react/`
+ * remains React-free, enforced by `react-core-import-ban.test.ts`.
  */
 
-import { createContext, type ReactNode, useContext, useRef, useSyncExternalStore } from 'react';
+import {
+  createContext,
+  type PropsWithChildren,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useSyncExternalStore,
+} from 'react';
+import type { z } from 'zod';
 import type { WorldStateObserver } from '../adapter';
+import { getDebugRegistry } from '../runtime/debug-registry';
 import { createFrameSelectorCache, type Equals, shallow } from '../runtime/frame-selector-cache';
 import type { Game } from '../runtime/game';
+import type { DebugCommandArgs } from '../runtime/types';
 
 /** Re-exported for convenience — the opt-in equality for selectors that
  *  return a fresh object/array/tuple every call (default is `Object.is`). */
@@ -47,10 +40,21 @@ export { shallow };
 const GameContext = createContext<Game | null>(null);
 
 /** Provide the `Game` to `useGameState`/`useGame` for everything mounted
- *  beneath it. Compose it around whatever renders your tree (`mountUI`, a
- *  react world's `createRoot(...).render(...)`, etc.) — see the module doc
- *  comment above for the context-identity rule this hook family depends on. */
-export function GameProvider({ game, children }: { game: Game; children: ReactNode }) {
+ *  beneath it. Adapter-root hosts install this provider automatically — see the module doc
+ *  comment above for the context-identity rule this hook family depends on.
+ *
+ *  Props use `PropsWithChildren` (children optional in the TYPE, not
+ *  runtime-optional in practice — you always want children mounted under
+ *  the provider) rather than a bare `{ children: ReactNode }` field: a
+ *  required `children` in `P` makes TS's `createElement<P>(type, props?:
+ *  Attributes & P, ...children)` overload reject the plain 3-arg call
+ *  `React.createElement(GameProvider, { game }, child)` (no JSX transform,
+ *  e.g. a `.ts` main composing a sibling `.tsx` HUD) with "Property
+ *  'children' is missing" even though the 3rd arg supplies it — issue #97.
+ *  Making `children` optional in the type lets that overload resolve; the
+ *  rest-arg children are still wired through to `children` at runtime by
+ *  React itself, unchanged. See `test/game-state-create-element-types.test.tsx`. */
+export function GameProvider({ game, children }: PropsWithChildren<{ game: Game }>) {
   return <GameContext.Provider value={game}>{children}</GameContext.Provider>;
 }
 
@@ -109,7 +113,7 @@ export function requireWorldObserver(game: Game, worldId: string): WorldStateObs
   const world = game.world(worldId);
   if (!world) {
     throw new Error(
-      `useWorldObservation: no world registered with id "${worldId}" — check game.worlds for the ` +
+      `useWorldObservation: no world registered with id "${worldId}" — check game.roots for the ` +
         'ids actually registered.',
     );
   }
@@ -170,3 +174,102 @@ export function useWorldObservation<T>(
     () => cacheRef.current!.get(versionRef.current, () => selector(observer.snapshot())),
   );
 }
+
+/**
+ * The debug seam's react-world registration door (Task 1.5,
+ * `docs/SYNTHETIC-PLAYER-SPEC.md` §3.1): react roots have no `setup()`/
+ * `ctx.debug` of their own, so this hook registers a named state provider
+ * into the SAME game-scoped registry every `GameComponent`'s `ctx.debug`
+ * feeds (`getDebugRegistry(game)`, `runtime/debug-registry.ts`), readable
+ * through `game.systemAdapters.debug.state(name)` exactly like a
+ * `ctx.debug.registerStateProvider` call.
+ *
+ * Registers ONCE per mount (keyed on `name`) and unregisters on unmount —
+ * silently, like hot-reload's `strip()`. Re-renders never re-register or
+ * re-warn: `fn` is kept in a ref updated every render, so the registered
+ * closure always calls the CURRENT `fn` without touching the registry.
+ * Outside a `<GameProvider>` (or against a bare test `Game` built without a
+ * registry) this is an inert no-op — it never throws, matching the "no seam
+ * without a consumer" degrade every optional `ctx.*` surface follows.
+ */
+export function useDebugProvider(
+  name: string,
+  fn: () => unknown,
+  opts?: { tier?: 'observable' | 'assisted' },
+): void {
+  const game = useContext(GameContext);
+  const fnRef = useRef(fn);
+  fnRef.current = fn;
+  const tier = opts?.tier;
+
+  useEffect(() => {
+    const registry = game && getDebugRegistry(game);
+    if (!registry) return;
+    return registry.registerReactProvider(name, () => fnRef.current(), { tier });
+    // `tier` is deliberately NOT a dep (same reasoning as `useDebugCommand`'s
+    // `spec`) — captured once at mount, so it never forces re-registration.
+  }, [game, name]);
+}
+
+/**
+ * The command-side counterpart of {@link useDebugProvider} — registers an
+ * invokable debug command into the same game-scoped registry, readable
+ * through `game.systemAdapters.debug.commands()`/`invoke(name, args)`.
+ *
+ * Same mount/unmount/ref-latest contract as {@link useDebugProvider}: `spec`
+ * (description/args/locus) is captured at registration time, `fn` always
+ * calls through to the latest render's closure via a ref, and the hook is an
+ * inert no-op with no `<GameProvider>` in scope.
+ *
+ * Generic over the declared `args` Zod tuple, same as
+ * `DebugCtxSurface.registerCommand` ({@link DebugCommandArgs}, dry-run
+ * finding — `docs/ACCEPTANCE-DRIVER-BUILD-PLAN.md` Wave 6 ledger): declaring
+ * `args: z.tuple([z.number(), z.string()])` types `fn`'s parameters as
+ * `(n: number, s: string) => ...` with no `unknown[]` cast; omitting `args`
+ * keeps `fn` typed `(...args: unknown[]) => ...` as before.
+ */
+export function useDebugCommand<T extends z.ZodTuple | undefined = undefined>(
+  name: string,
+  spec: { description?: string; args?: T; locus?: 'client' | 'server' },
+  fn: (...args: DebugCommandArgs<T>) => unknown | Promise<unknown>,
+): void {
+  const game = useContext(GameContext);
+  const fnRef = useRef(fn);
+  fnRef.current = fn;
+
+  useEffect(() => {
+    const registry = game && getDebugRegistry(game);
+    if (!registry) return;
+    return registry.registerReactCommand(name, spec, (...args: DebugCommandArgs<T>) =>
+      fnRef.current(...args),
+    );
+    // `spec` is deliberately NOT a dep (like `equals` above) — captured once
+    // at mount, so a fresh inline object literal every render never forces
+    // re-registration.
+  }, [game, name]);
+}
+
+/**
+ * The event-side counterpart of {@link useDebugProvider} and
+ * {@link useDebugCommand}. Returns a stable callback that writes a
+ * tick-stamped event to the game-scoped debug flight recorder:
+ *
+ * ```tsx
+ * const emit = useDebugEmit();
+ * emit('score-changed', { score });
+ * ```
+ *
+ * It is an inert no-op outside a `<GameProvider>`, matching the optional
+ * behavior of the other React debug hooks. Games never need to import the
+ * debug registry or know its internal React provenance id.
+ */
+export function useDebugEmit(): (event: string, detail?: unknown) => void {
+  const game = useContext(GameContext);
+  return useCallback(
+    (event: string, detail?: unknown) => {
+      if (!game) return;
+      getDebugRegistry(game)?.emitReact(event, detail);
+    },
+    [game],
+  );
+}

package/src/react/root-adapter.tsx

@@ -0,0 +1,49 @@
+import { type ComponentType, createElement } from 'react';
+import { flushSync } from 'react-dom';
+import { createRoot } from 'react-dom/client';
+import type { MountedReactGame, ReactRootAdapter, ReactWorldHost } from '../runtime/create-runtime';
+import { isAdapterRegistered, registerAdapter } from '../runtime/mount-game';
+import { GameProvider } from './game-state';
+
+interface ReactEntryModule {
+  readonly default?: ComponentType;
+}
+
+/** Construct one canonical React root adapter for direct host composition. */
+export function createReactRootAdapter(id: string, Entry: ComponentType): ReactRootAdapter {
+  return {
+    id,
+    async mount(host: ReactWorldHost): Promise<MountedReactGame> {
+      if (!host.game) throw new Error(`React root "${id}" requires a Game host.`);
+      const reactRoot = createRoot(host.container);
+      flushSync(() => {
+        reactRoot.render(createElement(GameProvider, { game: host.game! }, createElement(Entry)));
+      });
+      return {
+        kind: 'react',
+        container: host.container,
+        drivesOwnLoop: false,
+        dispose: () => reactRoot.unmount(),
+      };
+    },
+  };
+}
+
+/**
+ * Register the engine's React adapter-root factory. This module is an
+ * explicit optional React entry point: engine core never imports it, while a
+ * React game host imports it once and receives the canonical root lifecycle.
+ */
+export function registerReactAdapter(): void {
+  if (isAdapterRegistered('react')) return;
+  registerAdapter('react', (root, { entryModule }) => {
+    const Entry = (entryModule as ReactEntryModule | undefined)?.default;
+    if (!Entry) {
+      throw new Error(
+        `React root "${root.id}" entry "${root.entry ?? '(missing)'}" must default-export a component.`,
+      );
+    }
+
+    return { kind: 'react', adapter: createReactRootAdapter(root.id, Entry) };
+  });
+}

package/src/react/unmanaged-root-detector.ts

@@ -0,0 +1,66 @@
+export interface UnmanagedReactRootFinding {
+  readonly file: string;
+  readonly line: number;
+  readonly api: 'createRoot' | 'hydrateRoot' | 'ReactDOM.render';
+}
+
+function lineAt(source: string, offset: number): number {
+  return source.slice(0, offset).split('\n').length;
+}
+
+/**
+ * Find project-owned React DOM root creation. VGAI hosts React through
+ * manifest adapter roots, so any of these calls in game source creates an
+ * unmanaged second lifecycle and is a hard validation error.
+ */
+export function detectUnmanagedReactRoots(
+  source: string,
+  file: string,
+): UnmanagedReactRootFinding[] {
+  const findings: UnmanagedReactRootFinding[] = [];
+  const aliases = new Map<string, 'createRoot' | 'hydrateRoot'>();
+
+  for (const match of source.matchAll(/import\s*\{([^}]*)\}\s*from\s*['"]react-dom\/client['"]/g)) {
+    for (const member of (match[1] ?? '').split(',')) {
+      const parsed = member.trim().match(/^(createRoot|hydrateRoot)(?:\s+as\s+([\w$]+))?$/);
+      if (parsed) aliases.set(parsed[2] ?? parsed[1]!, parsed[1] as 'createRoot' | 'hydrateRoot');
+    }
+  }
+
+  for (const [alias, api] of aliases) {
+    const call = new RegExp(`\\b${alias.replace(/[$]/g, '\\$&')}\\s*\\(`, 'g');
+    for (const match of source.matchAll(call)) {
+      findings.push({ file, line: lineAt(source, match.index ?? 0), api });
+    }
+  }
+
+  const namespaceNames = new Set<string>();
+  for (const match of source.matchAll(
+    /import\s+(?:\*\s+as\s+|)([\w$]+)\s+from\s*['"]react-dom(?:\/client)?['"]/g,
+  )) {
+    namespaceNames.add(match[1]!);
+  }
+  namespaceNames.add('ReactDOM');
+  for (const name of namespaceNames) {
+    for (const api of ['createRoot', 'hydrateRoot', 'render'] as const) {
+      const call = new RegExp(`\\b${name}\\.${api}\\s*\\(`, 'g');
+      for (const match of source.matchAll(call)) {
+        findings.push({
+          file,
+          line: lineAt(source, match.index ?? 0),
+          api: api === 'render' ? 'ReactDOM.render' : api,
+        });
+      }
+    }
+  }
+
+  return findings.filter(
+    (finding, index) =>
+      findings.findIndex(
+        (candidate) =>
+          candidate.file === finding.file &&
+          candidate.line === finding.line &&
+          candidate.api === finding.api,
+      ) === index,
+  );
+}

package/src/react/use-data.ts

@@ -0,0 +1,124 @@
+/**
+ * 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 roots 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 roots, 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`;
+
+  const transactionalWriter = (
+    globalThis as typeof globalThis & {
+      __vgaiHistoryWriteData?: (path: string, content: string) => Promise<void>;
+    }
+  ).__vgaiHistoryWriteData;
+  if (transactionalWriter) {
+    await transactionalWriter(projectRelativePath, content);
+    return;
+  }
+
+  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]);
+}