@vgai/editor 0.2.0

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

@@ -0,0 +1,475 @@
+/**
+ * IngestAuthoringAdapter — the {@link AuthoringAdapter} for an UNMODIFIED external
+ * three.js game, implemented DIRECTLY over the game's live `Object3D` tree.
+ *
+ * This is the Phase-B anti-shim deliverable. The old `reflectSceneForIngest`
+ * fabricated a first-party `SceneEntity` for every foreign object so the
+ * `.vscn`-centric editor would accept it — the inversion run backwards. This
+ * adapter implements the SAME providers the editor already consumes
+ * (hierarchy/selection/transforms/inspector) with **no `SceneEntity` anywhere**:
+ *   - hierarchy walks `scene.children`,
+ *   - transforms read/write the `Object3D` pose,
+ *   - inspector reflects real three.js fields (name, visibility, material color).
+ *
+ * Identity: each object gets a deterministic **structural-path id** (stable for a
+ * given scene shape — the basis for Phase-C overlay persistence) which is also
+ * written to `userData.entityId` so the editor's existing object map / gizmo /
+ * selection (which key on `entityId`) bind to foreign objects with no further
+ * shim.
+ *
+ * Persistence (Phase C): edits are accumulated into an {@link IngestOverlay} keyed
+ * by that stable id and saved to `.vgai/overlays/<game>.json`; on the next ingest
+ * the overlay is reapplied after the game rebuilds its scene. We never touch the
+ * game's source — same `PersistenceProvider` interface as `.vscn`, different
+ * source of truth.
+ *
+ * Selection is editor-global UI state, so it delegates to the store's selection
+ * set (shared with the first-party adapter); everything else is over `Object3D`.
+ */
+
+import type {
+  AuthoringAdapter,
+  AuthoringCapabilities,
+  EditorNode,
+  HierarchyProvider,
+  InspectorProvider,
+  PersistenceProvider,
+  PickProvider,
+  PropertyDescriptor,
+  SelectionProvider,
+  Transform,
+  TransformOwner,
+  TransformProvider,
+} from '@engine/adapter';
+import {
+  applyOverlayToObjects,
+  assignStructuralIds,
+  colorMaterialOf,
+} from '@engine/adapter/ingest/overlay-apply';
+import type * as THREE from 'three';
+import type { EditorStore } from '../editor-store';
+import { captureSubtreeToVscn } from './ingest-capture';
+import type { IngestOverlay } from './ingest-overlay';
+import { notifyUndoableOp, registerUndoAdapter } from './undo-timeline';
+import { raycastPick } from './viewport-raycast';
+
+/** Loop-gate hooks so a stable edit can pause the game that owns the rAF. */
+export interface IngestLoopControl {
+  pause(): void;
+  resume(): void;
+}
+
+export interface IngestAuthoringOptions {
+  loop?: IngestLoopControl | undefined;
+  /** Overlay to reapply once the scene is walked (edits from a previous session). */
+  overlay?: IngestOverlay | undefined;
+  /** Save callback for `persistence.save()`. Absence ⇒ runtime-only (persist:false). */
+  persist?: ((overlay: IngestOverlay) => Promise<void>) | undefined;
+  /**
+   * Human-readable overlay destination (design §2), e.g. `.vgai/overlays/<id>.json`
+   * (see `overlayPath()`). Absence (no `persist` callback) reads as runtime-only.
+   */
+  destination?: string | undefined;
+  /** The captured render camera — surfaced as an inspectable hierarchy node. */
+  camera?: THREE.Camera | undefined;
+}
+
+function kindOf(o: THREE.Object3D): EditorNode['kind'] {
+  const any = o as THREE.Object3D & {
+    isMesh?: boolean;
+    isLight?: boolean;
+    isCamera?: boolean;
+  };
+  if (any.isLight) return 'light';
+  if (any.isCamera) return 'camera';
+  if (any.isMesh) return 'mesh';
+  if (o.children.length > 0) return 'group';
+  return 'object';
+}
+
+/** The object as a Light (intensity + color), if it is one. */
+function lightOf(o: THREE.Object3D): THREE.Light | null {
+  return (o as THREE.Object3D & { isLight?: boolean }).isLight ? (o as THREE.Light) : null;
+}
+
+/** The object as a PerspectiveCamera (fov/near/far), if it is one. */
+function perspectiveCameraOf(o: THREE.Object3D): THREE.PerspectiveCamera | null {
+  const c = o as THREE.PerspectiveCamera & { isPerspectiveCamera?: boolean };
+  return c.isPerspectiveCamera ? c : null;
+}
+
+/** The object's mesh geometry, if it is a mesh. */
+function geometryOf(o: THREE.Object3D): THREE.BufferGeometry | null {
+  const m = o as THREE.Mesh & { isMesh?: boolean };
+  return m.isMesh && m.geometry ? m.geometry : null;
+}
+
+export class IngestAuthoringAdapter implements AuthoringAdapter {
+  private readonly byId = new Map<string, THREE.Object3D>();
+  private readonly loop: IngestLoopControl | undefined;
+  private readonly persistFn: ((overlay: IngestOverlay) => Promise<void>) | undefined;
+  /** Human-readable overlay destination (design §2) — see {@link IngestAuthoringOptions.destination}. */
+  private readonly destination: string;
+  /** Captured render camera (not a scene child) surfaced as an extra root node. */
+  private readonly camera: THREE.Camera | undefined;
+  /** Accumulated edits (this session + reapplied overlay), keyed by stable id. */
+  private overlay: IngestOverlay = {};
+  private dirty = false;
+
+  readonly capabilities: AuthoringCapabilities;
+
+  constructor(
+    private readonly store: EditorStore,
+    private readonly scene: THREE.Scene,
+    opts: IngestAuthoringOptions = {},
+  ) {
+    this.loop = opts.loop;
+    this.persistFn = opts.persist;
+    this.destination =
+      opts.destination ?? (opts.persist ? '(ingest overlay)' : '(runtime-only — not persisted)');
+    this.camera = opts.camera;
+    // T3.2 slice 2: this adapter IS the undo/redo target the editor-global
+    // timeline dispatches to for entries it records below (`pushUndo`).
+    // `ingest-mode.ts`'s `exitIngestMode()` unregisters it on teardown, so a
+    // Ctrl+Z reaching an entry from a since-uninstalled ingest session drops it
+    // (with a warn) instead of undoing against a stale live scene.
+    registerUndoAdapter(this);
+    this.capabilities = {
+      transform: true,
+      material: true,
+      inspectorFields: true,
+      // Structural authoring (create/delete/reparent) is NOT supported for an
+      // ingested game: the foreign game owns + rebuilds its own scene graph, so a
+      // create/delete/reparent isn't deterministically reapplicable through the
+      // overlay. The overlay is bounded to per-object transform/material/visibility
+      // (visibility=false is the only "soft-delete" we can persist). This is the
+      // named Phase-F ceiling for external games — no `structure` provider here.
+      create: false,
+      delete: false,
+      reparent: false,
+      persist: !!this.persistFn, // runtime-only unless a persist callback is wired
+    };
+    this.refresh();
+    if (opts.overlay) this.applyOverlay(opts.overlay);
+  }
+
+  /**
+   * (Re)assign structural-path ids to every object and rebuild the id→object map.
+   * Idempotent and deterministic from scene structure (position + type + name),
+   * so the id re-binds to the same object after the game rebuilds its scene —
+   * the prerequisite for overlay persistence. Call again after streamed assets.
+   *
+   * Delegates the actual walk to `@engine/adapter/ingest/overlay-apply.ts`'s
+   * `assignStructuralIds` (T3.8, docs/DECISIONS-PENDING.md §D9) — the SAME
+   * structural-id scheme the ship-path runtime applier uses on an independent
+   * fresh walk, so ids minted here and ids minted there agree byte-for-byte.
+   */
+  refresh(): { count: number; meshes: number; lights: number } {
+    const { byId, count, meshes, lights } = assignStructuralIds(this.scene, this.camera);
+    this.byId.clear();
+    for (const [id, o] of byId) this.byId.set(id, o);
+    return { count, meshes, lights };
+  }
+
+  /**
+   * Result of the most recent {@link applyOverlay} call (constructor-time
+   * reapply, or a later `persistence.applyExternal`) — the seam `ingest-mode.ts`
+   * reads to build the D9 `OverlayApplyReport` (`./overlay-report.ts`) without
+   * re-deriving orphan/applied counts itself.
+   */
+  private _lastApplyResult: { applied: number; orphanedIds: string[] } = {
+    applied: 0,
+    orphanedIds: [],
+  };
+  get lastApplyResult(): { applied: number; orphanedIds: string[] } {
+    return this._lastApplyResult;
+  }
+
+  /**
+   * Reapply a saved overlay onto the (already-walked) live scene, and seed the
+   * in-memory overlay so a later save preserves it — INCLUDING orphaned ids
+   * (D9 fix: previously only entries that resolved to a live object were
+   * seeded, so an orphan `applyOverlay` couldn't resolve this session was
+   * silently DROPPED on the next `save()` — exactly the silent loss D9
+   * forbids; `ingest-authoring-adapter.test.ts`'s "orphaned entries survive a
+   * save round-trip" pins the fix). Ids absent from the current scene are
+   * "orphaned" — e.g. a dynamic child that didn't respawn, or the vendored
+   * game was bumped and restructured — never an error; reported (never
+   * silently) via `./overlay-report.ts`.
+   *
+   * The mutation loop itself (per-id resolve + apply position/rotation/scale/
+   * color/visible, collect orphans) delegates to `@engine/adapter/ingest/
+   * overlay-apply.ts`'s `applyOverlayToObjects` (T3.8) — the SAME core the
+   * ship-path runtime applier uses; this method adds only the editor-specific
+   * bookkeeping described above (seed EVERY entry, applied or orphaned, into
+   * `this.overlay`).
+   */
+  applyOverlay(overlay: IngestOverlay): {
+    applied: number;
+    orphaned: number;
+    orphanedIds: string[];
+  } {
+    const { applied, orphanedIds } = applyOverlayToObjects(this.byId, overlay);
+    for (const [id, ov] of Object.entries(overlay)) {
+      this.overlay[id] = { ...this.overlay[id], ...ov };
+    }
+    this._lastApplyResult = { applied, orphanedIds };
+    return { applied, orphaned: orphanedIds.length, orphanedIds };
+  }
+
+  private record(id: string, patch: Partial<IngestOverlay[string]>): void {
+    this.overlay[id] = { ...this.overlay[id], ...patch };
+    this.dirty = true;
+  }
+
+  private idOf(o: THREE.Object3D): string | null {
+    return (o.userData?.['entityId'] as string | undefined) ?? null;
+  }
+
+  private toNode(o: THREE.Object3D, parentId: string | null): EditorNode {
+    const id = this.idOf(o)!;
+    return {
+      id,
+      label: o.name || o.type || 'Object3D',
+      kind: kindOf(o),
+      parentId,
+      childIds: o.children.map((c) => this.idOf(c)!).filter(Boolean),
+      flags: { runtimeOnly: true, transformOwner: 'external' },
+    };
+  }
+
+  subscribe(listener: () => void): () => void {
+    return this.store.subscribe(listener);
+  }
+
+  readonly hierarchy: HierarchyProvider = {
+    roots: () => {
+      const roots = this.scene.children.map((o) => this.toNode(o, null));
+      if (this.camera) roots.push(this.toNode(this.camera, null));
+      return roots;
+    },
+    node: (id) => {
+      const o = this.byId.get(id);
+      if (!o) return null;
+      const parentId = o.parent && o.parent !== this.scene ? this.idOf(o.parent) : null;
+      return this.toNode(o, parentId);
+    },
+    object3D: (id) => this.byId.get(id) ?? null,
+    idForObject3D: (o) => this.idOf(o),
+  };
+
+  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`). An ingested foreign threejs
+   * game's objects sit in `store.objectMap` (`enterPlayScene`) tagged with
+   * `userData.entityId` — the SAME shape the raycast reads for a first-party
+   * scene — so this restores the pre-B4 canvas click-select that
+   * `_onPointerUp`'s unconditional raycast used to provide (both bare ingest
+   * mode, where THIS adapter is the active override, AND multi-world PLAY,
+   * where THIS adapter is the composite's threejs child the layered pick walk
+   * reaches last). The returned `entityId` routes through the store-backed
+   * `selection` above exactly as it did pre-B4.
+   */
+  readonly pickable: PickProvider = {
+    pick: (clientX, clientY) => raycastPick(this.store, clientX, clientY),
+  };
+
+  readonly transforms: TransformProvider = {
+    get: (id): Transform => {
+      const o = this.byId.get(id);
+      if (!o) return { position: [0, 0, 0], rotation: [0, 0, 0, 1], scale: [1, 1, 1] };
+      return {
+        position: o.position.toArray() as [number, number, number],
+        rotation: o.quaternion.toArray() as [number, number, number, number],
+        scale: o.scale.toArray() as [number, number, number],
+      };
+    },
+    // The game owns this object's transform; the editor freezes the game loop so
+    // its gizmo edit isn't overwritten next frame, then resumes on release.
+    owner: (): TransformOwner => 'external',
+    beginEdit: (id) => {
+      this.loop?.pause();
+      this.editStartTransform = this.transforms.get(id); // snapshot for undo
+    },
+    apply: (id, t) => this.writeTransform(id, t),
+    endEdit: (id) => {
+      this.loop?.resume();
+      const prev = this.editStartTransform;
+      this.editStartTransform = undefined;
+      if (!prev) return;
+      const next = this.transforms.get(id);
+      this.pushUndo({
+        undo: () => this.writeTransform(id, prev),
+        redo: () => this.writeTransform(id, next),
+      });
+    },
+  };
+
+  /** Write a transform to the live object + record it in the overlay (no undo push). */
+  private writeTransform(id: string, t: Transform): void {
+    const o = this.byId.get(id);
+    if (!o) return;
+    o.position.set(t.position[0], t.position[1], t.position[2]);
+    o.quaternion.set(t.rotation[0], t.rotation[1], t.rotation[2], t.rotation[3]);
+    o.scale.set(t.scale[0], t.scale[1], t.scale[2]);
+    this.record(id, { position: t.position, rotation: t.rotation, scale: t.scale });
+  }
+
+  readonly inspector: InspectorProvider = {
+    // The editor's generic InspectorProvider-driven panel renders THIS list — the
+    // reflectable three.js fields per object kind (no SceneEntity, no hardcoded UI).
+    properties: (id): PropertyDescriptor[] => {
+      const o = this.byId.get(id);
+      if (!o) return [];
+      const props: PropertyDescriptor[] = [
+        { path: 'name', label: 'Name', type: 'string' },
+        { path: 'visible', label: 'Visible', type: 'boolean' },
+      ];
+      if (colorMaterialOf(o)) props.push({ path: 'material.color', label: 'Color', type: 'color' });
+      const light = lightOf(o);
+      if (light) {
+        props.push({ path: 'light.intensity', label: 'Intensity', type: 'number' });
+        props.push({ path: 'light.color', label: 'Light Color', type: 'color' });
+      }
+      if (perspectiveCameraOf(o)) {
+        props.push({ path: 'camera.fov', label: 'FOV', type: 'number' });
+        props.push({ path: 'camera.near', label: 'Near', type: 'number' });
+        props.push({ path: 'camera.far', label: 'Far', type: 'number' });
+      }
+      if (geometryOf(o)) {
+        props.push({ path: 'mesh.vertices', label: 'Vertices', type: 'number', readonly: true });
+        // Shadow flags are reflectable from the mesh (Physics/Animation are N/A for a
+        // foreign object — no engine body/anim-graph — so they are simply absent).
+        props.push({ path: 'shadow.cast', label: 'Cast Shadow', type: 'boolean' });
+        props.push({ path: 'shadow.receive', label: 'Receive Shadow', type: 'boolean' });
+      }
+      return props;
+    },
+    get: (id, path) => {
+      const o = this.byId.get(id);
+      if (!o) return undefined;
+      if (path === 'name') return o.name;
+      if (path === 'visible') return o.visible;
+      if (path === 'material.color') {
+        const m = colorMaterialOf(o);
+        return m ? `#${m.color.getHexString()}` : undefined;
+      }
+      if (path === 'light.intensity') return lightOf(o)?.intensity;
+      if (path === 'light.color') {
+        const l = lightOf(o);
+        return l ? `#${l.color.getHexString()}` : undefined;
+      }
+      if (path === 'camera.fov') return perspectiveCameraOf(o)?.fov;
+      if (path === 'camera.near') return perspectiveCameraOf(o)?.near;
+      if (path === 'camera.far') return perspectiveCameraOf(o)?.far;
+      if (path === 'mesh.vertices') {
+        const g = geometryOf(o);
+        return g ? (g.getAttribute('position')?.count ?? 0) : undefined;
+      }
+      if (path === 'shadow.cast') return o.castShadow;
+      if (path === 'shadow.receive') return o.receiveShadow;
+      return undefined;
+    },
+    set: (id, path, value) => {
+      const prev = this.inspector.get(id, path); // snapshot for undo
+      this.writeProp(id, path, value);
+      this.pushUndo({
+        undo: () => this.writeProp(id, path, prev),
+        redo: () => this.writeProp(id, path, value),
+      });
+    },
+  };
+
+  /** Mutate one reflectable field on the live object + record persistable ones (no undo push). */
+  private writeProp(id: string, path: string, value: unknown): void {
+    const o = this.byId.get(id);
+    if (!o) return;
+    if (path === 'name') o.name = String(value);
+    else if (path === 'visible') {
+      o.visible = Boolean(value);
+      this.record(id, { visible: o.visible });
+    } else if (path === 'material.color') {
+      const m = colorMaterialOf(o);
+      if (m) {
+        m.color.set(String(value));
+        this.record(id, { color: `#${m.color.getHexString()}` });
+      }
+    } else if (path === 'light.intensity') {
+      const l = lightOf(o);
+      if (l) l.intensity = Number(value);
+    } else if (path === 'light.color') {
+      lightOf(o)?.color.set(String(value));
+    } else if (path === 'camera.fov' || path === 'camera.near' || path === 'camera.far') {
+      const c = perspectiveCameraOf(o);
+      if (c) {
+        (c as unknown as Record<string, number>)[path.split('.')[1]!] = Number(value);
+        c.updateProjectionMatrix();
+      }
+    } else if (path === 'shadow.cast') o.castShadow = Boolean(value);
+    else if (path === 'shadow.receive') o.receiveShadow = Boolean(value);
+    // (light/camera edits are live-only; transform/material/visibility persist via the overlay.)
+    this.store.notifyIngestEdit();
+  }
+
+  // --- Overlay-backed undo/redo (feat-edit-undo for ingested games) ---
+  private readonly undoStack: Array<{ undo: () => void; redo: () => void }> = [];
+  private readonly redoStack: Array<{ undo: () => void; redo: () => void }> = [];
+  private editStartTransform: Transform | undefined;
+
+  private pushUndo(entry: { undo: () => void; redo: () => void }): void {
+    this.undoStack.push(entry);
+    this.redoStack.length = 0;
+    notifyUndoableOp(this); // T3.2 slice 2 — tag this op on the global timeline
+  }
+
+  undo(): boolean {
+    // `false` tells the undo timeline "couldn't act — put the entry back"
+    // (see UndoAdapter in ./undo-timeline.ts).
+    const e = this.undoStack.pop();
+    if (!e) return false;
+    e.undo();
+    this.redoStack.push(e);
+    this.store.notifyIngestEdit();
+    return true;
+  }
+
+  redo(): boolean {
+    const e = this.redoStack.pop();
+    if (!e) return false;
+    e.redo();
+    this.undoStack.push(e);
+    this.store.notifyIngestEdit();
+    return true;
+  }
+
+  // A class GETTER, not a field initializer: a field initializer runs before the
+  // constructor body assigns `this.destination`, so a plain object-literal field
+  // would capture it as `undefined` (see the same fix on VgaiSceneAuthoringAdapter).
+  get persistence(): PersistenceProvider {
+    return {
+      isDirty: () => this.dirty,
+      save: async () => {
+        if (!this.persistFn) return;
+        await this.persistFn(this.overlay);
+        this.dirty = false;
+      },
+      serialize: () => this.overlay,
+      // Migration: capture selected ingested subtrees into first-party SceneEntities
+      // (the sanctioned ingest→.vscn bridge; geometry ceiling documented there).
+      captureToVscn: (ids) => captureSubtreeToVscn((id) => this.byId.get(id) ?? null, ids),
+      destination: this.destination,
+      // The reload contract (design §5): re-run the existing `applyOverlay` remount
+      // logic against the LIVE scene — it already IS the remount-free re-apply path
+      // (the constructor calls it the same way after the initial `refresh()`), just
+      // exposed here so a changed overlay file needn't remount the game.
+      applyExternal: (content) => {
+        this.applyOverlay(content as IngestOverlay);
+      },
+    };
+  }
+}

