@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/components/GameHierarchy.tsx

@@ -1,3 +1,12 @@
+import {
+  Button,
+  chromeSize,
+  IconButton,
+  space,
+  TextInput,
+  themeVars,
+  zIndex,
+} from '../design-system';
 /**
  * GameHierarchy — the ONE hierarchy panel (A2,
  * docs/unified-world-editor/26-unified-editor-spec.md §2 A2). Replaces the
@@ -15,12 +24,12 @@
  * unpack/open/save-as) live behind `hierarchy-menu-registry.ts`'s escape
  * hatch, registered elsewhere (`authoring/first-party-hierarchy-menu.ts`).
  *
- * Shape handling (the manager's reconciliation constraint): the ACTIVE
- * adapter is either a bare per-scene adapter (single-world edit, an ingested
- * game, …) — `adapter.hierarchy.roots()` returns real entity roots directly —
- * or `CompositeAuthoringAdapter` (2+ worlds) — roots are synthetic
- * `world:<id>` GROUP nodes (`flags.runtimeOnly`), each world's own roots
- * nested beneath. Both shapes are walked by the SAME generic row engine
+ * Shape handling: project authoring is a `CompositeAuthoringAdapter` rooted
+ * at Game for every N >= 1 composition. Each runtime world is a synthetic
+ * `world:<id>` group; adapter-owned surfaces such as scene UI may be nested
+ * beneath their owning world without pretending to be runtime roots. The
+ * same generic row engine also handles bare adapters used by bounded ingest
+ * and compatibility sessions. Both shapes are walked by the SAME generic row engine
  * (`flattenIngestRows` — the format-neutral `EditorNode`-typed row
  * flattener, not the legacy first-party-typed sibling module); a group node
  * only ever gets a small set of cosmetic extras (kind/zOrder badge, a
@@ -35,23 +44,51 @@
  * existing ingest-family e2e specs keep passing unchanged.
  */
 
-import type { AuthoringAdapter } from '@engine/adapter';
+import type {
+  AuthoringAdapter,
+  AuthoringProvenance,
+  EditorNode,
+  EditorNodeRole,
+} from '@engine/adapter';
+import type { IconDefinition } from '@fortawesome/fontawesome-svg-core';
 import {
+  faBookOpen,
+  faCamera,
   faCaretDown,
   faCaretRight,
+  faCircle,
+  faCircleDot,
+  faCirclePlay,
+  faCode,
   faCrosshairs,
+  faCube,
   faEye,
   faEyeSlash,
+  faFileCode,
+  faFolder,
   faHandPointer,
+  faImage,
+  faLayerGroup,
+  faLightbulb,
+  faLink,
+  faList,
   faLock,
   faLockOpen,
+  faMinus,
+  faObjectGroup,
   faPlus,
+  faPuzzlePiece,
+  faRotateLeft,
+  faSquare,
+  faTriangleExclamation,
 } from '@fortawesome/free-solid-svg-icons';
-import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
 import { useCallback, useEffect, useReducer, useRef, useState, useSyncExternalStore } from 'react';
 import { getActiveAuthoring, hasAuthoringOverride } from '../authoring/active-adapter';
 import { CompositeAuthoringAdapter } from '../authoring/composite-authoring-adapter';
+import { requestWorldFocus, worldFocusScenePath } from '../authoring/edit-mode-authoring';
+import { provenanceForNode, unavailableReason } from '../authoring/provenance';
 import { requestRootActivation } from '../authoring/root-activation';
