@volter/editor-threejs 0.5.65 → 0.5.67

package/src/kit/entity-lod.ts

@@ -0,0 +1,31 @@
+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.
+ */
+export function findEntityLod(
+  obj: THREE.Object3D,
+  isNestedAuthoringNode: (object: THREE.Object3D) => boolean = isEntityObject,
+): 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.
+  if ((obj as THREE.LOD).isLOD) return obj as THREE.LOD;
+  const stack = [...obj.children];
+  while (stack.length > 0) {
+    const node = stack.pop()!;
+    if (isNestedAuthoringNode(node)) continue; // nested entity subtree
+    if ((node as THREE.LOD).isLOD) return node as THREE.LOD;
+    stack.push(...node.children);
+  }
+  return null;
+}

package/src/kit/entity-object.ts

@@ -0,0 +1,92 @@
+/**
+ * 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.
+ */
+
+import type { AuthoringAdapter } from '@volter/editor-project/adapter';
+import { getUserData, setUserData } from '@volter/editor-threejs/ecs/user-data';
+import type * as THREE from 'three';
+import { threeObject } from '../adapter/three-contract';
+
+/** The live object `id` names, or `null` when nothing in this session answers to it. */
+export function entityObject3D(
+  adapter: AuthoringAdapter,
+  objectMap: ReadonlyMap<string, THREE.Object3D>,
+  id: string,
+): THREE.Object3D | null {
+  return threeObject(adapter.hierarchy, id) ?? objectMap.get(id) ?? null;
+}
+
+/**
+ * The id `object` answers to, or `undefined` when no adapter walk has admitted
+ * it as an authoring node.
+ */
+export function entityIdOf(object: THREE.Object3D | null | undefined): string | undefined {
+  const id = getUserData(object, 'entityId');
+  return typeof id === 'string' && id ? id : undefined;
+}
+
+/** Whether `object` is an admitted authoring node — see {@link entityIdOf}. */
+export function isEntityObject(object: THREE.Object3D | null | undefined): boolean {
+  return entityIdOf(object) !== undefined;
+}
+
+/**
+ * The nearest ancestor-or-self of `object` that is an admitted authoring node,
+ * or `null` when the climb reaches the top without finding one.
+ *
+ * This is what a raycast hit has to do: the ray lands on whatever geometry is
+ * in front, which is routinely a library-built part folded INTO a node rather
+ * than the node itself.
+ */
+export function nearestEntityObject(
+  object: THREE.Object3D | null | undefined,
+): THREE.Object3D | null {
+  let cursor: THREE.Object3D | null = object ?? null;
+  while (cursor && !isEntityObject(cursor)) cursor = cursor.parent;
+  return cursor;
+}
+
+/**
+ * Record that `object` is the authoring node `id` — called by the adapter walk
+ * that MINTED the id, and by nothing else. Every reader above is the other side
+ * of this one write.
+ */
+export function stampEntityId(object: THREE.Object3D, id: string): void {
+  setUserData(object, 'entityId', id);
+}

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

