@vgai/editor 0.2.0

package/src/authoring/composite-authoring-adapter.ts

@@ -0,0 +1,891 @@
+/**
+ * CompositeAuthoringAdapter — merges N per-world {@link AuthoringAdapter}s into ONE
+ * authoring tree so the editor's hierarchy lists EVERY mounted world's entities and
+ * selection/inspection routes to the right backend. This is the
+ * editor-multi-root-selection seam, generalized to N-ary (T6.1 slice 3,
+ * docs/MULTI-WORLD-DESIGN.md §1.F — GAME-ROOT-DESIGN §6.4's v1 scope, verbatim):
+ * one top-level GROUP NODE per world (`world:<id> (<kind>)`), the child adapter's
+ * own roots nested beneath it. Routing is by GROUP-NODE OWNERSHIP (which child
+ * adapter's tree actually contains a given node id) — not the old 2-child `w2d:`
+ * id-prefix sniff, which cannot generalize past exactly one 2D surface.
+ *
+ * The editor still talks to a single {@link AuthoringAdapter}; selection +
+ * inspection work in every world; the 3D transform gizmo stays threejs-only (a
+ * viewport concern, outside this adapter); play/pause stays game-level (T7.6).
+ */
+
+import type {
+  AssetDropProvider,
+  AuthoringAdapter,
+  AuthoringCapabilities,
+  ComponentsProvider,
+  EditorNode,
+  FileMapProvider,
+  HierarchyProvider,
+  InspectorProvider,
+  PersistenceProvider,
+  PropertyDescriptor,
+  RootGroup,
+  RootGroupsProvider,
+  SelectionProvider,
+  StoriesProvider,
+  StoryRef,
+  StructureProvider,
+  Transform,
+  TransformOwner,
+  TransformProvider,
+} from '@engine/adapter';
+import type * as THREE from 'three';
+import { editorConsole } from '../editor-console';
+
+/** One child world's authoring adapter, ordered as given to the constructor. */
+export interface CompositeChild {
+  /** Manifest world id (T3.1) — becomes the group node id `world:<worldId>`. */
+  readonly worldId: string;
+  /** World render substrate kind — shown in the group node's label. */
+  readonly kind: string;
+  readonly adapter: AuthoringAdapter;
+  /**
+   * D12 (B4) — the world's INSTALL-TIME manifest zOrder (`world.zOrder ?? 0`),
+   * independent of this child's position in the constructor's array. Absent
+   * (every pre-B4 call site) ⇒ `childAdapters()` falls back to the array
+   * index, today's behavior unchanged. See `childAdapters()`'s own doc
+   * comment for why this stopped being "array order doubles as z-order" and
+   * what "install-time" means here.
+   */
+  readonly zOrder?: number;
+  /**
+   * C3 (docs/unified-world-editor/26-unified-editor-spec.md §4 C3) — nest
+   * this child's group node UNDER another child's group node instead of at
+   * the top level (directly under the synthetic `game` root, or as a bare
+   * top-level root when there is no `gameRoot`). Used by the scene-UI child
+   * (`edit-mode-authoring.ts`'s UI child, `kind: 'scene-ui'`) to appear
+   * "under its owning world" in the ONE hierarchy, per the C3 spec text.
+   * Absent ⇒ today's flat top-level shape, unchanged.
+   */
+  readonly parentWorldId?: string;
+}
+
+const GROUP_PREFIX = 'world:';
+const GAME_ROOT_ID = 'game';
+
+function groupNodeId(worldId: string): string {
+  return `${GROUP_PREFIX}${worldId}`;
+}
+
+/** True for a synthetic group-node id this Composite itself manufactures (never
+ *  produced by a child adapter — the `world:` prefix is reserved for this use). */
+function isGroupNodeId(id: string): boolean {
+  return id.startsWith(GROUP_PREFIX);
+}
+
+/**
+ * A4 (D8) — the game root's manifest-backed property surface, implemented by
+ * `edit-mode-authoring.ts`'s `ManifestAuthoring` over the RAW `vgai.game.json`
+ * (read-modify-write, never round-tripped through Zod). Defined here (not
+ * imported from `edit-mode-authoring.ts`) to avoid a circular import — that
+ * module already imports `CompositeAuthoringAdapter`.
+ */
+export interface GameRootManifestProvider {
+  /** True while no `vgai.game.json` exists on disk yet (a synthesized
+   *  in-memory manifest) — edits buffer in memory instead of writing. */
+  readonly synthesized: boolean;
+  getGameName(): string;
+  setGameName(name: string): void;
+  getWorldZOrder(worldId: string): number;
+  setWorldZOrder(worldId: string, value: number): void;
+  getWorldPausable(worldId: string): boolean;
+  setWorldPausable(worldId: string, value: boolean): void;
+}
+
+/** OR every child's capabilities together — a feature is offered if ANY
+ *  child supports it (the editor gates per-node via the routed adapter
+ *  anyway). Factored out of the constructor (B1) so {@link
+ *  CompositeAuthoringAdapter.replaceChild} can recompute it after an
+ *  in-place child swap without duplicating the reduce. */
+function computeCapabilities(children: ReadonlyArray<CompositeChild>): AuthoringCapabilities {
+  return children.reduce<AuthoringCapabilities>(
+    (acc, c) => ({
+      transform: acc.transform || c.adapter.capabilities.transform,
+      material: acc.material || c.adapter.capabilities.material,
+      inspectorFields: acc.inspectorFields || c.adapter.capabilities.inspectorFields,
+      create: acc.create || c.adapter.capabilities.create,
+      delete: acc.delete || c.adapter.capabilities.delete,
+      reparent: acc.reparent || c.adapter.capabilities.reparent,
+      persist: acc.persist || c.adapter.capabilities.persist,
+    }),
+    {
+      transform: false,
+      material: false,
+      inspectorFields: false,
+      create: false,
+      delete: false,
+      reparent: false,
+      persist: false,
+    },
+  );
+}
+
+export class CompositeAuthoringAdapter implements AuthoringAdapter {
+  /** NOT `readonly` (interface-level `readonly` is a consumer contract, not a
+   *  ban on internal reassignment) — B1's {@link replaceChild} recomputes
+   *  this after an in-place child swap (e.g. a world's design-time layer
+   *  mounting successfully upgrades its Boundary adapter to a live one). */
+  capabilities: AuthoringCapabilities;
+  /**
+   * NOT `ReadonlyArray` (B1): {@link replaceChild} mutates ONE element of
+   * this array in place, preserving both the array's own identity-adjacent
+   * invariants (length, index/z-order) and — critically — THIS composite's
+   * OWN object identity, which `ViewportPanel.tsx`'s teardown-identity
+   * capture, `exitEditModeAuthoring`'s installed-instance check, and the
+   * `markEditModeOverride` brand all key off. A REBUILT composite (a new
+   * `CompositeAuthoringAdapter` instance) would silently break all three —
+   * see this class's own doc comment and `edit-mode-authoring.ts`'s. Copied
+   * (`[...children]`) out of the constructor's `ReadonlyArray` parameter so
+   * mutating it here never aliases a caller's own array.
+   */
+  private readonly children: CompositeChild[];
+  /** A4 (D8) — present only when the caller wants a synthetic game-root node
+   *  wrapping every world group (edit-mode's manifest-disclosing composite);
+   *  absent for every other composite construction (play-mode's
+   *  `installMultiWorldAuthoring`), which keeps `hierarchy.roots()` returning
+   *  world group nodes directly, UNCHANGED from before A4. */
+  private readonly gameRoot: GameRootManifestProvider | null;
+
+  /**
+   * N-ary (T6.1 slice 3): an ordered `{ worldId, kind, adapter }[]` — one group
+   * node per entry, in array order.
+   *
+   * The 2-positional-arg legacy overload (`new CompositeAuthoringAdapter(world3d,
+   * world2d)`, normalizing to synthetic `'world3d'`/`'world2d'` ids) is REMOVED
+   * this slice (T6.1 slice 4, docs/MULTI-WORLD-DESIGN.md §1.H): its only
+   * production call site was `world2d-mode.ts`'s dev-console-only hook, deleted
+   * with the rest of the world2d silo. Every production caller now goes through
+   * the N-ary array constructor (`play-mode.ts`'s `installMultiWorldAuthoring`).
+   *
+   * `gameRoot` (A4, D8) is an opt-in second argument: `edit-mode-authoring.ts`
+   * passes a `ManifestAuthoring` instance to wrap every world group under one
+   * synthetic `game` root; every other caller omits it and gets today's
+   * shape (world groups as roots) byte-for-byte unchanged.
+   */
+  constructor(children: ReadonlyArray<CompositeChild>, gameRoot?: GameRootManifestProvider) {
+    this.children = [...children];
+    this.gameRoot = gameRoot ?? null;
+    if (children.length === 0) {
+      throw new Error('CompositeAuthoringAdapter: at least one child world is required.');
+    }
+    this.capabilities = computeCapabilities(this.children);
+  }
+
+  /**
+   * B1 — swap `worldId`'s child adapter IN PLACE (the design-time layer
+   * mount's "adapter upgrade": a world's read-only `BoundaryAuthoringAdapter`
+   * is replaced by a live one — react: `ReactWorldAuthoringAdapter` — once its
+   * layer mounts successfully; a layer that fails/throws rebuilds the
+   * Boundary with the caught reason, also through this method). Mutates the
+   * existing children array (preserving array order — z-order/`childAdapters()`
+   * index is unaffected) and recomputes `capabilities`, rather than
+   * constructing a new `CompositeAuthoringAdapter` — a rebuild would break
+   * `ViewportPanel.tsx`'s captured teardown identity, `exitEditModeAuthoring`'s
+   * installed-instance check, and the `markEditModeOverride` brand, all of
+   * which key off THIS instance's identity (see the class doc comment).
+   *
+   * No-op (loud warn, #18 discipline) when `worldId` doesn't name an existing
+   * child — never silently routes to the wrong world or grows the array.
+   * Callers are responsible for their own side effects around the swap
+   * (undo-timeline registration for a newly-live adapter,
+   * `store.notifyIngestEdit()` so panels re-render against the new child) —
+   * this method only owns the swap + capability recompute.
+   */
+  replaceChild(worldId: string, adapter: AuthoringAdapter): void {
+    const index = this.children.findIndex((c) => c.worldId === worldId);
+    if (index === -1) {
+      editorConsole.warn(
+        `[CompositeAuthoringAdapter] replaceChild: no child with worldId "${worldId}" — ignoring.`,
+        'authoring',
+      );
+      return;
+    }
+    // D12 (B4) — carry the outgoing child's `zOrder` forward too (not just
+    // `kind`): a swap must not silently reset a world's install-time zOrder
+    // back to "no override" (array-index fallback). Built conditionally (not
+    // `{ ..., zOrder }`) because `zOrder` is an OPTIONAL property under this
+    // repo's `exactOptionalPropertyTypes` — an explicit `zOrder: undefined`
+    // is not the same as an absent property to the type checker.
+    const { kind, zOrder } = this.children[index]!;
+    this.children[index] =
+      zOrder === undefined ? { worldId, kind, adapter } : { worldId, kind, adapter, zOrder };
+    this.capabilities = computeCapabilities(this.children);
+  }
+
+  /** The group node id for a given child (exposed for callers building
+   *  post-construction selection/expansion state — e.g. tests, e2e hooks). */
+  groupNodeId(worldId: string): string {
+    return groupNodeId(worldId);
+  }
+
+  /** The child that owns `id` — by ACTUAL ownership (its hierarchy resolves the
+   *  id), not by any prefix convention. `null` for a group-node id or an id no
+   *  child recognizes. O(children) per call; fine at editor-UI scale, and avoids
+   *  a cache that could go stale as a live tree adds/removes nodes. */
+  private findOwnerChild(id: string): CompositeChild | null {
+    if (isGroupNodeId(id)) return null;
+    for (const child of this.children) {
+      if (child.adapter.hierarchy.node(id)) return child;
+    }
+    return null;
+  }
+
+  /** Route by ownership, falling back to the FIRST child for an unrecognized id
+   *  (matches the old 2-child adapter's "everything else is world3d" floor —
+   *  callers that pass a bogus id get inert/default responses, not a throw). */
+  private route(id: string): AuthoringAdapter {
+    return this.findOwnerChild(id)?.adapter ?? this.children[0]!.adapter;
+  }
+
+  /** PUBLIC ownership query (T0 — A3's inspector dispatch and B4's pick routing
+   *  both need it): the `worldId` of the child that owns `id`, or `null` for a
+   *  group-node id or an id no child recognizes. */
+  ownerOf(id: string): string | null {
+    return this.findOwnerChild(id)?.worldId ?? null;
+  }
+
+  /**
+   * PUBLIC read-only view of the wrapped children (T0), ordered as constructed.
+   *
+   * `zOrder` is EACH CHILD'S OWN `CompositeChild.zOrder` (the world's
+   * install-time manifest zOrder) when supplied, falling back to the array
+   * index otherwise. Array order is NOT z-order (D12/B4 correction of this
+   * doc comment's former claim): children are built in MANIFEST DECLARATION
+   * order (`edit-mode-authoring.ts`), not stacking order — paint/pick order is
+   * `stackOrder` over each child's manifest zOrder (mirroring
+   * `create-runtime.ts`'s real stacking pass and `design-time-layers.ts`'s
+   * layer z-index assignment), which is exactly why this field exists.
+   * "Install-time" — the zOrder captured when this composite/child was built,
+   * not a live subscription: a world's zOrder edited afterward (the generic
+   * inspector's `zOrder` property, `A4`/D8) does NOT retroactively reorder an
+   * already-mounted design-time layer stack or an already-computed pick walk
+   * order this call returns; both settle to the new order the next time the
+   * composite/layers are rebuilt. Callers that need the LIVE manifest value
+   * (e.g. `GameHierarchy.tsx`'s zOrder badge) read it from the manifest
+   * surface directly instead of trusting this field alone — see
+   * `compositeGroupBadge`'s own comment.
+   */
+  childAdapters(): ReadonlyArray<{
+    worldId: string;
+    adapter: AuthoringAdapter;
+    kind: string;
+    zOrder: number;
+  }> {
+    return this.children.map((c, index) => ({
+      worldId: c.worldId,
+      adapter: c.adapter,
+      kind: c.kind,
+      zOrder: c.zOrder ?? index,
+    }));
+  }
+
+  /** PUBLIC (A4, D8) — the synthetic game-root node's id when this composite
+   *  was built with a `gameRoot` manifest surface, else `null`. Mirrors
+   *  `groupNodeId()`'s "ask the adapter, don't hardcode the id" precedent —
+   *  the shell (`GameHierarchy.tsx`) reads this instead of the literal
+   *  string, so it never needs to know the reserved id itself. */
+  get gameRootId(): string | null {
+    return this.gameRoot ? GAME_ROOT_ID : null;
+  }
+
+  /**
+   * C3 — a child declared with `parentWorldId` nests its group node UNDER
+   * that parent's group node instead of at the top level: the parent's
+   * `parentId` resolution below picks up the nested group id automatically
+   * (`this.children.find(...).parentWorldId`), and this method also appends
+   * every child NESTED under `worldId` (in declaration order) to the END of
+   * `childIds`, after `worldId`'s own adapter roots — so e.g. a `scene-ui`
+   * child appears as a trailing "ui (scene-ui)" row under its owning world.
+   */
+  private groupNode(worldId: string, kind: string, childRoots: EditorNode[]): EditorNode {
+    const self = this.children.find((c) => c.worldId === worldId);
+    const parentId = self?.parentWorldId
+      ? groupNodeId(self.parentWorldId)
+      : this.gameRoot
+        ? GAME_ROOT_ID
+        : null;
+    const nestedGroupIds = this.children
+      .filter((c) => c.parentWorldId === worldId)
+      .map((c) => groupNodeId(c.worldId));
+    return {
+      id: groupNodeId(worldId),
+      label: `world:${worldId} (${kind})`,
+      kind: 'group',
+      parentId,
+      childIds: [...childRoots.map((r) => r.id), ...nestedGroupIds],
+      flags: { runtimeOnly: true },
+    };
+  }
+
+  /** C3 — every child NOT nested under another (`parentWorldId` unset): the
+   *  top-level group set, either wrapped under the synthetic `game` root or
+   *  returned directly (see callers). A nested child is reached only via its
+   *  parent's `childIds` (`groupNode` above), never listed here too — a node
+   *  in two parents' `childIds` would render twice / cycle the row walk. */
+  private topLevelChildren(): CompositeChild[] {
+    return this.children.filter((c) => !c.parentWorldId);
+  }
+
+  /** A4 (D8) — the synthetic `game` root wrapping every TOP-LEVEL world group
+   *  node (C3: a nested child, e.g. a scene-UI world, is reached through its
+   *  parent's own `childIds` instead — see `topLevelChildren`). Only ever
+   *  constructed when `this.gameRoot` is set. */
+  private gameRootNode(): EditorNode {
+    return {
+      id: GAME_ROOT_ID,
+      label: this.gameRoot?.getGameName() || 'Game',
+      kind: 'group',
+      parentId: null,
+      childIds: this.topLevelChildren().map((c) => groupNodeId(c.worldId)),
+      flags: { runtimeOnly: true },
+    };
+  }
+
+  readonly hierarchy: HierarchyProvider = {
+    roots: (): EditorNode[] => {
+      // A4 (D8) — wrap under a synthetic `game` root ONLY when a manifest
+      // surface was supplied at construction (edit-mode's composite); every
+      // other composite (play-mode) returns world groups as roots directly,
+      // exactly as before A4. Either way, only TOP-LEVEL groups are roots
+      // (C3) — a nested child (e.g. scene-UI) is reached via its parent's
+      // own `childIds`, never listed as a root of its own.
+      if (this.gameRoot) return [this.gameRootNode()];
+      return this.topLevelChildren().map((c) =>
+        this.groupNode(c.worldId, c.kind, c.adapter.hierarchy.roots()),
+      );
+    },
+    node: (id) => {
+      if (id === GAME_ROOT_ID) {
+        return this.gameRoot ? this.gameRootNode() : null;
+      }
+      if (isGroupNodeId(id)) {
+        const worldId = id.slice(GROUP_PREFIX.length);
+        const child = this.children.find((c) => c.worldId === worldId);
+        if (!child) return null;
+        return this.groupNode(child.worldId, child.kind, child.adapter.hierarchy.roots());
+      }
+      const owner = this.findOwnerChild(id);
+      if (!owner) return null;
+      const node = owner.adapter.hierarchy.node(id);
+      if (!node) return null;
+      // A child's OWN root has `parentId: null` in its adapter's tree — rewrite
+      // it to point at this world's group node so the merged tree is one
+      // connected forest instead of the child roots looking parentless again.
+      return node.parentId === null ? { ...node, parentId: groupNodeId(owner.worldId) } : node;
+    },
+    object3D: (id) =>
+      id === GAME_ROOT_ID || isGroupNodeId(id) ? null : this.route(id).hierarchy.object3D(id),
+    idForObject3D: (o: THREE.Object3D) => {
+      for (const child of this.children) {
+        const id = child.adapter.hierarchy.idForObject3D(o);
+        if (id) return id;
+      }
+      return null;
+    },
+  };
+
+  readonly selection: SelectionProvider = {
+    // Union of every child's own selection.
+    get: () => {
+      const seen = new Set<string>();
+      for (const child of this.children) {
+        for (const id of child.adapter.selection?.get() ?? []) seen.add(id);
+      }
+      return [...seen];
+    },
+    set: (ids) => {
+      // A group-node id (or the game root) is not a real entity in any
+      // child's tree — route it specially rather than forwarding a bogus id
+      // nobody owns. Route each REAL id to its owning child.
+      //
+      // Every existing adapter (first-party/ingest/world2d) delegates
+      // selection to the SAME editor-global `EditorStore` — `selectMultiple`
+      // REPLACES the store's whole selected-id set, it does not merge. So
+      // calling `.set([])` on every non-owning child (the naive "clear the
+      // rest" approach) would call `selectMultiple` a second time on the
+      // SAME shared store and immediately clear out whatever the owning
+      // child's `.set()` call just wrote — a single click could never
+      // actually select anything. Only forward to children that own at
+      // least one of `ids`.
+      //
+      // A4 (D8): when NONE do (an empty selection, OR a selection that is
+      // PURELY a synthetic id), forward to exactly ONE child (any child
+      // sharing the backing store reaches every other child too) — but
+      // forward the SYNTHETIC ID ITSELF (not an empty clear) when one was
+      // given. This is why `RightPanel.tsx`'s `[...store.selectedEntityIds][0]`
+      // (and `Inspector.tsx`'s identical read) can show the game root's/
+      // a world group's own properties: every stock adapter shares the SAME
+      // `EditorStore`, so writing `'game'`/`'world:<id>'` into any one
+      // child's selection lands in that one shared `selectedEntityIds` set,
+      // which both those raw-store reads AND this composite's OWN `get()`
+      // (via the owning-adapter's `selection.get()`) then see identically —
+      // no separate synthetic-id bookkeeping needed on this class at all.
+      const byChild = new Map<AuthoringAdapter, string[]>();
+      let synthetic: string | null = null;
+      for (const id of ids) {
+        if (isGroupNodeId(id) || id === this.gameRootId) {
+          synthetic = id; // last one wins — only used when NOTHING else claims byChild
+          continue;
+        }
+        const owner = this.findOwnerChild(id);
+        if (!owner) continue;
+        const arr = byChild.get(owner.adapter);
+        if (arr) arr.push(id);
+        else byChild.set(owner.adapter, [id]);
+      }
+      if (byChild.size === 0) {
+        this.children[0]!.adapter.selection?.set(synthetic ? [synthetic] : []);
+        return;
+      }
+      for (const [adapter, childIds] of byChild) adapter.selection?.set(childIds);
+    },
+  };
+
+  readonly transforms: TransformProvider = {
+    get: (id): Transform =>
+      this.route(id).transforms?.get(id) ?? {
+        position: [0, 0, 0],
+        rotation: [0, 0, 0, 1],
+        scale: [1, 1, 1],
+      },
+    owner: (id): TransformOwner => this.route(id).transforms?.owner(id) ?? 'editor',
+    beginEdit: (id) => this.route(id).transforms?.beginEdit(id),
+    apply: (id, t) => this.route(id).transforms?.apply(id, t),
+    endEdit: (id) => this.route(id).transforms?.endEdit(id),
+  };
+
+  /**
+   * A4 (D8) — the game root's `name` and each world group's `zOrder`/
+   * `pausable`/`kind` are a MANIFEST concept, not something any child
+   * adapter's own inspector knows about — intercepted here, BEFORE `route()`,
+   * so a real per-world adapter is never asked about an id it doesn't own.
+   * `null` when `id` isn't the game root or a group-node id (or there is no
+   * `gameRoot` manifest surface at all), letting the caller fall through to
+   * the ordinary routed behavior unchanged.
+   */
+  private gameRootProperties(id: string): PropertyDescriptor[] | null {
+    if (!this.gameRoot) return null;
+    if (id === GAME_ROOT_ID) {
+      return [{ path: 'name', label: 'Name', type: 'string' }];
+    }
+    if (isGroupNodeId(id) && this.children.some((c) => groupNodeId(c.worldId) === id)) {
+      return [
+        { path: 'kind', label: 'Kind', type: 'string', readonly: true },
+        { path: 'zOrder', label: 'Z Order', type: 'number' },
+        { path: 'pausable', label: 'Pausable', type: 'boolean' },
+      ];
+    }
+    return null;
+  }
+
+  readonly inspector: InspectorProvider = {
+    properties: (id): PropertyDescriptor[] =>
+      this.gameRootProperties(id) ?? this.route(id).inspector?.properties(id) ?? [],
+    get: (id, path) => {
+      if (this.gameRoot) {
+        if (id === GAME_ROOT_ID) {
+          return path === 'name' ? this.gameRoot.getGameName() : undefined;
+        }
+        const worldId = isGroupNodeId(id) ? id.slice(GROUP_PREFIX.length) : null;
+        const child = worldId ? this.children.find((c) => c.worldId === worldId) : undefined;
+        if (child) {
+          if (path === 'kind') return child.kind;
+          if (path === 'zOrder') return this.gameRoot.getWorldZOrder(worldId!);
+          if (path === 'pausable') return this.gameRoot.getWorldPausable(worldId!);
+          return undefined;
+        }
+      }
+      return this.route(id).inspector?.get(id, path);
+    },
+    set: (id, path, value) => {
+      if (this.gameRoot) {
+        if (id === GAME_ROOT_ID) {
+          if (path === 'name') this.gameRoot.setGameName(String(value));
+          return;
+        }
+        const worldId = isGroupNodeId(id) ? id.slice(GROUP_PREFIX.length) : null;
+        const child = worldId ? this.children.find((c) => c.worldId === worldId) : undefined;
+        if (child) {
+          if (path === 'zOrder') this.gameRoot.setWorldZOrder(worldId!, Number(value));
+          else if (path === 'pausable') this.gameRoot.setWorldPausable(worldId!, Boolean(value));
+          return;
+        }
+      }
+      this.route(id).inspector?.set(id, path, value);
+    },
+    remove: (id, path) => {
+      // U2 — game-root/world-group synthetic props have no removable override;
+      // everything else routes to the owning child (which optional-omits
+      // `remove` unless it's the react-world adapter).
+      if (this.gameRoot && (id === GAME_ROOT_ID || isGroupNodeId(id))) return;
+      this.route(id).inspector?.remove?.(id, path);
+    },
+  };
+
+  /**
+   * A2 (map §5) — resolve a `create`/`creatableKinds` target: a group-node id
+   * (`world:<w>`) targets that world's OWN root (forwarded parentId
+   * `undefined`); a real id targets its owning child (forwarded as-is);
+   * `null`/`undefined` (no parent — the toolbar's root-level "Add") targets
+   * the FIRST child that actually has a structure provider — in edit mode
+   * that is the one focused, live `VgaiSceneAuthoringAdapter`; every other
+   * child is a read-only `BoundaryAuthoringAdapter` with no `structure` at
+   * all. `null` when nothing can serve the request (never silently routed to
+   * the wrong world — #18).
+   */
+  private resolveStructureTarget(
+    parentId: string | null | undefined,
+  ): { child: CompositeChild; forwardParentId: string | undefined } | null {
+    if (parentId != null && isGroupNodeId(parentId)) {
+      const worldId = parentId.slice(GROUP_PREFIX.length);
+      const child = this.children.find((c) => c.worldId === worldId);
+      return child ? { child, forwardParentId: undefined } : null;
+    }
+    if (parentId != null) {
+      const child = this.findOwnerChild(parentId);
+      return child ? { child, forwardParentId: parentId } : null;
+    }
+    const child = this.children.find((c) => c.adapter.structure);
+    return child ? { child, forwardParentId: undefined } : null;
+  }
+
+  /**
+   * A2 (map §5) — structural pass-through, routed by ownership. Never a
+   * silent no-op when a request can't be served: `create`/`remove`/
+   * `duplicate` log loudly via `editorConsole.warn` and return an honest
+   * empty/unchanged result (#18) rather than pretending to route to the
+   * wrong world. `reorder` is the one exception — it mirrors the base
+   * contract's OWN "absent means no reorder UI" convention, so a missing
+   * `reorder` on the owning child is a silent no-op, not a warning.
+   */
+  readonly structure: StructureProvider = {
+    create: (kind, parentId) => {
+      const target = this.resolveStructureTarget(parentId ?? null);
+      if (!target?.child.adapter.structure) {
+        editorConsole.warn(
+          `[CompositeAuthoringAdapter] create: no owning child with a structure ` +
+            `provider for parent "${parentId ?? '(root)'}"`,
+          'authoring',
+        );
+        return '';
+      }
+      return target.child.adapter.structure.create(kind, target.forwardParentId);
+    },
+    remove: (id) => {
+      if (isGroupNodeId(id)) return; // a whole world isn't removable through this seam
+      const owner = this.findOwnerChild(id);
+      if (!owner?.adapter.structure) {
+        editorConsole.warn(
+          `[CompositeAuthoringAdapter] remove: no owner/structure for id "${id}"`,
+          'authoring',
+        );
+        return;
+      }
+      // Propagate the owning child's return value (a react-world child
+      // returns an awaitable) so `deleteSelection` can still serialize a
+      // multi-delete THROUGH the composite the same way it does for a
+      // directly-active override adapter (see that adapter's own `remove`
+      // doc comment).
+      return owner.adapter.structure.remove(id);
+    },
+    duplicate: (id) => {
+      if (isGroupNodeId(id)) return id; // no-op — nothing to duplicate
+      const owner = this.findOwnerChild(id);
+      if (!owner?.adapter.structure) {
+        editorConsole.warn(
+          `[CompositeAuthoringAdapter] duplicate: no owner/structure for id "${id}"`,
+          'authoring',
+        );
+        return id;
+      }
+      return owner.adapter.structure.duplicate(id);
+    },
+    reparent: (id, newParentId) => {
+      const owner = this.findOwnerChild(id);
+      if (!owner?.adapter.structure) {
+        editorConsole.warn(
+          `[CompositeAuthoringAdapter] reparent: no owner/structure for id "${id}"`,
+          'authoring',
+        );
+        return;
+      }
+      if (newParentId === null || newParentId === groupNodeId(owner.worldId)) {
+        owner.adapter.structure.reparent(id, null); // -> a root of its own world
+        return;
+      }
+      const newOwner = this.findOwnerChild(newParentId);
+      if (!newOwner || newOwner.worldId !== owner.worldId) {
+        editorConsole.warn(
+          `[CompositeAuthoringAdapter] reparent: refusing to move "${id}" across worlds ` +
+            `(target parent "${newParentId}" is not in world "${owner.worldId}")`,
+          'authoring',
+        );
+        return;
+      }
+      owner.adapter.structure.reparent(id, newParentId);
+    },
+    reorder: (id, beforeSiblingId) => {
+      if (isGroupNodeId(id)) return;
+      const owner = this.findOwnerChild(id);
+      if (!owner) return;
+      // Cross-world guard: a non-null sibling anchor MUST belong to the same
+      // child as `id`. Otherwise (e.g. a drag onto another world's row whose
+      // reparent was already refused) the child maps the foreign sibling id to
+      // "append to end" and silently moves the entity within its own list on an
+      // operation the composite just rejected. A null anchor (move to end) is
+      // always valid.
+      if (beforeSiblingId !== null && this.findOwnerChild(beforeSiblingId) !== owner) return;
+      owner.adapter.structure?.reorder?.(id, beforeSiblingId);
+    },
+    creatableKinds: (parentId) => {
+      const target = this.resolveStructureTarget(parentId);
+      return (
+        target?.child.adapter.structure?.creatableKinds?.(target.forwardParentId ?? null) ?? []
+      );
+    },
+    // D3.a (spec 27 §6) — forward wrap/unwrap to the owning child, same
+    // owner-lookup + loud-warn-on-miss shape as `duplicate`/`remove` above
+    // (unlike `reorder`, which mirrors the base contract's OWN "absent means
+    // no UI" silent-no-op convention — wrap/unwrap follow the LOUD group
+    // instead since they're triggered from an explicit, always-visible menu
+    // item, same as duplicate/delete).
+    wrap: (id, wrapperTag) => {
+      if (isGroupNodeId(id)) return;
+      const owner = this.findOwnerChild(id);
+      if (!owner?.adapter.structure?.wrap) {
+        editorConsole.warn(
+          `[CompositeAuthoringAdapter] wrap: no owner/structure.wrap for id "${id}"`,
+          'authoring',
+        );
+        return;
+      }
+      owner.adapter.structure.wrap(id, wrapperTag);
+    },
+    unwrap: (id) => {
+      if (isGroupNodeId(id)) return;
+      const owner = this.findOwnerChild(id);
+      if (!owner?.adapter.structure?.unwrap) {
+        editorConsole.warn(
+          `[CompositeAuthoringAdapter] unwrap: no owner/structure.unwrap for id "${id}"`,
+          'authoring',
+        );
+        return;
+      }
+      owner.adapter.structure.unwrap(id);
+    },
+  };
+
+  /**
+   * A2 (map §5) — asset-drop pass-through. FIXES the pre-existing mis-route: a
+   * group-node id (`world:<w>`) used to fall through `route()`'s "unknown id ->
+   * first child" floor, so dropping an asset onto a world's OWN group row
+   * silently targeted whatever child happened to be FIRST in the array,
+   * regardless of which world's row was actually under the cursor. Translate
+   * the group-node id to that world's child directly, forwarding `''` (the
+   * shell/`VgaiSceneAuthoringAdapter` root-drop sentinel — see that adapter's
+   * `assetDrop` doc comment) as the node id, since the synthetic `world:<w>`
+   * string means nothing to the child's own hierarchy.
+   */
+  private resolveAssetDropTarget(nodeId: string): { adapter: AuthoringAdapter; forwardId: string } {
+    if (isGroupNodeId(nodeId)) {
+      const worldId = nodeId.slice(GROUP_PREFIX.length);
+      const child = this.children.find((c) => c.worldId === worldId);
+      return child
+        ? { adapter: child.adapter, forwardId: '' }
+        : { adapter: this.children[0]!.adapter, forwardId: '' };
+    }
+    const owner = this.findOwnerChild(nodeId);
+    // Unknown real id: same "first child" floor `route()` uses elsewhere, forwarding
+    // the id unchanged (parity with the pre-existing bogus-id behavior).
+    return owner
+      ? { adapter: owner.adapter, forwardId: nodeId }
+      : { adapter: this.children[0]!.adapter, forwardId: nodeId };
+  }
+
+  /**
+   * D4 (B2) — resolves a `stories` call THE SAME WAY `resolveAssetDropTarget`
+   * (above) resolves an asset drop: a group-node id (`world:<w>`) used to
+   * fall through `route()`'s "unknown id -> first child" floor, so
+   * `storiesFor('world:hud')` silently asked whatever child happened to be
+   * FIRST in the array (never the actual owner), meaning the story picker
+   * could NEVER appear on the world's own group row — the one place B2's
+   * shell (`Inspector.tsx`) actually calls it. Translated to `<w>`'s own
+   * child adapter. Unlike the asset-drop translation, the node id is
+   * forwarded UNCHANGED (not blanked to `''`) — B2's `ReactWorldAuthoringAdapter.stories`
+   * is world-level and ignores `nodeId` entirely (see that class's doc
+   * comment), but a future per-node catalog (B3) will want the real id, so
+   * there is no sentinel to invent here.
+   */
+  private resolveStoriesTarget(nodeId: string): { adapter: AuthoringAdapter; forwardId: string } {
+    if (isGroupNodeId(nodeId)) {
+      const worldId = nodeId.slice(GROUP_PREFIX.length);
+      const child = this.children.find((c) => c.worldId === worldId);
+      return child
+        ? { adapter: child.adapter, forwardId: nodeId }
+        : { adapter: this.children[0]!.adapter, forwardId: nodeId };
+    }
+    const owner = this.findOwnerChild(nodeId);
+    return owner
+      ? { adapter: owner.adapter, forwardId: nodeId }
+      : { adapter: this.children[0]!.adapter, forwardId: nodeId };
+  }
+
+  /**
+   * D8 — union of every child's own {@link RootGroup}s, each group id prefixed
+   * `<worldId>:` so groups from different worlds never collide. `activate`
+   * strips the prefix back off to find the owning child and the child's own
+   * (unprefixed) group id.
+   */
+  readonly rootGroups: RootGroupsProvider = {
+    groups: (): RootGroup[] =>
+      this.children.flatMap(
+        (c) =>
+          c.adapter.rootGroups?.groups().map((g) => ({ ...g, id: `${c.worldId}:${g.id}` })) ?? [],
+      ),
+    activate: (groupId, rootId) => {
+      const sep = groupId.indexOf(':');
+      if (sep < 0) return undefined;
+      const worldId = groupId.slice(0, sep);
+      const childGroupId = groupId.slice(sep + 1);
+      const child = this.children.find((c) => c.worldId === worldId);
+      return child?.adapter.rootGroups?.activate(childGroupId, rootId);
+    },
+  };
+
+  /** First NON-NULL child answer, in child order. */
+  readonly files: FileMapProvider = {
+    rootForFile: (path) => {
+      for (const child of this.children) {
+        const id = child.adapter.files?.rootForFile(path);
+        if (id) return id;
+      }
+      return null;
+    },
+  };
+
+  /** D4 — storybook stories, routed by node ownership (group-node ids
+   *  translated — see `resolveStoriesTarget` above, the same fix
+   *  `resolveAssetDropTarget` applied for asset drops). A node whose owning
+   *  adapter has no `stories` provider reports/does nothing (empty list, null
+   *  active, no-op apply/isolate) rather than throwing. */
+  readonly stories: StoriesProvider = {
+    storiesFor: (nodeId): StoryRef[] => {
+      const { adapter, forwardId } = this.resolveStoriesTarget(nodeId);
+      return adapter.stories?.storiesFor(forwardId) ?? [];
+    },
+    active: (nodeId) => {
+      const { adapter, forwardId } = this.resolveStoriesTarget(nodeId);
+      return adapter.stories?.active(forwardId) ?? null;
+    },
+    apply: (nodeId, storyId) => {
+      const { adapter, forwardId } = this.resolveStoriesTarget(nodeId);
+      adapter.stories?.apply(forwardId, storyId);
+    },
+    isolate: (nodeId, storyId) => {
+      // A null nodeId (exit isolation) has no owner to route by — forward the
+      // exit to every child that implements `isolate` so nothing is left stuck
+      // in an isolated state.
+      if (nodeId === null) {
+        for (const child of this.children) child.adapter.stories?.isolate?.(null, storyId);
+        return;
+      }
+      const { adapter, forwardId } = this.resolveStoriesTarget(nodeId);
+      adapter.stories?.isolate?.(forwardId, storyId);
+    },
+  };
+
+  /** D6 (S-C) — GameComponent management, routed by node ownership. */
+  readonly components: ComponentsProvider = {
+    available: (nodeId): string[] => this.route(nodeId).components?.available(nodeId) ?? [],
+    list: (nodeId): { type: string }[] => this.route(nodeId).components?.list(nodeId) ?? [],
+    add: (nodeId, type) => this.route(nodeId).components?.add(nodeId, type),
+    remove: (nodeId, type) => this.route(nodeId).components?.remove(nodeId, type),
+    config: (nodeId, type) => this.route(nodeId).components?.config?.(nodeId, type) ?? null,
+  };
+
+  /** Asset drop, routed by node ownership (group-node ids translated — see
+   *  `resolveAssetDropTarget` above). */
+  readonly assetDrop: AssetDropProvider = {
+    accepts: (nodeId, assetPath) => {
+      const target = this.resolveAssetDropTarget(nodeId);
+      return target.adapter.assetDrop?.accepts(target.forwardId, assetPath) ?? false;
+    },
+    drop: (nodeId, assetPath) => {
+      const target = this.resolveAssetDropTarget(nodeId);
+      target.adapter.assetDrop?.drop(target.forwardId, assetPath);
+    },
+  };
+
+  // NOTE: `pickable` is deliberately NOT implemented here — layered viewport
+  // picking (D12) across children is shell policy (B4), not something this
+  // composite merges. Callers needing per-layer pick should go through
+  // `childAdapters()` and pick each child's own `pickable` themselves.
+
+  subscribe(listener: () => void): () => void {
+    const unsubs = this.children
+      .map((c) => c.adapter.subscribe?.(listener))
+      .filter((u): u is () => void => !!u);
+    return () => {
+      for (const u of unsubs) u();
+    };
+  }
+
+  /**
+   * Persistence (T3.2 slice 3, generalized 2→N unchanged in semantics): `isDirty`
+   * = OR of children that actually have a provider (a child without one, e.g. an
+   * embed-only adapter, is simply skipped — it has nothing to be dirty about);
+   * `save()` saves the dirty children SEQUENTIALLY, logging loudly per-child on
+   * failure without aborting the rest; `destination` joins child destinations
+   * with `' + '`.
+   *
+   * No own undo: the global timeline (`undo-timeline.ts`) already dispatches
+   * per-adapter, and each child that supports undo registers ITSELF — wrapping
+   * one in a Composite changes nothing about that registration.
+   */
+  get persistence(): PersistenceProvider {
+    // Always a REAL (never `undefined`) provider — see composite-authoring-adapter's
+    // 2-child precedent / `ephemeral-persistence.ts` for the same pattern.
+    const persistable = this.children.filter(
+      (
+        c,
+      ): c is CompositeChild & {
+        adapter: AuthoringAdapter & { persistence: PersistenceProvider };
+      } => c.adapter.capabilities.persist && !!c.adapter.persistence,
+    );
+    return {
+      isDirty: () => persistable.some((c) => c.adapter.persistence.isDirty()),
+      save: async () => {
+        for (const c of persistable) {
+          const p = c.adapter.persistence;
+          if (!p.isDirty()) continue;
+          try {
+            await p.save();
+          } catch (err) {
+            console.error(
+              `[CompositeAuthoringAdapter] save failed for world "${c.worldId}" ` +
+                `(destination: ${p.destination}) — continuing with remaining worlds:`,
+              err,
+            );
+          }
+        }
+      },
+      // A labeled record keyed by world id — the N-ary generalization of the
+      // 2-child `{world3d, world2d}` shape (§4/§6.5); report if a different
+      // shape (e.g. a flat merge) is actually wanted.
+      serialize: () =>
+        Object.fromEntries(
+          this.children.map((c) => [c.worldId, c.adapter.persistence?.serialize()]),
+        ),
+      destination:
+        persistable.length > 0
+          ? persistable.map((c) => c.adapter.persistence.destination).join(' + ')
+          : '(no persistable child)',
+    };
+  }
+}