@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

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

@@ -5,7 +5,9 @@
  * 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
+ * own roots nested beneath it. The project/game identity already lives in the
+ * editor chrome, so the authoring projection starts at those real world roots —
+ * it does not add a redundant synthetic Game row. 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.
  *
@@ -37,6 +39,7 @@ import type {
 } from '@engine/adapter';
 import type * as THREE from 'three';
 import { editorConsole } from '../editor-console';
+import type { HierarchyProjection, HierarchyProjectionGroup } from '../hierarchy-projection';
 
 /** One child world's authoring adapter, ordered as given to the constructor. */
 export interface CompositeChild {
@@ -44,6 +47,11 @@ export interface CompositeChild {
   readonly worldId: string;
   /** World render substrate kind — shown in the group node's label. */
   readonly kind: string;
+  /** Runtime manifest roots are the default. A nested authoring surface is
+   * adapter-owned content of its parent world, not another runtime world. */
+  readonly role?: 'world' | 'surface';
+  /** Optional user-facing label for a nested authoring surface. */
+  readonly label?: string;
   readonly adapter: AuthoringAdapter;
   /**
    * D12 (B4) — the world's INSTALL-TIME manifest zOrder (`world.zOrder ?? 0`),
@@ -54,11 +62,14 @@ export interface CompositeChild {
    * what "install-time" means here.
    */
   readonly zOrder?: number;
+  /** Manifest pausing policy, retained for read-only play-mode inspection. */
+  readonly pausable?: boolean;
+  /** Adapter-owned content declaration, retained for play-mode inspection. */
+  readonly content?: string;
   /**
    * 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
+   * this child's group node UNDER another child's group node instead of
+   * directly in the hierarchy root list. 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.
@@ -67,7 +78,14 @@ export interface CompositeChild {
 }
 
 const GROUP_PREFIX = 'world:';
-const GAME_ROOT_ID = 'game';
+const KIND_PREFIX = 'kind:';
+const PROJECTION_PREFIX = 'projection:';
+
+const KIND_LABELS: Readonly<Record<string, string>> = {
+  threejs: 'Three.js',
+  react: 'React',
+  pixijs: 'PixiJS',
+};
 
 function groupNodeId(worldId: string): string {
   return `${GROUP_PREFIX}${worldId}`;
@@ -79,19 +97,34 @@ function isGroupNodeId(id: string): boolean {
   return id.startsWith(GROUP_PREFIX);
 }
 
+function kindNodeId(kind: string): string {
+  return `${KIND_PREFIX}${kind}`;
+}
+
+function projectionNodeId(id: string): string {
+  return `${PROJECTION_PREFIX}${id}`;
+}
+
+function isOrganizationNodeId(id: string): boolean {
+  return id.startsWith(KIND_PREFIX) || id.startsWith(PROJECTION_PREFIX);
+}
+
+function humanizeId(id: string): string {
+  const words = id.replace(/[-_]+/g, ' ').trim();
+  return words ? words.replace(/\b\w/g, (letter) => letter.toUpperCase()) : id;
+}
+
 /**
- * A4 (D8) — the game root's manifest-backed property surface, implemented by
+ * A4 (D8) — manifest-backed properties on each authored root, 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;
+export interface RootManifestProvider {
+  /** Adapter-owned content declaration shown on the world boundary (for
+   * example `Scene · scenes/default.vscn.json` or `Entry · src/ui/App.tsx`). */
+  getWorldContentSource?(worldId: string): string | undefined;
   getWorldZOrder(worldId: string): number;
   setWorldZOrder(worldId: string, value: number): void;
   getWorldPausable(worldId: string): boolean;
@@ -145,12 +178,13 @@ export class CompositeAuthoringAdapter implements AuthoringAdapter {
    * 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;
+  /** Optional writable manifest surface for world composition properties.
+   * Runtime still has one semantic Game root; the authoring hierarchy does not
+   * mirror that project-level wrapper because the editor chrome already owns it. */
+  private readonly manifest: RootManifestProvider | null;
+  /** Optional editor-only organization; never consulted by runtime mounting. */
+  private readonly projection: HierarchyProjection | null;
+  private readonly resolvedProjectionGroups: Array<HierarchyProjectionGroup & { roots: string[] }>;
 
   /**
    * N-ary (T6.1 slice 3): an ordered `{ worldId, kind, adapter }[]` — one group
@@ -161,19 +195,23 @@ export class CompositeAuthoringAdapter implements AuthoringAdapter {
    * 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`).
+   * the N-ary array constructor (`play-mode.ts`'s `installPlayWorldAuthoring`).
    *
-   * `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.
+   * `manifest` is an optional writable provider. Omitting it leaves root
+   * composition properties read-only.
    */
-  constructor(children: ReadonlyArray<CompositeChild>, gameRoot?: GameRootManifestProvider) {
+  constructor(
+    children: ReadonlyArray<CompositeChild>,
+    manifest?: RootManifestProvider,
+    projection?: HierarchyProjection,
+  ) {
     this.children = [...children];
-    this.gameRoot = gameRoot ?? null;
+    this.manifest = manifest ?? null;
+    this.projection = projection ?? null;
     if (children.length === 0) {
       throw new Error('CompositeAuthoringAdapter: at least one child world is required.');
     }
+    this.resolvedProjectionGroups = this.resolveProjectionGroups();
     this.capabilities = computeCapabilities(this.children);
   }
 
@@ -193,8 +231,7 @@ export class CompositeAuthoringAdapter implements AuthoringAdapter {
    * 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) —
+   * (`store.notifyIngestEdit()` so panels re-render against the new child) —
    * this method only owns the swap + capability recompute.
    */
   replaceChild(worldId: string, adapter: AuthoringAdapter): void {
@@ -212,9 +249,8 @@ export class CompositeAuthoringAdapter implements AuthoringAdapter {
     // `{ ..., 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 };
+    const previous = this.children[index]!;
+    this.children[index] = { ...previous, worldId, adapter };
     this.capabilities = computeCapabilities(this.children);
   }
 
@@ -224,12 +260,17 @@ export class CompositeAuthoringAdapter implements AuthoringAdapter {
     return groupNodeId(worldId);
   }
 
+  /** True for a read-only shell node manufactured only for hierarchy layout. */
+  isOrganizationNode(nodeId: string): boolean {
+    return isOrganizationNodeId(nodeId);
+  }
+
   /** 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;
+    if (isGroupNodeId(id) || isOrganizationNodeId(id)) return null;
     for (const child of this.children) {
       if (child.adapter.hierarchy.node(id)) return child;
     }
@@ -276,24 +317,17 @@ export class CompositeAuthoringAdapter implements AuthoringAdapter {
     adapter: AuthoringAdapter;
     kind: string;
     zOrder: number;
+    role: 'world' | 'surface';
   }> {
     return this.children.map((c, index) => ({
       worldId: c.worldId,
       adapter: c.adapter,
       kind: c.kind,
       zOrder: c.zOrder ?? index,
+      role: c.role ?? 'world',
     }));
   }
 
-  /** 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
@@ -307,16 +341,18 @@ export class CompositeAuthoringAdapter implements AuthoringAdapter {
     const self = this.children.find((c) => c.worldId === worldId);
     const parentId = self?.parentWorldId
       ? groupNodeId(self.parentWorldId)
-      : this.gameRoot
-        ? GAME_ROOT_ID
-        : null;
+      : this.parentForTopLevelWorld(worldId, kind);
     const nestedGroupIds = this.children
       .filter((c) => c.parentWorldId === worldId)
       .map((c) => groupNodeId(c.worldId));
     return {
       id: groupNodeId(worldId),
-      label: `world:${worldId} (${kind})`,
-      kind: 'group',
+      label:
+        self?.role === 'surface'
+          ? (self.label ?? `${worldId} (${kind})`)
+          : this.labelForWorld(worldId, kind),
+      role: self?.role === 'surface' ? 'document' : 'root',
+      kind,
       parentId,
       childIds: [...childRoots.map((r) => r.id), ...nestedGroupIds],
       flags: { runtimeOnly: true },
@@ -324,45 +360,126 @@ export class CompositeAuthoringAdapter implements AuthoringAdapter {
   }
 
   /** 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
+   *  top-level group set. 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 {
+  private runtimeRootChildren(): CompositeChild[] {
+    return this.topLevelChildren().filter((c) => (c.role ?? 'world') === 'world');
+  }
+
+  private resolveProjectionGroups(): Array<HierarchyProjectionGroup & { roots: string[] }> {
+    const known = new Set(this.runtimeRootChildren().map((child) => child.worldId));
+    const placed = new Set<string>();
+    return (this.projection?.groups ?? []).flatMap((group) => {
+      const roots = group.roots.filter((rootId) => {
+        if (!known.has(rootId)) {
+          editorConsole.warn(
+            `[CompositeAuthoringAdapter] hierarchy group "${group.label}" references unknown root "${rootId}" — ignoring.`,
+            'authoring',
+          );
+          return false;
+        }
+        if (placed.has(rootId)) {
+          editorConsole.warn(
+            `[CompositeAuthoringAdapter] hierarchy root "${rootId}" is referenced by more than one group; the tree projection uses its first placement.`,
+            'authoring',
+          );
+          return false;
+        }
+        placed.add(rootId);
+        return true;
+      });
+      return roots.length > 0 ? [{ ...group, roots }] : [];
+    });
+  }
+
+  private projectionGroups(): Array<HierarchyProjectionGroup & { roots: string[] }> {
+    return this.resolvedProjectionGroups;
+  }
+
+  private projectionGroupFor(worldId: string): HierarchyProjectionGroup | undefined {
+    return this.projectionGroups().find((group) => group.roots.includes(worldId));
+  }
+
+  private unprojectedRoots(): CompositeChild[] {
+    const projected = new Set(this.projectionGroups().flatMap((group) => group.roots));
+    return this.runtimeRootChildren().filter((child) => !projected.has(child.worldId));
+  }
+
+  private rootsOfKind(kind: string): CompositeChild[] {
+    return this.unprojectedRoots().filter((child) => child.kind === kind);
+  }
+
+  private parentForTopLevelWorld(worldId: string, kind: string): string | null {
+    const group = this.projectionGroupFor(worldId);
+    if (group) return projectionNodeId(group.id);
+    return this.rootsOfKind(kind).length > 1 ? kindNodeId(kind) : null;
+  }
+
+  private labelForWorld(worldId: string, kind: string): string {
+    const configured = this.projection?.rootLabels?.[worldId]?.trim();
+    if (configured) return configured;
+    return this.rootsOfKind(kind).length === 1 && !this.projectionGroupFor(worldId)
+      ? (KIND_LABELS[kind] ?? humanizeId(kind))
+      : humanizeId(worldId);
+  }
+
+  private kindNode(kind: string): EditorNode {
+    return {
+      id: kindNodeId(kind),
+      label: KIND_LABELS[kind] ?? humanizeId(kind),
+      role: 'folder',
+      kind: 'group',
+      parentId: null,
+      childIds: this.rootsOfKind(kind).map((child) => groupNodeId(child.worldId)),
+      flags: { runtimeOnly: true },
+    };
+  }
+
+  private projectionGroupNode(group: HierarchyProjectionGroup & { roots: string[] }): EditorNode {
     return {
-      id: GAME_ROOT_ID,
-      label: this.gameRoot?.getGameName() || 'Game',
+      id: projectionNodeId(group.id),
+      label: group.label,
+      role: 'folder',
       kind: 'group',
       parentId: null,
-      childIds: this.topLevelChildren().map((c) => groupNodeId(c.worldId)),
+      childIds: group.roots.map(groupNodeId),
       flags: { runtimeOnly: true },
     };
   }
 
+  private defaultProjectionNodeIds(): string[] {
+    const ids: string[] = [];
+    const seenKinds = new Set<string>();
+    for (const child of this.unprojectedRoots()) {
+      if (seenKinds.has(child.kind)) continue;
+      seenKinds.add(child.kind);
+      const peers = this.rootsOfKind(child.kind);
+      ids.push(peers.length > 1 ? kindNodeId(child.kind) : groupNodeId(child.worldId));
+    }
+    return ids;
+  }
+
   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()),
-      );
-    },
+    roots: (): EditorNode[] => [
+      ...this.projectionGroups().map((group) => this.projectionGroupNode(group)),
+      ...this.defaultProjectionNodeIds()
+        .map((id) => this.hierarchy.node(id))
+        .filter((node): node is EditorNode => node !== null),
+    ],
     node: (id) => {
-      if (id === GAME_ROOT_ID) {
-        return this.gameRoot ? this.gameRootNode() : null;
+      if (id.startsWith(KIND_PREFIX)) {
+        const kind = id.slice(KIND_PREFIX.length);
+        return this.rootsOfKind(kind).length > 1 ? this.kindNode(kind) : null;
+      }
+      if (id.startsWith(PROJECTION_PREFIX)) {
+        const groupId = id.slice(PROJECTION_PREFIX.length);
+        const group = this.projectionGroups().find((candidate) => candidate.id === groupId);
+        return group ? this.projectionGroupNode(group) : null;
       }
       if (isGroupNodeId(id)) {
         const worldId = id.slice(GROUP_PREFIX.length);
@@ -380,7 +497,7 @@ export class CompositeAuthoringAdapter implements AuthoringAdapter {
       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),
+      isGroupNodeId(id) || isOrganizationNodeId(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);
@@ -400,7 +517,7 @@ export class CompositeAuthoringAdapter implements AuthoringAdapter {
       return [...seen];
     },
     set: (ids) => {
-      // A group-node id (or the game root) is not a real entity in any
+      // A group-node id 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.
       //
@@ -419,9 +536,9 @@ export class CompositeAuthoringAdapter implements AuthoringAdapter {
       // 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
+      // (and `Inspector.tsx`'s identical read) can show a world group's own
+      // properties: every stock adapter shares the SAME `EditorStore`, so
+      // writing `'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 —
@@ -429,7 +546,7 @@ export class CompositeAuthoringAdapter implements AuthoringAdapter {
       const byChild = new Map<AuthoringAdapter, string[]>();
       let synthetic: string | null = null;
       for (const id of ids) {
-        if (isGroupNodeId(id) || id === this.gameRootId) {
+        if (isGroupNodeId(id) || isOrganizationNodeId(id)) {
           synthetic = id; // last one wins — only used when NOTHING else claims byChild
           continue;
         }
@@ -461,24 +578,40 @@ export class CompositeAuthoringAdapter implements AuthoringAdapter {
   };
 
   /**
-   * A4 (D8) — the game root's `name` and each world group's `zOrder`/
-   * `pausable`/`kind` are a MANIFEST concept, not something any child
+   * A4 (D8) — each adapter root's stable `id`, `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.
+   * Without a writable provider, these synthetic nodes still expose read-only
+   * composition facts instead of being routed into a child that cannot own them.
    */
-  private gameRootProperties(id: string): PropertyDescriptor[] | null {
-    if (!this.gameRoot) return null;
-    if (id === GAME_ROOT_ID) {
-      return [{ path: 'name', label: 'Name', type: 'string' }];
+  private rootProperties(id: string): PropertyDescriptor[] | null {
+    if (isOrganizationNodeId(id)) {
+      return [{ path: 'organization', label: 'Authoring Group', type: 'string', readonly: true }];
     }
-    if (isGroupNodeId(id) && this.children.some((c) => groupNodeId(c.worldId) === id)) {
+    if (
+      isGroupNodeId(id) &&
+      this.children.some((c) => (c.role ?? 'world') === 'world' && groupNodeId(c.worldId) === id)
+    ) {
+      const child = this.children.find((candidate) => groupNodeId(candidate.worldId) === id);
       return [
+        { path: 'id', label: 'Root ID', type: 'string', readonly: true },
         { path: 'kind', label: 'Kind', type: 'string', readonly: true },
-        { path: 'zOrder', label: 'Z Order', type: 'number' },
-        { path: 'pausable', label: 'Pausable', type: 'boolean' },
+        ...(this.manifest?.getWorldContentSource || child?.content
+          ? ([{ path: 'content', label: 'Content', type: 'string', readonly: true }] as const)
+          : []),
+        {
+          path: 'zOrder',
+          label: 'Z Order',
+          type: 'number',
+          ...(this.manifest ? {} : { readonly: true }),
+        },
+        {
+          path: 'pausable',
+          label: 'Pausable',
+          type: 'boolean',
+          ...(this.manifest ? {} : { readonly: true }),
+        },
       ];
     }
     return null;
@@ -486,44 +619,47 @@ export class CompositeAuthoringAdapter implements AuthoringAdapter {
 
   readonly inspector: InspectorProvider = {
     properties: (id): PropertyDescriptor[] =>
-      this.gameRootProperties(id) ?? this.route(id).inspector?.properties(id) ?? [],
+      this.rootProperties(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;
+      if (isOrganizationNodeId(id)) {
+        return path === 'organization' ? 'Editor-only hierarchy projection' : undefined;
+      }
+      const worldId = isGroupNodeId(id) ? id.slice(GROUP_PREFIX.length) : null;
+      const child = worldId ? this.children.find((c) => c.worldId === worldId) : undefined;
+      if (child && (child.role ?? 'world') === 'world') {
+        if (path === 'id') return child.worldId;
+        if (path === 'kind') return child.kind;
+        if (path === 'content') {
+          return this.manifest?.getWorldContentSource?.(worldId!) ?? child.content;
         }
-        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;
+        if (path === 'zOrder') {
+          return this.manifest?.getWorldZOrder(worldId!) ?? child.zOrder ?? 0;
         }
+        if (path === 'pausable') {
+          return this.manifest?.getWorldPausable(worldId!) ?? child.pausable ?? true;
+        }
+        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;
+      const worldId = isGroupNodeId(id) ? id.slice(GROUP_PREFIX.length) : null;
+      const child = worldId ? this.children.find((c) => c.worldId === worldId) : undefined;
+      if (child && (child.role ?? 'world') === 'world') {
+        if (this.manifest && path === 'zOrder') {
+          this.manifest.setWorldZOrder(worldId!, Number(value));
+        } else if (this.manifest && path === 'pausable') {
+          this.manifest.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;
+      // U2 — root-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;
+      if (isGroupNodeId(id) || isOrganizationNodeId(id)) return;
       this.route(id).inspector?.remove?.(id, path);
     },
   };
@@ -542,6 +678,7 @@ export class CompositeAuthoringAdapter implements AuthoringAdapter {
   private resolveStructureTarget(
     parentId: string | null | undefined,
   ): { child: CompositeChild; forwardParentId: string | undefined } | null {
+    if (parentId != null && isOrganizationNodeId(parentId)) return null;
     if (parentId != null && isGroupNodeId(parentId)) {
       const worldId = parentId.slice(GROUP_PREFIX.length);
       const child = this.children.find((c) => c.worldId === worldId);
@@ -549,7 +686,16 @@ export class CompositeAuthoringAdapter implements AuthoringAdapter {
     }
     if (parentId != null) {
       const child = this.findOwnerChild(parentId);
-      return child ? { child, forwardParentId: parentId } : null;
+      if (!child) return null;
+      const parent = child.adapter.hierarchy.node(parentId);
+      return {
+        child,
+        // Documents and design states organize an adapter's native roots;
+        // they are not native parent ids. The structure contract's root
+        // spelling is `undefined`/`null`, so forward that explicitly.
+        forwardParentId:
+          parent?.role === 'document' || parent?.role === 'story' ? undefined : parentId,
+      };
     }
     const child = this.children.find((c) => c.adapter.structure);
     return child ? { child, forwardParentId: undefined } : null;
@@ -578,7 +724,7 @@ export class CompositeAuthoringAdapter implements AuthoringAdapter {
       return target.child.adapter.structure.create(kind, target.forwardParentId);
     },
     remove: (id) => {
-      if (isGroupNodeId(id)) return; // a whole world isn't removable through this seam
+      if (isGroupNodeId(id) || isOrganizationNodeId(id)) return;
       const owner = this.findOwnerChild(id);
       if (!owner?.adapter.structure) {
         editorConsole.warn(
@@ -594,8 +740,35 @@ export class CompositeAuthoringAdapter implements AuthoringAdapter {
       // doc comment).
       return owner.adapter.structure.remove(id);
     },
+    removeMany: async (ids) => {
+      const groups = new Map<CompositeChild, string[]>();
+      for (const id of ids) {
+        if (isGroupNodeId(id) || isOrganizationNodeId(id)) continue;
+        const owner = this.findOwnerChild(id);
+        if (!owner?.adapter.structure) {
+          editorConsole.warn(
+            `[CompositeAuthoringAdapter] removeMany: no owner/structure for id "${id}"`,
+            'authoring',
+          );
+          continue;
+        }
+        const ownedIds = groups.get(owner);
+        if (ownedIds) ownedIds.push(id);
+        else groups.set(owner, [id]);
+      }
+
+      // Preserve each child's strongest atomicity guarantee. In the common case
+      // (one world's multi-selection), this is one child batch and therefore one
+      // history transaction. Cross-world selections remain one ordered batch per
+      // owner because no child can soundly mutate another world's document.
+      for (const [owner, ownedIds] of groups) {
+        const structure = owner.adapter.structure!;
+        if (structure.removeMany) await structure.removeMany(ownedIds);
+        else for (const id of ownedIds) await structure.remove(id);
+      }
+    },
     duplicate: (id) => {
-      if (isGroupNodeId(id)) return id; // no-op — nothing to duplicate
+      if (isGroupNodeId(id) || isOrganizationNodeId(id)) return id;
       const owner = this.findOwnerChild(id);
       if (!owner?.adapter.structure) {
         editorConsole.warn(
@@ -622,16 +795,21 @@ export class CompositeAuthoringAdapter implements AuthoringAdapter {
       const newOwner = this.findOwnerChild(newParentId);
       if (!newOwner || newOwner.worldId !== owner.worldId) {
         editorConsole.warn(
-          `[CompositeAuthoringAdapter] reparent: refusing to move "${id}" across worlds ` +
+          `[CompositeAuthoringAdapter] reparent: refusing to move "${id}" across roots ` +
             `(target parent "${newParentId}" is not in world "${owner.worldId}")`,
           'authoring',
         );
         return;
       }
+      const newParent = newOwner.adapter.hierarchy.node(newParentId);
+      if (newParent?.role === 'document' || newParent?.role === 'story') {
+        owner.adapter.structure.reparent(id, null);
+        return;
+      }
       owner.adapter.structure.reparent(id, newParentId);
     },
     reorder: (id, beforeSiblingId) => {
-      if (isGroupNodeId(id)) return;
+      if (isGroupNodeId(id) || isOrganizationNodeId(id)) return;
       const owner = this.findOwnerChild(id);
       if (!owner) return;
       // Cross-world guard: a non-null sibling anchor MUST belong to the same
@@ -656,7 +834,7 @@ export class CompositeAuthoringAdapter implements AuthoringAdapter {
     // instead since they're triggered from an explicit, always-visible menu
     // item, same as duplicate/delete).
     wrap: (id, wrapperTag) => {
-      if (isGroupNodeId(id)) return;
+      if (isGroupNodeId(id) || isOrganizationNodeId(id)) return;
       const owner = this.findOwnerChild(id);
       if (!owner?.adapter.structure?.wrap) {
         editorConsole.warn(
@@ -668,7 +846,7 @@ export class CompositeAuthoringAdapter implements AuthoringAdapter {
       owner.adapter.structure.wrap(id, wrapperTag);
     },
     unwrap: (id) => {
-      if (isGroupNodeId(id)) return;
+      if (isGroupNodeId(id) || isOrganizationNodeId(id)) return;
       const owner = this.findOwnerChild(id);
       if (!owner?.adapter.structure?.unwrap) {
         editorConsole.warn(
@@ -703,8 +881,12 @@ export class CompositeAuthoringAdapter implements AuthoringAdapter {
     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).
+    const node = owner?.adapter.hierarchy.node(nodeId);
     return owner
-      ? { adapter: owner.adapter, forwardId: nodeId }
+      ? {
+          adapter: owner.adapter,
+          forwardId: node?.role === 'document' || node?.role === 'story' ? '' : nodeId,
+        }
       : { adapter: this.children[0]!.adapter, forwardId: nodeId };
   }
 
@@ -738,7 +920,7 @@ export class CompositeAuthoringAdapter implements AuthoringAdapter {
 
   /**
    * D8 — union of every child's own {@link RootGroup}s, each group id prefixed
-   * `<worldId>:` so groups from different worlds never collide. `activate`
+   * `<worldId>:` so groups from different roots never collide. `activate`
    * strips the prefix back off to find the owning child and the child's own
    * (unprefixed) group id.
    */
@@ -844,9 +1026,8 @@ export class CompositeAuthoringAdapter implements AuthoringAdapter {
    * 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.
+   * History is resource-driven, so the composite needs no ordering or inverse
+   * logic of its own; its children journal into the open project's service.
    */
   get persistence(): PersistenceProvider {
     // Always a REAL (never `undefined`) provider — see composite-authoring-adapter's
@@ -869,7 +1050,7 @@ export class CompositeAuthoringAdapter implements AuthoringAdapter {
           } catch (err) {
             console.error(
               `[CompositeAuthoringAdapter] save failed for world "${c.worldId}" ` +
-                `(destination: ${p.destination}) — continuing with remaining worlds:`,
+                `(destination: ${p.destination}) — continuing with remaining roots:`,
               err,
             );
           }