package/src/authoring/ingest-capture.ts

@@ -0,0 +1,94 @@
+/**
+ * Capture-to-`.vscn` — the sanctioned migration bridge from an ingested game's live
+ * `Object3D` subtree to first-party `SceneEntity` descriptors (the founding doc's
+ * "Capture to VGAI" persistence mode: `ADAPTER-VISION-ORIGINAL.md` §'Persistence
+ * Strategies'). This is the ONE place outside the first-party adapter where the
+ * ingest path deliberately produces `SceneEntity` — turning "inspect a foreign
+ * game" into "author first-party content".
+ *
+ * HONEST CEILING (geometry): a vgai `SceneEntity.mesh` only expresses the built-in
+ * primitive types (box/sphere/plane/cylinder/capsule) or a GLTF `src`. A foreign
+ * game's arbitrary `BufferGeometry` is NOT expressible — recognizable primitives map
+ * faithfully; anything else captures as a placeholder `box` (transform/material/
+ * hierarchy are captured faithfully). This is the documented bound on capture.
+ */
+
+import type { SceneEntity, SceneMesh } from '@engine/scene/scene-types';
+import type * as THREE from 'three';
+
+function meshOf(o: THREE.Object3D): SceneMesh | undefined {
+  const g = (o as THREE.Mesh).geometry;
+  if (!g) return undefined;
+  switch (g.type) {
+    case 'BoxGeometry':
+      return { type: 'box' };
+    case 'SphereGeometry':
+      return { type: 'sphere' };
+    case 'PlaneGeometry':
+      return { type: 'plane' };
+    case 'CylinderGeometry':
+      return { type: 'cylinder' };
+    case 'CapsuleGeometry':
+      return { type: 'capsule' };
+    default:
+      return { type: 'box' }; // foreign geometry not expressible → placeholder (ceiling)
+  }
+}
+
+function colorOf(o: THREE.Object3D): string | undefined {
+  const mat = (o as THREE.Mesh).material;
+  if (!mat || Array.isArray(mat)) return undefined;
+  const c = (mat as THREE.MeshStandardMaterial).color;
+  return c ? `#${c.getHexString()}` : undefined;
+}
+
+function lightTypeOf(o: THREE.Object3D): NonNullable<SceneEntity['light']>['type'] {
+  const t = o.type;
+  if (t.includes('Directional')) return 'directional';
+  if (t.includes('Hemisphere') || t.includes('Ambient')) return 'hemisphere';
+  if (t.includes('Spot')) return 'spot';
+  return 'point';
+}
+
+function captureOne(o: THREE.Object3D): SceneEntity {
+  const any = o as THREE.Object3D & { isMesh?: boolean; isLight?: boolean };
+  const e: SceneEntity = {
+    id: crypto.randomUUID(),
+    name: o.name || o.type || 'Object3D',
+    transform: {
+      position: o.position.toArray() as [number, number, number],
+      rotation: o.quaternion.toArray() as [number, number, number, number],
+      scale: o.scale.toArray() as [number, number, number],
+    },
+    visible: o.visible,
+  };
+  if (any.isMesh) {
+    e.mesh = meshOf(o);
+    const color = colorOf(o);
+    if (color) e.material = { type: 'standard', color };
+  }
+  if (any.isLight) {
+    e.light = { type: lightTypeOf(o), intensity: (o as THREE.Light).intensity };
+  }
+  const kids = o.children
+    .filter((c) => {
+      const a = c as THREE.Object3D & { isMesh?: boolean; isLight?: boolean };
+      return a.isMesh || a.isLight || c.children.length > 0;
+    })
+    .map(captureOne);
+  if (kids.length) e.children = kids;
+  return e;
+}
+
+/** Capture the given ingested object ids (+ their subtrees) as first-party SceneEntities. */
+export function captureSubtreeToVscn(
+  getObject: (id: string) => THREE.Object3D | null,
+  ids: string[],
+): SceneEntity[] {
+  const out: SceneEntity[] = [];
+  for (const id of ids) {
+    const o = getObject(id);
+    if (o) out.push(captureOne(o));
+  }
+  return out;
+}