@@ -0,0 +1,74 @@
+/**
+ * The one place the hierarchy panel's mark convention meets a real `Object3D`.
+ *
+ * `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
+ * 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.
+ *
+ * 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 { HierarchyProvider } from '@volter/editor-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/editor-sdk/kit/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);
+  // 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;
+  }
+  const authored = getUserData(object, 'authoringComponent');
+  return typeof authored === 'string' && authored ? authored : undefined;
+}
+
+/**
+ * A memoized reader over `hierarchy.object3D`.
+ *
+ * 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
+ * the refresh point on a live adapter). Within one pass the marks cannot move,
+ * 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;
+  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),
+        }
+      : undefined;
+    cache.set(id, marks);
+    return marks;
+  };
+}

package/src/kit/instanced-presentation.ts

@@ -0,0 +1,164 @@
+/**
+ * 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.
+ */
+
+import * as THREE from 'three';
+
+/**
+ * Element-wise slack against the identity matrix. Generous enough to survive
+ * the float round-trip of a `Matrix4` composed from an untouched
+ * position/quaternion/scale, tight enough that any authored placement — a
+ * millimetre offset included — fails it.
+ */
+const IDENTITY_EPSILON = 1e-4;
+
+/** The world-anchored class's ONE sentence, shown verbatim wherever it appears. */
+export const WORLD_ANCHORED_INSTANCED_NOTE =
+  'World-anchored — content is placed in world space by the game each frame; moving this container offsets future placements away from their source.';
+
+/** Everything both surfaces need about one node's instancing, or `null` when the
+ *  node is not an instanced draw at all. */
+export interface InstancedPresentation {
+  /** `InstancedMesh.count` — the units this one object draws. Always ≥ 1. */
+  readonly units: number;
+  /** The hierarchy row's dim detail: `200 instanced units`. */
+  readonly detail: string;
+  /** True for the class described in the module header. */
+  readonly worldAnchored: boolean;
+  /** {@link WORLD_ANCHORED_INSTANCED_NOTE} when {@link worldAnchored}, else `null`. */
+  readonly note: string | null;
+}
+
+/**
+ * `InstancedMesh.count`, or 0 for anything that is not one.
+ *
+ * `count` is the DRAWN range, not the allocated capacity, which is the number a
+ * reader is looking at. A count of 0 is not an instanced draw for presentation
+ * purposes — there is nothing to annotate — so it answers 0 like a plain mesh.
+ */
+export function instancedUnitCount(object: THREE.Object3D | null | undefined): number {
+  if (!object) return 0;
+  const instanced = object as THREE.Object3D & { isInstancedMesh?: boolean; count?: number };
+  if (instanced.isInstancedMesh !== true) return 0;
+  const count = instanced.count;
+  return typeof count === 'number' && count > 0 ? count : 0;
+}
+
+/** Is `matrix` the identity matrix, within {@link IDENTITY_EPSILON}? */
+export function isNearIdentityMatrix(matrix: THREE.Matrix4): boolean {
+  const e = matrix.elements;
+  for (let i = 0; i < 16; i++) {
+    const expected = i % 5 === 0 ? 1 : 0;
+    const value = e[i]!;
+    if (!Number.isFinite(value) || Math.abs(value - expected) > IDENTITY_EPSILON) return false;
+  }
+  return true;
+}
+
+/** Scratch for the reference volume below — this module is synchronous and
+ *  single-threaded, so one instance serves every call. */
+const pivotVolume = new THREE.Box3();
+const contentCentre = new THREE.Vector3();
+
+/**
+ * The whole presentation verdict for one live node.
+ *
+ * `contentBounds` is the node's measured world-space content (`content-bounds.ts`
+ * — `contentWorldBounds`, which resolves instance matrices live rather than
+ * through three's cached object box). It is passed IN rather than measured here
+ * so this module stays a pure predicate: a caller that has the walk already does
+ * not pay for a second one, and a test can state the geometry directly.
+ */
+export function describeInstancedPresentation(
+  object: THREE.Object3D | null | undefined,
+  contentBounds: THREE.Box3 | null | undefined,
+): InstancedPresentation | null {
+  const units = instancedUnitCount(object);
+  if (units === 0) return null;
+  const worldAnchored = isWorldAnchored(object as THREE.InstancedMesh, contentBounds);
+  return {
+    units,
+    detail: unitsLabel(units),
+    worldAnchored,
+    note: worldAnchored ? WORLD_ANCHORED_INSTANCED_NOTE : null,
+  };
+}
+
+function isWorldAnchored(
+  mesh: THREE.InstancedMesh,
+  contentBounds: THREE.Box3 | null | undefined,
+): boolean {
+  if (!contentBounds || contentBounds.isEmpty()) return false;
+  if (!isNearIdentityMatrix(mesh.matrixWorld)) return false;
+  const geometry = mesh.geometry;
+  if (geometry.boundingBox === null) geometry.computeBoundingBox();
+  if (!geometry.boundingBox) return false;
+  // The container's own drawn shape, at its own (identity) origin — see the
+  // header. A degenerate box still works: a flat plane's centre test is the
+  // in-plane one, which is the right question for a decal system.
+  pivotVolume.copy(geometry.boundingBox);
+  contentBounds.getCenter(contentCentre);
+  return !pivotVolume.containsPoint(contentCentre);
+}
+
+/**
+ * The hierarchy row's detail for `id`, or `null` — the whole of what a row needs.
+ *
+ * Rows are rendered for every visible node on every notify, so this is
+ * deliberately the CHEAP half: a type check and a number read, with no bounds
+ * walk. The world-anchored class costs a walk and is therefore an
+ * inspector-only fact, on the one node the reader has actually selected.
+ */
+export function instancedRowDetail(object: THREE.Object3D | null | undefined): string | null {
+  const units = instancedUnitCount(object);
+  return units === 0 ? null : unitsLabel(units);
+}
+
+/** The ONE wording, so the row and the inspector cannot drift apart. */
+function unitsLabel(units: number): string {
+  return `${units} instanced unit${units === 1 ? '' : 's'}`;
+}

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

