@vgai/editor 0.2.0

package/src/scene-sync.ts

@@ -0,0 +1,587 @@
+import { loadingManager, resolveUrl } from '@engine/loader';
+import { DEFAULTS } from '@engine/scene/defaults';
+import { parseMaterialFile, parsePrefabFile } from '@engine/scene/parse';
+import {
+  mergePrefabInstance,
+  type PrefabFile,
+  type SceneEntity,
+  type SceneEnvironment,
+  type SceneFile,
+  type SceneMaterial,
+} from '@engine/scene/scene-types';
+import { deleteUserData, getUserData, setUserData } from '@engine/scene/user-data';
+import * as THREE from 'three';
+import { RGBELoader } from 'three/addons/loaders/RGBELoader.js';
+import type { BatchedRenderer, ParticleSystem } from 'three.quarks';
+import { readProjectTextFile } from './editor-api';
+import type { ShadingMode } from './editor-store';
+import { createEntityObject, disposeEntityAnimation } from './entity-factory';
+
+/**
+ * Resolve any scene-authored animated attachments whose target skeleton is
+ * available. Safe to call every editor frame: GLTF content arrives async, so
+ * an attachment that cannot resolve during buildPreview is picked up as soon
+ * as the named bone exists.
+ */
+export function resolvePreviewBoneAttachments(objectMap: Map<string, THREE.Object3D>): void {
+  for (const object of objectMap.values()) {
+    const entity = getUserData(object, 'entity') as SceneEntity | undefined;
+    const attachment = entity?.boneAttachment;
+    if (!attachment) continue;
+    const target = objectMap.get(attachment.target);
+    const socket = target?.getObjectByName(attachment.bone);
+    if (!socket || !object.parent) continue;
+
+    // Preserve the editor's authored entity hierarchy. serializeScene derives
+    // the .vscn tree from that hierarchy, so physically reparenting here would
+    // make a top-level weapon disappear from the Play snapshot. Instead,
+    // evaluate socketWorld * authoredOffset into the object's existing parent
+    // space. The serializer keeps the authored offset for attachments.
+    socket.updateWorldMatrix(true, false);
+    object.parent.updateWorldMatrix(true, false);
+    const offset = entity.transform;
+    const offsetMatrix = new THREE.Matrix4().compose(
+      new THREE.Vector3().fromArray(offset?.position ?? DEFAULTS.transform.position),
+      new THREE.Quaternion().fromArray(offset?.rotation ?? DEFAULTS.transform.rotation),
+      new THREE.Vector3().fromArray(offset?.scale ?? DEFAULTS.transform.scale),
+    );
+    const localMatrix = object.parent.matrixWorld
+      .clone()
+      .invert()
+      .multiply(socket.matrixWorld)
+      .multiply(offsetMatrix);
+    localMatrix.decompose(object.position, object.quaternion, object.scale);
+  }
+}
+
+/**
+ * Dispose the geometry + materials owned by an Object3D subtree (ED4/ED5).
+ *
+ * Skips nodes tagged `__sharedGeometry` (GLTF clones share geometry/materials
+ * with the cached source — freeing them corrupts the cache) and particle
+ * emitters (managed by three.quarks / unregisterParticles). Also stops any
+ * AnimationMixer so it doesn't leak.
+ */
+function disposeObject3D(root: THREE.Object3D): void {
+  root.traverse((node) => {
+    if (getUserData(node, '_animMixer')) disposeEntityAnimation(node);
+    if (getUserData(node, '__sharedGeometry')) return;
+    if (getUserData(node, 'editorHelperType') === 'particles') return;
+    const mesh = node as THREE.Mesh;
+    if (mesh.geometry) mesh.geometry.dispose();
+    const mat = mesh.material as THREE.Material | THREE.Material[] | undefined;
+    if (mat) {
+      for (const m of Array.isArray(mat) ? mat : [mat]) m.dispose();
+    }
+  });
+}
+
+/** Cache for prefab files fetched for editor preview. */
+const prefabPreviewCache = new Map<string, PrefabFile>();
+
+/** Cache for loaded .mat.json materials. */
+const materialRefCache = new Map<string, SceneMaterial>();
+
+/** Cache for processed environment map textures. */
+const envTextureCache = new Map<string, THREE.Texture>();
+let _pmremGenerator: THREE.PMREMGenerator | null = null;
+
+/** Resolve a prefab entity by fetching and merging the prefab definition. */
+async function resolvePrefabEntity(entity: SceneEntity): Promise<SceneEntity> {
+  if (!entity.prefab) return entity;
+
+  let prefab = prefabPreviewCache.get(entity.prefab);
+  if (!prefab) {
+    try {
+      // Storage-first (so a just-saved OPFS prefab resolves in the browser build),
+      // HTTP fallback for shipped static prefabs.
+      const text = await readProjectTextFile(entity.prefab);
+      if (text === null) return entity;
+      prefab = parsePrefabFile(JSON.parse(text), entity.prefab);
+      prefabPreviewCache.set(entity.prefab, prefab);
+    } catch {
+      return entity;
+    }
+  }
+
+  return tryMergePrefabInstance(prefab.root, entity);
+}
+
+/**
+ * Editor-safe wrapper over `mergePrefabInstance`, which (since T1.10)
+ * re-validates the merged entity and THROWS on an invalid combination (e.g.
+ * prefab inline `material` + instance `materialRef`). The runtime loader is
+ * right to throw — but the editor's sync path must not crash the whole panel
+ * over one bad entity: log loudly and render the instance un-merged (its raw
+ * descriptor, no prefab expansion) so the user can see and fix it.
+ */
+function tryMergePrefabInstance(prefabRoot: SceneEntity, entity: SceneEntity): SceneEntity {
+  try {
+    return mergePrefabInstance(prefabRoot, entity);
+  } catch (err) {
+    console.error(
+      `[scene-sync] invalid prefab instance "${entity.name}" (prefab: ${entity.prefab}) — rendering un-merged:`,
+      err,
+    );
+    return entity;
+  }
+}
+
+/** Invalidate the prefab preview cache (e.g. when a prefab is saved). */
+export function clearPrefabPreviewCache(): void {
+  prefabPreviewCache.clear();
+}
+
+/** Invalidate the material ref cache (e.g. when a .mat.json is saved). */
+export function clearMaterialRefCache(): void {
+  materialRefCache.clear();
+}
+
+/**
+ * If entity has materialRef, return a copy with material resolved from cache.
+ * If not cached yet, kicks off async load and returns entity as-is (will rebuild later).
+ */
+function resolveEntityMaterial(
+  entity: SceneEntity,
+  objectMap: Map<string, THREE.Object3D>,
+  scene: THREE.Scene,
+): SceneEntity {
+  if (!entity.materialRef) return entity;
+
+  const cached = materialRefCache.get(entity.materialRef);
+  if (cached) {
+    return { ...entity, material: cached };
+  }
+
+  // Async load and rebuild when ready. Validated via Zod (T4.6) — a malformed
+  // .mat.json is logged loudly (SceneParseError names the file + issues)
+  // rather than corrupting the live preview with a partially-typed value; the
+  // entity just keeps its unresolved materialRef (same fallback as an
+  // unreachable/404 file).
+  const ref = entity.materialRef;
+  const id = entity.id;
+  fetch(resolveUrl(ref))
+    .then((res) => (res.ok ? res.json() : null))
+    .then((json) => (json === null ? null : parseMaterialFile(json, ref)))
+    .then((file) => {
+      if (!file) return;
+      materialRefCache.set(ref, file.material);
+      // Rebuild the entity's preview object with the loaded material
+      if (id) {
+        const resolved = { ...entity, material: file.material };
+        updateEntityPreview(resolved, objectMap, scene);
+      }
+    })
+    .catch((err) => {
+      console.error(`[scene-sync] invalid material ref "${ref}" — not resolved:`, err);
+    });
+
+  return entity;
+}
+
+// --- Particle system lifecycle ---
+
+/** Register any particle system stashed in obj.userData with the BatchedRenderer. */
+export function registerParticles(
+  obj: THREE.Object3D,
+  batchedRenderer: BatchedRenderer | null,
+): void {
+  if (!batchedRenderer) return;
+  const ps = getUserData(obj, '_particleSystem') as ParticleSystem | undefined;
+  if (ps) batchedRenderer.addSystem(ps);
+  // Also check children (e.g. prefab resolved objects)
+  for (const child of obj.children) {
+    registerParticles(child, batchedRenderer);
+  }
+}
+
+/** Unregister any particle system stashed in obj.userData from the BatchedRenderer. */
+export function unregisterParticles(
+  obj: THREE.Object3D,
+  batchedRenderer: BatchedRenderer | null,
+): void {
+  if (!batchedRenderer) return;
+  const ps = getUserData(obj, '_particleSystem') as ParticleSystem | undefined;
+  if (ps) {
+    try {
+      batchedRenderer.deleteSystem(ps);
+    } catch {
+      // System may already be removed
+    }
+  }
+  for (const child of obj.children) {
+    unregisterParticles(child, batchedRenderer);
+  }
+}
+
+/**
+ * Build the full Three.js preview from a SceneFile document.
+ * Returns a map of entity id → Object3D for lookup.
+ *
+ * Prefab handling follows the real-engine pattern (Unity/Unreal/Godot):
+ * - If the prefab file is already cached, resolve synchronously — the visual
+ *   object IS the entity in the scene graph, no placeholder wrapper.
+ * - If not cached (first load), create a Group placeholder and resolve async.
+ *   The placeholder carries the original instance descriptor (with `prefab`
+ *   field) so serialization always preserves the prefab reference.
+ */
+export function buildPreview(
+  doc: SceneFile,
+  scene: THREE.Scene,
+  shadingMode: ShadingMode = 'solid',
+  renderer?: THREE.WebGLRenderer,
+  batchedRenderer?: BatchedRenderer | null,
+): Map<string, THREE.Object3D> {
+  // Remove all editor-managed objects (tagged with entityId or envObject)
+  clearPreview(scene, batchedRenderer);
+
+  const objectMap = new Map<string, THREE.Object3D>();
+  const br = batchedRenderer ?? null;
+
+  function addEntities(entities: SceneEntity[], parent: THREE.Object3D): void {
+    for (const entity of entities) {
+      if (entity.prefab) {
+        addPrefabEntity(entity, parent, objectMap, br);
+        continue;
+      }
+
+      const resolved = resolveEntityMaterial(entity, objectMap, scene);
+      const obj = createEntityObject(resolved);
+      // Restore original (unresolved) entity so userData['entity'] doesn't have
+      // a stale resolved material from materialRef cache.
+      setUserData(obj, 'entity', JSON.parse(JSON.stringify(entity)) as SceneEntity);
+      obj.visible = entity.visible !== false;
+      parent.add(obj);
+      registerParticles(obj, br);
+      if (entity.id) objectMap.set(entity.id, obj);
+      if (entity.children) {
+        addEntities(entity.children, obj);
+      }
+    }
+  }
+
+  /**
+   * Add a prefab instance to the scene graph.
+   *
+   * Two paths:
+   * 1. Cached (synchronous) — prefab already fetched. Create the visual object
+   *    directly from merged data. This is the common path on rebuilds (undo,
+   *    redo, external updates) and eliminates race conditions.
+   * 2. Not cached (async) — first encounter. Create a Group placeholder, fetch
+   *    the prefab file, add visual as child when ready.
+   *
+   * In both cases, `userData['entity']` stores the ORIGINAL instance descriptor
+   * (with `prefab` field intact) — never the merged result.
+   */
+  function addPrefabEntity(
+    entity: SceneEntity,
+    parent: THREE.Object3D,
+    map: Map<string, THREE.Object3D>,
+    batchedR: BatchedRenderer | null,
+  ): void {
+    const cachedPrefab = prefabPreviewCache.get(entity.prefab!);
+
+    if (cachedPrefab) {
+      // --- Synchronous path: prefab cached, create visual directly ---
+      const merged = tryMergePrefabInstance(cachedPrefab.root, entity);
+      const obj = createEntityObject(merged);
+      setUserData(obj, 'entityId', entity.id as string);
+      // Store the ORIGINAL instance descriptor (with prefab ref) as source of truth.
+      setUserData(obj, 'entity', JSON.parse(JSON.stringify(entity)) as SceneEntity);
+      const t = entity.transform;
+      if (t?.position) obj.position.set(t.position[0], t.position[1], t.position[2]);
+      if (t?.rotation)
+        obj.quaternion.set(t.rotation[0], t.rotation[1], t.rotation[2], t.rotation[3]);
+      if (t?.scale) obj.scale.set(t.scale[0], t.scale[1], t.scale[2]);
+      obj.visible = entity.visible !== false;
+      parent.add(obj);
+      registerParticles(obj, batchedR);
+      if (entity.id) map.set(entity.id, obj);
+      if (merged.children) {
+        addEntities(merged.children, obj);
+      }
+      return;
+    }
+
+    // --- Async path: first load, prefab not yet fetched ---
+    const placeholder = new THREE.Group();
+    setUserData(placeholder, 'entityId', entity.id as string);
+    setUserData(placeholder, 'entity', JSON.parse(JSON.stringify(entity)) as SceneEntity);
+    const t = entity.transform;
+    if (t?.position) placeholder.position.set(t.position[0], t.position[1], t.position[2]);
+    if (t?.rotation)
+      placeholder.quaternion.set(t.rotation[0], t.rotation[1], t.rotation[2], t.rotation[3]);
+    if (t?.scale) placeholder.scale.set(t.scale[0], t.scale[1], t.scale[2]);
+    placeholder.visible = entity.visible !== false;
+    parent.add(placeholder);
+    if (entity.id) map.set(entity.id, placeholder);
+
+    // Fetch and populate
+    resolvePrefabEntity(entity).then((resolved) => {
+      const obj = createEntityObject(resolved);
+      // Visual child of the placeholder — strip entity tags so _buildEntityTree
+      // doesn't double-count it.
+      deleteUserData(obj, 'entityId');
+      deleteUserData(obj, 'entity');
+      placeholder.add(obj);
+      registerParticles(obj, batchedR);
+      if (resolved.children) {
+        addEntities(resolved.children, obj);
+      }
+    });
+  }
+
+  addEntities(doc.entities, scene);
+  resolvePreviewBoneAttachments(objectMap);
+
+  // Apply environment
+  applyEnvironment(doc.environment, scene, renderer);
+
+  // Apply shading mode override
+  if (shadingMode !== 'solid') {
+    applyShadingOverride(scene, shadingMode);
+  }
+
+  return objectMap;
+}
+
+/** Remove all objects tagged with entityId or envObject from the scene. */
+export function clearPreview(scene: THREE.Scene, batchedRenderer?: BatchedRenderer | null): void {
+  const toRemove: THREE.Object3D[] = [];
+  scene.traverse((obj) => {
+    if (getUserData(obj, 'entityId') !== undefined || getUserData(obj, 'envObject')) {
+      toRemove.push(obj);
+    }
+  });
+  // Only remove top-level tagged objects (children are removed with parent)
+  for (const obj of toRemove) {
+    if (
+      obj.parent &&
+      getUserData(obj.parent, 'entityId') === undefined &&
+      !getUserData(obj.parent, 'envObject')
+    ) {
+      unregisterParticles(obj, batchedRenderer ?? null);
+      disposeObject3D(obj);
+      obj.parent.remove(obj);
+    }
+  }
+  // Clear fog and environment
+  scene.fog = null;
+  scene.environment = null;
+}
+
+/**
+ * Update a single entity's Object3D in the map.
+ * Rebuilds the object if structural properties changed, otherwise patches in place.
+ */
+export function updateEntityPreview(
+  entity: SceneEntity,
+  objectMap: Map<string, THREE.Object3D>,
+  scene: THREE.Scene,
+  batchedRenderer?: BatchedRenderer | null,
+): void {
+  if (!entity.id) return;
+
+  const existing = objectMap.get(entity.id);
+  if (!existing) return;
+
+  // Unregister old particle systems (only on the entity itself, not child entities)
+  unregisterParticles(existing, batchedRenderer ?? null);
+
+  // Collect entity children to reparent (not helpers) and detach them so the
+  // disposal below doesn't free resources we're about to re-use.
+  const entityChildren: THREE.Object3D[] = [];
+  for (const child of [...existing.children]) {
+    if (getUserData(child, 'entityId') !== undefined && !getUserData(child, 'editorHelper')) {
+      entityChildren.push(child);
+      existing.remove(child);
+    }
+  }
+
+  // Rebuild the object in place
+  const parent = existing.parent ?? scene;
+  const index = parent.children.indexOf(existing);
+  // Dispose the old object's owned geometry/materials + animation (ED4/ED5).
+  disposeObject3D(existing);
+  parent.remove(existing);
+
+  // For prefab instances, build visual from merged data but keep original descriptor.
+  let visualEntity: SceneEntity;
+  if (entity.prefab) {
+    // The entity still has the prefab ref — resolve it for visual creation.
+    // Use cached prefab data (already loaded by buildPreview).
+    const cached = prefabPreviewCache.get(entity.prefab);
+    visualEntity = cached ? tryMergePrefabInstance(cached.root, entity) : entity;
+  } else {
+    visualEntity = resolveEntityMaterial(entity, objectMap, scene);
+  }
+  const newObj = createEntityObject(visualEntity);
+  // Restore the original (unresolved) entity as the source of truth.
+  // This preserves prefab ref, materialRef, and any instance-level overrides.
+  setUserData(newObj, 'entity', JSON.parse(JSON.stringify(entity)) as SceneEntity);
+  newObj.visible = entity.visible !== false;
+
+  // Reparent entity children from old object to new object
+  for (const child of entityChildren) {
+    newObj.add(child);
+  }
+
+  if (index >= 0) {
+    parent.children.splice(index, 0, newObj);
+    newObj.parent = parent;
+  } else {
+    parent.add(newObj);
+  }
+  objectMap.set(entity.id, newObj);
+
+  // Register new particle systems
+  registerParticles(newObj, batchedRenderer ?? null);
+}
+
+/** Apply scene environment settings (background, ambient light, fog, skybox/IBL). */
+export function applyEnvironment(
+  env: SceneEnvironment | undefined,
+  scene: THREE.Scene,
+  renderer?: THREE.WebGLRenderer,
+): void {
+  // Always reset to defaults — callers (buildPreview, play-mode restore) clear the
+  // scene first, so we must re-apply even when env is undefined.
+  const DEFAULT_BG = '#aaaaaa';
+  const DEFAULT_AMBIENT_COLOR = '#ffffff';
+  const DEFAULT_AMBIENT_INTENSITY = 0.5;
+
+  scene.background = new THREE.Color(env?.background ?? DEFAULT_BG);
+
+  // Ambient light
+  const ambientColor = env?.ambient?.color ?? DEFAULT_AMBIENT_COLOR;
+  const ambientIntensity = env?.ambient?.intensity ?? DEFAULT_AMBIENT_INTENSITY;
+  const ambient = new THREE.AmbientLight(ambientColor, ambientIntensity);
+  setUserData(ambient, 'envObject', true);
+  scene.add(ambient);
+
+  if (env?.fog) {
+    if (env.fog.type === 'linear') {
+      // Fallbacks from DEFAULTS (T1.13) — this previously used `?? 10` for
+      // near while the runtime loader used the DEFAULTS value of 1, so the
+      // editor preview and the running game disagreed on default fog.
+      scene.fog = new THREE.Fog(
+        env.fog.color,
+        env.fog.near ?? DEFAULTS.fog.linear.near,
+        env.fog.far ?? DEFAULTS.fog.linear.far,
+      );
+    } else {
+      scene.fog = new THREE.FogExp2(
+        env.fog.color,
+        env.fog.density ?? DEFAULTS.fog.exponential.density,
+      );
+    }
+  }
+
+  // Skybox / IBL environment map
+  if (env?.skybox && renderer) {
+    const cached = envTextureCache.get(env.skybox);
+    if (cached) {
+      scene.background = cached;
+      scene.environment = cached;
+      scene.environmentIntensity = env.envMapIntensity ?? 1.0;
+    } else {
+      loadEnvTexture(env.skybox, renderer).then((texture) => {
+        if (texture) {
+          envTextureCache.set(env.skybox!, texture);
+          scene.background = texture;
+          scene.environment = texture;
+          scene.environmentIntensity = env.envMapIntensity ?? 1.0;
+        }
+      });
+    }
+  }
+}
+
+/** Load an equirectangular texture and process with PMREMGenerator for IBL. */
+async function loadEnvTexture(
+  path: string,
+  renderer: THREE.WebGLRenderer,
+): Promise<THREE.Texture | null> {
+  try {
+    if (!_pmremGenerator) {
+      _pmremGenerator = new THREE.PMREMGenerator(renderer);
+      _pmremGenerator.compileEquirectangularShader();
+    }
+
+    const ext = path.split('.').pop()?.toLowerCase();
+    let rawTexture: THREE.Texture;
+
+    if (ext === 'hdr') {
+      rawTexture = await new RGBELoader(loadingManager).loadAsync(path);
+    } else {
+      rawTexture = await new THREE.TextureLoader(loadingManager).loadAsync(path);
+    }
+
+    rawTexture.mapping = THREE.EquirectangularReflectionMapping;
+    const envMap = _pmremGenerator.fromEquirectangular(rawTexture).texture;
+    rawTexture.dispose();
+    return envMap;
+  } catch {
+    return null;
+  }
+}
+
+function asMaterialArray(m: THREE.Material | THREE.Material[]): THREE.Material[] {
+  return Array.isArray(m) ? m : [m];
+}
+
+/**
+ * Apply (and revert) the viewport shading override on a single mesh.
+ *
+ * Reversible across all three modes so the toolbar toggle can re-shade live
+ * meshes without a full scene rebuild (ED1):
+ *  - solid: restore the original material(s), clear wireframe.
+ *  - wireframe: restore original material(s), set wireframe on.
+ *  - unlit: swap in MeshBasicMaterial(s) built from the original color.
+ *
+ * The original material is stashed in `userData['__shadeOrig']` the first time
+ * the mesh is touched; unlit overrides are stashed in `__shadeUnlit` so they
+ * can be disposed when leaving unlit.
+ */
+function applyShadingToMesh(mesh: THREE.Mesh, mode: ShadingMode): void {
+  if (getUserData(mesh, '__shadeOrig') === undefined) {
+    setUserData(mesh, '__shadeOrig', mesh.material);
+  }
+  const orig = getUserData(mesh, '__shadeOrig') as THREE.Material | THREE.Material[];
+  const unlit = getUserData(mesh, '__shadeUnlit') as THREE.Material[] | undefined;
+
+  if (mode === 'unlit') {
+    if (unlit) {
+      mesh.material = Array.isArray(orig) ? unlit : unlit[0]!;
+      return;
+    }
+    const created = asMaterialArray(orig).map((m) => {
+      const color = (m as THREE.MeshStandardMaterial).color?.clone() ?? new THREE.Color(0x888888);
+      return new THREE.MeshBasicMaterial({ color });
+    });
+    setUserData(mesh, '__shadeUnlit', created);
+    mesh.material = Array.isArray(orig) ? created : created[0]!;
+    return;
+  }
+
+  // solid or wireframe: restore originals and drop any unlit override.
+  mesh.material = orig;
+  if (unlit) {
+    for (const m of unlit) m.dispose();
+    deleteUserData(mesh, '__shadeUnlit');
+  }
+  const wire = mode === 'wireframe';
+  for (const m of asMaterialArray(orig)) {
+    if ('wireframe' in m) (m as THREE.MeshStandardMaterial).wireframe = wire;
+  }
+}
+
+/** Apply viewport shading override to all entity meshes. Reversible (ED1). */
+export function applyShadingOverride(scene: THREE.Scene, mode: ShadingMode): void {
+  scene.traverse((obj) => {
+    if (getUserData(obj, 'entityId') === undefined) return;
+    const mesh = obj as THREE.Mesh;
+    if (!mesh.isMesh || !mesh.material) return;
+    applyShadingToMesh(mesh, mode);
+  });
+}

