@volter/editor-threejs 0.5.211 → 0.5.213

package/src/kit/projection/three.ts

@@ -1,49 +1,13 @@
 /**
- * THE PROJECTOR FOR THE THREE SURFACE — one walk, one index, one set of derived
- * views, for every authoring adapter that drives a live `Object3D` graph
- * (ARCHITECTURE-CORE §The editor protocol, projection family).
- *
- * The projection unit is the RUNTIME OBJECT. Nothing here reads source, an AST
- * or a document; a walk answers from the graph that is actually mounted, so an
- * empty projection over a mounted world is a defect rather than a fact.
- *
- * ## What this owns, and what it deliberately does not
- *
- * OWNS — the four things all three three-surface authoring classes used to
- * spell separately:
- *
- *  - the DFS itself ({@link walkThreeGraph}), including the editor-furniture
- *    skip and the fold-into-the-nearest-admitted-ancestor rule,
- *  - IDENTITY MINTING, parameterized by scheme ({@link oidIdentity},
- *    {@link structuralIdentity}, {@link sourceOidIdentity},
- *    {@link documentPathIdentity}) — the id FORMATS are the schemes', the walk
- *    that applies them is one,
- *  - the INDEX both directions ({@link ThreeProjector.objects} /
- *    {@link ThreeProjector.idsByObject}) plus the `userData.entityId` stamp
- *    that makes the viewport's raycast, the gizmo and `store.objectMap` agree
- *    with the walk,
- *  - PICKING as a derived view over that index
- *    ({@link ThreeProjector.pick}).
- *
- * DOES NOT own the LANE-SPECIFIC hierarchy VIEW built on top. The R3F source
- * lane collapses a component instance's interior into one row; the live lane
- * resolves the same question over projected nodes with different top-level
- * semantics. Both read this projection and derive their rows from it; merging
- * the two collapse rules would be inventing a third, not extracting a shared
- * one.
- *
- * BOUNDS are not here either, because they were never in the authoring classes:
- * `@volter/editor-threejs/viewport/content-bounds` (`contentWorldBounds`) is the bounds walk
- * every consumer uses, and it takes the `Object3D` this index resolves.
+ * Project a live Object3D graph into one traversal, two-way object/id index and picker. Skip editor
+ * furniture, fold omitted nodes into admitted ancestors, and mint identities using the supplied
+ * scheme. Authoring adapters derive their hierarchy rows and write targets from this projection;
+ * viewport/content-bounds owns the separate bounds walk.
  */
 
 import type { EditorNode } from '@volter/project/adapter';
 import { isEditorOwnedObject } from '@volter/editor-threejs/viewport/editor-layers';
 import { constraintsOf } from '@volter/editor-threejs/adapter/constraint';
-import {
-  CAMERA_ID,
-  collectStructuralIds,
-} from '@volter/editor-threejs/adapter/ingest/structural-ids';
 import { object3DAuthoringSubjectOf } from '@volter/editor-threejs/adapter/object3d-authoring-subject';
 import { reflectionProbeOf } from '@volter/editor-threejs/adapter/reflection-probe';
 import { getUserData } from '@volter/editor-threejs/ecs/user-data';
@@ -52,17 +16,16 @@ import { authoringOidOf, occurrenceId } from '../authoring/component-instance-ro
 import { raycastCandidates, raycastPick } from '../authoring/viewport-raycast';
 import type { EditorShellStore } from '../editor-shell-store';
 import { entityIdOf, stampEntityId } from '../entity-object';
-import type { ProjectedNode, Projection } from '@volter/sdk/kit/projection-types';
+import type { ProjectedNode, Projection } from '@volter/sdk/projection-types';
 
