@volter/editor-threejs 0.5.65 → 0.5.67

package/serving/animation-live-module.ts

@@ -0,0 +1,70 @@
+/**
+ * The module the animation stamp imports into a project's modules (`animation-stamp.ts`), served
+ * as source into the GAME's own graph. It imports no three: it wraps the mixer the game's own
+ * three built, so the game keeps exactly the library it installed.
+ *
+ * A stamped mixer lists itself with every clip the game plays through it (`clipAction`) and every
+ * root those actions animate, so a mixer drei's `useAnimations` makes without a root is still
+ * found by the object it moves. The registry lives on `globalThis` under a `Symbol.for` key, where
+ * the editor's bundle reads it (`src/animation/live-mixers.ts`).
+ */
+
+export const ANIMATION_LIVE_MODULE_ID = 'virtual:vgai-three-animation-live';
+
+export const animationLiveModuleSource = `
+const live = (globalThis[Symbol.for('volter.three.animation.live')] ??= {
+  mixers: new Map(),
+  listeners: new Set(),
+  version: 0,
+});
+function notify() {
+  live.version++;
+  for (const listener of live.listeners) {
+    try { listener(); } catch (error) { console.error(error); }
+  }
+}
+export function __vgaiMixer(mixer, key) {
+  if (!mixer || typeof mixer.clipAction !== 'function') return mixer;
+  if (mixer.__vgaiMixerKey) return mixer;
+  Object.defineProperty(mixer, '__vgaiMixerKey', { value: key });
+  const entry = { key, mixer, clips: new Map(), roots: new Set() };
+  live.mixers.set(mixer, entry);
+  const clipAction = mixer.clipAction;
+  mixer.clipAction = function (clip, root, blendMode) {
+    const action = clipAction.call(this, clip, root, blendMode);
+    if (action) {
+      const played = action.getClip();
+      const target = action.getRoot();
+      let changed = false;
+      if (played && !entry.clips.has(played.name)) { entry.clips.set(played.name, played); changed = true; }
+      if (target && !entry.roots.has(target)) { entry.roots.add(target); changed = true; }
+      if (changed) notify();
+    }
+    return action;
+  };
+  const uncacheRoot = mixer.uncacheRoot;
+  mixer.uncacheRoot = function (root) {
+    const result = uncacheRoot.call(this, root);
+    entry.roots.delete(root);
+    if (root === this.getRoot()) live.mixers.delete(this);
+    notify();
+    return result;
+  };
+  notify();
+  return mixer;
+}
+/** drei's \`useAnimations\` result: its mixer, and the clips it was handed. */
+export function __vgaiAnimations(result, key) {
+  if (!result || !result.mixer) return result;
+  __vgaiMixer(result.mixer, key);
+  const entry = live.mixers.get(result.mixer);
+  if (entry && Array.isArray(result.clips)) {
+    let changed = false;
+    for (const clip of result.clips) {
+      if (clip && clip.name && !entry.clips.has(clip.name)) { entry.clips.set(clip.name, clip); changed = true; }
+    }
+    if (changed) notify();
+  }
+  return result;
+}
+`;

package/serving/animation-stamp.ts

