@vgai/editor 0.2.0

package/src/authoring/vgai-scene-authoring-adapter.ts

@@ -0,0 +1,746 @@
+/**
+ * VgaiSceneAuthoringAdapter — the FIRST-PARTY {@link AuthoringAdapter}.
+ *
+ * It implements the editor's authoring contract by delegating to the existing
+ * {@link EditorStore}. `SceneEntity` / `.vscn` is this adapter's PRIVATE model:
+ * this is the one editor module (besides the store/serializer internals) that is
+ * allowed to import `SceneEntity`. The editor UI talks to the `AuthoringAdapter`
+ * interface and never sees `SceneEntity` — that confinement is the inversion.
+ *
+ * An ingested external game's `IngestAuthoringAdapter` (Phase B) implements the
+ * SAME providers directly over its live `Object3D` tree, with no `SceneEntity`.
+ */
+
+import type {
+  AssetDropProvider,
+  AuthoringAdapter,
+  AuthoringCapabilities,
+  ComponentsProvider,
+  EditorNode,
+  FileMapProvider,
+  HierarchyProvider,
+  InspectorProvider,
+  PersistenceProvider,
+  PickProvider,
+  PropertyDescriptor,
+  RootGroup,
+  RootGroupsProvider,
+  SelectionProvider,
+  StructureProvider,
+  Transform,
+  TransformOwner,
+  TransformProvider,
+} from '@engine/adapter';
+import { resolveUrl } from '@engine/loader';
+import { parseSceneFile } from '@engine/scene/parse';
+import type { SceneEntity, SceneFile } from '@engine/scene/scene-types';
+import { getUserData } from '@engine/scene/user-data';
+import type { FieldKind } from '../components/inspectors/zod-fields';
+import { introspectSchema } from '../components/inspectors/zod-fields';
+import { getEditorMode } from '../editor-mode';
+import type { EditorStore } from '../editor-store';
+import { getLoadedComponents } from '../script-loader';
+import { getStorageBackend } from '../storage';
+import { getActiveNetworking, getActivePhysics } from './active-systems';
+import { ensureProjectScenesLoaded, getCachedProjectScenes } from './project-scenes';
+import { raycastPick } from './viewport-raycast';
+
+type ComponentDataMap = NonNullable<SceneEntity['components']>;
+
+/** `zod-fields.ts`'s `FieldKind` → `PropertyDescriptor.type` (D6 — zod stays
+ *  behind `introspectSchema`; the contract only ever sees this format-neutral
+ *  mapping, never a zod shape). `select` folds into `enum` — both render as a
+ *  dropdown over `options`; every other kind name matches 1:1. */
+function fieldKindToPropertyType(kind: FieldKind): PropertyDescriptor['type'] {
+  return kind === 'select' ? 'enum' : kind;
+}
+
+// ---------------------------------------------------------------------------
+// D8 — root groups (radio roots over the project's `*.vscn.json` files)
+// ---------------------------------------------------------------------------
+
+const SCENE_ROOT_PREFIX = 'sceneRoot:';
+
+/** Member node id for a project-relative scene path — stable, opaque to the
+ *  shell (GameHierarchy discovers membership only via `rootGroups.groups()`
+ *  data, never by decoding this prefix itself). */
+function sceneRootId(path: string): string {
+  return `${SCENE_ROOT_PREFIX}${path}`;
+}
+
+/** Inverse of {@link sceneRootId} — `null` for any id this adapter didn't mint. */
+function pathForSceneRootId(id: string): string | null {
+  return id.startsWith(SCENE_ROOT_PREFIX) ? id.slice(SCENE_ROOT_PREFIX.length) : null;
+}
+
+function normalizeScenePath(path: string): string {
+  return path.startsWith('/') ? path.slice(1) : path;
+}
+
+async function fetchSceneDoc(path: string): Promise<SceneFile> {
+  // Mirrors `initial-scene.ts`'s browser-vs-server branch: browser builds
+  // read scene files through the active `StorageBackend` (OPFS/File System
+  // Access), not `fetch()`; the server dev build serves them over HTTP.
+  if (getEditorMode() === 'browser') {
+    return parseSceneFile(JSON.parse(await getStorageBackend().read(path)));
+  }
+  const res = await fetch(resolveUrl(`/${path}`));
+  if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${path}`);
+  return parseSceneFile(await res.json());
+}
+
+function kindOf(e: SceneEntity): EditorNode['kind'] {
+  if (e.light) return 'light';
+  if (e.camera) return 'camera';
+  if (e.mesh) return 'mesh';
+  if (e.children && e.children.length > 0) return 'group';
+  return 'object';
+}
+
+function toNode(e: SceneEntity, parentId: string | null): EditorNode {
+  return {
+    id: e.id!,
+    label: e.name,
+    kind: kindOf(e),
+    parentId,
+    childIds: (e.children ?? []).map((c) => c.id!),
+    flags: { locked: e.locked === true },
+  };
+}
+
+/** Locate an entity + its parent id within the store's entity tree. */
+function findInTree(
+  roots: SceneEntity[],
+  id: string,
+): { entity: SceneEntity; parentId: string | null } | null {
+  const walk = (
+    list: SceneEntity[],
+    parentId: string | null,
+  ): { entity: SceneEntity; parentId: string | null } | null => {
+    for (const e of list) {
+      if (e.id === id) return { entity: e, parentId };
+      const hit = e.children ? walk(e.children, e.id!) : null;
+      if (hit) return hit;
+    }
+    return null;
+  };
+  return walk(roots, null);
+}
+
+/**
+ * The 12-kind creation palette (A2 parity growth — ported verbatim from
+ * `SceneHierarchy.tsx`'s `addMenuItems`, formerly toolbar-only) plus the two
+ * legacy slugs ('box'/'mesh' both -> Box, 'group' -> an empty container) that
+ * pre-date this table and are pinned by `structure-provider.test.ts`. Shared
+ * by `structure.create` and `structure.creatableKinds` so the palette and the
+ * actual entity shape can never drift apart.
+ */
+const KIND_TEMPLATES: Record<string, { label: string; make: () => SceneEntity }> = {
+  empty: { label: 'Empty', make: () => ({ id: crypto.randomUUID(), name: 'Empty' }) },
+  box: {
+    label: 'Box',
+    make: () => ({
+      id: crypto.randomUUID(),
+      name: 'Box',
+      mesh: { type: 'box' },
+      material: { type: 'standard', color: '#888888' },
+    }),
+  },
+  mesh: {
+    label: 'Box',
+    make: () => ({
+      id: crypto.randomUUID(),
+      name: 'Box',
+      mesh: { type: 'box' },
+      material: { type: 'standard', color: '#888888' },
+    }),
+  },
+  sphere: {
+    label: 'Sphere',
+    make: () => ({
+      id: crypto.randomUUID(),
+      name: 'Sphere',
+      mesh: { type: 'sphere' },
+      material: { type: 'standard', color: '#888888' },
+    }),
+  },
+  plane: {
+    label: 'Plane',
+    make: () => ({
+      id: crypto.randomUUID(),
+      name: 'Plane',
+      mesh: { type: 'plane' },
+      material: { type: 'standard', color: '#888888' },
+    }),
+  },
+  cylinder: {
+    label: 'Cylinder',
+    make: () => ({
+      id: crypto.randomUUID(),
+      name: 'Cylinder',
+      mesh: { type: 'cylinder' },
+      material: { type: 'standard', color: '#888888' },
+    }),
+  },
+  capsule: {
+    label: 'Capsule',
+    make: () => ({
+      id: crypto.randomUUID(),
+      name: 'Capsule',
+      mesh: { type: 'capsule' },
+      material: { type: 'standard', color: '#888888' },
+    }),
+  },
+  group: { label: 'Group', make: () => ({ id: crypto.randomUUID(), name: 'Group', children: [] }) },
+  dirLight: {
+    label: 'Dir Light',
+    make: () => ({
+      id: crypto.randomUUID(),
+      name: 'DirectionalLight',
+      light: { type: 'directional', intensity: 1 },
+      transform: { position: [5, 10, 5] },
+    }),
+  },
+  pointLight: {
+    label: 'Point Light',
+    make: () => ({
+      id: crypto.randomUUID(),
+      name: 'PointLight',
+      light: { type: 'point', intensity: 1 },
+    }),
+  },
+  spotLight: {
+    label: 'Spot Light',
+    make: () => ({
+      id: crypto.randomUUID(),
+      name: 'SpotLight',
+      light: { type: 'spot', intensity: 1 },
+    }),
+  },
+  camera: {
+    label: 'Camera',
+    make: () => ({ id: crypto.randomUUID(), name: 'Camera', camera: { type: 'perspective' } }),
+  },
+  audioSource: {
+    label: 'Audio Source',
+    make: () => ({
+      id: crypto.randomUUID(),
+      name: 'AudioSource',
+      audio: { spatial: true, volume: 1 },
+    }),
+  },
+  spline: {
+    label: 'Spline',
+    make: () => ({
+      id: crypto.randomUUID(),
+      name: 'Spline',
+      spline: {
+        curveType: 'centripetal',
+        points: [
+          [0, 0, 0],
+          [1, 0, 1],
+          [2, 0, 0],
+        ],
+        closed: false,
+      },
+    }),
+  },
+};
+
+/** The palette order shown in the creation menu — the 12 first-class kinds
+ *  (legacy 'mesh'/'box' duplicate and internal-only 'group' are reachable by
+ *  slug but not listed twice / not part of the user-facing palette). */
+const PALETTE_ORDER = [
+  'empty',
+  'box',
+  'sphere',
+  'plane',
+  'cylinder',
+  'capsule',
+  'dirLight',
+  'pointLight',
+  'spotLight',
+  'camera',
+  'audioSource',
+  'spline',
+] as const;
+
+/** A minimal first-party `SceneEntity` for a structural `create(kind)`. */
+function entityForKind(kind: string): SceneEntity {
+  return (KIND_TEMPLATES[kind] ?? KIND_TEMPLATES['empty']!).make();
+}
+
+type AssetDropKind = 'model' | 'image' | 'prefab' | 'audio';
+
+/** Classify a dropped asset path by extension — the adapter's own private
+ *  reading of the shell's asset path string (the shell never passes a `kind`;
+ *  see `AssetDropProvider`'s contract). Mirrors `AssetBrowser.tsx`'s
+ *  `getAssetKind`, trimmed to the kinds this adapter can turn into an entity. */
+function kindFromAssetPath(path: string): AssetDropKind | null {
+  const lower = path.toLowerCase();
+  if (lower.endsWith('.glb') || lower.endsWith('.gltf')) return 'model';
+  if (/\.(png|jpe?g|webp|svg|gif)$/.test(lower)) return 'image';
+  if (lower.endsWith('.prefab.json')) return 'prefab';
+  if (/\.(mp3|ogg|wav|flac)$/.test(lower)) return 'audio';
+  return null;
+}
+
+/** Create entity data from a dropped asset path (mirrors the former
+ *  `SceneHierarchy.tsx`'s `entityFromAssetDrop`, now keyed off the
+ *  path-derived kind instead of a caller-supplied one). */
+function entityFromAssetPath(path: string, kind: AssetDropKind): SceneEntity | null {
+  const name = path.split('/').pop() ?? path;
+  const baseName = name.replace(/\.[^.]+$/, '');
+  const id = crypto.randomUUID();
+  switch (kind) {
+    case 'model':
+      return { id, name: baseName, mesh: { type: 'gltf', src: path } };
+    case 'image':
+      return {
+        id,
+        name: baseName,
+        mesh: { type: 'plane', args: [2, 2] },
+        material: { type: 'standard', map: path },
+      };
+    case 'prefab':
+      return { id, name: baseName, prefab: path };
+    case 'audio':
+      return { id, name: baseName, audio: { src: path, spatial: true, volume: 1 } };
+  }
+}
+
+export class VgaiSceneAuthoringAdapter implements AuthoringAdapter {
+  constructor(private readonly store: EditorStore) {}
+
+  readonly capabilities: AuthoringCapabilities = {
+    transform: true,
+    material: true,
+    inspectorFields: true,
+    create: true,
+    delete: true,
+    reparent: true,
+    persist: true,
+  };
+
+  subscribe(listener: () => void): () => void {
+    return this.store.subscribe(listener);
+  }
+
+  readonly hierarchy: HierarchyProvider = {
+    // D8 — member (scene-file root) rows are APPENDED after the store's own
+    // entity roots (never interleaved between them): several existing e2e
+    // specs range-select or index-scan entity rows by relative position
+    // (`29-game-hierarchy.spec.ts`'s multi-select, drag-reorder) — appending
+    // keeps every entity's relative order/adjacency byte-identical to today,
+    // the only delta is N additional childless rows at the tail.
+    roots: () => [...this.store.entities.map((e) => toNode(e, null)), ...this.memberNodes()],
+    node: (id) => {
+      const memberPath = pathForSceneRootId(id);
+      if (memberPath !== null) return this.memberNode(memberPath);
+      const hit = findInTree(this.store.entities, id);
+      return hit ? toNode(hit.entity, hit.parentId) : null;
+    },
+    object3D: (id) => this.store.objectMap.get(id) ?? null,
+    idForObject3D: (o) => (getUserData(o, 'entityId') as string | undefined) ?? null,
+  };
+
+  /** The project's scene files (module-cached, D8) — [] until the async
+   *  listing lands, at which point `notifyIngestEdit` re-renders the panel. */
+  private scenesList(): string[] {
+    ensureProjectScenesLoaded(() => this.store.notifyIngestEdit());
+    return getCachedProjectScenes();
+  }
+
+  private memberNodes(): EditorNode[] {
+    return this.scenesList()
+      .map((path) => this.memberNode(path))
+      .filter((n): n is EditorNode => n !== null);
+  }
+
+  /** `null` for a path that isn't (or is no longer) a known project scene —
+   *  a stale/dangling `sceneRoot:` id resolves to nothing rather than a
+   *  fabricated node. */
+  private memberNode(path: string): EditorNode | null {
+    if (!this.scenesList().includes(path)) return null;
+    const isActive =
+      this.store.savePath !== null && normalizeScenePath(this.store.savePath) === path;
+    return {
+      id: sceneRootId(path),
+      label: path,
+      kind: 'object',
+      parentId: null,
+      childIds: [],
+      // D8 — member of a RootGroup, not the active one (see `authoring.ts`'s
+      // `EditorNode.flags.inactiveRoot` doc). The active member gets NO flag
+      // so both radio states are plain childless rows (GameHierarchy renders
+      // the ● / ○ radio from `rootGroups` data, not from this flag alone).
+      flags: isActive ? {} : { inactiveRoot: true },
+    };
+  }
+
+  /**
+   * D8 — one mutually-exclusive "Scenes" group over every project
+   * `*.vscn.json`. `activate()` flushes a pending autosave first (belt: the
+   * 300ms debounce could otherwise lose an edit made just before switching),
+   * then loads the target scene into the live store exactly like opening it
+   * from the asset browser (`DefaultEditorLayout.tsx`'s `openSceneFromAsset`
+   * recipe) — `loadDocument` itself notifies subscribers.
+   */
+  readonly rootGroups: RootGroupsProvider = {
+    groups: (): RootGroup[] => {
+      const scenes = this.scenesList();
+      const activeRootId = this.store.savePath
+        ? sceneRootId(normalizeScenePath(this.store.savePath))
+        : null;
+      return [
+        {
+          id: 'scenes',
+          label: 'Scenes',
+          memberRootIds: scenes.map(sceneRootId),
+          activeRootId,
+        },
+      ];
+    },
+    activate: async (groupId, rootId) => {
+      if (groupId !== 'scenes') return;
+      const path = pathForSceneRootId(rootId);
+      if (!path) return;
+      if (this.store.isDirty) await this.store.saveNow();
+      try {
+        const doc = await fetchSceneDoc(path);
+        this.store.loadDocument(doc, path);
+      } catch (err) {
+        // Plain `console` (not `editorConsole`, which touches `window` at
+        // module scope) — this adapter is exercised by node-environment unit
+        // tests with no DOM, same reasoning as `editor-store.ts`'s own
+        // `console.warn` in `_autoSave`.
+        console.error(`[VgaiSceneAuthoringAdapter] failed to activate scene root "${path}":`, err);
+      }
+    },
+  };
+
+  /** D8 — `*.vscn.json` files map to their scene-root id; anything else maps
+   *  to nothing (this adapter owns no other file kind as a root). */
+  readonly files: FileMapProvider = {
+    rootForFile: (path) => {
+      const normalized = normalizeScenePath(path);
+      return normalized.endsWith('.vscn.json') ? sceneRootId(normalized) : null;
+    },
+  };
+
+  readonly selection: SelectionProvider = {
+    get: () => [...this.store.selectedEntityIds],
+    set: (ids) => this.store.selectMultiple(ids),
+  };
+
+  /**
+   * D12 (B4) — the threejs viewport raycast, delegating to the SHARED
+   * `raycastPick` helper (`viewport-raycast.ts`) that was extracted verbatim
+   * from `editor-viewport.ts`'s former `_raycastEntity` (behavior-identical
+   * checkpoint: `09-editor-interaction.spec.ts` must stay green). Shared so
+   * `IngestAuthoringAdapter` reuses the EXACT same raycast (restoring ingest/
+   * multi-world-play canvas click-select, which pre-B4 ran unconditionally) —
+   * see that helper's doc comment. Absent viewport context ⇒ `null`, an honest
+   * headless degrade.
+   */
+  readonly pickable: PickProvider = {
+    pick: (clientX, clientY) => raycastPick(this.store, clientX, clientY),
+  };
+
+  readonly transforms: TransformProvider = {
+    get: (id): Transform => {
+      const obj = this.store.objectMap.get(id);
+      if (!obj) return { position: [0, 0, 0], rotation: [0, 0, 0, 1], scale: [1, 1, 1] };
+      return {
+        position: obj.position.toArray() as [number, number, number],
+        rotation: obj.quaternion.toArray() as [number, number, number, number],
+        scale: obj.scale.toArray() as [number, number, number],
+      };
+    },
+    // Transform owner reflects the active system adapters: a Rapier-driven body
+    // reports 'physics'; a replicated remote/server object reports 'network'.
+    owner: (id): TransformOwner => {
+      const obj = this.store.objectMap.get(id);
+      if (!obj) return 'editor';
+      const net = getActiveNetworking();
+      if (net?.networkId(obj) && net.authority(obj) !== 'local') return 'network';
+      return getActivePhysics()?.ownerOf(obj) ?? 'editor';
+    },
+    // beginEdit snapshots for undo and, for a physics-owned object, FREEZES the
+    // body (kinematic) so the gizmo edit isn't overwritten mid-drag. Remote/server
+    // network-authoritative objects are inspect-only → the edit is a no-op.
+    beginEdit: (id) => {
+      const obj = this.store.objectMap.get(id);
+      if (obj && !this.editable(obj)) return; // inspect-only (network-owned)
+      this.store.pushUndoSnapshot();
+      if (obj) getActivePhysics()?.freeze(obj);
+    },
+    // apply is the LIVE path: move the object + sync the descriptor without
+    // pushing undo (beginEdit already snapshotted). The store's ECS-sync callback
+    // commits the pose to the owning body (PhysicsAdapter.commit) so it tracks.
+    apply: (id, t) => {
+      const obj = this.store.objectMap.get(id);
+      if (obj && !this.editable(obj)) return; // inspect-only (network-owned)
+      if (obj) {
+        obj.position.set(t.position[0], t.position[1], t.position[2]);
+        obj.quaternion.set(t.rotation[0], t.rotation[1], t.rotation[2], t.rotation[3]);
+        obj.scale.set(t.scale[0], t.scale[1], t.scale[2]);
+      }
+      this.store.updateTransformLive(id, t.position, t.rotation, t.scale);
+    },
+    endEdit: (id) => {
+      const obj = this.store.objectMap.get(id);
+      if (obj) getActivePhysics()?.unfreeze(obj);
+      this.store.commitLiveTransform();
+    },
+  };
+
+  /** False when the active networking adapter marks the object inspect-only. */
+  private editable(obj: import('three').Object3D): boolean {
+    const net = getActiveNetworking();
+    return net ? net.editable(obj) : true;
+  }
+
+  readonly inspector: InspectorProvider = {
+    properties: (id): PropertyDescriptor[] => {
+      const e = this.store.getEntityById(id);
+      if (!e) return [];
+      const props: PropertyDescriptor[] = [
+        { path: 'name', label: 'Name', type: 'string' },
+        { path: 'visible', label: 'Visible', type: 'boolean' },
+        // A2 parity growth — surfaced so the shell's reserved-path lock
+        // affordance (hierarchy panel) sees it via `properties()`, exactly
+        // like `visible`. Own flag only (NOT `store.isEntityLocked`'s
+        // ancestor-merged read) — matches the pre-A2 hierarchy row, whose
+        // lock icon/toggle always reflected/toggled the entity's OWN flag.
+        { path: 'locked', label: 'Locked', type: 'boolean' },
+      ];
+      if (e.material) props.push({ path: 'material.color', label: 'Color', type: 'color' });
+      // C1 — component CONFIG fields, one PropertyDescriptor per schema field,
+      // grouped by component name (mirrors `ComponentsSection.tsx`'s
+      // per-component field rows). Only components whose class has a `static
+      // schema` get descriptors — schema-less components' raw data isn't
+      // format-neutral, so this contract surface stays silent on them (same
+      // gate `ComponentsSection` uses for `addable`/`renderSchemaFields`).
+      const classes = getLoadedComponents();
+      for (const compName of Object.keys(e.components ?? {})) {
+        const schema = classes[compName]?.schema;
+        if (!schema) continue;
+        for (const f of introspectSchema(schema)) {
+          props.push({
+            path: `components.${compName}.${f.name}`,
+            label: f.name,
+            type: fieldKindToPropertyType(f.kind),
+            group: compName,
+            ...(f.options ? { options: f.options } : {}),
+          });
+        }
+      }
+      return props;
+    },
+    get: (id, path) => {
+      const e = this.store.getEntityById(id);
+      if (!e) return undefined;
+      if (path === 'name') return e.name;
+      if (path === 'visible') return e.visible !== false;
+      if (path === 'locked') return e.locked === true;
+      if (path === 'material.color') return e.material?.color;
+      const compField = /^components\.([^.]+)\.(.+)$/.exec(path);
+      const compName = compField?.[1];
+      const fieldName = compField?.[2];
+      if (compName !== undefined && fieldName !== undefined) {
+        const comp = e.components?.[compName] as Record<string, unknown> | undefined;
+        return comp?.[fieldName];
+      }
+      return undefined;
+    },
+    set: (id, path, value) => {
+      const compField = /^components\.([^.]+)\.(.+)$/.exec(path);
+      const compName = compField?.[1];
+      const fieldName = compField?.[2];
+      if (compName !== undefined && fieldName !== undefined) {
+        const e = this.store.getEntityById(id);
+        if (!e) return;
+        const components = (e.components ?? {}) as Record<string, Record<string, unknown>>;
+        const next: Record<string, Record<string, unknown>> = {
+          ...components,
+          [compName]: { ...components[compName], [fieldName]: value },
+        };
+        this.store.updateEntity(id, { components: next as unknown as ComponentDataMap });
+        return;
+      }
+      if (path === 'name') this.store.updateEntity(id, { name: String(value) });
+      else if (path === 'visible') this.store.updateEntity(id, { visible: Boolean(value) });
+      else if (path === 'locked') {
+        const e = this.store.getEntityById(id);
+        if (e && (e.locked === true) !== Boolean(value)) this.store.toggleLocked(id);
+      } else if (path === 'material.color') {
+        this.store.batchMutate([id], (e) => {
+          if (e.material) e.material.color = String(value);
+        });
+      }
+    },
+  };
+
+  /**
+   * C1 (D6, `docs/unified-world-editor/26-unified-editor-spec.md` §C1) —
+   * GameComponent management. Mirrors `ComponentsSection.tsx:44-75` byte for
+   * byte: there are no dedicated store verbs, add/remove both go through
+   * `store.updateEntity(id, { components })` — undo is FREE (`updateEntity`
+   * calls `_pushUndo()` before mutating), so this provider needs no `undo()`
+   * of its own and must never push its own snapshot. `getLoadedComponents()`
+   * is empty until a project's scripts have been loaded at least once (play
+   * mode, or `setLoadedComponents` in tests) — that is a real design-time
+   * limitation this provider mirrors rather than works around (out of scope
+   * here — see the plan's eager-load exclusion).
+   */
+  readonly components: ComponentsProvider = {
+    available: (nodeId) => {
+      const e = this.store.getEntityById(nodeId);
+      if (!e) return [];
+      const components = (e.components ?? {}) as Record<string, Record<string, unknown>>;
+      const classes = getLoadedComponents();
+      return Object.keys(classes)
+        .filter((name) => classes[name]?.schema && !(name in components))
+        .sort();
+    },
+    list: (nodeId) => {
+      const e = this.store.getEntityById(nodeId);
+      if (!e) return [];
+      return Object.keys(e.components ?? {}).map((type) => ({ type }));
+    },
+    config: (nodeId, type) => {
+      const e = this.store.getEntityById(nodeId);
+      const comp = (e?.components as Record<string, Record<string, unknown>> | undefined)?.[type];
+      return comp ? { ...comp } : null;
+    },
+    add: (nodeId, type) => {
+      const e = this.store.getEntityById(nodeId);
+      if (!e) return;
+      const components = (e.components ?? {}) as Record<string, Record<string, unknown>>;
+      const schema = getLoadedComponents()[type]?.schema;
+      const data: Record<string, unknown> = {};
+      if (schema) {
+        for (const f of introspectSchema(schema)) {
+          if (f.default !== undefined) data[f.name] = f.default;
+        }
+      }
+      const next: Record<string, Record<string, unknown>> = { ...components, [type]: data };
+      this.store.updateEntity(nodeId, { components: next as unknown as ComponentDataMap });
+    },
+    remove: (nodeId, type) => {
+      const e = this.store.getEntityById(nodeId);
+      if (!e) return;
+      const next = { ...(e.components ?? {}) } as Record<string, Record<string, unknown>>;
+      delete next[type];
+      this.store.updateEntity(nodeId, { components: next as unknown as ComponentDataMap });
+    },
+  };
+
+  readonly structure: StructureProvider = {
+    create: (kind, parentId) => {
+      const entity = entityForKind(kind);
+      this.store.addEntity(parentId ?? null, entity);
+      return entity.id!;
+    },
+    remove: (id) => this.store.removeEntity(id),
+    duplicate: (id) => {
+      this.store.duplicateEntity(id);
+      // duplicateEntity selects the clone → read its id back.
+      return [...this.store.selectedEntityIds][0] ?? id;
+    },
+    reparent: (id, newParentId) => {
+      // Append under the new parent (large index → splice appends).
+      this.store.moveEntity([id], newParentId, Number.MAX_SAFE_INTEGER);
+    },
+    // A2 parity growth — sibling reorder, wrapping `store.moveEntity` (the
+    // same verb `reparent` above already wraps) with an index computed from
+    // the CURRENT sibling list minus the moving id itself (moveEntity always
+    // removes the dragged objects from their old parent before re-reading
+    // the target's children, so the index must already exclude them).
+    reorder: (id, beforeSiblingId) => {
+      const hit = findInTree(this.store.entities, id);
+      if (!hit) return;
+      const parentId = hit.parentId;
+      const parentEntity = parentId ? findInTree(this.store.entities, parentId)?.entity : null;
+      const siblings = (parentId ? (parentEntity?.children ?? []) : this.store.entities).filter(
+        (e) => e.id !== id,
+      );
+      const index =
+        beforeSiblingId === null
+          ? siblings.length
+          : (() => {
+              const idx = siblings.findIndex((e) => e.id === beforeSiblingId);
+              return idx < 0 ? siblings.length : idx;
+            })();
+      this.store.moveEntity([id], parentId, index);
+    },
+    // A2 parity growth — the former toolbar-only `addMenuItems` list (12
+    // kinds), now driving the shell's generic Create▸ palette for ANY
+    // parent (root via the toolbar `+`, or a specific row via the context
+    // menu) — a capability the old toolbar-only Add menu never had.
+    creatableKinds: () =>
+      PALETTE_ORDER.map((kind) => ({ kind, label: KIND_TEMPLATES[kind]!.label })),
+  };
+
+  /**
+   * A2 parity growth — port of the former `SceneHierarchy.tsx`'s
+   * `entityFromAssetDrop` + its animation-attach special case, now living
+   * behind the format-neutral `AssetDropProvider` seam. The shell passes only
+   * a node id + asset path (never a `kind` — that would leak `SceneEntity`
+   * vocabulary across Rule Zero), so this adapter re-derives the kind from
+   * the path extension itself (`kindFromAssetPath`).
+   *
+   * Root-drop sentinel: `nodeId === ''` means "no target row" (the shell's
+   * tail/background drop) — there being no `AssetDropProvider` parameter for
+   * "no parent" (unlike `StructureProvider.create`'s optional `parentId`),
+   * this adapter and its callers (the shell, and
+   * `CompositeAuthoringAdapter`'s group-node translation) share this one
+   * local convention. Any OTHER nodeId is treated as "drop into/onto this
+   * entity" (becomes its child). (The former 'animation' asset kind — drop a
+   * `.animgraph.json` onto an entity to attach it directly — was removed by
+   * E5; there is no drop-an-asset equivalent for XState-driven animation, it
+   * is authored in component code.)
+   */
+  readonly assetDrop: AssetDropProvider = {
+    accepts: (_nodeId, assetPath) => kindFromAssetPath(assetPath) !== null,
+    drop: (nodeId, assetPath) => {
+      const kind = kindFromAssetPath(assetPath);
+      if (!kind) return;
+      const parentId = nodeId === '' ? null : nodeId;
+      const entity = entityFromAssetPath(assetPath, kind);
+      if (entity) this.store.addEntity(parentId, entity);
+    },
+  };
+
+  // A class GETTER (not a field initializer) — a field initializer runs before
+  // the constructor body assigns `this.store` (parameter properties assign in
+  // the constructor body, same as any other constructor statement), so a plain
+  // object-literal field would capture `this.store` as `undefined`. A getter
+  // defers construction of the provider object until first access, by which
+  // point the instance is fully built.
+  get persistence(): PersistenceProvider {
+    const store = this.store;
+    return {
+      isDirty: () => store.isDirty,
+      save: async () => {
+        await store.saveNow();
+      },
+      serialize: () => store.getDocument(),
+      captureToVscn: (ids) =>
+        ids.map((id) => store.getEntityById(id)).filter((e): e is SceneEntity => e !== null),
+      // Live — reflects `store.savePath`, which changes on loadDocument/loadPrefab.
+      get destination(): string {
+        return store.savePath ?? '(no scene loaded)';
+      },
+      // The reload contract (design §5): the existing `applyExternalUpdate`
+      // diff-apply path, exposed through the provider instead of the SSE handler
+      // reaching into the store directly (`rawContent` forwarded so own-echo
+      // detection — `EditorStore`'s private epoch/cooldown discipline — still
+      // works exactly as it did before this was routed through the provider).
+      applyExternal: (content, rawContent) => {
+        store.applyExternalUpdate(content as SceneFile, rawContent);
+      },
+    };
+  }
+}