-export type { ProjectedNode, Projection } from '@volter/sdk/kit/projection-types';
+export type { ProjectedNode, Projection } from '@volter/sdk/projection-types';
 
 /** One projected authoring node over a live three graph. */
 export type ThreeNode = ProjectedNode<THREE.Object3D>;
 
 /**
  * Reflection stats for one walk. Surfaced by the adapters' `refresh()` for
- * proof/telemetry (the ingest console line, the `__volterIngest.reflected` hook) —
- * deliberately a fresh measurement each walk rather than a mount-time snapshot,
+ * proof/telemetry — deliberately a fresh measurement each walk rather than a mount-time snapshot,
  * because a running world keeps streaming objects in.
  */
 export interface ThreeWalkStats {
@@ -76,9 +39,7 @@ export interface ThreeWalkStats {
    * object drawing N units — so `count`/`meshes` (and the hierarchy rows built
    * from the same nodes) report 1 where a reader sees N, with no error
    * anywhere, because both numbers are individually correct. These two fields
-   * are the only place the shortfall is expressible; a probe's
-   * instanced-content check reads exactly this pair
-   * (`packages/editor/src/doctor/detection-gaps.ts`).
+   * make that difference visible to an instanced-content inspection.
    */
   readonly instancedMeshes: number;
   readonly instances: number;
@@ -189,19 +150,7 @@ function tally(nodes: ReadonlyMap<string, ThreeNode>): ThreeWalkStats {
   return { count: nodes.size, meshes, lights, ...instancedTally(nodes) };
 }
 
-/**
- * THE WALK. One DFS over a live scene, projecting it into authoring nodes and
- * stamping `userData.entityId` on each, so the viewport raycast/gizmo and
- * `EditorShellStore.objectMap` key off the same identity the walk minted.
- *
- * Every scheme that goes through here addresses a graph the editor is entitled
- * to stamp. The one scheme that is not ({@link structuralIdentity}, over
- * foreign objects) keeps identity in the projection instead and does not use
- * this walk at all — see #1965.
- *
- * Idempotent for every scheme that reuses an existing stamp: re-walking a scene
- * re-derives the same ids for the same objects.
- */
+/** Project a live scene in one DFS and stamp entityId so raycast, gizmo and objectMap share the same identities. Reused stamps make repeated walks stable. */
 export function walkThreeGraph(scene: THREE.Scene, scheme: ThreeIdentityScheme): ThreeProjection {
   const nodes = new Map<string, ThreeNode>();
   const rootIds: string[] = [];
@@ -237,15 +186,7 @@ export function walkThreeGraph(scene: THREE.Scene, scheme: ThreeIdentityScheme):
   return { nodes, rootIds, stats: tally(nodes) };
 }
 
-/**
- * The scheme half of every three-lane entity id (`r3f:<worldId>:<oid>`).
- *
- * Spelled ONCE because it is read as well as written: the editor shell tests a
- * focused id with `startsWith` to decide whether the three lane owns it
- * (`components/DefaultEditorLayout.tsx`), so a literal changed at one of the
- * mint sites and not at the reader is a silent loss of that decision rather
- * than a compile error.
- */
+/** Shared scheme for Three-lane entity ids, r3f:<worldId>:<oid>. */
 export const THREE_ENTITY_ID_SCHEME = 'r3f:';
 
 /** `r3f:<worldId>:<oid>` — the one place the three lane's id shape is built. */
@@ -253,297 +194,6 @@ export function threeEntityId(worldId: string, oid: string): string {
   return `${THREE_ENTITY_ID_SCHEME}${worldId}:${oid}`;
 }
 
-/**
- * The LIVE OID scheme. A node stamped by the served TSX's `__volterOid` transform
- * keeps `r3f:<worldId>:<oid>`, so selection survives Edit→Play; anything a
- * source location cannot claim gets a session-stable `live:<worldId>:<n>`.
- */
-function liveOidScheme(worldId: string): ThreeIdentityScheme {
-  const oidOccurrences = new Map<string, number>();
-  const reservedOccurrenceOwners = new Map<string, THREE.Object3D>();
-  const occurrenceBelongsTo = (id: string, base: string): boolean =>
-    id === base || (id.startsWith(`${base}#`) && /^\d+$/u.test(id.slice(base.length + 1)));
-
-  const reserveExistingOccurrences = (scene: THREE.Scene): void => {
-    reservedOccurrenceOwners.clear();
-    const visit = (object: THREE.Object3D): void => {
-      if (isEditorOwnedObject(object)) return;
-      const sourceOid = authoringOidOf(object);
-      const stamped = entityIdOf(object);
-      if (sourceOid !== undefined && stamped !== undefined) {
-        const base = threeEntityId(worldId, sourceOid);
-        if (occurrenceBelongsTo(stamped, base) && !reservedOccurrenceOwners.has(stamped)) {
-          reservedOccurrenceOwners.set(stamped, object);
-        }
-      }
-      for (const child of object.children) visit(child);
-    };
-    for (const child of scene.children) visit(child);
-  };
-
-  const reusableStampedIdentity = (
-    object: THREE.Object3D,
-    sourceOid: string | undefined,
-  ): string | undefined => {
-    const stamped = entityIdOf(object);
-    if (stamped === undefined || sourceOid === undefined) return stamped;
-    const base = threeEntityId(worldId, sourceOid);
-    if (!occurrenceBelongsTo(stamped, base)) return stamped;
-    return reservedOccurrenceOwners.get(stamped) === object ? stamped : undefined;
-  };
-
-  const claimSourceIdentity = (object: THREE.Object3D, sourceOid: string): string => {
-    const base = threeEntityId(worldId, sourceOid);
-    let occurrence = oidOccurrences.get(sourceOid) ?? 0;
-    let identity = occurrenceId(base, occurrence);
-    while (reservedOccurrenceOwners.has(identity)) {
-      occurrence += 1;
-      identity = occurrenceId(base, occurrence);
-    }
-    oidOccurrences.set(sourceOid, occurrence + 1);
-    reservedOccurrenceOwners.set(identity, object);
-    return identity;
-  };
-
-  return {
-    begin: (scene) => {
-      oidOccurrences.clear();
-      reserveExistingOccurrences(scene);
-    },
-    identify: (object, context) => {
-      // Count every source-stamped runtime node in native traversal order,
-      // including projected-away wrappers/parts, so surviving authoring roots
-      // keep the same id across Edit and Play (mirrors the R3F design adapter's
-      // duplicate-OID suffixing exactly).
-      const sourceOid = authoringOidOf(object);
-      const stamped = reusableStampedIdentity(object, sourceOid);
-      if (stamped !== undefined) return stamped;
-      // Two live objects carrying one old occurrence stamp is the precise
-      // collision the reservation pass repairs. The first object in the
-      // current graph keeps the address; this later one receives the first
-      // free occurrence and is restamped by walkThreeGraph.
-      const sourceIdentity =
-        sourceOid === undefined ? undefined : claimSourceIdentity(object, sourceOid);
-      // ADMISSION. Three independent grounds, and the FIRST is what makes a
-      // play mount project the world the author wrote:
-      //
-      //  - A SOURCE IDENTITY. The served TSX stamped this element, so it is a
-      //    node the author authored — `<object3D name='Coins'>` as much as the
-      //    `<Coin/>` instances inside it. Ownership by an ancestor is beside the
-      //    point: an authored node is not its owner's implementation detail.
-      //    Without this, a fresh play mount (where nothing is pre-stamped with
-      //    an `entityId` yet) admitted only the nodes whose `authoringInstance`
-      //    differed from their parent's — so `Stage`'s whole interior collapsed
-      //    and its 49 component instances rendered FLAT, with the `Coins` and
-      //    `Enemies` groups that really parent them gone from the panel.
-      //  - NO OWNER ABOVE. An unstamped world (an ingest, an adopted graph) has
-      //    no source identities at all; its outermost objects are the rows, and
-      //    everything under them stays folded in as parts.
-      //  - AN EXPLICIT OPT-IN. `userData.authoringRoot` is how a runtime
-      //    descendant of such a world asks to be a row of its own.
-      //
-      // What stays folded is exactly what has none of the three: the parts a
-      // library builds under an authored node (GLTF meshes, bones, a light's
-      // `target`), which the mark convention folds by classification instead.
-      if (
-        sourceIdentity !== undefined ||
-        !context.ownedByAncestor ||
-        getUserData(object, 'authoringRoot') === true
-      ) {
-        return sourceIdentity ?? `live:${worldId}:${mintedIdCounter++}`;
-      }
-      return null;
-    },
-  };
-}
-
-/**
- * Walk a live scene under the OID scheme. Exported because scene ADOPTION runs
- * the same walk the adapter does (`viewport-root-presentation.ts`), and the two must
- * agree about every id.
- */
-export function projectThreeScene(scene: THREE.Scene, worldId: string): ThreeProjection {
-  return walkThreeGraph(scene, liveOidScheme(worldId));
-}
-
-/**
- * Stamp identities on a live scene and return the id → Object3D map the store
- * adopts as its `objectMap`. The adapter's own index is built by the same walk,
- * so the two can never disagree about an id.
- */
-export function stampThreeIdentities(
-  scene: THREE.Scene,
-  worldId: string,
-): Map<string, THREE.Object3D> {
-  const { nodes } = projectThreeScene(scene, worldId);
-  const map = new Map<string, THREE.Object3D>();
-  for (const [id, node] of nodes) map.set(id, node.object);
-  return map;
-}
-
-/**
- * The OID identity (see {@link liveOidScheme}), for a LIVE world.
- *
- * `camera` is the SAME allowance {@link structuralIdentity} makes and for the
- * same reason: a captured world's render camera often is not a child of the
- * scene it renders, and a camera that is not a node is not selectable,
- * inspectable, or reachable by the viewport's framing. It joins as an extra
- * root under the fixed {@link CAMERA_ID} only when the walk did not already
- * meet it as a scene child — an R3F world usually authors its camera inside the
- * tree, and admitting it twice would put the same object on two rows.
- */
-export function oidIdentity(
-  worldId: string,
-  options: { readonly camera?: THREE.Camera | undefined } = {},
-): ThreeIdentity {
-  const camera = options.camera;
-  return {
-    incremental: { kind: 'live-oid', worldId },
-    project: (scene) => {
-      const projection = projectThreeScene(scene, worldId);
-      if (!camera || [...projection.nodes.values()].some((node) => node.object === camera)) {
-        return projection;
-      }
-      stampEntityId(camera, CAMERA_ID);
-      projection.nodes.set(CAMERA_ID, {
-        object: camera,
-        id: CAMERA_ID,
-        parentId: null,
-        childIds: [],
-      });
-      projection.rootIds.push(CAMERA_ID);
-      return { ...projection, stats: { ...projection.stats, count: projection.nodes.size } };
-    },
-  };
-}
-
-export interface StructuralIdentityOptions {
-  /**
-   * A render camera that is NOT a scene child — surfaced as an extra root node
-   * under the fixed {@link CAMERA_ID} so it is selectable and inspectable. A
-   * captured world's camera usually lives outside the tree it renders.
-   */
-  readonly camera?: THREE.Camera | undefined;
-}
-
-/**
- * The STRUCTURAL-PATH scheme. Deterministic from the scene's shape (position in
- * the tree + three.js type + name), so the same id re-binds to the same object
- * after the world rebuilds part of its graph within a session. This is the
- * scheme for a graph whose source was never stamped, and it pairs with the
- * creation-site anchors the persistence backend writes through.
- *
- * The walk itself lives in `@volter/editor-threejs/adapter/ingest/structural-ids` — it is
- * the engine's own ingest walk and stays there; this provider is the projection
- * hop, turning its pure flat id→object map into the parent/child node graph
- * every authoring provider reads, WITHOUT stamping the foreign objects.
- */
-export function structuralIdentity(options: StructuralIdentityOptions = {}): ThreeIdentity {
-  const camera = options.camera;
-  return {
-    project: (scene) => {
-      const walk = collectStructuralIds(scene, camera);
-      // Reverse the walk's own map rather than storing identity on the foreign
-      // objects. A re-walk after a rebuild therefore has no stale stamps to
-      // collide with live ids or parent under the wrong object.
-      const idByObject = new Map<THREE.Object3D, string>();
-      for (const [id, object] of walk.byId) idByObject.set(object, id);
-      const nodes = new Map<string, ThreeNode>();
-      const rootIds: string[] = [];
-      for (const [id, object] of walk.byId) {
-        const parent = object.parent;
-        const parentId = (parent && parent !== scene ? idByObject.get(parent) : undefined) ?? null;
-        // `childIds` is filtered to the walk's own membership: editor furniture
-        // parked in the world's scene is skipped by `assignStructuralIds`, and
-        // it must not reappear as a hierarchy row through a parent's children.
-        const childIds = object.children
-          .map((child) => idByObject.get(child))
-          .filter((childId): childId is string => childId !== undefined);
-        nodes.set(id, { object, id, parentId, childIds });
-        if (parentId === null) rootIds.push(id);
-      }
-      return {
-        nodes,
-        rootIds,
-        stats: {
-          count: walk.count,
-          meshes: walk.meshes,
-          lights: walk.lights,
-          ...instancedTally(nodes),
-        },
-      };
-    },
-  };
-}
-
-/**
- * The SOURCE OID identity, for a first-party R3F world whose TSX the editor
- * serves: every object is a node (the lane's hierarchy view does its own
- * collapsing on top), addressed by its authored callsite where it has one and
- * by its structural path where it does not.
- *
- * It also reports the two OID-lane facts the walk is the only place able to
- * measure, refreshed on every `project`:
- *
- *  - `instanceRoots` — how many times each authored element RENDERS, counted at
- *    instance ROOTS only (an object with no ancestor carrying the same
- *    identity). Every host element inside a component definition carries that
- *    instance's stamp, so counting stamped objects would report a component as
- *    rendering ~50 times instead of once.
- *  - `representatives` — the FIRST live object that resolved to each oid: the
- *    occurrence that keeps the bare address, and the one every `…#n`
- *    occurrence's write authority is decided against.
- */
-export interface SourceOidIdentity extends ThreeIdentity {
-  readonly instanceRoots: ReadonlyMap<string, number>;
-  readonly representatives: ReadonlyMap<string, THREE.Object3D>;
-}
-
-export function sourceOidIdentity(worldId: string): SourceOidIdentity {
-  let instanceRoots: ReadonlyMap<string, number> = new Map();
-  let representatives: ReadonlyMap<string, THREE.Object3D> = new Map();
-  return {
-    get instanceRoots() {
-      return instanceRoots;
-    },
-    get representatives() {
-      return representatives;
-    },
-    project: (scene) => {
-      const oidOccurrence = new Map<string, number>();
-      const roots = new Map<string, number>();
-      const reps = new Map<string, THREE.Object3D>();
-      /** Authoring identities of the objects ON the current DFS path. */
-      const ancestorIdentities = new Set<string>();
-      const openedBy = new Map<THREE.Object3D, string>();
-      const projection = walkThreeGraph(scene, {
-        identify: (object, context) => {
-          const oid = authoringOidOf(object);
-          if (oid === undefined) return threeEntityId(worldId, `@${context.path.join('.')}`);
-          const n = oidOccurrence.get(oid) ?? 0;
-          oidOccurrence.set(oid, n + 1);
-          if (n === 0) reps.set(oid, object);
-          if (!ancestorIdentities.has(oid)) {
-            roots.set(oid, (roots.get(oid) ?? 0) + 1);
-            ancestorIdentities.add(oid);
-            openedBy.set(object, oid);
-          }
-          return occurrenceId(threeEntityId(worldId, oid), n);
-        },
-        leave: (object) => {
-          const opened = openedBy.get(object);
-          if (opened === undefined) return;
-          ancestorIdentities.delete(opened);
-          openedBy.delete(object);
-        },
-      });
-      instanceRoots = roots;
-      representatives = reps;
-      return projection;
-    },
-  };
-}
-
 /**
  * The DOCUMENT-PATH identity, for a native Object3D graph opened as a document
  * (a loaded model, a project source graph): document-scoped structural ids over
@@ -580,10 +230,7 @@ export function nativeKindOf(object: THREE.Object3D): EditorNode['kind'] {
   if ((object as THREE.Bone).isBone) return 'bone';
   if ((object as THREE.Light).isLight) return 'light';
   if ((object as THREE.Camera).isCamera) return 'camera';
-  // Three tags its audio nodes only through `type` — there is no `isAudio`
-  // flag to read like the lines above, and an `Audio`/`AudioListener` carries
-  // no geometry, so without this it fell through to the generic `object`
-  // circle and a world's sound was the one thing the hierarchy could not name.
+  // Audio nodes expose their kind through type rather than an isAudio flag or geometry.
   if (
     object.type === 'Audio' ||
     object.type === 'PositionalAudio' ||
@@ -886,13 +533,13 @@ export class ThreeProjector {
   private pickProjection():
     | {
         objects: Iterable<THREE.Object3D>;
-        idForObject3D: (object: THREE.Object3D) => string | null;
+        idForNativeObject: (object: THREE.Object3D) => string | null;
       }
     | undefined {
     if (this.options.pickScope === 'store-object-map') return undefined;
     return {
       objects: this.objectsById.values(),
-      idForObject3D: (object) => this.idOf(object),
+      idForNativeObject: (object) => this.idOf(object),
     };
   }
 }

package/src/kit/retained-document-states.ts

@@ -0,0 +1,91 @@
+interface DisposableSource {
+  dispose(): void;
+}
+
+export interface RetainedDocumentState {
+  readonly documentId: string;
+  inUse: boolean;
+  source: DisposableSource | null;
+}
+
+/** CPU state belongs to an open document, not to the lifetime of its last pane. */
+export class RetainedDocumentStates<T extends RetainedDocumentState> {
+  private readonly states = new Map<string, T[]>();
+  private readonly generations = new WeakMap<T, number>();
+  private unsubscribe: (() => void) | null = null;
+
+  constructor(
+    private readonly create: (documentId: string) => T,
+    private readonly isOpen: (documentId: string) => boolean,
+    private readonly subscribe: (changed: () => void) => () => void,
+  ) {}
+
+  claim(documentId: string): T {
+    const states = this.states.get(documentId) ?? [];
+    let state = states.find(candidate => !candidate.inUse);
+    if (!state) {
+      state = this.create(documentId);
+      states.push(state);
+      this.states.set(documentId, states);
+    }
+    state.inUse = true;
+    this.generations.set(state, this.generation(state) + 1);
+    this.unsubscribe ??= this.subscribe(() => this.discardClosed());
+    return state;
+  }
+
+  generation(state: T): number {
+    return this.generations.get(state) ?? 0;
+  }
+
+  release(state: T, generation = this.generation(state)): void {
+    if (this.generation(state) !== generation) return;
+    state.inUse = false;
+    // React cleanup may precede the registry's close notification. The
+    // subscription also handles closing a pane that was already unmounted.
+    queueMicrotask(() => this.discardClosed());
+  }
+
+  /** A gesture may finish releasing its source after its document has closed
+   * or its state slot has been claimed by a replacement pane. */
+  retain(state: T, source: NonNullable<T['source']>, generation: number): void {
+    if (
+      !this.isOpen(state.documentId) ||
+      !this.states.get(state.documentId)?.includes(state) ||
+      this.generation(state) !== generation
+    ) {
+      source.dispose();
+      return;
+    }
+    const previous = state.source;
+    state.source = source;
+    if (previous !== source) previous?.dispose();
+  }
+
+  private discardClosed(): void {
+    const discarded: T[] = [];
+    for (const [documentId, states] of this.states) {
+      if (this.isOpen(documentId)) continue;
+      const remaining = states.filter(state => state.inUse);
+      discarded.push(...states.filter(state => !state.inUse));
+      if (remaining.length) this.states.set(documentId, remaining);
+      else this.states.delete(documentId);
+    }
+    if (this.states.size === 0) {
+      this.unsubscribe?.();
+      this.unsubscribe = null;
+    }
+    // Remove ownership first, even if a disposer throws or publishes a change.
+    const failures: unknown[] = [];
+    for (const state of discarded) {
+      const source = state.source;
+      state.source = null;
+      try {
+        source?.dispose();
+      } catch (error) {
+        failures.push(error);
+      }
+    }
+    if (failures.length) throw new AggregateError(failures, 'Retained document cleanup failed');
+  }
+}

package/src/kit/scene-document-viewport.ts

@@ -1,12 +1,12 @@
 /**
- * THE SCENE'S VIEWPORT (`@volter/sdk/kit/document-viewports`): the world
+ * THE SCENE'S VIEWPORT (`@volter/sdk/document-viewports`): the world
  * stage draws the Scene through the session store's own camera, shading and
  * grid, and frames the shell's selection. It keeps no selection of its own, so a
  * view's selection is the shell's.
  */
-import type { DocumentViewport } from '@volter/sdk/kit/document-viewports';
+import type { DocumentViewport } from '@volter/sdk/document-viewports';
 import type { EditorShellStore } from './editor-shell-store';
-import { viewGridVisible } from '@volter/sdk/kit/viewport-presentation';
+import { viewGridVisible } from '@volter/sdk/viewport-presentation';
 
 type ShadingMode = Parameters<EditorShellStore['setShadingMode']>[0];