@vgai/engine 0.5.2 → 0.5.3

package/src/{scene → physics}/collider-dimensions.ts

@@ -23,8 +23,8 @@
  * than silently simulating (or rendering) the wrong shape.
  */
 
-import { DEFAULTS } from './defaults';
-import type { SceneCollider } from './scene-types';
+import type { ColliderDescriptor } from '../asset-formats/collider';
+import { DEFAULTS } from '../defaults';
 
 /** Axes are considered "uniform enough" within this tolerance (float error only). */
 const UNIFORM_SCALE_EPSILON = 1e-4;
@@ -51,7 +51,7 @@ export interface ColliderWorldDimensions {
  *   non-uniform world scale (beyond {@link UNIFORM_SCALE_EPSILON}).
  */
 export function computeColliderWorldDimensions(
-  collider: SceneCollider,
+  collider: ColliderDescriptor,
   worldScale: readonly [number, number, number],
   entityLabel: string,
 ): ColliderWorldDimensions {

package/src/physics/physics-registry.ts

@@ -13,7 +13,7 @@ export interface PhysicsRefs {
  *
  * Replaces the old bitecs RigidBodyRef/ColliderRef SoA components. Two indexes:
  *  - `Object3D → {body, collider}` for the postPhysics transform writer and for
- *    GameComponents/editor to reach an entity's physics.
+ *    game code/editor to reach an entity's physics.
  *  - `colliderHandle → Object3D` reverse index for collision/trigger dispatch
  *    (Rapier collision events report collider handles).
  */

package/src/{world2d/authoring-2d.ts → pixi/authoring.ts}

@@ -1,10 +1,10 @@
 import type { Container } from 'pixi.js';
 
 /**
- * AuthoringAdapter-2D — the world2d analog of the editor AuthoringAdapter /
- * IngestAuthoringAdapter, implemented DIRECTLY over a live PixiJS display tree
- * (no fabricated Scene2D / SceneEntity — the anti-shim rule). Used by the editor to
- * inspect + edit world2d entities (first-party OR an ingested unmodified game),
+ * AuthoringAdapter-2D — the Pixi analog of the editor AuthoringAdapter /
+ * LiveThreeAuthoringAdapter, implemented DIRECTLY over a live PixiJS display tree
+ * (no fabricated document — the anti-shim rule). Used by the editor to
+ * inspect + edit Pixi display-tree entities (first-party OR an ingested unmodified game),
  * with stable structural-path ids so edits re-bind after the tree rebuilds.
  */
 
@@ -29,7 +29,7 @@ export interface Property2D {
   value: unknown;
 }
 
-/** A persisted edit overlay keyed by structural-path id (the 2D analog of IngestOverlay). */
+/** An in-memory edit overlay keyed by structural-path id (2D). */
 export interface Override2D {
   label?: string;
   alpha?: number;
@@ -62,8 +62,16 @@ export class AuthoringAdapter2D {
     this.refresh();
   }
 
-  /** Walk the live tree assigning deterministic structural-path ids, reapply overlay. */
-  refresh(): { count: number; sprites: number } {
+  /**
+   * Walk the live tree assigning deterministic structural-path ids.
+   *
+   * Separate from {@link refresh} because the two are wanted at different rates: the ids have to be
+   * current whenever the tree is READ (a world that mounts its content asynchronously — a
+   * translated port waiting on its resources, anything behind Suspense — commits real nodes after
+   * the adapter was handed its root, and an unindexed node is one the hierarchy cannot name), while
+   * re-applying the edit overlay is a WRITE and must happen only when something asked for it.
+   */
+  reindex(): { count: number; sprites: number } {
     this.byId.clear();
     let count = 0;
     let sprites = 0;
@@ -80,11 +88,16 @@ export class AuthoringAdapter2D {
     this.root.children.forEach((c, i) => {
       visit(c as Container, `${i}`);
     });
-    // Reapply any saved overlay edits to the live tree.
-    for (const [id, ov] of Object.entries(this.overlay)) this.applyOverride(id, ov);
     return { count, sprites };
   }
 
+  /** {@link reindex}, then reapply every saved overlay edit to the live tree. */
+  refresh(): { count: number; sprites: number } {
+    const counts = this.reindex();
+    for (const [id, ov] of Object.entries(this.overlay)) this.applyOverride(id, ov);
+    return counts;
+  }
+
   roots(): EditorNode2D[] {
     return this.root.children.map((c) => this.toNode(c as Container));
   }
@@ -186,7 +199,7 @@ export class AuthoringAdapter2D {
    * it into the in-memory overlay so a later `serializeOverlay()`/save preserves it
    * and a later `refresh()` re-applies it again. Ids absent from the current tree
    * are skipped (orphaned, not an error) — the 2D analog of
-   * `IngestAuthoringAdapter.applyOverlay` (T3.2 slice 3). Used both for the initial
+   * `LiveThreeAuthoringAdapter.applyOverlay` (T3.2 slice 3). Used both for the initial
    * reload (constructor `opts.overlay`) and for `PersistenceProvider.applyExternal`
    * (re-apply a changed overlay file without a full remount).
    */
@@ -217,7 +230,7 @@ export class AuthoringAdapter2D {
     for (const [id, ov] of Object.entries(this.overlay)) this.applyOverride(id, ov);
     this.dirty = true;
   }
-  /** Clear the dirty flag after a successful save (mirrors IngestAuthoringAdapter). */
+  /** Clear the dirty flag after a successful save (mirrors LiveThreeAuthoringAdapter). */
   markClean(): void {
     this.dirty = false;
   }

package/src/pixi/index.ts

@@ -0,0 +1,43 @@
+/**
+ * pixi — the PixiJS surface substrate.
+ *
+ * PixiJS is opt-in: the engine core never imports it, so a three-only bundle
+ * never pays for it. What lives here is what the host needs to mount and
+ * inspect a PixiJS game it did not write — the render-call capture trap, the
+ * in-realm and iframe mounts, the live display-tree authoring adapter, and the
+ * Rapier-2D handle registry the editor's transform coordination reads.
+ */
+
+export {
+  AuthoringAdapter2D,
+  type EditorNode2D,
+  type Overlay2D,
+  type Override2D,
+  type Property2D,
+  type Transform2DValue,
+} from './authoring';
+export {
+  type ExtraDepsResolution2D,
+  type IngestGame2D,
+  type IngestMount2D,
+  mountIngestGame2D,
+} from './ingest';
+export {
+  type EmbedMount2D,
+  type IframeReachableMount2D,
+  type IframeReachableMultiOpts,
+  mountIngestGame2DEmbed,
+  mountIngestGame2DIframeReachable,
+  mountIngestGame2DIframeReachableMulti,
+} from './ingest-iframe';
+export {
+  createPhysics2DRegistry,
+  type Physics2DRefs,
+  type Physics2DRegistry,
+} from './physics-registry';
+export {
+  type CapturedRuntime2D,
+  installSceneCapture2D,
+  type SceneCapture2DHandle,
+} from './scene-capture';
+export { createPhysicsAdapter2D, type PhysicsAdapter2D } from './system-adapters';

package/src/{world2d/ingest-iframe-2d.ts → pixi/ingest-iframe.ts}

@@ -1,5 +1,5 @@
 /**
- * world2d iframe ingest tiers — the PixiJS analogs of the 3D ingest-iframe adapters.
+ * Pixi iframe ingest tiers — the PixiJS analogs of the 3D ingest-iframe adapters.
  *
  *  - OPAQUE EMBED (tier 0-1): a prebuilt/self-contained bundle runs in a sandboxed
  *    iframe; hosted + sized + disposed, NOT introspectable.
@@ -12,7 +12,7 @@ import {
   type CapturedRuntime2D,
   installSceneCapture2D,
   type SceneCapture2DHandle,
-} from './scene-capture-2d';
+} from './scene-capture';
 
 export interface EmbedMount2D {
   iframe: HTMLIFrameElement;
@@ -77,13 +77,13 @@ export interface IframeReachableMultiOpts {
    */
   extraDeps?: Record<string, Record<string, unknown>>;
   /**
-   * D-Z3 (docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md) — bare-specifier -> VERBATIM
-   * URL importmap entries (the project-node_modules fallback for a specifier
-   * that isn't in the host-namespace registry but IS installed in the open
-   * project's own `node_modules`). Written into the importmap DIRECTLY
-   * alongside the `extraDeps` blob-namespace entries — no host-side import,
-   * no blob wrapping, no decision logic here: this function just merges
-   * whatever `Record<specifier, url>` the caller (editor-side
+   * Bare-specifier -> VERBATIM URL importmap entries (the
+   * project-node_modules fallback for a specifier that isn't in the
+   * host-namespace registry but IS installed in the open project's own
+   * `node_modules`). Written into the importmap DIRECTLY alongside the
+   * `extraDeps` blob-namespace entries — no host-side import, no blob
+   * wrapping, no decision logic here: this function just merges whatever
+   * `Record<specifier, url>` the caller (editor-side
    * `host-namespace-registry.ts`) already decided. The URL's own transitive
    * `import 'pixi.js'` resolves through this SAME importmap back to the host
    * pixi trap (§0.3), keeping module identity converged without a second pixi

package/src/{world2d/ingest2d.ts → pixi/ingest.ts}

@@ -1,12 +1,12 @@
-import { installSceneCapture2D, type SceneCapture2DHandle } from './scene-capture-2d';
+import { installSceneCapture2D, type SceneCapture2DHandle } from './scene-capture';
 
 /**
- * D-Z3 (docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md) — a manifest's `extraDeps`
- * resolve to TWO kinds of importmap entry: `namespaces` are today's
- * registry-known bare specifiers (host-namespace-registry.ts), re-exported
- * via a blob module (`ingest-iframe-2d.ts`'s `makeHostNamespaceReexportUrl`);
- * `urls` are the D-Z3 fallback — a specifier that isn't registered but IS
- * present in the open project's own `node_modules`, mapped DIRECTLY to its
+ * A manifest's `extraDeps` resolve to TWO kinds of importmap entry:
+ * `namespaces` are today's registry-known bare specifiers
+ * (host-namespace-registry.ts), re-exported via a blob module
+ * (`ingest-iframe-2d.ts`'s `makeHostNamespaceReexportUrl`); `urls` are the
+ * D-Z3 fallback — a specifier that isn't registered but IS present in the
+ * open project's own `node_modules`, mapped DIRECTLY to its
  * `/project-game-static/node_modules/<spec>/<esm entry>` URL (no host-side
  * import, no blob — the dep executes in the iframe realm and its own
  * transitive `import 'pixi.js'` resolves through the same importmap back to
@@ -21,7 +21,7 @@ export interface ExtraDepsResolution2D {
   urls: Record<string, string>;
 }
 
-/** A registered unmodified PixiJS game (the world2d analog of `IngestGame`). */
+/** A registered unmodified PixiJS game (the Pixi analog of `IngestGame`). */
 export interface IngestGame2D {
   id: string;
   name: string;
@@ -32,18 +32,19 @@ export interface IngestGame2D {
   tier?: 'shared' | 'iframe-reachable' | 'opaque-embed';
   captureTimeoutMs?: number;
   /**
-   * IFRAME-REACHABLE-MULTI fields (Track P, docs/PIXI-INGEST-LANDING-DESIGN.md
-   * §2): an externalized built bundle mounted via
-   * `mountIngestGame2DIframeReachableMulti` (`./ingest-iframe-2d.ts`) instead
-   * of `load()` — populated only when `tier` is `'iframe-reachable'` AND
-   * `load` is absent. Mirror `IframeReachableMultiOpts`'s fields, EXCEPT
-   * `extraDeps`/`pixiNamespace` are THUNKS here, not resolved values — the
-   * same "lazy, only invoked at mount time" shape `load` already uses, so
-   * building this descriptor (`resolveIngest2DDescriptor` / `discovery2d.ts`,
-   * editor-side) never has to be async just to wire up which specifiers/
-   * version-skew URL a game needs; only actually MOUNTING it (the ingest-mode
-   * mount bridge) pays for the dynamic import of `@pixi/sound`/`gsap`/spine/
-   * a standalone pixi build.
+   * IFRAME-REACHABLE-MULTI fields (Track P): an externalized built bundle
+   * mounted via `mountIngestGame2DIframeReachableMulti`
+   * (`./ingest-iframe-2d.ts`) instead of `load()` — populated only when `tier`
+   * is `'iframe-reachable'` AND `load` is absent. Mirror
+   * `IframeReachableMultiOpts`'s fields, EXCEPT `extraDeps`/`pixiNamespace` are
+   * THUNKS here, not resolved values — the same "lazy, only invoked at mount
+   * time" shape `load` already uses, so building this descriptor
+   * (`resolveIngest2DDescriptor` / the canvas surface's
+   * `ingest/surface-canvas.ts`, editor-side — Wave 0.6 replaced the three
+   * per-surface `discovery*.ts` modules with one manifest-driven registry) never
+   * has to be async just to wire up which specifiers/ version-skew URL a game
+   * needs; only actually MOUNTING it (the ingest-mode mount bridge) pays for the
+   * dynamic import of `@pixi/sound`/`gsap`/spine/ a standalone pixi build.
    */
   bundleUrl?: string;
   /** <base href> for the iframe (see `IframeReachableMultiOpts.baseHref`). */
@@ -65,14 +66,13 @@ export interface IngestGame2D {
   /** DOM the game expects before boot (see `IframeReachableMultiOpts.bodyHtml`). */
   bodyHtml?: string;
   /**
-   * Lazily read an OPAQUE prebuilt bundle's self-contained HTML (D-W2,
-   * docs/WAVE4-FTUE-HARDENING-DESIGN.md) — the pixi twin of `IngestGame.embedHtml`.
-   * Always a lazy thunk here (no in-tree world2d opaque-embed fixture exists
-   * yet to need a plain-string form, unlike the three side):
-   * `resolveIngest2DDescriptor` (adapter-resolver.ts) builds one that reads
+   * Lazily read an OPAQUE prebuilt bundle's self-contained HTML (D-W2) — the pixi
+   * twin of `IngestGame.embedHtml`. Always a lazy thunk here (no in-tree Pixi
+   * opaque-embed fixture exists yet to need a plain-string form, unlike the three
+   * side): `resolveIngest2DDescriptor` (adapter-resolver.ts) builds one that reads
    * the declared `entryHtml` file's bytes through the `/project-game-static/`
-   * route, only when the game is actually mounted. The host runs the
-   * resolved HTML in a sandboxed iframe at the embed-only floor (Tier 0-1),
+   * route, only when the game is actually mounted. The host runs the resolved HTML
+   * in a sandboxed iframe at the embed-only floor (Tier 0-1),
    * `mountIngestGame2DEmbed` (`./ingest-iframe-2d.ts`).
    */
   embedHtml?: () => Promise<string>;
@@ -105,7 +105,7 @@ export async function mountIngestGame2D(
     await game.load?.();
   } catch (err) {
     capture.uninstall();
-    throw new Error(`world2d ingest: game "${game.id}" failed to load: ${err}`);
+    throw new Error(`pixi ingest: game "${game.id}" failed to load: ${err}`);
   }
 
   const timeout = opts.captureTimeoutMs ?? game.captureTimeoutMs ?? 8000;

package/src/{world2d/physics2d-registry.ts → pixi/physics-registry.ts}

@@ -9,7 +9,7 @@ export interface Physics2DRefs {
 
 /**
  * Maps PixiJS display objects to their Rapier 2D bodies/colliders and back —
- * the world2d analog of `PhysicsRegistry`. Two indexes:
+ * the Pixi analog of `PhysicsRegistry`. Two indexes:
  *  - `Container → {body, collider}` for the postPhysics transform writer.
  *  - `colliderHandle → Container` reverse index for collision/trigger dispatch.
  */

package/src/{world2d/scene-capture-2d.ts → pixi/scene-capture.ts}

@@ -1,5 +1,5 @@
 /**
- * Scene capture for world2d — the PixiJS analog of the three.js render
+ * Scene capture for the Pixi surface — the PixiJS analog of the three.js render
  * accessor-trap (`adapter/ingest/scene-capture.ts`).
  *
  * An unmodified PixiJS game owns its own `Application`, `stage`, renderer, and
@@ -18,7 +18,7 @@
  * way (degrade to iframe-reachable or opaque-embed tiers — see the spec).
  */
 
-/** A live world2d runtime captured from an external PixiJS game. */
+/** A live Pixi runtime captured from an external PixiJS game. */
 export interface CapturedRuntime2D {
   /** The game's root stage Container. */
   stage: unknown;
@@ -92,7 +92,7 @@ export function installSceneCapture2D(pixiNamespace: unknown): SceneCapture2DHan
           if (i >= 0) waiters.splice(i, 1);
           reject(
             new Error(
-              `world2d scene capture timed out after ${timeoutMs}ms — the game never ` +
+              `pixi scene capture timed out after ${timeoutMs}ms — the game never ` +
                 `rendered, or it bundles its own (un-shared) copy of pixi.js.`,
             ),
           );

package/src/{world2d/system-adapters-2d.ts → pixi/system-adapters.ts}

@@ -1,8 +1,8 @@
 import type { Container } from 'pixi.js';
-import type { Physics2DRegistry } from './physics2d-registry';
+import type { Physics2DRegistry } from './physics-registry';
 
 /**
- * PhysicsAdapter2D — the world2d analog of the 3D PhysicsAdapter (rapier-physics-adapter).
+ * PhysicsAdapter2D — the Pixi analog of the 3D PhysicsAdapter (rapier-physics-adapter).
  * Lets the editor coordinate editing of a Rapier-2D-driven entity WITHOUT owning the
  * simulation: report transform ownership, then freeze → commit → unfreeze so a drag
  * sticks instead of being stomped by the next physics step.

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

@@ -8,15 +8,40 @@ function lineAt(source: string, offset: number): number {
   return source.slice(0, offset).split('\n').length;
 }
 
+/**
+ * The project's own `dom`-root adapter implementation, which is ALLOWED to
+ * create a React root because creating it is the whole job.
+ *
+ * The rule here is "a React root must come from a declared manifest root, not
+ * from game code mounting a second lifecycle beside it". That held trivially
+ * while the only `createRoot` in existence lived in the engine. It stopped
+ * holding when the `react-root` capability moved INTO the project (`vgai add
+ * react-root`): its `createRoot` is precisely what serves a declared `dom`
+ * root — the opposite of bypassing the manifest.
+ *
+ * Matched on the capability's DIRECTORY rather than a filename, so that
+ * editing the copied source — the entire point of the copied-source model —
+ * cannot re-arm the rule against itself. A Vue or Svelte replacement never
+ * trips it at all: only React DOM's own API is detected.
+ */
+const DOM_ROOT_ADAPTER_DIR = /(^|[/\\])src[/\\]lib[/\\]react-root[/\\]/;
+
 /**
  * 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.
+ * unmanaged second lifecycle and is a hard validation error — except in the
+ * project's own dom-root adapter (see {@link DOM_ROOT_ADAPTER_DIR}).
+ *
+ * The exemption lives HERE, in the detector, rather than in either caller:
+ * the editor's validate-on-change watcher and `vgai validate` both scan the
+ * same tree, and a rule that means two different things depending on who asks
+ * is worse than no rule.
  */
 export function detectUnmanagedReactRoots(
   source: string,
   file: string,
 ): UnmanagedReactRootFinding[] {
+  if (DOM_ROOT_ADAPTER_DIR.test(file)) return [];
   const findings: UnmanagedReactRootFinding[] = [];
   const aliases = new Map<string, 'createRoot' | 'hydrateRoot'>();
 

package/src/react/use-data.ts

@@ -1,6 +1,6 @@
 /**
- * React hooks for data assets — the tool-hooks half of
- * `docs/DATA-TOOLS-DESIGN.md` §3.3, shipped with W4 (dock tools).
+ * React hooks for data assets — the tool-hooks half, 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
@@ -72,7 +72,7 @@ export async function writeData(
   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), ' +
+        'src/data/**/*.data.json, addressed project-relative, ' +
         "e.g. writeData('src/data/tuning.data.json', next).",
     );
   }
@@ -109,8 +109,8 @@ export async function writeData(
   } 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) — ' +
+        'editor-tool plumbing and only works inside the running ' +
+        'editor. Game code must not write data assets: they are immutable at runtime — ' +
         `keep runtime state in your game's own store. (${String(err)})`,
     );
   }

package/src/react/use-selection.tsx

@@ -1,11 +1,7 @@
 /**
- * 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).
+ * W3.1 — `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.
  *
  * Scope, v1:
  *  - INSPECTOR-placement tools only (`placement: 'inspector'`,
@@ -14,17 +10,9 @@
  *    (`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.
+ *  - READ-only. Write through `InspectorProvider.set` / `writeData` (the
+ *    existing paths), never by mutating what this hook returns. Per-entity
+ *    WRITE-from-tool is deferred with `useTunable` (§10).
  *
  * Liveness — two existing paths reused, no new mechanism (§4's "reuse that
  * path" rule):
@@ -32,12 +20,11 @@
  *     `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.
+ *  2. Edits while the SAME node stays selected: `adapter.subscribe` fires —
+ *     this hook keeps a local version counter bumped per notification
+ *     (exactly `game-state.tsx`'s `useRootObservation` pattern: the adapter
+ *     has no snapshot/version of its own, `subscribe` is fire-only) and
+ *     recomputes.
  */
 
 import {
@@ -76,22 +63,13 @@ export function EditorSelectionProvider({
   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).
+ * The selected entity, live (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
@@ -102,7 +80,7 @@ export function useSelection(): EditorSelection {
   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 " +
+        "INSPECTOR tool (placement: 'inspector'). Dock tools and " +
         'game code have no selection to read.',
     );
   }
@@ -110,7 +88,7 @@ export function useSelection(): EditorSelection {
 
   // 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).
+  // as `useRootObservation`'s `versionRef`, game-state.tsx).
   const versionRef = useRef(0);
   const version = useSyncExternalStore(
     (onStoreChange) =>
@@ -123,12 +101,7 @@ export function useSelection(): EditorSelection {
 
   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 };
+    return { nodeId, node };
     // `version` has no value of its own — only its CHANGE matters, as the
     // liveness signal described above.
   }, [adapter, nodeId, version]);