+import { resolveFocusedViewportWorldId } from '../authoring/world-hidden-viewport';
 import {
   isWorldHidden,
   isWorldInteractive,
@@ -60,8 +97,15 @@ import {
   toggleWorldInteractive,
   toggleWorldPickLock,
 } from '../authoring/world-session-state';
+import { DisclosureIcon, DropIndicator, EditorIcon, EditorToolbar, Panel } from '../design-system';
 import { useEditorStore } from '../EditorContext';
 import type { EditorStore } from '../editor-store';
+import { isSameWorldDrop } from '../hierarchy-drop';
+import {
+  clearHierarchyExpansionPreferences,
+  hierarchyExpansionPreference,
+  setHierarchyExpansionPreferences,
+} from '../hierarchy-expansion-state';
 import { getHierarchyMenuItems } from '../hierarchy-menu-registry';
 import { CHILD_CAP } from '../hierarchy-rows';
 import { setActiveScope } from '../hotkeys';
@@ -71,12 +115,14 @@ import {
   ingestRowKey,
   ingestRowWindow,
 } from '../ingest-hierarchy-rows';
+import { getCurrentProject } from '../project-manager';
+import { activateWorldDocument } from '../world-document-routing';
 import { OverlayReportBanner } from './OverlayReportBanner';
-import { Panel } from './primitives/Panel';
+import { openStoryDocumentByStoryId } from './story-documents';
 
 const ASSET_MIME = 'application/x-editor-asset';
 const REORDER_MIME = 'application/x-hierarchy-reorder';
-const ROW_HEIGHT = 24;
+const ROW_HEIGHT = chromeSize.treeRow;
 const INDENT = 14;
 
 // Wave-18-ported scroll-window sizing (docs/WAVE18-INGEST-HIERARCHY-VIRTUALIZATION-DESIGN.md),
@@ -102,19 +148,49 @@ const DEFAULT_VIEWPORT_PX = 2400;
 // dungeon is ~1900 rows), which is exactly the case wave-18 targeted.
 const VIRTUALIZE_MIN_ROWS = 300;
 
-const KIND_GLYPH: Record<string, string> = {
-  mesh: '◧',
-  light: '☀',
-  camera: '▣',
-  group: '▾',
-  object: '•',
-  // B3 — a react world's catalog component node (`kind:'component'`, the
-  // registry entry, not the entry-preview's DOM subtree). A neutral glyph
-  // (NOT react-branded) — this shell only ever knows the format-neutral
-  // `EditorNode.kind` string, never react internals.
-  component: '❖',
+const ROLE_ICON: Partial<Record<EditorNodeRole, IconDefinition>> = {
+  folder: faFolder,
+  document: faFileCode,
+  story: faCirclePlay,
+  component: faPuzzlePiece,
+  boundary: faTriangleExclamation,
+};
+
+const KIND_ICON: Record<string, IconDefinition> = {
+  threejs: faCube,
+  react: faCode,
+  pixijs: faLayerGroup,
+  scene: faBookOpen,
+  mesh: faCube,
+  light: faLightbulb,
+  camera: faCamera,
+  group: faObjectGroup,
+  object: faCircle,
+  component: faPuzzlePiece,
+  img: faImage,
+  a: faLink,
+  ul: faList,
+  ol: faList,
+  li: faList,
+  button: faSquare,
 };
 
+function iconForNode(node: EditorNode): IconDefinition {
+  if (node.role === 'root') return KIND_ICON[node.kind] ?? faLayerGroup;
+  if (node.role === 'entity' || node.role === 'element') {
+    return KIND_ICON[node.kind] ?? faCircle;
+  }
+  return (node.role ? ROLE_ICON[node.role] : undefined) ?? KIND_ICON[node.kind] ?? faCircle;
+}
+
+const STRUCTURAL_ROLES = new Set<EditorNodeRole>([
+  'folder',
+  'root',
+  'document',
+  'story',
+  'boundary',
+]);
+
 type DropZone = 'before' | 'child' | 'after';
 interface DropTarget {
   nodeId: string;
@@ -166,11 +242,17 @@ function siblingIdsOf(adapter: AuthoringAdapter, parentId: string | null): strin
 function compositeGroupBadge(
   adapter: AuthoringAdapter,
   nodeId: string,
-): { zOrder: number; worldId: string } | null {
+): {
+  zOrder: number;
+  worldId: string;
+  role: 'world' | 'surface';
+  kind: string;
+  provenance: AuthoringProvenance | null;
+} | null {
   if (!(adapter instanceof CompositeAuthoringAdapter)) return null;
   for (const child of adapter.childAdapters()) {
     if (adapter.groupNodeId(child.worldId) === nodeId) {
-      // A4 (D8) — prefer the LIVE manifest zOrder (editable on the game root,
+      // A4 (D8) — prefer the LIVE manifest zOrder (editable on the root row,
       // `composite.inspector.get(groupId, 'zOrder')`) over the array-index
       // fallback `child.zOrder`, so editing zOrder through the generic
       // inspector is reflected on this badge immediately (the write path
@@ -187,6 +269,11 @@ function compositeGroupBadge(
         // — eye/interactive/pick-lock) consistently with `design-time-layers.ts`,
         // which reads the SAME id off `composite.childAdapters()` directly.
         worldId: child.worldId,
+        role: child.role,
+        kind: child.kind,
+        // Spec 29 §5 — the world's own seam-level provenance declaration
+        // (null when the child adapter declared none; the row shows no chip).
+        provenance: child.adapter.provenance ?? null,
       };
     }
   }
@@ -200,15 +287,23 @@ function isCompositeGroupNode(adapter: AuthoringAdapter, nodeId: string): boolea
   return compositeGroupBadge(adapter, nodeId) !== null;
 }
 
+/** Editor-only kind/semantic projection rows have no native entity owner. */
+function isCompositeOrganizationNode(adapter: AuthoringAdapter, nodeId: string): boolean {
+  return adapter instanceof CompositeAuthoringAdapter && adapter.isOrganizationNode(nodeId);
+}
+
 /**
- * A4 (D8) — true only for the composite's synthetic game-root row. Asks the
- * adapter for its reserved id (`CompositeAuthoringAdapter.gameRootId`) rather
- * than hardcoding the string here — same "ask, don't sniff" discipline as
- * `groupNodeId()`/`compositeGroupBadge` above (Rule zero: this file never
- * decodes an adapter-minted id itself).
+ * The composite child adapter that OWNS `nodeId` — the adapter whose
+ * PROVIDERS answer for it — or the active adapter itself when bare. Affordance
+ * GATES must ask the owner (the composite's own `structure`/`inspector` are
+ * never-undefined routers, so probing them says "yes" for a row whose owning
+ * child would refuse — the false-claim pattern spec 29 §3 forbids); ACTIONS
+ * still go through the ACTIVE adapter, which routes by ownership.
  */
-function isGameRootNode(adapter: AuthoringAdapter, nodeId: string): boolean {
-  return adapter instanceof CompositeAuthoringAdapter && adapter.gameRootId === nodeId;
+function ownerAdapterOf(adapter: AuthoringAdapter, nodeId: string): AuthoringAdapter {
+  if (!(adapter instanceof CompositeAuthoringAdapter)) return adapter;
+  const worldId = adapter.ownerOf(nodeId);
+  return adapter.childAdapters().find((c) => c.worldId === worldId)?.adapter ?? adapter;
 }
 
 /**
@@ -230,6 +325,141 @@ function buildRootMembers(
   return map;
 }
 
+function isStructuralHierarchyNode(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+  role: EditorNodeRole | undefined,
+  rootMembers: ReadonlyMap<string, { groupId: string; active: boolean }>,
+): boolean {
+  return (
+    isCompositeGroupNode(adapter, nodeId) ||
+    isCompositeOrganizationNode(adapter, nodeId) ||
+    rootMembers.has(nodeId) ||
+    (role !== undefined && STRUCTURAL_ROLES.has(role))
+  );
+}
+
+/**
+ * First-open policy: organizational rows stay open, as does the first real
+ * authored node below them. Single-child wrapper chains continue open until
+ * the first meaningful branch; branches beneath that point start folded.
+ * This is shape-based — never label- or kind-based — so the same rule covers
+ * Three.js, React, PixiJS, and arbitrary projections.
+ */
+function defaultExpansionByNode(
+  rows: readonly IngestRow[],
+  adapter: AuthoringAdapter,
+  rootMembers: ReadonlyMap<string, { groupId: string; active: boolean }>,
+): Map<string, boolean> {
+  const result = new Map<string, boolean>();
+  const authoredDepthAtTreeDepth: number[] = [];
+  const nodeAtTreeDepth: IngestRow['node'][] = [];
+  for (const row of rows) {
+    if (row.more) continue;
+    const parentAuthoredDepth =
+      row.depth === 0 ? 0 : (authoredDepthAtTreeDepth[row.depth - 1] ?? 0);
+    const parentNode = row.depth === 0 ? null : nodeAtTreeDepth[row.depth - 1];
+    const structural = isStructuralHierarchyNode(adapter, row.node.id, row.node.role, rootMembers);
+    const authoredDepth = parentAuthoredDepth + (structural ? 0 : 1);
+    authoredDepthAtTreeDepth[row.depth] = authoredDepth;
+    authoredDepthAtTreeDepth.length = row.depth + 1;
+    nodeAtTreeDepth[row.depth] = row.node;
+    nodeAtTreeDepth.length = row.depth + 1;
+    result.set(row.node.id, structural || authoredDepth <= 1 || parentNode?.childIds.length === 1);
+  }
+  return result;
+}
+
+function ancestorPathKeys(pathKey: string): string[] {
+  const parts = pathKey.split('.');
+  const ancestors: string[] = [];
+  for (let i = 1; i < parts.length; i++) ancestors.push(parts.slice(0, i).join('.'));
+  return ancestors;
+}
+
+function searchPathKeys(rows: readonly IngestRow[], term: string): Set<string> {
+  const visible = new Set<string>();
+  for (const row of rows) {
+    if (row.more || !row.node.label.toLowerCase().includes(term)) continue;
+    visible.add(row.pathKey);
+    for (const ancestor of ancestorPathKeys(row.pathKey)) visible.add(ancestor);
+  }
+  return visible;
+}
+
+/** Make capped browse mode include a selected node at any sibling index. */
+function selectedRevealCounts(
+  rows: readonly IngestRow[],
+  selectedIds: ReadonlySet<string>,
+): Map<string, number> {
+  const revealed = new Map<string, number>();
+  for (const row of rows) {
+    if (!selectedIds.has(row.node.id)) continue;
+    const parts = row.pathKey.split('.');
+    let parent = parts[0]!;
+    for (let i = 1; i < parts.length; i++) {
+      const childIndex = Number(parts[i]);
+      if (Number.isFinite(childIndex)) {
+        revealed.set(parent, Math.max(revealed.get(parent) ?? 0, childIndex + 1));
+      }
+      parent = `${parent}.${parts[i]}`;
+    }
+  }
+  return revealed;
+}
+
+function selectedAncestorNodeIds(
+  rows: readonly IngestRow[],
+  selectedIds: ReadonlySet<string>,
+): Set<string> {
+  const ids = new Set<string>();
+  const byPath = new Map(rows.filter((row) => !row.more).map((row) => [row.pathKey, row.node.id]));
+  for (const row of rows) {
+    if (!selectedIds.has(row.node.id)) continue;
+    for (const ancestor of ancestorPathKeys(row.pathKey)) {
+      const id = byPath.get(ancestor);
+      if (id) ids.add(id);
+    }
+  }
+  return ids;
+}
+
+function mergeRevealCounts(
+  persisted: ReadonlyMap<string, number>,
+  temporary: ReadonlyMap<string, number>,
+): Map<string, number> {
+  const merged = new Map(persisted);
+  for (const [pathKey, count] of temporary) {
+    merged.set(pathKey, Math.max(merged.get(pathKey) ?? 0, count));
+  }
+  return merged;
+}
+
+function ViewButton({
+  label,
+  icon,
+  testId,
+  onClick,
+}: {
+  label: string;
+  icon: IconDefinition;
+  testId: string;
+  onClick: () => void;
+}) {
+  return (
+    <IconButton
+      title={label}
+      aria-label={label}
+      data-testid={testId}
+      onClick={onClick}
+      variant="secondary"
+      size="compact"
+    >
+      <EditorIcon icon={icon} aria-hidden="true" />
+    </IconButton>
+  );
+}
+
 // --- Context menu ---
 
 interface ContextMenuState {
@@ -283,54 +513,118 @@ function ContextMenu({
   if (!node) return null;
 
   const creatableKinds = adapter.structure?.creatableKinds?.(state.nodeId) ?? [];
-  const hasStructure = !!adapter.structure;
+  // Gates ask the OWNING child (see ownerAdapterOf) — the composite's own
+  // structure/inspector are never-undefined routers, so probing THEM would
+  // advertise operations the owner refuses (live-caught on a Boundary row:
+  // Duplicate/Hide/Delete rendered enabled and no-op'd). `visible` is a
+  // VALUE probe like `name`/`locked`: every live adapter answers it, a
+  // Boundary answers undefined.
+  const owner = ownerAdapterOf(adapter, state.nodeId);
+  const ownerStructure = owner.structure;
+  const hasStructure = !!ownerStructure;
   const nameKnown = adapter.inspector?.get(state.nodeId, 'name') !== undefined;
   const lockedKnown = adapter.inspector?.get(state.nodeId, 'locked') !== undefined;
   const locked = adapter.inspector?.get(state.nodeId, 'locked') === true;
-  const visibleKnown = adapter.inspector !== undefined;
+  const visibleKnown = adapter.inspector?.get(state.nodeId, 'visible') !== undefined;
   const visible = adapter.inspector?.get(state.nodeId, 'visible') !== false;
 
-  const items: { label: string; action: () => void; color?: string }[] = [];
-
-  if (!isGroupNode) {
-    if (nameKnown) {
+  // Spec 29 §5 disabled-with-reason: when the SUBJECT of an operation is
+  // present (the row exists) but the adapter can't perform it, the item
+  // renders DISABLED with the world's own provenance explanation as its
+  // tooltip — the complement of spec 28's rule (chrome whose subject is
+  // absent is hidden, not disabled).
+  const reason = unavailableReason(provenanceForNode(adapter, state.nodeId));
+  const items: {
+    label: string;
+    testId?: string;
+    action: () => void;
+    color?: string;
+    disabledReason?: string;
+  }[] = [];
+
+  // A4 (focus-switch) — a group row's ONE menu verb: make an unfocused
+  // threejs world (with a loadable scene) the live one. Same dirty-gated
+  // path as the row's double-click.
+  if (isGroupNode) {
+    const groupBadge = compositeGroupBadge(adapter, state.nodeId);
+    if (groupBadge && worldFocusScenePath(groupBadge.worldId) !== null) {
       items.push({
-        label: 'Rename',
+        label: 'Edit This World',
         action: () => {
-          onRename(state.nodeId);
+          requestWorldFocus(store, groupBadge.worldId);
           onClose();
         },
       });
     }
-    if (hasStructure) {
+  }
+
+  if (!isGroupNode) {
+    items.push({
+      label: 'Rename',
+      testId: 'hierarchy-context-menu-rename',
+      ...(nameKnown ? {} : { disabledReason: reason }),
+      action: () => {
+        onRename(state.nodeId);
+        onClose();
+      },
+    });
+    items.push({
+      label: 'Duplicate',
+      testId: 'hierarchy-context-menu-duplicate',
+      ...(hasStructure ? {} : { disabledReason: reason }),
+      action: () => {
+        adapter.structure!.duplicate(state.nodeId);
+        onClose();
+      },
+    });
+    if (ownerStructure?.wrap) {
       items.push({
-        label: 'Duplicate',
+        label: 'Wrap',
+        testId: 'hierarchy-context-menu-wrap',
         action: () => {
-          adapter.structure!.duplicate(state.nodeId);
+          ownerStructure.wrap!(state.nodeId);
           onClose();
         },
       });
     }
-    if (visibleKnown) {
+    if (ownerStructure?.unwrap) {
       items.push({
-        label: visible ? 'Hide' : 'Show',
+        label: 'Unwrap',
+        testId: 'hierarchy-context-menu-unwrap',
         action: () => {
-          adapter.inspector!.set(state.nodeId, 'visible', !visible);
-          store.notifyIngestEdit();
+          ownerStructure.unwrap!(state.nodeId);
           onClose();
         },
       });
     }
-    if (lockedKnown) {
+    if (node.parentId !== null) {
       items.push({
-        label: locked ? 'Unlock' : 'Lock',
+        label: 'Select Parent',
+        testId: 'hierarchy-context-menu-select-parent',
         action: () => {
-          adapter.inspector!.set(state.nodeId, 'locked', !locked);
-          store.notifyIngestEdit();
+          adapter.selection?.set([node.parentId!]);
           onClose();
         },
       });
     }
+    items.push({
+      label: visibleKnown && !visible ? 'Show' : 'Hide',
+      ...(visibleKnown ? {} : { disabledReason: reason }),
+      action: () => {
+        adapter.inspector!.set(state.nodeId, 'visible', !visible);
+        store.notifyIngestEdit();
+        onClose();
+      },
+    });
+    items.push({
+      label: locked ? 'Unlock' : 'Lock',
+      ...(lockedKnown ? {} : { disabledReason: reason }),
+      action: () => {
+        adapter.inspector!.set(state.nodeId, 'locked', !locked);
+        store.notifyIngestEdit();
+        onClose();
+      },
+    });
     // First-party escape-hatch extras (prefab unpack/open/save-as, …) —
     // permanent adapter-module contribution seam (see hierarchy-menu-registry.ts).
     for (const extra of getHierarchyMenuItems({ nodeId: state.nodeId, store })) {
@@ -343,16 +637,16 @@ function ContextMenu({
         },
       });
     }
-    if (hasStructure) {
-      items.push({
-        label: 'Delete',
-        color: '#ff6b6b',
-        action: () => {
-          adapter.structure!.remove(state.nodeId);
-          onClose();
-        },
-      });
-    }
+    items.push({
+      label: 'Delete',
+      testId: 'hierarchy-context-menu-delete',
+      color: themeVars.semantic.danger,
+      ...(hasStructure ? {} : { disabledReason: reason }),
+      action: () => {
+        adapter.structure!.remove(state.nodeId);
+        onClose();
+      },
+    });
   }
 
   return (
@@ -363,39 +657,52 @@ function ContextMenu({
         position: 'fixed',
         left: state.x,
         top: state.y,
-        background: '#2c2c2c',
-        border: '1px solid #444',
-        borderRadius: 4,
-        padding: '4px 0',
-        zIndex: 1000,
+        // Menus/popovers contract (editor-style-polish §5): bg-2/border-2/
+        // radius-md/shadow-md, item padding aligned to `.vgai-menu-item`.
+        background: themeVars.surface.chrome,
+        border: `1px solid ${themeVars.boundary.strong}`,
+        borderRadius: themeVars.shape.medium,
+        padding: `${space[2]}px 0`,
+        zIndex: zIndex.sticky,
         minWidth: 150,
         maxWidth: 260,
-        boxShadow: '0 4px 12px rgba(0,0,0,0.5)',
-        fontSize: 12,
-        color: '#c5c8ce',
+        boxShadow: themeVars.elevation.medium,
+        fontSize: 'var(--vgai-font-base)',
+        color: themeVars.content.primary,
       }}
     >
       {/* A4 (D8): also suppressed for a root-group MEMBER row, same as an
           existing composite group row — `isGroupNode` covers both (see the
-          caller's computation below). Create▸ on a member id would silently
+          caller's computation below). The Create submenu on a member id would silently
           land at the scene root instead of doing anything meaningful. */}
       {!isGroupNode && creatableKinds.length > 0 && (
         <div>
           <div
+            data-testid="hierarchy-context-menu-create"
             role="menuitem"
             tabIndex={0}
             onClick={() => setCreateOpen((v) => !v)}
             onKeyDown={(e) => {
               if (e.key === 'Enter') setCreateOpen((v) => !v);
             }}
-            style={{ padding: '5px 12px', cursor: 'pointer' }}
+            style={{
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'space-between',
+              gap: space[4],
+              padding: `${space[2]}px ${space[4]}px`,
+              cursor: 'pointer',
+            }}
           >
-            Create ▸
+            <span>Create</span>
+            <DisclosureIcon direction="right" tone="dim" />
           </div>
           {createOpen &&
             creatableKinds.map((k) => (
               <div
+                className="vgai-menu-item"
                 key={k.kind}
+                data-testid={`hierarchy-context-menu-create-${k.kind}`}
                 role="menuitem"
                 tabIndex={0}
                 onClick={() => {
@@ -412,12 +719,9 @@ function ContextMenu({
                     onClose();
                   }
                 }}
-                style={{ padding: '5px 12px 5px 24px', cursor: 'pointer' }}
-                onMouseEnter={(e) => {
-                  (e.currentTarget as HTMLDivElement).style.background = '#3a3a3a';
-                }}
-                onMouseLeave={(e) => {
-                  (e.currentTarget as HTMLDivElement).style.background = 'transparent';
+                style={{
+                  padding: `${space[2]}px ${space[4]}px ${space[2]}px 24px`,
+                  cursor: 'pointer',
                 }}
               >
                 {k.label}
@@ -425,33 +729,60 @@ function ContextMenu({
             ))}
         </div>
       )}
-      {items.map((item) => (
-        <div
-          key={item.label}
-          role="menuitem"
-          tabIndex={0}
-          onClick={item.action}
-          onKeyDown={(e) => {
-            if (e.key === 'Enter') item.action();
-          }}
-          style={{ padding: '5px 12px', cursor: 'pointer', color: item.color ?? '#c5c8ce' }}
-          onMouseEnter={(e) => {
-            (e.currentTarget as HTMLDivElement).style.background = '#3a3a3a';
-          }}
-          onMouseLeave={(e) => {
-            (e.currentTarget as HTMLDivElement).style.background = 'transparent';
-          }}
-        >
-          {item.label}
-        </div>
-      ))}
+      {items.map((item) =>
+        item.disabledReason !== undefined ? (
+          <div
+            className="vgai-menu-item"
+            key={item.label}
+            data-testid={item.testId}
+            role="menuitem"
+            aria-disabled="true"
+            title={item.disabledReason}
+            style={{
+              padding: `${space[2]}px ${space[4]}px`,
+              // L-21 — disabled rows get a dedicated muted color (not just
+              // opacity-faded active text) plus a not-allowed cursor.
+              cursor: 'not-allowed',
+              color: themeVars.content.dim,
+              opacity: 0.7,
+            }}
+          >
+            {item.label}
+          </div>
+        ) : (
+          <div
+            key={item.label}
+            data-testid={item.testId}
+            role="menuitem"
+            tabIndex={0}
+            onClick={item.action}
+            onKeyDown={(e) => {
+              if (e.key === 'Enter') item.action();
+            }}
+            style={{
+              padding: `${space[2]}px ${space[4]}px`,
+              cursor: 'pointer',
+              color: item.color ?? themeVars.content.primary,
+            }}
+          >
+            {item.label}
+          </div>
+        ),
+      )}
       {/* Bounded-authoring honest degrade (landmine f): the ACTIVE adapter has
           no `structure` provider at all (an ingested/foreign game owns its
           own scene graph) — Rename/Show-Hide/Lock above still work (they're
           gated independently, on `inspector`), but Create/Duplicate/Delete/
           Reparent are not, so say so plainly instead of hiding the menu. */}
       {!hasStructure && (
-        <div style={{ padding: '8px 12px', color: '#c9a227', maxWidth: 240, lineHeight: 1.4 }}>
+        <div
+          style={{
+            padding: `${space[4]}px ${space[6]}px`,
+            color: themeVars.semantic.warning,
+            maxWidth: 240,
+            lineHeight: 1.4,
+          }}
+        >
           <strong>Create / Delete / Reparent — not available.</strong> This game owns its own scene
           graph, so structural authoring isn't reapplicable. You can edit transform / material /
           visibility, or capture a subtree into the first-party editable format.
@@ -474,6 +805,7 @@ function CreateMenu({ adapter, parentId }: { adapter: AuthoringAdapter; parentId
   // the same commit; a ref reset on each open bounds it to one create per open.
   const creatingRef = useRef(false);
   const kinds = adapter.structure?.creatableKinds?.(parentId) ?? [];
+  const targetLabel = parentId ? adapter.hierarchy.node(parentId)?.label : null;
 
   useEffect(() => {
     if (!open) return;
@@ -496,42 +828,42 @@ function CreateMenu({ adapter, parentId }: { adapter: AuthoringAdapter; parentId
 
   return (
     <div ref={ref} style={{ position: 'relative', flexShrink: 0 }}>
-      <span
-        role="button"
-        title="Add Entity"
+      {/* L-11 — same fixed 20×20 boxed treatment as its `ViewButton` siblings
+          in the toolbar row (collapse/expand/reset), instead of an unboxed
+          inline span with mismatched padding. */}
+      <Button
+        title={targetLabel ? `Add to ${targetLabel}` : 'Add'}
+        aria-label={targetLabel ? `Add to ${targetLabel}` : 'Add'}
+        aria-expanded={open}
         data-testid="hierarchy-add-menu"
         onClick={() => setOpen(!open)}
-        style={{
-          cursor: 'pointer',
-          fontSize: 13,
-          padding: '1px 4px',
-          borderRadius: 3,
-          background: open ? '#3a3a3a' : 'transparent',
-          userSelect: 'none',
-          color: '#c5c8ce',
-        }}
+        variant={open ? 'primary' : 'secondary'}
+        size="compact"
       >
-        <FontAwesomeIcon icon={faPlus} style={{ fontSize: 10 }} />{' '}
-        <FontAwesomeIcon icon={faCaretDown} style={{ fontSize: 9 }} />
-      </span>
+        <EditorIcon icon={faPlus} style={{ fontSize: 'var(--vgai-font-sm)' }} />{' '}
+        <EditorIcon icon={faCaretDown} style={{ fontSize: 'var(--vgai-font-xs)' }} />
+      </Button>
       {open && (
         <div
           style={{
             position: 'absolute',
             top: '100%',
             right: 0,
-            marginTop: 4,
-            background: '#2c2c2c',
-            border: '1px solid #444',
-            borderRadius: 4,
-            padding: '4px 0',
-            zIndex: 1000,
+            marginTop: space[2],
+            background: themeVars.surface.chrome,
+            border: `1px solid ${themeVars.boundary.strong}`,
+            borderRadius: themeVars.shape.medium,
+            padding: `${space[2]}px 0`,
+            zIndex: zIndex.sticky,
             minWidth: 130,
-            boxShadow: '0 4px 12px rgba(0,0,0,0.5)',
+            maxHeight: 'min(480px, 70vh)',
+            overflowY: 'auto',
+            boxShadow: themeVars.elevation.medium,
           }}
         >
           {kinds.map((k) => (
             <div
+              className="vgai-menu-item"
               key={k.kind}
               data-testid={`hierarchy-add-${k.kind}`}
               onClick={() => {
@@ -540,12 +872,11 @@ function CreateMenu({ adapter, parentId }: { adapter: AuthoringAdapter; parentId
                 adapter.structure!.create(k.kind, parentId ?? undefined);
                 setOpen(false);
               }}
-              style={{ padding: '5px 12px', cursor: 'pointer', fontSize: 12, color: '#c5c8ce' }}
-              onMouseEnter={(e) => {
-                (e.currentTarget as HTMLDivElement).style.background = '#3a3a3a';
-              }}
-              onMouseLeave={(e) => {
-                (e.currentTarget as HTMLDivElement).style.background = 'transparent';
+              style={{
+                padding: `${space[2]}px ${space[4]}px`,
+                cursor: 'pointer',
+                fontSize: 'var(--vgai-font-base)',
+                color: themeVars.content.primary,
               }}
             >
               {k.label}
@@ -562,27 +893,18 @@ function CreateMenu({ adapter, parentId }: { adapter: AuthoringAdapter; parentId
 function MoreRow({ row, onReveal }: { row: IngestRow; onReveal: (parentPathKey: string) => void }) {
   const hidden = row.more!.hidden;
   return (
-    <button
+    <Button
       type="button"
+      variant="ghost"
+      className="vgai-hierarchy-more"
       data-testid="ingest-row-more"
       onClick={() => onReveal(row.more!.parentPathKey)}
       style={{
-        display: 'flex',
-        alignItems: 'center',
-        width: '100%',
-        height: ROW_HEIGHT,
         paddingLeft: row.depth * INDENT + INDENT,
-        border: 'none',
-        background: 'transparent',
-        color: '#7d828c',
-        fontSize: 12,
-        fontStyle: 'italic',
-        textAlign: 'left',
-        cursor: 'pointer',
       }}
     >
       … {hidden} more
-    </button>
+    </Button>
   );
 }
 
@@ -608,7 +930,11 @@ function highlightSegments(label: string, term: string): React.ReactNode {
       <mark
         key={key++}
         data-testid="ingest-row-search-highlight"
-        style={{ background: '#e0a030', color: '#1a1a1a', borderRadius: 2 }}
+        style={{
+          background: themeVars.semantic.warning,
+          color: themeVars.surface.shell,
+          borderRadius: themeVars.shape.small,
+        }}
       >
         {label.slice(idx, idx + needle.length)}
       </mark>,
@@ -633,6 +959,7 @@ function Row({
   searchTerm,
   onToggleOpen,
   onStartEditing,
+  focusedWorldId,
   onContextMenu,
   onDragStart,
   onClick,
@@ -649,28 +976,36 @@ function Row({
   /** A4 (D8) — set when this row is a root-group member (a scene-file
    *  root); `active` is whether it's the currently-loaded one. */
   rootMember: { groupId: string; active: boolean } | undefined;
+  /** A4 (focus-switch) — the live/focused viewport world, recomputed by the
+   *  panel per notify (`resolveFocusedViewportWorldId`); group rows render
+   *  the ●/○ focus radio against it. */
+  focusedWorldId: string | null;
   /** D4 — the trimmed, lowercased-by-the-caller search term (empty string
    *  when the search box is empty), for {@link highlightSegments}. */
   searchTerm: string;
-  onToggleOpen: (pathKey: string) => void;
+  onToggleOpen: (row: IngestRow, recursive: boolean) => void;
   onStartEditing: (id: string) => void;
   onContextMenu: (e: React.MouseEvent, id: string) => void;
   onDragStart: (e: React.DragEvent, id: string) => void;
   onClick: (e: React.MouseEvent, id: string) => void;
   onActivateRoot: (groupId: string, rootId: string) => void;
 }) {
-  const { node, depth, hasChildren, pathKey } = row;
+  const { node, depth, hasChildren } = row;
   // A composite `world:<id>` group row (session-local eye per D9, zOrder badge,
   // non-draggable) — NOT merely a runtime-only node (see `isCompositeGroupNode`).
   const badge = compositeGroupBadge(adapter, node.id);
   const isGroupNode = badge !== null;
-  // A4 (D8) — the synthetic game root, and a root-group member (scene-file
-  // root) row. Neither owns a real name/visible/locked path, isn't
+  // A4 (D8) — a root-group member (scene-file root) row does not own a real
+  // name/visible/locked path, isn't
   // draggable, and carries no `data-entity-name` (landmine: every project
   // ships 2+ scene-file members — they must not pollute `getEntityNames()`).
-  const isGameRootRow = isGameRootNode(adapter, node.id);
   const isMemberRow = rootMember !== undefined;
-  const isStructural = isGroupNode || isGameRootRow || isMemberRow;
+  const isOrganizationRow = isCompositeOrganizationNode(adapter, node.id);
+  const isStructural =
+    isGroupNode ||
+    isOrganizationRow ||
+    isMemberRow ||
+    (node.role !== undefined && STRUCTURAL_ROLES.has(node.role));
   // Reserved-path reads, resolved ONCE per row and only for non-structural
   // rows: an adapter that doesn't support a reserved path returns
   // `undefined` (its affordance simply doesn't render). Cheap for every
@@ -679,7 +1014,11 @@ function Row({
   // reads a plain descriptor.
   const lockedValue = isStructural ? undefined : adapter.inspector?.get(node.id, 'locked');
   const nameValue = isStructural ? undefined : adapter.inspector?.get(node.id, 'name');
-  const visibleKnown = !isStructural && adapter.inspector !== undefined;
+  // VALUE probe like `locked`/`name` above (not provider presence — the
+  // composite's inspector is a never-undefined router, which put a no-op eye
+  // on Boundary rows): every live adapter answers `visible`; a Boundary
+  // answers undefined and gets no eye.
+  const visibleKnown = !isStructural && adapter.inspector?.get(node.id, 'visible') !== undefined;
   // B1 (D9) — a group row's eye/interactive/pick-lock read the LIFTED,
   // module-level session store (`world-session-state.ts`), keyed by the
   // RAW manifest world id `badge.worldId` — not the group-node id itself.
@@ -691,20 +1030,57 @@ function Row({
   const locked = lockedValue === true;
   const nameKnown = nameValue !== undefined;
 
-  const bg =
-    dropZone === 'child' ? 'rgba(87, 158, 255, 0.25)' : isSelected ? '#2a4a7a' : 'transparent';
-
   return (
     <div
-      data-entity-name={isMemberRow || isGameRootRow ? undefined : node.label}
+      className="vgai-tree-row"
+      data-entity-name={isMemberRow || isOrganizationRow ? undefined : node.label}
       data-testid="ingest-row"
       data-ingest-name={node.label}
+      data-node-role={node.role}
+      data-selected={isSelected ? 'true' : undefined}
+      data-dragging={isDragged ? 'true' : undefined}
+      data-muted={
+        (!isStructural && !visible) || (rootMember && !rootMember.active) ? 'true' : undefined
+      }
       draggable={!isStructural}
       onDragStart={(e) => onDragStart(e, node.id)}
-      onClick={(e) => onClick(e, node.id)}
+      onClick={(e) => {
+        if (badge?.role === 'world') {
+          // Runtime composition belongs to Game. In edit mode a manifest
+          // world row is a document navigator: one click reveals that
+          // world's isolated authoring surface, matching scene/file trees in
+          // established editors. A Three world additionally switches the
+          // native scene slot when it is not already focused.
+          activateWorldDocument(badge.worldId);
+          if (
+            badge.kind === 'threejs' &&
+            focusedWorldId !== badge.worldId &&
+            worldFocusScenePath(badge.worldId) !== null
+          ) {
+            requestWorldFocus(store, badge.worldId);
+          }
+        }
+        if (node.role === 'story') {
+          // §4.2 (W2): clicking a story row selects it, applies it to its
+          // React root (the existing behavior below), AND opens/activates
+          // its CENTER story document — resolved through the live story
+          // registry; a row whose id isn't a discovered portable story
+          // (e.g. a legacy registry story) opens no document (nothing is
+          // fabricated). During Play the live connector owns the root:
+          // portable-story rows aren't projected then, and the document
+          // path never touches the play session either way.
+          if (node.flags.active !== true) adapter.stories?.apply(node.id, node.id);
+          openStoryDocumentByStoryId(store, node.id);
+        }
+        onClick(e, node.id);
+      }}
       onDoubleClick={() => {
         if (rootMember && !rootMember.active) {
           onActivateRoot(rootMember.groupId, node.id);
+        } else if (badge?.role === 'world' && worldFocusScenePath(badge.worldId) !== null) {
+          // A4 — same gesture as the D8 radio roots, one level up: an
+          // inactive-but-switchable threejs world becomes the focused one.
+          requestWorldFocus(store, badge.worldId);
         } else if (nameKnown) {
           onStartEditing(node.id);
         }
@@ -715,88 +1091,96 @@ function Row({
       }}
       style={{
         position: 'relative',
-        display: 'flex',
-        alignItems: 'center',
         height: ROW_HEIGHT,
         paddingLeft: depth * INDENT,
         paddingRight: 4,
         gap: 4,
         cursor: 'pointer',
-        background: bg,
-        outline: dropZone === 'child' ? '1px dashed #579EFF' : 'none',
+        outline: dropZone === 'child' ? `1px dashed ${themeVars.accent.default}` : 'none',
         whiteSpace: 'nowrap',
         overflow: 'hidden',
-        opacity:
-          isDragged || (!isStructural && !visible) || (rootMember && !rootMember.active) ? 0.45 : 1,
-        fontSize: 13,
-        color: '#c5c8ce',
-        userSelect: 'none',
+        fontSize: 'var(--vgai-font-lg)',
       }}
     >
       {dropZone === 'before' && (
-        <div
-          style={{
-            position: 'absolute',
-            top: 0,
-            left: depth * INDENT,
-            right: 0,
-            height: 2,
-            background: '#579EFF',
-            pointerEvents: 'none',
-            zIndex: 10,
-          }}
-        />
+        <DropIndicator position="before" style={{ left: depth * INDENT }} />
       )}
-      {dropZone === 'after' && (
-        <div
-          style={{
-            position: 'absolute',
-            bottom: 0,
-            left: depth * INDENT,
-            right: 0,
-            height: 2,
-            background: '#579EFF',
-            pointerEvents: 'none',
-            zIndex: 10,
+      {dropZone === 'after' && <DropIndicator position="after" style={{ left: depth * INDENT }} />}
+
+      {hasChildren ? (
+        <IconButton
+          type="button"
+          variant="ghost"
+          size="compact"
+          aria-label={isCollapsed ? `Expand ${node.label}` : `Collapse ${node.label}`}
+          data-testid="ingest-row-caret"
+          onClick={(e) => {
+            e.stopPropagation();
+            onToggleOpen(row, e.altKey);
           }}
+          title="Expand/collapse (Option/Alt-click applies to the branch)"
+          className="vgai-tree-caret"
+        >
+          <EditorIcon icon={isCollapsed ? faCaretRight : faCaretDown} aria-hidden="true" />
+        </IconButton>
+      ) : (
+        <span
+          data-testid="ingest-row-caret"
+          aria-hidden="true"
+          style={{ width: 12, flexShrink: 0 }}
         />
       )}
 
-      <span
-        data-testid="ingest-row-caret"
-        onClick={(e) => {
-          e.stopPropagation();
-          onToggleOpen(pathKey);
-        }}
-        style={{
-          width: 12,
-          fontSize: 8,
-          textAlign: 'center',
-          flexShrink: 0,
-          cursor: hasChildren ? 'pointer' : 'default',
-          color: '#8c8c8c',
-        }}
-      >
-        {hasChildren ? <FontAwesomeIcon icon={isCollapsed ? faCaretRight : faCaretDown} /> : ''}
-      </span>
-
       {rootMember && (
         <span
           data-testid="root-radio"
           data-root-active={rootMember.active ? 'true' : 'false'}
           title={rootMember.active ? 'Active root' : 'Inactive root — double-click to activate'}
-          style={{ fontSize: 9, opacity: 0.8, flexShrink: 0 }}
+          style={{ fontSize: 'var(--vgai-font-xs)', opacity: 0.8, flexShrink: 0 }}
         >
-          {rootMember.active ? '●' : '○'}
+          <EditorIcon icon={rootMember.active ? faCircleDot : faCircle} aria-hidden="true" />
         </span>
       )}
 
-      <span style={{ fontSize: 10, opacity: 0.6, flexShrink: 0 }}>
-        {KIND_GLYPH[node.kind] ?? '•'}
+      {/* A4 (focus-switch) — the world-level radio, same visual grammar as the
+       *  D8 scene-root radio above: ● = the live/focused viewport world,
+       *  ○ = an unfocused threejs world with a loadable scene (double-click or
+       *  context-menu "Edit This World" to focus it). Worlds that are neither
+       *  (DOM/pixi kinds, entry-only threejs) show no dot — nothing to claim. */}
+      {badge?.role === 'world' &&
+        (badge.worldId === focusedWorldId || worldFocusScenePath(badge.worldId) !== null) && (
+          <span
+            data-testid="world-focus-radio"
+            data-world-focused={badge.worldId === focusedWorldId ? 'true' : 'false'}
+            title={
+              badge.worldId === focusedWorldId
+                ? 'Focused world — live in the viewport'
+                : 'Inactive world — double-click to edit it'
+            }
+            style={{ fontSize: 'var(--vgai-font-xs)', opacity: 0.8, flexShrink: 0 }}
+          >
+            <EditorIcon
+              icon={badge.worldId === focusedWorldId ? faCircleDot : faCircle}
+              aria-hidden="true"
+            />
+          </span>
+        )}
+
+      <span
+        title={node.role ? `${node.role}: ${node.kind}` : node.kind}
+        style={{
+          width: 12,
+          fontSize: 'var(--vgai-font-sm)',
+          opacity: 0.65,
+          flexShrink: 0,
+          textAlign: 'center',
+        }}
+      >
+        <EditorIcon icon={iconForNode(node)} aria-hidden="true" />
       </span>
 
       {isEditing ? (
-        <input
+        <TextInput
           autoFocus
           defaultValue={node.label}
           onBlur={(e) => {
@@ -816,44 +1200,80 @@ function Row({
           style={{
             flex: 1,
             minWidth: 0,
-            background: '#1a1a1a',
-            border: '1px solid #579EFF',
-            borderRadius: 2,
-            color: '#c5c8ce',
-            fontSize: 13,
-            padding: '0 4px',
+            background: themeVars.surface.inset,
+            border: `1px solid ${themeVars.accent.default}`,
+            borderRadius: themeVars.shape.small,
+            color: themeVars.content.primary,
+            fontSize: 'var(--vgai-font-lg)',
+            padding: `0 ${space[2]}px`,
             outline: 'none',
           }}
         />
       ) : (
         <span style={{ flex: 1, minWidth: 0, overflow: 'hidden', textOverflow: 'ellipsis' }}>
           {highlightSegments(node.label, searchTerm)}
-          {badge && (
-            <span style={{ marginLeft: 6, fontSize: 10, opacity: 0.6 }}>z{badge.zOrder}</span>
+          {node.secondaryLabel && (
+            <span style={{ marginLeft: 6, fontSize: 'var(--vgai-font-sm)', opacity: 0.5 }}>
+              {node.secondaryLabel}
+            </span>
+          )}
+          {badge?.role === 'world' && badge.zOrder !== 0 && (
+            <span
+              title={`Z order: ${badge.zOrder}`}
+              style={{ marginLeft: 6, fontSize: 'var(--vgai-font-sm)', opacity: 0.6 }}
+            >
+              Z {badge.zOrder}
+            </span>
+          )}
+          {badge?.provenance && (
+            <span
+              data-testid="world-provenance"
+              data-provenance={badge.provenance.source}
+              title={badge.provenance.detail}
+              style={{
+                marginLeft: 6,
+                fontSize: 'var(--vgai-font-xs)',
+                padding: `0 ${space[2]}px`,
+                borderRadius: themeVars.shape.small,
+                border: `1px solid ${themeVars.boundary.strong}`,
+                color: themeVars.content.muted,
+                verticalAlign: 'middle',
+              }}
+            >
+              {badge.provenance.label}
+            </span>
           )}
         </span>
       )}
 
       {lockedKnown && (
-        <span
+        <IconButton
+          type="button"
+          variant="ghost"
+          size="compact"
           data-testid="ingest-row-lock"
-          title="Toggle Lock"
+          title={locked ? 'Unlock' : 'Lock'}
+          aria-label={locked ? `Unlock ${node.label}` : `Lock ${node.label}`}
+          aria-pressed={locked}
           onClick={(e) => {
             e.stopPropagation();
             adapter.inspector!.set(node.id, 'locked', !locked);
             store.notifyIngestEdit();
           }}
-          style={{ fontSize: 9, cursor: 'pointer', flexShrink: 0, opacity: locked ? 0.8 : 0.35 }}
         >
-          <FontAwesomeIcon icon={locked ? faLock : faLockOpen} />
-        </span>
+          <EditorIcon icon={locked ? faLock : faLockOpen} aria-hidden="true" />
+        </IconButton>
       )}
 
       {(visibleKnown || isGroupNode) && (
-        <button
+        <IconButton
           type="button"
+          variant="ghost"
+          size="compact"
           data-testid="ingest-row-visibility"
           title={visible ? 'Hide' : 'Show'}
+          aria-label={visible ? `Hide ${node.label}` : `Show ${node.label}`}
+          aria-pressed={!visible}
           onClick={(e) => {
             e.stopPropagation();
             if (badge) {
@@ -864,19 +1284,9 @@ function Row({
               store.notifyIngestEdit();
             }
           }}
-          style={{
-            width: 20,
-            height: 20,
-            border: 'none',
-            background: 'transparent',
-            color: visible ? '#9aa0a6' : '#e0a030',
-            cursor: 'pointer',
-            fontSize: 11,
-            flexShrink: 0,
-          }}
         >
-          <FontAwesomeIcon icon={visible ? faEye : faEyeSlash} />
-        </button>
+          <EditorIcon icon={visible ? faEye : faEyeSlash} aria-hidden="true" />
+        </IconButton>
       )}
 
       {/* B1 (D9) — session-local, per-world design-time toggles: `interactive`
@@ -885,48 +1295,46 @@ function Row({
        *  for B4's layered viewport picking to consume. Group rows only —
        *  neither concept applies to an ordinary entity row. */}
       {badge && (
-        <span
+        <IconButton
+          type="button"
+          variant="ghost"
+          size="compact"
           data-testid="world-interactive-toggle"
           title={
             worldInteractive
               ? 'Interactive (layer forwards pointer events)'
               : 'Not interactive (layer is pointer-events:none)'
           }
+          aria-label={`Forward pointer events to ${node.label}`}
+          aria-pressed={worldInteractive}
           onClick={(e) => {
             e.stopPropagation();
             toggleWorldInteractive(badge.worldId);
             store.notifyIngestEdit();
           }}
-          style={{
-            fontSize: 9,
-            cursor: 'pointer',
-            flexShrink: 0,
-            opacity: worldInteractive ? 0.9 : 0.35,
-          }}
         >
-          <FontAwesomeIcon icon={faHandPointer} />
-        </span>
+          <EditorIcon icon={faHandPointer} aria-hidden="true" />
+        </IconButton>
       )}
       {badge && (
-        <span
+        <IconButton
+          type="button"
+          variant="ghost"
+          size="compact"
           data-testid="world-picklock-toggle"
           title={
             worldPickLocked ? 'Pick-locked (skipped by topmost-layer picking)' : 'Not pick-locked'
           }
+          aria-label={`Exclude ${node.label} from viewport picking`}
+          aria-pressed={worldPickLocked}
           onClick={(e) => {
             e.stopPropagation();
             toggleWorldPickLock(badge.worldId);
             store.notifyIngestEdit();
           }}
-          style={{
-            fontSize: 9,
-            cursor: 'pointer',
-            flexShrink: 0,
-            opacity: worldPickLocked ? 0.9 : 0.35,
-          }}
         >
-          <FontAwesomeIcon icon={faCrosshairs} />
-        </span>
+          <EditorIcon icon={faCrosshairs} aria-hidden="true" />
+        </IconButton>
       )}
     </div>
   );
@@ -938,6 +1346,9 @@ export function GameHierarchy() {
   const store = useEditorStore();
   useSyncExternalStore(store.subscribe, store.getSnapshot);
   const adapter = getActiveAuthoring(store);
+  // A4 — recomputed per notify (never cached across notifies): drives the
+  // world-group rows' ●/○ focus radio.
+  const focusedViewportWorldId = resolveFocusedViewportWorldId(store);
 
   const [search, setSearch] = useState('');
   const [contextMenu, setContextMenu] = useState<ContextMenuState | null>(null);
@@ -957,28 +1368,94 @@ export function GameHierarchy() {
   const [scrollTop, setScrollTop] = useState(0);
 
   const containerRef = useRef<HTMLDivElement>(null);
-  const collapsedKeysRef = useRef(new Set<string>());
   const revealedRef = useRef(new Map<string, number>());
+  const sessionExpansionRef = useRef(new Map<string, boolean>());
+  const sessionExpansionProjectRef = useRef<string | null>(null);
+  const lastSelectionExpansionRef = useRef<{
+    adapter: AuthoringAdapter;
+    selection: string;
+  } | null>(null);
   const lastClickedRef = useRef<string | null>(null);
+  const lastAutoRevealRef = useRef<{ adapter: AuthoringAdapter; selection: string } | null>(null);
   const [, forceUpdate] = useReducer((x: number) => x + 1, 0);
 
   const term = search.trim().toLowerCase();
+  const projectIdentity = getCurrentProject()?.rootPath ?? '__unscoped__';
+  // A4 (D8) — every root-group member, rebuilt each render straight from
+  // `rootGroups.groups()` (never from the id string — see `buildRootMembers`'s
+  // doc comment).
+  const rootMembers = buildRootMembers(adapter);
+  const selected = adapter.selection?.get() ?? [];
+  const selectedIds = new Set(selected);
+  // The toolbar's generic Add menu targets the selected hierarchy node. The
+  // composite adapter then routes the request to that node's owning world
+  // adapter, whose `creatableKinds` is the sole source of menu contents.
+  // Multi-selection has no unambiguous parent, so it intentionally falls
+  // back to the active adapter's root-level insertion behavior.
+  const createTargetId = selected.length === 1 ? selected[0]! : null;
+  const selectionSignature = [...selectedIds].sort().join('\0');
+
+  if (sessionExpansionProjectRef.current !== projectIdentity) {
+    sessionExpansionRef.current.clear();
+    sessionExpansionProjectRef.current = projectIdentity;
+    lastSelectionExpansionRef.current = null;
+  }
+
+  // Always take one uncapped, uncollapsed structural snapshot first. It is
+  // the source for stable defaults, search ancestry, selection reveal, and
+  // branch operations. The final browse tree below is still capped and
+  // virtualized, so this does not inflate rendered DOM for large ingests.
+  const structuralRows = flattenIngestRows(adapter.hierarchy, new Set());
+  const defaultExpansion = defaultExpansionByNode(structuralRows, adapter, rootMembers);
+
+  // Selection reveal behaves like an ordinary tree expansion for the rest of
+  // this editor session. It is applied only when selection changes, so a user
+  // can explicitly collapse the revealed branch without the current
+  // selection immediately forcing it open again.
+  const lastExpansion = lastSelectionExpansionRef.current;
+  if (lastExpansion?.adapter !== adapter || lastExpansion.selection !== selectionSignature) {
+    for (const id of selectedAncestorNodeIds(structuralRows, selectedIds)) {
+      sessionExpansionRef.current.set(id, true);
+    }
+    lastSelectionExpansionRef.current = { adapter, selection: selectionSignature };
+  }
+
+  const isExpanded = (row: IngestRow): boolean =>
+    sessionExpansionRef.current.get(row.node.id) ??
+    hierarchyExpansionPreference(projectIdentity, row.node.id) ??
+    defaultExpansion.get(row.node.id) ??
+    true;
+
+  const persistedCollapsedPaths = new Set(
+    structuralRows
+      .filter((row) => !row.more && row.hasChildren && !isExpanded(row))
+      .map((row) => row.pathKey),
+  );
+  const effectiveCollapsedPaths = persistedCollapsedPaths;
+
   // Cap browse-view children (D-C1) whenever a non-first-party/composite
   // session is active (an ingested/multi-world tree may be huge), OR while
   // playing (a live scene graph can also balloon) — matches the exact
   // capping policy the former SceneHierarchy (play-only) / IngestHierarchy
   // (always, unless searching) components each had on their own.
   const capEnabled = term.length === 0 && (hasAuthoringOverride() || store.playState !== 'stopped');
-
-  const allRows = flattenIngestRows(
-    adapter.hierarchy,
-    collapsedKeysRef.current,
+  const temporaryRevealed = mergeRevealCounts(
     revealedRef.current,
+    selectedRevealCounts(structuralRows, selectedIds),
+  );
+  const browseRows = flattenIngestRows(
+    adapter.hierarchy,
+    effectiveCollapsedPaths,
+    temporaryRevealed,
     capEnabled,
   );
+  const matchingPaths = term ? searchPathKeys(structuralRows, term) : null;
+  const sourceRows = matchingPaths
+    ? structuralRows.filter((row) => matchingPaths.has(row.pathKey))
+    : browseRows;
   // Session-local world-hide (D9): drop every row belonging to a hidden world
   // group (the group row itself stays, dimmed by its own `visible` flag above).
-  const worldFiltered = allRows.filter((row) => {
+  const worldFiltered = sourceRows.filter((row) => {
     if (isCompositeGroupNode(adapter, row.node.id)) return true; // the group row itself always shows
     let current: string | null = row.node.parentId;
     while (current) {
@@ -988,9 +1465,7 @@ export function GameHierarchy() {
     }
     return true;
   });
-  const rows = term
-    ? worldFiltered.filter((r) => r.node.label.toLowerCase().includes(term))
-    : worldFiltered.filter((r) => !r.hiddenByCollapse);
+  const rows = term ? worldFiltered : worldFiltered.filter((r) => !r.hiddenByCollapse);
 
   // Wave-18-ported: a filtered-down result set shouldn't leave the viewport
   // parked at a stale deep scroll offset from a previous (larger) list.
@@ -1015,12 +1490,45 @@ export function GameHierarchy() {
   const topSpacerPx = start * ROW_HEIGHT;
   const bottomSpacerPx = (rows.length - end) * ROW_HEIGHT;
 
-  const toggleOpen = useCallback((pathKey: string) => {
-    const set = collapsedKeysRef.current;
-    if (set.has(pathKey)) set.delete(pathKey);
-    else set.add(pathKey);
+  const toggleOpen = useCallback(
+    (row: IngestRow, recursive: boolean) => {
+      const expanded = !isExpanded(row);
+      const updates: Array<readonly [string, boolean]> = [[row.node.id, expanded]];
+      if (recursive) {
+        const prefix = `${row.pathKey}.`;
+        for (const descendant of structuralRows) {
+          if (descendant.hasChildren && descendant.pathKey.startsWith(prefix)) {
+            updates.push([descendant.node.id, expanded]);
+          }
+        }
+      }
+      for (const [id, value] of updates) sessionExpansionRef.current.set(id, value);
+      setHierarchyExpansionPreferences(projectIdentity, updates);
+      forceUpdate();
+    },
+    [isExpanded, projectIdentity, structuralRows],
+  );
+
+  const setAllExpanded = useCallback(
+    (expanded: boolean) => {
+      const updates = structuralRows
+        .filter((row) => row.hasChildren)
+        .map((row) => [row.node.id, expanded] as const);
+      for (const [id, value] of updates) sessionExpansionRef.current.set(id, value);
+      setHierarchyExpansionPreferences(projectIdentity, updates);
+      forceUpdate();
+    },
+    [projectIdentity, structuralRows],
+  );
+
+  const resetExpansion = useCallback(() => {
+    sessionExpansionRef.current.clear();
+    for (const id of selectedAncestorNodeIds(structuralRows, selectedIds)) {
+      sessionExpansionRef.current.set(id, true);
+    }
+    clearHierarchyExpansionPreferences(projectIdentity);
     forceUpdate();
-  }, []);
+  }, [projectIdentity, selectionSignature, structuralRows]);
 
   const revealMore = useCallback((parentPathKey: string) => {
     const m = revealedRef.current;
@@ -1028,14 +1536,11 @@ export function GameHierarchy() {
     forceUpdate();
   }, []);
 
-  // A4 (D8) — every root-group member, rebuilt each render straight from
-  // `rootGroups.groups()` (never from the id string — see `buildRootMembers`'s
-  // doc comment). `handleActivateRoot` is the ONE choke point a double-click
+  // `handleActivateRoot` is the ONE choke point a double-click
   // on an inactive member row goes through, shared with the asset-browser's
   // scene double-click (`DefaultEditorLayout.tsx`'s `handleOpenScene`) via
   // `requestRootActivation` so the dirty-gate/confirmation UX can't drift
   // between the two call sites.
-  const rootMembers = buildRootMembers(adapter);
   const handleActivateRoot = useCallback(
     (groupId: string, rootId: string) => {
       requestRootActivation(adapter, groupId, rootId);
@@ -1043,7 +1548,29 @@ export function GameHierarchy() {
     [adapter],
   );
 
-  const selectedIds = new Set(adapter.selection?.get() ?? []);
+  // Viewport picks and external editor-control selection reveal the selected
+  // row, including through a previously collapsed path and a virtualized
+  // list. Do this only when the selection or adapter changes; ordinary store
+  // notifications must not fight a user's manual scroll position.
+  useEffect(() => {
+    if (!selectionSignature) {
+      lastAutoRevealRef.current = null;
+      return;
+    }
+    const last = lastAutoRevealRef.current;
+    if (last?.adapter === adapter && last.selection === selectionSignature) return;
+    lastAutoRevealRef.current = { adapter, selection: selectionSignature };
+    const index = rows.findIndex((row) => selectedIds.has(row.node.id));
+    const container = containerRef.current;
+    if (index < 0 || !container) return;
+    const top = index * ROW_HEIGHT;
+    const bottom = top + ROW_HEIGHT;
+    if (top < container.scrollTop) container.scrollTop = top;
+    else if (bottom > container.scrollTop + container.clientHeight) {
+      container.scrollTop = Math.max(0, bottom - container.clientHeight);
+    }
+    setScrollTop(container.scrollTop);
+  }, [adapter, rows, selectedIds, selectionSignature]);
 
   const handleRowClick = useCallback(
     (e: React.MouseEvent, nodeId: string) => {
@@ -1119,12 +1646,21 @@ export function GameHierarchy() {
         const targetId = row.node.id;
         if (draggedIds.includes(targetId)) return;
         if (isDescendantOfAny(targetId, draggedIds, adapter)) return;
+        if (!isSameWorldDrop(adapter, draggedIds, targetId)) {
+          setDropTarget(null);
+          return;
+        }
       }
       if (isCompositeGroupNode(adapter, row.node.id) && zone !== 'child') {
         // A composite world-group row has no siblings of its own kind to
         // reorder against — only "drop into this world" makes sense.
         zone = 'child';
       }
+      if (row.node.role === 'document' || row.node.role === 'story') zone = 'child';
+      if (row.node.role === 'folder' || row.node.role === 'boundary') {
+        setDropTarget(null);
+        return;
+      }
 
       setDropTarget({ nodeId: row.node.id, zone });
     },
@@ -1207,14 +1743,36 @@ export function GameHierarchy() {
   );
 
   const panelName = adapter.persistence?.destination ?? 'Untitled';
+  const compositeHierarchy = adapter instanceof CompositeAuthoringAdapter;
 
   return (
     <Panel
       name={
         <span data-testid="scene-name" data-scene={panelName}>
           {panelName}
+          {/* Spec 29 §5 — a BARE adapter's provenance renders here (its whole
+              panel is one world); a composite's renders per world-group row. */}
+          {!(adapter instanceof CompositeAuthoringAdapter) && adapter.provenance && (
+            <span
+              data-testid="panel-provenance"
+              data-provenance={adapter.provenance.source}
+              title={adapter.provenance.detail}
+              style={{
+                marginLeft: 6,
+                fontSize: 'var(--vgai-font-xs)',
+                fontWeight: 400,
+                padding: `0 ${space[2]}px`,
+                borderRadius: themeVars.shape.small,
+                border: `1px solid ${themeVars.boundary.strong}`,
+                color: themeVars.content.muted,
+              }}
+            >
+              {adapter.provenance.label}
+            </span>
+          )}
         </span>
       }
+      hideHeader={compositeHierarchy}
       onPointerDown={() => setActiveScope('hierarchy')}
       onDragOver={(e) => {
         if (e.dataTransfer.types.includes(ASSET_MIME)) {
@@ -1222,39 +1780,63 @@ export function GameHierarchy() {
           e.dataTransfer.dropEffect = 'copy';
         }
       }}
-      style={{ width: 240, borderRight: '1px solid #333' }}
+      // Dockview owns the group's resizable/collapsible persisted width; this
+      // panel fills whatever its current group gives it.
+      style={{
+        flex: 1,
+        minWidth: 0,
+        minHeight: 0,
+        borderRight: `1px solid ${themeVars.boundary.default}`,
+      }}
     >
+      {compositeHierarchy && (
+        <span data-testid="scene-name" data-scene={panelName} style={{ display: 'none' }}>
+          {panelName}
+        </span>
+      )}
       <OverlayReportBanner />
-      <div
+      <EditorToolbar
+        label="Hierarchy controls"
+        compact
         style={{
-          padding: '4px 8px',
-          borderBottom: '1px solid #333',
-          display: 'flex',
-          alignItems: 'center',
           gap: 4,
           flexShrink: 0,
         }}
       >
-        <input
+        {/* L-6 — `.vgai-input` supplies a real `:focus-visible` border/outline
+            (this box previously did `outline:'none'` with no replacement). */}
+        <TextInput
           type="text"
           data-testid="ingest-search"
           placeholder="Search..."
+          className="vgai-input"
           value={search}
           onChange={(e) => setSearch(e.target.value)}
           style={{
             flex: 1,
             minWidth: 0,
-            background: '#1e1e1e',
-            border: '1px solid #333',
-            borderRadius: 3,
-            color: '#c5c8ce',
-            fontSize: 11,
-            padding: '3px 6px',
-            outline: 'none',
           }}
         />
-        <CreateMenu adapter={adapter} parentId={null} />
-      </div>
+        <ViewButton
+          label="Collapse all"
+          icon={faMinus}
+          testId="hierarchy-collapse-all"
+          onClick={() => setAllExpanded(false)}
+        />
+        <ViewButton
+          label="Reset to default openness"
+          icon={faRotateLeft}
+          testId="hierarchy-reset-expansion"
+          onClick={resetExpansion}
+        />
+        <ViewButton
+          label="Expand all"
+          icon={faPlus}
+          testId="hierarchy-expand-all"
+          onClick={() => setAllExpanded(true)}
+        />
+        <CreateMenu adapter={adapter} parentId={createTargetId} />
+      </EditorToolbar>
 
       <div
         ref={containerRef}
@@ -1289,10 +1871,11 @@ export function GameHierarchy() {
               store={store}
               isSelected={selectedIds.has(row.node.id)}
               isEditing={editingId === row.node.id}
-              isCollapsed={collapsedKeysRef.current.has(row.pathKey)}
+              isCollapsed={term ? false : effectiveCollapsedPaths.has(row.pathKey)}
               dropZone={dropTarget && dropTarget.nodeId === row.node.id ? dropTarget.zone : null}
               isDragged={draggedIds?.includes(row.node.id) ?? false}
               rootMember={rootMembers.get(row.node.id)}
+              focusedWorldId={focusedViewportWorldId}
               searchTerm={term}
               onToggleOpen={toggleOpen}
               onStartEditing={setEditingId}
@@ -1313,9 +1896,9 @@ export function GameHierarchy() {
               right: 0,
               top: rows.length * ROW_HEIGHT,
               height: 2,
-              background: '#579EFF',
+              background: themeVars.accent.default,
               pointerEvents: 'none',
-              zIndex: 10,
+              zIndex: zIndex.overlayLow,
             }}
           />
         )}
@@ -1324,13 +1907,13 @@ export function GameHierarchy() {
       {contextMenu &&
         (() => {
           const menuNode = adapter.hierarchy.node(contextMenu.nodeId);
-          // A4 (D8): a root-group member or the game root gets the same
+          // A4 (D8): a root-group member gets the same
           // "no structural affordances" treatment as an existing composite
           // group row — none of the three own a name/visible/locked path or
           // a meaningful Create/Duplicate/Delete target.
           const isGroupNode = menuNode
             ? isCompositeGroupNode(adapter, menuNode.id) ||
-              isGameRootNode(adapter, menuNode.id) ||
+              isCompositeOrganizationNode(adapter, menuNode.id) ||
               rootMembers.has(menuNode.id)
             : false;
           return (