@volter/editor-threejs 0.5.211 → 0.5.213

package/src/kit/entity-lod.ts

@@ -1,24 +1,11 @@
 import type * as THREE from 'three';
-import { isEntityObject } from './entity-object';
 
-/**
- * The selected object when it is itself a live THREE.LOD (the native R3F
- * shape), otherwise the entity's live THREE.LOD preview object, or null while
- * an async asset is still loading. A subtree search skips child authoring
- * nodes so a nested LOD entity can never shadow this one's.
- *
- * Format-neutral: reads the caller's native-node membership answer and
- * Three's own `isLOD` marker, never a scene descriptor. The default retains
- * stamp-based compatibility for first-party callers. `editor-viewport.ts`'s
- * per-frame forced-LOD-level enforcement is the only caller.
- */
+/** Resolve the selected native THREE.LOD, otherwise its live preview LOD. Skip child authoring nodes and return null while its asset loads. */
 export function findEntityLod(
   obj: THREE.Object3D,
-  isNestedAuthoringNode: (object: THREE.Object3D) => boolean = isEntityObject,
+  isNestedAuthoringNode: (object: THREE.Object3D) => boolean,
 ): THREE.LOD | null {
-  // Adapter-backed worlds can expose the native LOD itself as the selected
-  // authored row (for example Drei Detailed), rather than wrapping it in the
-  // old entity preview object this helper was originally extracted for.
+  // An adapter can expose its native LOD directly as the authored row.
   if ((obj as THREE.LOD).isLOD) return obj as THREE.LOD;
   const stack = [...obj.children];
   while (stack.length > 0) {

package/src/kit/entity-object.ts

@@ -1,42 +1,4 @@
-/**
- * One answer to "which live `Object3D` is this entity id?", for every editor
- * surface that needs one.
- *
- * There are TWO places an id can resolve, and neither is a superset of the
- * other. The ACTIVE ADAPTER's `hierarchy.object3D` is authoritative: a
- * source-backed component may select one identity and render its transform on a
- * child, and an ADOPTED live scene (play mode) is walked by the adapter, so its
- * ids exist there and nowhere else. `EditorShellStore.objectMap` is the shell's
- * own map, which the adapter's answer falls back to.
- *
- * Asking only the store is how `editor.frame(id)` came to refuse an entity the
- * same session had just selected and drawn a cage around. Measured live
- * (2026-08-14, the translated platformer in play mode): `editor.status()`
- * listed `r3f:world:o4a7fjmzo`, `editor.select` on it put a bracket cage on the
- * coin — and `editor.frame` on that same id answered
- * `Entity not found: r3f:world:o4a7fjmzo`, because the adopted play scene's
- * nodes live in the adapter's walk and not in `objectMap`. A verb's EXISTENCE
- * CHECK has to be the resolver its ACTION uses, or the refusal is about a
- * different question than the one asked.
- *
- * ## The REVERSE direction lives here too, and that is the point
- *
- * `userData.entityId` is the stamp an adapter's walk writes when it ADMITS an
- * object as an authoring node (`projection/three.ts`,
- * `R3fSourceAuthoringAdapter.indexGraph`). Reading that stamp is the node → id
- * half of the very same question `entityObject3D` answers id → node, so both
- * halves are spelled once, here — and the surfaces that used to reach for
- * `getUserData(object, 'entityId')` themselves (the viewport gizmo and its
- * surface-snap, the raycast climb, the store's adoption index, the LOD walk)
- * ask this module instead.
- *
- * Presence of the stamp is also the ADMISSION answer: an object the walk
- * skipped (an editor helper, a library-built internal folded into its owner)
- * carries none, which is exactly what {@link isEntityObject} and
- * {@link nearestEntityObject} read. Do not re-derive that from a type test, a
- * name convention or a layer — those disagree with the walk, and a surface that
- * disagrees with the walk is the "one id, three answers" defect.
- */
+/** Resolve an entity through the active adapter’s nativeObject, then the shell’s object map. Share the authoring walk’s ownership rules across editor surfaces. */
 
 import type { AuthoringAdapter } from '@volter/project/adapter';
 import { getUserData, setUserData } from '@volter/editor-threejs/ecs/user-data';

package/src/kit/hierarchy-mark-reader.ts

@@ -3,50 +3,37 @@
  *
  * `hierarchy-component-marks.ts` is deliberately pure — it takes a
  * {@link NodeMarkReader} and never learns what a node is made of — and
- * `GameHierarchy` is deliberately contract-only (rule zero: no 3D-library value
+ * `Hierarchy` is deliberately contract-only (rule zero: no 3D-library value
  * import). This module is the seam between them: it asks the adapter's OPTIONAL
- * `object3D` capability for the node and reads
- * `@volter/editor-threejs/adapter/hierarchy-marks`' two marks off it.
+ * `nativeObject` capability for the node and reads its component off it.
  *
  * An adapter with no `Object3D` seam (React, Pixi, DOM) yields {@link NO_MARKS},
  * which `componentMarkView` recognizes by identity and short-circuits on — so a
  * non-three surface pays nothing and renders byte-identically.
  */
 
+import type * as THREE from 'three';
 import type { HierarchyProvider } from '@volter/project/adapter';
-import { componentRootName, isBuiltInternal } from '@volter/editor-threejs/adapter/hierarchy-marks';
 import { getUserData } from '@volter/editor-threejs/ecs/user-data';
 import { isComponentInstanceRoot } from './authoring/component-instance-root';
-import { NO_MARKS, type NodeMarkReader, type NodeMarks } from '@volter/sdk/kit/hierarchy-component-marks';
+import { NO_MARKS, type NodeMarkReader, type NodeMarks } from '@volter/sdk/hierarchy-component-marks';
 import { threeObject } from '../adapter/three-contract';
 
 /** Project-local R3F source already carries its component ownership on the
- * native node. Read that existing stamp as the automatic equivalent of an
- * imperative `markComponentRoot`; explicit marks still win. */
-function componentName(object: Parameters<typeof componentRootName>[0]): string | undefined {
-  const explicit = componentRootName(object);
+ * native node; that stamp is the component mark. */
+function componentName(object: THREE.Object3D): string | undefined {
   // Some project-local components are the native authoring ENTITY constructor rather than a
   // reusable component boundary. Importers are the canonical case: `<UnityNode>` creates the
   // GameObject itself, while a generated `<Player>` prefab remains a component instance around
   // that node. `authoringRoot` is the existing generic declaration for exactly that distinction.
-  // An explicit component mark still wins, so a prefab root can be both its own authoring object
-  // and the boundary of the reusable prefab instance. A built-internal mark suppresses only the
-  // automatic component classification: a React helper that renders implementation machinery is
-  // still implementation, not a prefab merely because Fiber recorded its component boundary.
-  if (
-    explicit ||
-    isBuiltInternal(object) ||
-    getUserData(object, 'authoringRoot') === true ||
-    !isComponentInstanceRoot(object)
-  ) {
-    return explicit;
+  if (getUserData(object, 'authoringRoot') === true || !isComponentInstanceRoot(object)) {
+    return undefined;
   }
   const authored = getUserData(object, 'authoringComponent');
   return typeof authored === 'string' && authored ? authored : undefined;
 }
-
 /**
- * A memoized reader over `hierarchy.object3D`.
+ * A memoized reader over `hierarchy.nativeObject`.
  *
  * The cache lives for the reader's lifetime — one render pass — because the
  * live graph it reads is re-walked every render anyway (`hierarchy.roots()` IS
@@ -54,19 +41,15 @@ function componentName(object: Parameters<typeof componentRootName>[0]): string
  * and the walk asks for the same id many times: once per `node()` projection,
  * again per internals probe.
  */
-export function markReaderFor(hierarchy: Pick<HierarchyProvider, 'object3D'>): NodeMarkReader {
-  const object3D = hierarchy.object3D;
-  if (typeof object3D !== 'function') return NO_MARKS;
+export function markReaderFor(hierarchy: Pick<HierarchyProvider, 'nativeObject'>): NodeMarkReader {
+  const nativeObject = hierarchy.nativeObject;
+  if (typeof nativeObject !== 'function') return NO_MARKS;
   const cache = new Map<string, NodeMarks | undefined>();
   return (id) => {
     if (cache.has(id)) return cache.get(id);
     const object = threeObject(hierarchy, id);
     const marks: NodeMarks | undefined = object
-      ? {
-          componentRoot: componentName(object),
-          authoredEntity: getUserData(object, 'authoringRoot') === true,
-          builtInternal: isBuiltInternal(object),
-        }
+      ? { componentRoot: componentName(object) }
       : undefined;
     cache.set(id, marks);
     return marks;

package/src/kit/instanced-presentation.ts

@@ -1,50 +1,4 @@
-/**
- * What an `InstancedMesh` IS to a reader looking at it — derived by measuring
- * the live object, never by guessing what the game meant.
- *
- * ## The two questions, and why the second one exists
- *
- * 1. **How many units does this row draw?** Every other count in the editor is
- *    keyed on OBJECTS, and an `InstancedMesh` is one object drawing N units, so
- *    a hierarchy row reports 1 where a reader sees 200 — both numbers correct,
- *    no error anywhere. `ThreeWalkStats.instances`
- *    (`projection/three.ts`) is the world-level half of the same
- *    shortfall; this is the per-node half.
- *
- * 2. **Is this a WORLD-ANCHORED instanced system?** The measured case
- *    (2026-08-16, the vendored racing-game): `Dust` and `Skid` write per-unit
- *    matrices in WORLD coordinates — `wheels[2].current.getWorldPosition(v)` →
- *    `setItemAt` — while the `instancedMesh` container sits at identity at the
- *    world origin, deliberately, because a skid mark must stay where it was laid
- *    (`vendor/games/racing-game/src/models/vehicle/Vehicle.tsx` renders both
- *    OUTSIDE `<Chassis>` for exactly that reason). Selecting one put the
- *    selection cage and the gizmo on (0,0,0) while every unit the reader can see
- *    is out at the car — measured live: focusing `Dust` flew the camera inside
- *    the canyon to two bracket marks at the origin, which reads as a broken
- *    editor rather than as a correctly-drawn trail system.
- *
- * The class is the native-engine vocabulary (Unity calls it simulation space).
- * We do not read the game's intent to find it: the SIGNATURE is measurable and
- * three.js forces it — to write world coordinates into instance matrices the
- * container's own world matrix MUST be identity, so "identity container, content
- * elsewhere" is the pattern's fingerprint and not an inference about it.
- *
- * ## What "elsewhere" is measured against, and why it is not a threshold
- *
- * The reference volume is the container's OWN drawn geometry, sitting at its own
- * origin. That is the only intrinsic scale an instanced draw has, and it makes
- * the test tuning-free: content whose centre still falls inside the shape the
- * container itself draws is content the pivot is already on top of, and nothing
- * about that reads as broken.
- *
- * It also makes the answer honest at REST, which matters more than it looks.
- * `new InstancedMesh(geometry, material, count)` seeds every unit to IDENTITY
- * (three r180 `InstancedMesh.js` — the constructor's `setMatrixAt(i, _identity)`
- * loop), so a system that has placed nothing yet genuinely draws `count` copies
- * stacked on the container's origin. There is no world-space anchoring to see
- * there, and the class correctly does not fire until the game has actually put
- * content somewhere else.
- */
+/** Report an InstancedMesh’s drawn unit count and whether its content is anchored in world space, using the live object’s instance matrices and bounds. */
 
 import * as THREE from 'three';
 

package/src/kit/live-gesture-lock.ts

@@ -0,0 +1,35 @@
+/** Hold absorb-by-remount swaps until continuous viewport gestures finish. The viewport sets the lock; the design session waits through whenLiveGestureIdle. */
+
+let active = 0;
+let waiters: Array<() => void> = [];
+
+export function beginLiveGesture(): void {
+  active += 1;
+}
+
+export function endLiveGesture(): void {
+  active = Math.max(0, active - 1);
+  if (active === 0) {
+    const resolved = waiters;
+    waiters = [];
+    for (const resolve of resolved) resolve();
+  }
+}
+
+/** Whether any gesture (a drag, or a gesture's still-landing write) holds
+ *  the lock right now — the swap's settle loop re-checks this after each
+ *  wait, because a lock taken in the same task that released the previous
+ *  one can race a waiter that already resolved. */
+export function liveGestureActive(): boolean {
+  return active > 0;
+}
+
+/** Resolves immediately when no gesture is running, else on the current
+ *  gesture's end. */
+export function whenLiveGestureIdle(): Promise<void> {
+  return active === 0
+    ? Promise.resolve()
+    : new Promise((resolve) => {
+        waiters.push(resolve);
+      });
+}

package/src/kit/live-module-source.ts

@@ -1,31 +1,11 @@
 /**
- * The module→`Object3D` step, IN THE BROWSER — the live twin of the bake
- * lane's Node-side `module-source.ts`
- * (`catalog/project-source/editor/tools/module-source.ts`), and deliberately the
- * SAME contract: a project TypeScript module whose export builds a native
- * `THREE.Object3D`. `project.bake.module` / `project.bake.preview` /
- * the editor's `screenshot <module>` command already define that contract; the live modeling
- * document opens the same thing, so a module that bakes opens, and a module
- * that opens bakes (docs/BLENDER-PARITY.md §The model file).
- *
- * TWO HALVES, ONE CONTRACT. Node imports a `file://` url and has no GPU; the
- * browser imports the dev server's `/@fs/` url and IS the GPU. Nothing else
- * differs, which is why this file re-states the resolution rather than
- * importing the tool's copy: that copy is `host: 'node'` capability source
- * (`node:fs/promises`, `node:url`) that a project's own tsconfig excludes from
- * its browser build. Sharing the module would drag Node into the editor
- * bundle; sharing the CONTRACT is what matters, and the contract is small
- * enough to be stated twice and obviously identical.
- *
- * DETECTION IS STRUCTURAL, not a filename convention — the quarks precedent
- * (`components/asset-viewers/JsonAssetDocument.tsx`: three.quarks names no
- * extension of its own, so the file's own structure is what says whether it is
- * a particle document). There is no `.model.ts`: a project `.ts`/`.tsx`
- * whose export RESOLVES to an `Object3D` is a model module, and everything
- * else falls back to the ordinary source viewer.
+ * Resolve a project module's export to a native THREE.Object3D in the browser. Import the module
+ * through the session's /@fs/ URL and use its default export, or its single named export. A builder
+ * may be asynchronous and return an Object3D or a result with root and optional animations/disposal.
+ * Detection is structural; modules with other exports use the ordinary source viewer.
  */
 
-import { liveModuleImportUrl } from '@volter/sdk/session/project-module-url';
+import { liveModuleImportUrl } from '@volter/sdk/project-module-url';
 import type * as THREE from 'three';
 
 /** Why this module is not a live model module — the sentence the document
@@ -71,13 +51,8 @@ function isObject3D(value: unknown): value is THREE.Object3D {
   );
 }
 
-/**
- * Pick the export this module offers as its subject, matching the bake lane's
- * `exportName` default: the DEFAULT export, or — when there is no default —
- * the single named export. Two named exports and no default is ambiguous and
- * refuses by name rather than guessing; the bake verbs make the caller say
- * which one, and a document has nobody to ask.
- */
+/** Choose the default export, or the single named export. Multiple named exports without a
+ * default refuse as ambiguous rather than guessing which subject the document should build. */
 export function pickLiveModuleExport(
   namespace: Record<string, unknown>,
 ): { readonly name: string; readonly value: unknown } | LiveModuleRefusal {
@@ -99,20 +74,9 @@ export function pickLiveModuleExport(
 }
 
 /**
- * THE TWO SHAPES A MODEL MODULE MAY PRODUCE — the same pair the Node twin
- * normalizes (`catalog/project-source/editor/tools/module-source.ts`'s
- * `asModuleBuild`), because a module that bakes must open and a module that
- * opens must bake:
- *
- * 1. a bare `THREE.Object3D`;
- * 2. a BUILD RESULT `{ root, animations?, dispose? }` — what every parametric
- *    lib in the kit returns (`createBird`'s `BirdBuild` and its descendants),
- *    and what `bakeObject3DSource`'s `build` callback has always taken.
- *
- * `animations` is written onto `root.animations`, three's own carrier for a
- * model's clips — so the clip list travels with the graph the document mounts
- * and every reader downstream (the Object3D document session, its animation
- * transport) finds it where it finds a GLTF's.
+ * Accept a bare Object3D or `{ root, animations?, dispose? }`. Supplied animations fill an empty
+ * root.animations list so clips travel with the graph the document and its transport inspect.
+ * A supplied disposer replaces generic graph disposal.
  */
 function asLiveModuleBuild(
   built: unknown,
@@ -150,12 +114,8 @@ const ACCEPTED_SHAPES =
   'a model module returns a THREE.Object3D, or a build result ' +
   '`{ root, animations?, dispose? }` whose `root` is one.';
 
-/**
- * Resolve a picked export to an `Object3D`. A FUNCTION is called (its result
- * may be a promise — the bake lane awaits it too); a VALUE is taken as-is, so
- * `export default new THREE.Group()` is as legitimate a model module as
- * `export default () => …`.
- */
+/** Resolve a picked export to an Object3D: accept its value directly, or call a builder and
+ * await its result. Both `export default new THREE.Group()` and a builder are supported. */
 export async function resolveLiveModuleExport(
   name: string,
   value: unknown,

package/src/kit/model-thumbnail.ts

@@ -12,7 +12,7 @@
  * - Self-cleaning: each loaded object is disposed after the thumbnail is captured.
  */
 
-import { registerAssetThumbnailRenderer } from '@volter/sdk/kit/asset-thumbnails';
+import { registerAssetThumbnailRenderer } from '@volter/sdk/asset-thumbnails';
 import type { SparkRenderer, SplatMesh } from '@sparkjsdev/spark';
 import { markHostRenderer } from '@volter/editor-threejs/viewport/renderer-ownership';
 import { loadSplat } from '@volter/editor-threejs/asset-loaders';
@@ -44,7 +44,6 @@ export type ModelThumbnailFormat =
 export interface ModelThumbnailSpec {
   url: string;
   format?: ModelThumbnailFormat;
-  materialUrl?: string;
   background?: 'transparent' | 'neutral';
   output?: 'png' | 'webp';
 }
@@ -344,7 +343,7 @@ export async function loadModelThumbnailObject(
     }
     case 'obj': {
       const { OBJLoader } = await import('three/addons/loaders/OBJLoader.js');
-      const materialUrl = spec.materialUrl ?? (await discoverObjMaterial(spec.url));
+      const materialUrl = await discoverObjMaterial(spec.url);
       const loader = new OBJLoader();
       if (materialUrl) {
         const { MTLLoader } = await import('three/addons/loaders/MTLLoader.js');
@@ -357,6 +356,8 @@ export async function loadModelThumbnailObject(
     case 'dae': {
       const { ColladaLoader } = await import('three/addons/loaders/ColladaLoader.js');
       const collada = await new ColladaLoader().loadAsync(spec.url);
+      // The loader answers null for a file that is not a COLLADA document (stated in r186's types).
+      if (!collada) throw new Error(`${spec.url} is not a COLLADA document`);
       const animations = (collada as unknown as { animations?: THREE.AnimationClip[] }).animations;
       if (animations) collada.scene.animations = [...animations];
       return collada.scene;
@@ -481,35 +482,6 @@ async function discoverObjMaterial(url: string): Promise<string | undefined> {
   }
 }
 
-/** Normalize an upstream/source preview image through the same thumbnail canvas. */
-export async function renderImageThumbnail(
-  url: string,
-  options: { output?: 'png' | 'webp'; background?: 'transparent' | 'neutral' } = {},
-): Promise<string> {
-  const image = await new Promise<HTMLImageElement>((resolve, reject) => {
-    const element = new Image();
-    element.onload = () => resolve(element);
-    element.onerror = () => reject(new Error(`Failed to load preview image: ${url}`));
-    element.src = url;
-  });
-  const canvas = document.createElement('canvas');
-  canvas.width = SIZE;
-  canvas.height = SIZE;
-  const context = canvas.getContext('2d');
-  if (!context) throw new Error('2D thumbnail canvas is unavailable.');
-  if (options.background === 'neutral') {
-    context.fillStyle = '#20242a';
-    context.fillRect(0, 0, SIZE, SIZE);
-  }
-  const scale = Math.min(SIZE / image.naturalWidth, SIZE / image.naturalHeight);
-  const width = image.naturalWidth * scale;
-  const height = image.naturalHeight * scale;
-  context.drawImage(image, (SIZE - width) / 2, (SIZE - height) / 2, width, height);
-  return options.output === 'webp'
-    ? canvas.toDataURL('image/webp', 0.86)
-    : canvas.toDataURL('image/png');
-}
-
 /** Get (or create) the shared thumbnail renderer. */
 export function getModelThumbnailRenderer(): ModelThumbnailRenderer {
   if (!instance) instance = new ModelThumbnailRenderer();
@@ -518,13 +490,13 @@ export function getModelThumbnailRenderer(): ModelThumbnailRenderer {
 
 // A Fast Refresh invalidation creates a fresh module singleton. Release the
 // previous module's offscreen WebGL context first instead of silently leaking
-// one context per AssetBrowser edit.
+// one context per edit.
 if (import.meta.hot) {
   import.meta.hot.dispose(() => instance?.dispose());
 }
 
-/** This renderer, as the asset browser's thumbnail for every model format it
- *  loads (`@volter/sdk/kit/asset-thumbnails`). */
+/** This renderer, as the asset thumbnail for every model format it loads
+ *  (`@volter/sdk/asset-thumbnails`). */
 export function registerModelThumbnails(): () => void {
   return registerAssetThumbnailRenderer({
     accepts: (url) => modelThumbnailFormat(url) !== undefined,

package/src/kit/play-camera-flight.ts

@@ -1,13 +1,13 @@
 /**
  * THE PLAY ENTRY CAMERA FLIGHT — the Three integration's half of Play's immersive entry
- * (`@volter/sdk/kit/play-camera-flight`). The kit's transition owns the phases and the
+ * (`@volter/sdk/play-camera-flight`). The kit's transition owns the phases and the
  * chrome; this owns the camera: the editor viewport flies along a Catmull-Rom spline from its
  * preview pose to the AUTHORED game camera's pose, retargets to the game's live camera once it
  * boots so the cross-fade is pixel-continuous, and restores the preview pose when Play ends. The
  * flight reads the authored viewport's rig through the viewport door and rides its frame hook, so
  * flight pacing rides the editor's own frame clock.
  */
-import { registerPlayCameraFlight, type LiveCameraLookup } from '@volter/sdk/kit/play-camera-flight';
+import { registerPlayCameraFlight, type LiveCameraLookup } from '@volter/sdk/play-camera-flight';
 import { onViewportFrame, viewportRig } from '../viewport-door';
 import * as THREE from 'three';
 import { threeStoreForHost } from './three-state';
@@ -105,17 +105,8 @@ function targetFromObject(
 }
 
 /**
- * Find the authored game camera in the CURRENT (pre-play) editor scene.
- *
- * A world's source IS its document, so there is no descriptor to read a
- * declared camera out of: the design session adopts the mounted fiber scene
- * into the store, which makes the authored camera (e.g. drei
- * `<PerspectiveCamera makeDefault>`) a live `THREE.Camera` in the mapped
- * object graphs. Take the first one outside editor-only (layer-31) and gizmo
- * branches, at its live world transform.
- *
- * `null` when no camera is found — play then keeps today's behavior (game
- * starts at the preview pose, no flight).
+ * Find the authored camera in the current editor scene outside editor-only and gizmo branches, and
+ * return its live world transform. Return null when the mapped object graph contains no camera.
  */
 export function resolveAuthoredCameraTarget(
   store: PlayCameraSourceStore,
@@ -152,8 +143,8 @@ interface ActiveFlight {
   readonly runtime: FlightRuntime;
   readonly snapshot: { position: THREE.Vector3; target: THREE.Vector3; up: THREE.Vector3; fov: number };
   readonly onLanded: () => void;
-  /** Live game camera, registered at game-ready — the flight retargets to it
-   *  each frame so the hand-off converges on whatever the game actually does
+  /** Live camera, registered at live-ready — the flight retargets to it
+   *  each frame so the hand-off converges on whatever the project actually does
    *  with its camera during boot (follow rigs, SceneCamera components…). */
   getLiveCamera: LiveCameraLookup | null;
   /** Driving the camera: from `begin` until the game is on screen (`settle`) or Play ends. */
@@ -197,7 +188,7 @@ function begin(onLanded: () => void): boolean {
 }
 
 /** After the flight, leave OrbitControls in a sane state at the landed pose
- *  so a `set-viewport-tab scene` during play still orbits correctly. */
+ *  so the viewport still orbits correctly during play. */
 function settle(): void {
   const viewport = viewportRig();
   const active = _flight;