@@ -0,0 +1,88 @@
+/**
+ * `@volter/editor-threejs`'s server half: the ANIMATION STAMP over the project's served modules.
+ *
+ * THE GAME REGISTERS NOTHING (ARCHITECTURE.md rule 4). A module animates with three's own API
+ * (`new THREE.AnimationMixer(model)`, `mixer.clipAction(clip).play()`) or drei's
+ * (`useAnimations(animations, ref)`); in the editor's served graph only, each of those call sites
+ * is wrapped so the mixer it makes reports itself (`animation-live-module.ts`). The editor's
+ * animation instruments drive the mixer the game made instead of minting a second writer over
+ * the same skeleton. A standalone build never passes through this plugin.
+ */
+
+import { relative, sep } from 'node:path';
+import ts from 'typescript';
+import type { Plugin } from 'vite';
+import { ANIMATION_LIVE_MODULE_ID, animationLiveModuleSource } from './animation-live-module';
+
+/** The kit services this plugin reads (`@volter/editor-sdk/session/project-serving`), by shape. */
+export interface AnimationServingServices {
+  readonly projectRoots: () => ReadonlySet<string>;
+  readonly currentProjectRoot: () => string | undefined;
+}
+
+const VIRTUAL_ID = `\0${ANIMATION_LIVE_MODULE_ID}`;
+const NODE_MODULES = /[\\/]node_modules[\\/]/;
+const SCRIPT = /\.[cm]?[jt]sx?$/;
+
+function isMixerConstruction(node: ts.Node): node is ts.NewExpression {
+  if (!ts.isNewExpression(node)) return false;
+  const callee = node.expression;
+  if (ts.isIdentifier(callee)) return callee.text === 'AnimationMixer';
+  return ts.isPropertyAccessExpression(callee) && callee.name.text === 'AnimationMixer';
+}
+
+function isUseAnimations(node: ts.Node): node is ts.CallExpression {
+  return ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === 'useAnimations';
+}
+
+/** Wrap every mixer a module makes; `null` when it makes none. */
+export function stampAnimation(code: string, file: string, relativeFile: string): string | null {
+  if (!code.includes('AnimationMixer') && !code.includes('useAnimations')) return null;
+  const kind = file.endsWith('.tsx') ? ts.ScriptKind.TSX : file.endsWith('.jsx') ? ts.ScriptKind.JSX : ts.ScriptKind.TS;
+  const source = ts.createSourceFile(file, code, ts.ScriptTarget.Latest, true, kind);
+  const sites: { start: number; end: number; wrapper: '__vgaiMixer' | '__vgaiAnimations' }[] = [];
+  const visit = (node: ts.Node): void => {
+    if (isMixerConstruction(node)) sites.push({ start: node.getStart(source), end: node.getEnd(), wrapper: '__vgaiMixer' });
+    else if (isUseAnimations(node)) sites.push({ start: node.getStart(source), end: node.getEnd(), wrapper: '__vgaiAnimations' });
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  if (sites.length === 0) return null;
+  let out = code;
+  for (const site of [...sites].sort((a, b) => b.start - a.start)) {
+    const { line, character } = source.getLineAndCharacterOfPosition(site.start);
+    const key = `${relativeFile}:${line + 1}:${character + 1}`;
+    out = `${out.slice(0, site.start)}${site.wrapper}(${out.slice(site.start, site.end)}, ${JSON.stringify(key)})${out.slice(site.end)}`;
+  }
+  return `import { __vgaiMixer, __vgaiAnimations } from ${JSON.stringify(ANIMATION_LIVE_MODULE_ID)};\n${out}`;
+}
+
+export function animationStampPlugin(services: AnimationServingServices): Plugin {
+  let serverRoot = process.cwd();
+  const isProjectFile = (file: string): boolean => {
+    if (NODE_MODULES.test(file) || !SCRIPT.test(file)) return false;
+    const roots = [...services.projectRoots(), services.currentProjectRoot()].filter((root): root is string => !!root);
+    return roots.some((root) => file.startsWith(root + sep) || file.startsWith(root + '/'));
+  };
+  return {
+    name: 'vgai-three-animation',
+    enforce: 'pre',
+    resolveId(id) {
+      return id === ANIMATION_LIVE_MODULE_ID ? VIRTUAL_ID : null;
+    },
+    load(id) {
+      return id === VIRTUAL_ID ? animationLiveModuleSource : null;
+    },
+    configureServer(server) {
+      serverRoot = server.config.root;
+    },
+    transform(code, id) {
+      if (id.startsWith('\0')) return null;
+      const file = id.split('?')[0] ?? id;
+      if (!isProjectFile(file)) return null;
+      const root = services.currentProjectRoot() ?? serverRoot;
+      const stamped = stampAnimation(code, file, relative(root, file).split(sep).join('/'));
+      return stamped === null ? null : { code: stamped, map: null };
+    },
+  };
+}

package/serving/index.ts

@@ -0,0 +1,14 @@
+/**
+ * `@volter/editor-threejs`'s server half (`package.json#vgai.serving`): the animation stamp that
+ * lets the editor drive the mixers a project's own code makes, and the conversion of source model
+ * formats to runtime GLB for the asset library's imports.
+ */
+
+import type { ProjectServingServices } from '@volter/editor-sdk/session/project-serving';
+import { animationStampPlugin } from './animation-stamp';
+import { threeModelConverter } from './model-import-conversion';
+
+export const servingPlugins = (services: ProjectServingServices): readonly unknown[] => {
+  services.registerModelConverter(threeModelConverter);
+  return [animationStampPlugin(services)];
+};

package/serving/model-import-conversion.ts

@@ -0,0 +1,344 @@
+/// <reference lib="dom" />
+
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, extname } from 'node:path';
+import * as THREE from 'three';
+import { GLTFExporter } from 'three/addons/exporters/GLTFExporter.js';
+import { ColladaLoader } from 'three/addons/loaders/ColladaLoader.js';
+import { FBXLoader } from 'three/addons/loaders/FBXLoader.js';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { MTLLoader } from 'three/addons/loaders/MTLLoader.js';
+import { OBJLoader } from 'three/addons/loaders/OBJLoader.js';
+import { PLYLoader } from 'three/addons/loaders/PLYLoader.js';
+import { STLLoader } from 'three/addons/loaders/STLLoader.js';
+import { TDSLoader } from 'three/addons/loaders/TDSLoader.js';
+import { mergeVertices } from 'three/addons/utils/BufferGeometryUtils.js';
+import type { ModelConverter, ModelImportSettings } from '@volter/editor-sdk/session/project-serving';
+
+/** three.js's conversion of the source formats its loaders read, as the asset library's
+ *  model converter (`ProjectServingServices.registerModelConverter`). */
+export const threeModelConverter: ModelConverter = {
+  formats: ['fbx', 'obj', 'dae', 'stl', 'ply', '3ds'],
+  convert: (primaryPath, format, settings) => convertStagedModelToGlb(primaryPath, format, settings),
+};
+
+/** Convert a staged source model to a runtime GLB without requiring Blender. */
+export async function convertStagedModelToGlb(
+  primaryPath: string,
+  format: string,
+  settings: ModelImportSettings,
+): Promise<Uint8Array> {
+  installNodeDom();
+  const bytes = new Uint8Array(await readFile(primaryPath));
+  const object = await parseSourceModel(primaryPath, format.toLowerCase(), bytes);
+  discardUnloadedTextures(object);
+  applyModelImportSettings(object, settings);
+  installNodeFileReader();
+  try {
+    const result = await new Promise<ArrayBuffer>((resolve, reject) => {
+      new GLTFExporter().parse(
+        object,
+        (output) =>
+          output instanceof ArrayBuffer
+            ? resolve(output)
+            : reject(new Error('Model conversion produced JSON instead of binary GLB.')),
+        reject,
+        { binary: true, animations: object.animations, onlyVisible: false },
+      );
+    });
+    const output = new Uint8Array(result);
+    await validateConvertedGlb(output);
+    return output;
+  } finally {
+    disposeObject(object);
+  }
+}
+
+const materialTextureSlots = [
+  'map',
+  'alphaMap',
+  'aoMap',
+  'bumpMap',
+  'displacementMap',
+  'emissiveMap',
+  'envMap',
+  'lightMap',
+  'metalnessMap',
+  'normalMap',
+  'roughnessMap',
+  'specularMap',
+] as const;
+
+/** Apply the persisted conversion settings before the runtime GLB is exported. */
+export function applyModelImportSettings(
+  object: THREE.Object3D,
+  settings: ModelImportSettings,
+): void {
+  object.scale.multiplyScalar(settings.scale * sourceUnitScale(settings.sourceUnits));
+  object.quaternion.premultiply(importAxisRotation(settings.upAxis, settings.forwardAxis));
+
+  const discardedTextures = new Set<THREE.Texture>();
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one traversal deliberately applies the persisted mesh, material, texture, normal, tangent, and optimization settings to each converted renderable.
+  object.traverse((node) => {
+    const mesh = node as THREE.Mesh;
+    if (!mesh.geometry) return;
+    let geometry = mesh.geometry;
+    if (settings.meshOptimization !== 'none') {
+      const optimized = mergeVertices(
+        geometry,
+        settings.meshOptimization === 'aggressive' ? 1e-3 : 1e-6,
+      );
+      if (optimized !== geometry) {
+        mesh.geometry = optimized;
+        geometry.dispose();
+        geometry = optimized;
+      }
+    }
+    if (settings.normals !== 'preserve') {
+      geometry.deleteAttribute('normal');
+      geometry.computeVertexNormals();
+    }
+    if (settings.tangents === 'discard') geometry.deleteAttribute('tangent');
+    if (
+      settings.tangents === 'generate' &&
+      geometry.index &&
+      geometry.hasAttribute('position') &&
+      geometry.hasAttribute('normal') &&
+      geometry.hasAttribute('uv')
+    ) {
+      geometry.computeTangents();
+    }
+    geometry.computeBoundingBox();
+    geometry.computeBoundingSphere();
+
+    const priorMaterials = Array.isArray(mesh.material)
+      ? mesh.material
+      : mesh.material
+        ? [mesh.material]
+        : [];
+    if (settings.materials === 'discard') {
+      mesh.material = Array.isArray(mesh.material)
+        ? priorMaterials.map(() => new THREE.MeshStandardMaterial())
+        : new THREE.MeshStandardMaterial();
+      for (const material of priorMaterials) material.dispose();
+      return;
+    }
+    if (settings.textures !== 'discard') return;
+    for (const material of priorMaterials) {
+      const textured = material as THREE.Material & Record<string, unknown>;
+      for (const slot of materialTextureSlots) {
+        const texture = textured[slot];
+        if (texture instanceof THREE.Texture) discardedTextures.add(texture);
+        textured[slot] = null;
+      }
+      material.needsUpdate = true;
+    }
+  });
+  for (const texture of discardedTextures) texture.dispose();
+
+  if (settings.animations.length > 0) {
+    const requested = new Set(settings.animations);
+    const selected = object.animations.filter((clip) => requested.has(clip.name));
+    const missing = settings.animations.filter(
+      (name) => !selected.some((clip) => clip.name === name),
+    );
+    if (missing.length > 0) throw new Error(`Animation clips not found: ${missing.join(', ')}.`);
+    object.animations = selected;
+  }
+  object.updateWorldMatrix(true, true);
+}
+
+function sourceUnitScale(units: ModelImportSettings['sourceUnits']): number {
+  return { auto: 1, mm: 0.001, cm: 0.01, m: 1, in: 0.0254, ft: 0.3048 }[units];
+}
+
+function importAxisRotation(
+  upAxis: ModelImportSettings['upAxis'],
+  forwardAxis: ModelImportSettings['forwardAxis'],
+): THREE.Quaternion {
+  const up = upAxis === 'auto' ? null : axisVector(upAxis);
+  const forward = forwardAxis === 'auto' ? null : axisVector(forwardAxis);
+  if (up && forward) {
+    if (Math.abs(up.dot(forward)) > 0.001)
+      throw new Error('Import up and forward axes must be perpendicular.');
+    const right = new THREE.Vector3().crossVectors(forward, up).normalize();
+    const correctedForward = new THREE.Vector3().crossVectors(up, right).normalize();
+    const sourceBasis = new THREE.Matrix4().makeBasis(right, up, correctedForward.clone().negate());
+    return new THREE.Quaternion().setFromRotationMatrix(sourceBasis.invert());
+  }
+  if (up) return new THREE.Quaternion().setFromUnitVectors(up, new THREE.Vector3(0, 1, 0));
+  if (forward)
+    return new THREE.Quaternion().setFromUnitVectors(forward, new THREE.Vector3(0, 0, -1));
+  return new THREE.Quaternion();
+}
+
+function axisVector(axis: Exclude<ModelImportSettings['forwardAxis'], 'auto'> | 'x' | 'y' | 'z') {
+  const sign = axis.startsWith('-') ? -1 : 1;
+  const name = axis.replace('-', '');
+  return new THREE.Vector3(
+    name === 'x' ? sign : 0,
+    name === 'y' ? sign : 0,
+    name === 'z' ? sign : 0,
+  );
+}
+
+async function parseSourceModel(
+  primaryPath: string,
+  format: string,
+  bytes: Uint8Array,
+): Promise<THREE.Object3D> {
+  const resourcePath = `${dirname(primaryPath)}/`;
+  switch (format) {
+    case 'fbx':
+      return new FBXLoader().parse(bytes.buffer as ArrayBuffer, resourcePath);
+    case 'obj': {
+      const loader = new OBJLoader();
+      const materialPath = primaryPath.replace(/\.obj$/i, '.mtl');
+      try {
+        const materials = new MTLLoader().parse(await readFile(materialPath, 'utf8'), resourcePath);
+        materials.preload();
+        loader.setMaterials(materials);
+      } catch {
+        // Geometry-only OBJ conversion remains valid when no MTL is present.
+      }
+      return loader.parse(new TextDecoder().decode(bytes));
+    }
+    case 'dae': {
+      return new ColladaLoader().parse(new TextDecoder().decode(bytes), resourcePath).scene;
+    }
+    case 'stl': {
+      const geometry = new STLLoader().parse(bytes.buffer as ArrayBuffer);
+      return new THREE.Mesh(
+        geometry,
+        new THREE.MeshStandardMaterial({ color: 0x8fb5da, roughness: 0.75 }),
+      );
+    }
+    case 'ply': {
+      const geometry = new PLYLoader().parse(bytes.buffer as ArrayBuffer);
+      if (!geometry.hasAttribute('normal')) geometry.computeVertexNormals();
+      return new THREE.Mesh(
+        geometry,
+        new THREE.MeshStandardMaterial({
+          color: geometry.hasAttribute('color') ? 0xffffff : 0xb8d09b,
+          vertexColors: geometry.hasAttribute('color'),
+          roughness: 0.8,
+          side: THREE.DoubleSide,
+        }),
+      );
+    }
+    case '3ds':
+      return new TDSLoader().parse(bytes.buffer as ArrayBuffer, resourcePath);
+    default:
+      throw new Error(`Built-in conversion does not support ${format || extname(primaryPath)}.`);
+  }
+}
+
+/** Three's source loaders construct browser image elements even when the
+ * conversion runs in Node. JSDOM supplies that parser boundary; unresolved
+ * asynchronous images are removed below rather than passed to GLTFExporter
+ * as invalid zero-sized image objects. */
+function installNodeDom(): void {
+  if (typeof document !== 'undefined' && typeof DOMParser !== 'undefined') return;
+  const { JSDOM } = createRequire(import.meta.url)('jsdom') as {
+    JSDOM: new () => {
+      window: {
+        document: Document;
+        DOMParser: typeof DOMParser;
+        HTMLImageElement: typeof HTMLImageElement;
+        HTMLCanvasElement: typeof HTMLCanvasElement;
+        Image: typeof Image;
+      };
+    };
+  };
+  const window = new JSDOM().window;
+  Object.assign(globalThis, {
+    document: window.document,
+    DOMParser: window.DOMParser,
+    HTMLImageElement: window.HTMLImageElement,
+    HTMLCanvasElement: window.HTMLCanvasElement,
+    Image: window.Image,
+  });
+}
+
+function discardUnloadedTextures(root: THREE.Object3D): void {
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one bounded traversal removes only unresolved image slots across every supported material shape.
+  root.traverse((object) => {
+    const mesh = object as THREE.Mesh;
+    const materials = Array.isArray(mesh.material)
+      ? mesh.material
+      : mesh.material
+        ? [mesh.material]
+        : [];
+    for (const material of materials) {
+      const textured = material as THREE.Material & Record<string, unknown>;
+      for (const slot of materialTextureSlots) {
+        const value = textured[slot];
+        if (!(value instanceof THREE.Texture)) continue;
+        const image = value.image as { width?: number; height?: number } | null;
+        if (image && (image.width ?? 0) > 0 && (image.height ?? 0) > 0) continue;
+        textured[slot] = null;
+        value.dispose();
+      }
+      material.needsUpdate = true;
+    }
+  });
+}
+
+async function validateConvertedGlb(bytes: Uint8Array): Promise<void> {
+  const parsed = await new GLTFLoader().parseAsync(Uint8Array.from(bytes).buffer, '');
+  let renderable = false;
+  parsed.scene.traverse((object) => {
+    renderable ||= Boolean((object as THREE.Mesh).isMesh || (object as THREE.Points).isPoints);
+  });
+  disposeObject(parsed.scene);
+  if (!renderable && parsed.animations.length === 0) {
+    throw new Error('Converted GLB contains neither renderable geometry nor animation clips.');
+  }
+}
+
+function installNodeFileReader(): void {
+  if (typeof FileReader !== 'undefined') return;
+  class NodeFileReader {
+    result: string | ArrayBuffer | null = null;
+    error: Error | null = null;
+    onloadend: ((event: ProgressEvent<FileReader>) => void) | null = null;
+    onerror: ((event: ProgressEvent<FileReader>) => void) | null = null;
+    readAsArrayBuffer(blob: Blob): void {
+      void blob.arrayBuffer().then(
+        (result) => {
+          this.result = result;
+          this.onloadend?.({ target: this } as unknown as ProgressEvent<FileReader>);
+        },
+        (error) => {
+          this.error = error instanceof Error ? error : new Error(String(error));
+          this.onerror?.({ target: this } as unknown as ProgressEvent<FileReader>);
+        },
+      );
+    }
+    readAsDataURL(blob: Blob): void {
+      void blob.arrayBuffer().then((result) => {
+        this.result = `data:${blob.type || 'application/octet-stream'};base64,${Buffer.from(result).toString('base64')}`;
+        this.onloadend?.({ target: this } as unknown as ProgressEvent<FileReader>);
+      });
+    }
+  }
+  Object.assign(globalThis, { FileReader: NodeFileReader });
+}
+
+function disposeObject(root: THREE.Object3D): void {
+  root.traverse((object) => {
+    const renderable = object as THREE.Mesh;
+    renderable.geometry?.dispose();
+    const materials = Array.isArray(renderable.material)
+      ? renderable.material
+      : renderable.material
+        ? [renderable.material]
+        : [];
+    for (const material of materials) {
+      for (const value of Object.values(material))
+        if (value instanceof THREE.Texture) value.dispose();
+      material.dispose();
+    }
+  });
+}