@@ -0,0 +1,230 @@
+/**
+ * The module→`Object3D` step, IN THE BROWSER — the live twin of the bake
+ * lane's Node-side `module-source.ts`
+ * (`catalog/project-source/src/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` /
+ * `vgai screenshot <module>` 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.
+ */
+
+import { liveModuleImportUrl } from '@volter/editor-sdk/session/project-module-url';
+import type * as THREE from 'three';
+
+/** Why this module is not a live model module — the sentence the document
+ *  shows, and the reason it fell back to the source viewer. */
+export type LiveModuleRefusal =
+  /** Nothing importable at all: a syntax error, a throwing top level, a
+   *  missing dependency. The one refusal that is USUALLY a defect in a module
+   *  that WAS a model module a moment ago, which is why the document keeps its
+   *  last good root on screen for it. */
+  | { readonly kind: 'import-failed'; readonly message: string; readonly stack?: string }
+  /** It imported fine, it is simply not a model module. */
+  | { readonly kind: 'not-a-model'; readonly message: string };
+
+export interface LiveModuleBuild {
+  readonly root: THREE.Object3D;
+  /** Which export produced it — `default`, or the single named export. */
+  readonly exportName: string;
+  /** The BUILDER's own teardown, when the export returned a build result that
+   *  carried one. The document runs it in place of the generic graph dispose:
+   *  a rig holds mixers, actions and materials a `traverse` walk cannot see. */
+  readonly dispose?: () => void;
+}
+
+export class LiveModuleError extends Error {
+  constructor(readonly refusal: LiveModuleRefusal) {
+    super(refusal.message);
+    this.name = 'LiveModuleError';
+  }
+}
+
+/** The module-namespace keys that are never a candidate export. */
+function candidateExportNames(namespace: Record<string, unknown>): string[] {
+  return Object.keys(namespace).filter(
+    (name) => name !== '__esModule' && name !== 'Symbol.toStringTag',
+  );
+}
+
+function isObject3D(value: unknown): value is THREE.Object3D {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as { isObject3D?: unknown }).isObject3D === true
+  );
+}
+
+/**
+ * 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.
+ */
+export function pickLiveModuleExport(
+  namespace: Record<string, unknown>,
+): { readonly name: string; readonly value: unknown } | LiveModuleRefusal {
+  if ('default' in namespace) return { name: 'default', value: namespace['default'] };
+  const named = candidateExportNames(namespace);
+  if (named.length === 0) {
+    return { kind: 'not-a-model', message: 'This module exports nothing.' };
+  }
+  if (named.length > 1) {
+    return {
+      kind: 'not-a-model',
+      message:
+        `This module has no default export and ${named.length} named exports ` +
+        `(${named.join(', ')}), so there is no single subject to build. A model module ` +
+        'default-exports its builder.',
+    };
+  }
+  return { name: named[0]!, value: namespace[named[0]!] };
+}
+
+/**
+ * THE TWO SHAPES A MODEL MODULE MAY PRODUCE — the same pair the Node twin
+ * normalizes (`catalog/project-source/src/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.
+ */
+function asLiveModuleBuild(
+  built: unknown,
+): { root: THREE.Object3D; dispose?: () => void } | undefined {
+  if (isObject3D(built)) return { root: built };
+  if (!built || typeof built !== 'object') return undefined;
+  const result = built as { root?: unknown; animations?: unknown; dispose?: unknown };
+  if (!isObject3D(result.root)) return undefined;
+  const root = result.root;
+  if (Array.isArray(result.animations) && root.animations.length === 0) {
+    root.animations = result.animations as THREE.AnimationClip[];
+  }
+  return {
+    root,
+    ...(typeof result.dispose === 'function'
+      ? { dispose: () => (result.dispose as () => void).call(built) }
+      : {}),
+  };
+}
+
+/** What the export returned, for a refusal that can be acted on — `object`
+ *  alone cannot tell a build result with a mistyped key from a wrong value. */
+function describeReturn(built: unknown): string {
+  if (built === undefined) return 'undefined';
+  if (built === null) return 'null';
+  if (typeof built !== 'object') return typeof built;
+  if (Array.isArray(built)) return 'an array';
+  const keys = Object.keys(built);
+  return keys.length > 0
+    ? `an object with keys ${keys.slice(0, 8).join(', ')}`
+    : 'an object with no own keys';
+}
+
+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 () => …`.
+ */
+export async function resolveLiveModuleExport(
+  name: string,
+  value: unknown,
+): Promise<LiveModuleBuild | LiveModuleRefusal> {
+  const direct = asLiveModuleBuild(value);
+  if (direct) return { ...direct, exportName: name };
+  if (typeof value !== 'function') {
+    return {
+      kind: 'not-a-model',
+      message:
+        `Export '${name}' is ${describeReturn(value)}, not a function and not a model — ` +
+        ACCEPTED_SHAPES,
+    };
+  }
+  let built: unknown;
+  try {
+    built = await (value as () => unknown)();
+  } catch (error) {
+    return {
+      kind: 'import-failed',
+      message: `Export '${name}' threw while building: ${messageOf(error)}`,
+      ...(error instanceof Error && error.stack ? { stack: error.stack } : {}),
+    };
+  }
+  const build = asLiveModuleBuild(built);
+  if (!build) {
+    return {
+      kind: 'not-a-model',
+      message: `Export '${name}' ran but returned ${describeReturn(built)} — ${ACCEPTED_SHAPES}`,
+    };
+  }
+  return { ...build, exportName: name };
+}
+
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Import `modulePath` from the dev server and build its `Object3D`.
+ *
+ * `revision` is the document's rebuild counter — see
+ * {@link liveModuleImportUrl} for why the url carries it and why that is only
+ * half the freshness story.
+ *
+ * Throws {@link LiveModuleError}; the `refusal.kind` is what the caller routes
+ * on (`not-a-model` falls back to the source viewer, `import-failed` keeps the
+ * last good root and shows the failure).
+ */
+export async function buildLiveModuleObject3D(
+  projectRoot: string,
+  modulePath: string,
+  revision: number,
+): Promise<LiveModuleBuild> {
+  let namespace: Record<string, unknown>;
+  try {
+    namespace = (await import(
+      /* @vite-ignore */ liveModuleImportUrl(projectRoot, modulePath, revision)
+    )) as Record<string, unknown>;
+  } catch (error) {
+    throw new LiveModuleError({
+      kind: 'import-failed',
+      message: messageOf(error),
+      ...(error instanceof Error && error.stack ? { stack: error.stack } : {}),
+    });
+  }
+  const picked = pickLiveModuleExport(namespace);
+  if ('kind' in picked) throw new LiveModuleError(picked);
+  const resolved = await resolveLiveModuleExport(picked.name, picked.value);
+  if ('kind' in resolved) throw new LiveModuleError(resolved);
+  return resolved;
+}