package/src/scene-ui-mode/active-scene-ui.ts

@@ -0,0 +1,58 @@
+/**
+ * Scene-UI-mode chrome (E1.a/b/c, spec-27 §7 E1 — the remaining half of "Absorb
+ * scene-UI as a mode, not a separate app": palette, keyframe timeline, prefabs).
+ *
+ * Files under THIS folder are the §10 item-7 grep-ban exemption's home
+ * ("outside the migrated scene-UI-mode files"): they may import `UIEditStore`
+ * and its neighbours (`ui-editor/*`) freely, because they exist SPECIFICALLY to
+ * author a `.vscn` `ui` tree. The generic editor shell (`components/
+ * DefaultEditorLayout.tsx`, `components/GameHierarchy.tsx`, `components/
+ * BottomPanel.tsx`, …) may compose a `scene-ui-mode/*` component/hook by
+ * IMPORTING it (exactly like it already composes `GameHierarchy`/`RightPanel`),
+ * but must never import `UIEditStore` (or `SceneEntity`/`THREE.`) itself — that
+ * boundary is what keeps `rg "UIEditStore" src/components` a meaningful,
+ * zero-hit grep gate outside this folder.
+ *
+ * This module resolves WHICH `UIAuthoringAdapter` (if any) is the open
+ * project's live scene-UI child, so every other file in this folder has one
+ * place to ask "is scene-UI authoring live right now?" instead of re-deriving
+ * the composite-child lookup.
+ */
+
+import { useSyncExternalStore } from 'react';
+import { getAuthoringOverride } from '../authoring/active-adapter';
+import { CompositeAuthoringAdapter } from '../authoring/composite-authoring-adapter';
+import { UIAuthoringAdapter } from '../authoring/ui-authoring-adapter';
+import { useEditorStore } from '../EditorContext';
+
+/**
+ * The active `UIAuthoringAdapter`, whether it is installed directly as the
+ * override (the standalone harness's pre-C3 shape, `ui-editor/harness.tsx`) or
+ * nested as the edit-mode `CompositeAuthoringAdapter`'s `kind: 'scene-ui'`
+ * child (C3, the unified editor's real shape — at most one such child exists
+ * per open scene, `edit-mode-authoring.ts`'s `buildUIChild`). `null` when
+ * neither applies: no override installed, a bare non-UI override (ingest/
+ * play), or a composite with no scene-UI child yet (the open scene has no
+ * `ui` roots — §3.1's install gate).
+ */
+export function resolveActiveSceneUIAdapter(): UIAuthoringAdapter | null {
+  const active = getAuthoringOverride();
+  if (active instanceof UIAuthoringAdapter) return active;
+  if (active instanceof CompositeAuthoringAdapter) {
+    const child = active.childAdapters().find((c) => c.kind === 'scene-ui');
+    return child?.adapter instanceof UIAuthoringAdapter ? child.adapter : null;
+  }
+  return null;
+}
+
+/**
+ * React-hook form of {@link resolveActiveSceneUIAdapter} — re-resolves on
+ * every `EditorStore` notify (edit-mode composite install/teardown, scene
+ * switch, undo/redo of the whole document all fire one), which is exactly the
+ * signal that can flip whether a scene-UI child exists at all.
+ */
+export function useActiveSceneUIAdapter(): UIAuthoringAdapter | null {
+  const store = useEditorStore();
+  useSyncExternalStore(store.subscribe, store.getSnapshot);
+  return resolveActiveSceneUIAdapter();
+}