package/src/adapter/ingest/scene-capture.ts

@@ -53,6 +53,7 @@
  * (`docs/f13-bloom-composer-proof/record-fixed.mjs`).
  */
 
+import type { WorldAdoptionEvent } from '@volter/editor-sdk/kit/world-adoption-event';
 import type * as THREE from 'three';
 import {
   type CaptureWaitOptions,
@@ -144,29 +145,6 @@ export interface SceneCaptureOptions {
   onWorldAdoption?: (event: WorldAdoptionEvent) => void;
 }
 
-/**
- * One world-adoption fact. `adopted` fires exactly once, when the trap commits
- * to a (scene, camera, renderer) triple; `alternate` fires for each DISTINCT
- * triple seen afterwards, up to {@link MAX_RECORDED_ALTERNATES}.
- */
-export type WorldAdoptionEvent =
-  | {
-      readonly phase: 'adopted';
-      /** `declared` = the contract named this scene; `measured` = first render won. */
-      readonly source: 'declared' | 'measured';
-      readonly sceneId: string;
-      readonly cameraId: string;
-    }
-  | {
-      readonly phase: 'alternate';
-      readonly sceneId: string;
-      readonly cameraId: string;
-      /** `false` ⇒ a SECOND renderer is drawing, which is the stronger signal. */
-      readonly sameRenderer: boolean;
-      /** Draws observed when this alternate first appeared — how far past the
-       *  adoption it is, without a wall clock. */
-      readonly drawCount: number;
-    };
 
 /**
  * How many distinct alternates are recorded before the trap stops looking.

package/src/adapter/renderer-config.ts

@@ -4,9 +4,8 @@
  * The SHAPE is the project contract's (`@volter/editor-project/adapter/renderer-config`,
  * whose header states the rule and the three load-bearing properties); this
  * file is what writes it onto a live `WebGLRenderer` and hands back the
- * restore. `world3d-react/r3f-root-factory.tsx` is the declarer,
- * `runtime/create-runtime.ts` the host, the editor's world-root stage the
- * applier.
+ * restore. A mounted three root declares it (`MountedThreeRoot.rendererConfig`)
+ * and the editor's world-root stage applies it.
  */
 
 import type {
@@ -28,7 +27,7 @@ export type {
  * Apply `config` to `renderer`, returning the restore function that puts back what was there.
  *
  * `three` is passed in rather than imported for values so the enum constants come from the HOST's
- * three instance — the same identity rule `r3f-root-factory.tsx` follows for the scene and camera.
+ * three instance — the same identity rule `r3f-root.tsx` follows for the scene and camera.
  */
 export function applyWorldRendererConfig(
   three: typeof THREE,

package/src/adapter/three-contract.ts

@@ -0,0 +1,72 @@
+/**
+ * The Three-typed half of the adapter contract. `@volter/editor-project`
+ * states the `three` surface with its medium objects opaque (a scene, a
+ * camera, a renderer, a hierarchy's scene objects, navigation's debug mesh);
+ * this module names them as three.js objects for the editor side that renders
+ * and authors them. A `three`-surface adapter hands exactly these objects, so
+ * each view below is a narrowing of what the contract already carries, not a
+ * conversion.
+ */
+
+import type {
+  AuthoringAdapter,
+  HierarchyProvider,
+  MountedThreeRoot,
+  NavigationAdapter,
+  PhysicsAdapter,
+  ThreeHostContext,
+} from '@volter/editor-project/adapter';
+import type { NavBakeParams } from '@volter/editor-project/adapter/system-adapter';
+import type * as THREE from 'three';
+
+/** Shared GLTF/texture cache a `three` host hands its roots. */
+export interface ThreeAssetCache {
+  /** Load an asset by URL. Returns a cached promise if already loading/loaded. */
+  load<T = unknown>(url: string): Promise<T>;
+  /** Get a previously-loaded asset synchronously. Throws if not yet loaded. */
+  get<T = unknown>(url: string): T;
+}
+
+/** What a `three`-surface root is handed, Three-typed. */
+export type ThreeRootHostContext = ThreeHostContext<typeof THREE, THREE.WebGLRenderer, ThreeAssetCache>;
+
+/** A live, mounted Three world, Three-typed. */
+export type ThreeMountedRoot = MountedThreeRoot<THREE.Scene, THREE.Camera>;
+
+/** A mounted `three` root, as the Three objects it hands. */
+export function threeRoot(mounted: MountedThreeRoot): ThreeMountedRoot {
+  return mounted as ThreeMountedRoot;
+}
+
+/** The hierarchy's scene-object doors, Three-typed. */
+export interface ThreeHierarchy {
+  object3D?(id: string): THREE.Object3D | null;
+  idForObject3D?(o: THREE.Object3D): string | null;
+}
+
+/** A `three`-surface authoring adapter's hierarchy, as the Three objects it hands. */
+export function threeHierarchy(adapter: Pick<AuthoringAdapter, 'hierarchy'>): HierarchyProvider & ThreeHierarchy {
+  return adapter.hierarchy as HierarchyProvider & ThreeHierarchy;
+}
+
+/** The live Three object a `three`-surface hierarchy hands for `id` (null
+ * when it has none, or omits the door). */
+export function threeObject(hierarchy: Pick<HierarchyProvider, 'object3D'>, id: string): THREE.Object3D | null {
+  return (hierarchy.object3D?.(id) ?? null) as THREE.Object3D | null;
+}
+
+/** A `three`-surface navigation adapter, as the Three objects it trades in. */
+export interface ThreeNavigationAdapter extends NavigationAdapter {
+  debugMesh(scene: THREE.Scene): THREE.Object3D | null;
+  bake?(meshes: THREE.Mesh[], params?: NavBakeParams): boolean;
+  clear?(scene: THREE.Scene): void;
+}
+
+export function threeNavigation(adapter: NavigationAdapter): ThreeNavigationAdapter {
+  return adapter as ThreeNavigationAdapter;
+}
+
+/** A `three`-surface physics adapter's debug-draw object. */
+export function threePhysicsDebugDraw(adapter: PhysicsAdapter): THREE.Object3D | null {
+  return (adapter.debugDraw?.() ?? null) as THREE.Object3D | null;
+}