@volter/editor-threejs 0.5.64 → 0.5.66

package/NOTICE

@@ -2,6 +2,8 @@ Copyright 2026 Volter AI, Inc.
 
 Modules under src/viewport and src/capture were imported from the
 AGPL-3.0-only @vgai/threejs package; LICENSE contains that license.
+serving/model-import-conversion.ts was imported from the AGPL-3.0-only
+@vgai/editor package's server and retains that license.
 
 Modules under src/adapter, src/animation, src/ecs and src/render, together
 with src/asset-loaders.ts, src/asset-parse-error.ts and src/loader.ts, were

package/contributions/animation-mixers.service.ts

@@ -0,0 +1,20 @@
+/**
+ * The animation stamp's status facet (`@volter/editor-sdk/services`, a `workspace.service`
+ * contribution): `vgai status` reports the mixers the running world's own code made, with the
+ * clips it has played through each and the objects each animates, so "the timeline found
+ * nothing" is answerable from the session.
+ */
+import { editorHost } from '@volter/editor-sdk/host';
+import { liveMixers } from '../src/animation/live-mixers';
+
+export const point = 'workspace.service';
+
+export function start(): () => void {
+  return editorHost().session.reportFacet(() => ({
+    liveMixers: liveMixers().map((entry) => ({
+      site: entry.key,
+      clips: [...entry.clips.keys()],
+      animates: [...entry.roots].map((root) => (root as { name?: string }).name || '(unnamed)'),
+    })),
+  }));
+}

package/dist-node/serving.mjs

@@ -0,0 +1,405 @@
+// serving/animation-stamp.ts
+import { relative, sep } from "node:path";
+import ts from "typescript";
+
+// serving/animation-live-module.ts
+var ANIMATION_LIVE_MODULE_ID = "virtual:vgai-three-animation-live";
+var 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;
+}
+`;
+
+// serving/animation-stamp.ts
+var VIRTUAL_ID = `\0${ANIMATION_LIVE_MODULE_ID}`;
+var NODE_MODULES = /[\\/]node_modules[\\/]/;
+var SCRIPT = /\.[cm]?[jt]sx?$/;
+function isMixerConstruction(node) {
+  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) {
+  return ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "useAnimations";
+}
+function stampAnimation(code, file, relativeFile) {
+  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 = [];
+  const visit = (node) => {
+    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)};
+${out}`;
+}
+function animationStampPlugin(services) {
+  let serverRoot = process.cwd();
+  const isProjectFile = (file) => {
+    if (NODE_MODULES.test(file) || !SCRIPT.test(file)) return false;
+    const roots = [...services.projectRoots(), services.currentProjectRoot()].filter((root) => !!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 };
+    }
+  };
+}
+
+// serving/model-import-conversion.ts
+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";
+var threeModelConverter = {
+  formats: ["fbx", "obj", "dae", "stl", "ply", "3ds"],
+  convert: (primaryPath, format, settings) => convertStagedModelToGlb(primaryPath, format, settings)
+};
+async function convertStagedModelToGlb(primaryPath, format, settings) {
+  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((resolve, reject) => {
+      new GLTFExporter().parse(
+        object,
+        (output2) => output2 instanceof ArrayBuffer ? resolve(output2) : 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);
+  }
+}
+var materialTextureSlots = [
+  "map",
+  "alphaMap",
+  "aoMap",
+  "bumpMap",
+  "displacementMap",
+  "emissiveMap",
+  "envMap",
+  "lightMap",
+  "metalnessMap",
+  "normalMap",
+  "roughnessMap",
+  "specularMap"
+];
+function applyModelImportSettings(object, settings) {
+  object.scale.multiplyScalar(settings.scale * sourceUnitScale(settings.sourceUnits));
+  object.quaternion.premultiply(importAxisRotation(settings.upAxis, settings.forwardAxis));
+  const discardedTextures = /* @__PURE__ */ new Set();
+  object.traverse((node) => {
+    const mesh = node;
+    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;
+      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) {
+  return { auto: 1, mm: 1e-3, cm: 0.01, m: 1, in: 0.0254, ft: 0.3048 }[units];
+}
+function importAxisRotation(upAxis, forwardAxis) {
+  const up = upAxis === "auto" ? null : axisVector(upAxis);
+  const forward = forwardAxis === "auto" ? null : axisVector(forwardAxis);
+  if (up && forward) {
+    if (Math.abs(up.dot(forward)) > 1e-3)
+      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) {
+  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, format, bytes) {
+  const resourcePath = `${dirname(primaryPath)}/`;
+  switch (format) {
+    case "fbx":
+      return new FBXLoader().parse(bytes.buffer, 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 {
+      }
+      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);
+      return new THREE.Mesh(
+        geometry,
+        new THREE.MeshStandardMaterial({ color: 9418202, roughness: 0.75 })
+      );
+    }
+    case "ply": {
+      const geometry = new PLYLoader().parse(bytes.buffer);
+      if (!geometry.hasAttribute("normal")) geometry.computeVertexNormals();
+      return new THREE.Mesh(
+        geometry,
+        new THREE.MeshStandardMaterial({
+          color: geometry.hasAttribute("color") ? 16777215 : 12112027,
+          vertexColors: geometry.hasAttribute("color"),
+          roughness: 0.8,
+          side: THREE.DoubleSide
+        })
+      );
+    }
+    case "3ds":
+      return new TDSLoader().parse(bytes.buffer, resourcePath);
+    default:
+      throw new Error(`Built-in conversion does not support ${format || extname(primaryPath)}.`);
+  }
+}
+function installNodeDom() {
+  if (typeof document !== "undefined" && typeof DOMParser !== "undefined") return;
+  const { JSDOM } = createRequire(import.meta.url)("jsdom");
+  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) {
+  root.traverse((object) => {
+    const mesh = object;
+    const materials = Array.isArray(mesh.material) ? mesh.material : mesh.material ? [mesh.material] : [];
+    for (const material of materials) {
+      const textured = material;
+      for (const slot of materialTextureSlots) {
+        const value = textured[slot];
+        if (!(value instanceof THREE.Texture)) continue;
+        const image = value.image;
+        if (image && (image.width ?? 0) > 0 && (image.height ?? 0) > 0) continue;
+        textured[slot] = null;
+        value.dispose();
+      }
+      material.needsUpdate = true;
+    }
+  });
+}
+async function validateConvertedGlb(bytes) {
+  const parsed = await new GLTFLoader().parseAsync(Uint8Array.from(bytes).buffer, "");
+  let renderable = false;
+  parsed.scene.traverse((object) => {
+    renderable ||= Boolean(object.isMesh || object.isPoints);
+  });
+  disposeObject(parsed.scene);
+  if (!renderable && parsed.animations.length === 0) {
+    throw new Error("Converted GLB contains neither renderable geometry nor animation clips.");
+  }
+}
+function installNodeFileReader() {
+  if (typeof FileReader !== "undefined") return;
+  class NodeFileReader {
+    result = null;
+    error = null;
+    onloadend = null;
+    onerror = null;
+    readAsArrayBuffer(blob) {
+      void blob.arrayBuffer().then(
+        (result) => {
+          this.result = result;
+          this.onloadend?.({ target: this });
+        },
+        (error) => {
+          this.error = error instanceof Error ? error : new Error(String(error));
+          this.onerror?.({ target: this });
+        }
+      );
+    }
+    readAsDataURL(blob) {
+      void blob.arrayBuffer().then((result) => {
+        this.result = `data:${blob.type || "application/octet-stream"};base64,${Buffer.from(result).toString("base64")}`;
+        this.onloadend?.({ target: this });
+      });
+    }
+  }
+  Object.assign(globalThis, { FileReader: NodeFileReader });
+}
+function disposeObject(root) {
+  root.traverse((object) => {
+    const renderable = object;
+    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();
+    }
+  });
+}
+
+// serving/index.ts
+var servingPlugins = (services) => {
+  services.registerModelConverter(threeModelConverter);
+  return [animationStampPlugin(services)];
+};
+export {
+  servingPlugins
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@volter/editor-threejs",
   "author": "Volter AI, Inc.",
-  "version": "0.5.64",
+  "version": "0.5.66",
   "publishConfig": {
     "access": "public"
   },
@@ -15,12 +15,16 @@
   },
   "files": [
     "src",
+    "serving",
+    "contributions",
+    "dist-node",
     "LICENSE",
     "NOTICE",
     "LICENSE-APACHE"
   ],
   "exports": {
     "./package.json": "./package.json",
+    "./contributions/*": "./contributions/*",
     "./*": {
       "types": "./src/*.ts",
       "default": "./src/*"
@@ -29,15 +33,29 @@
     "./loader": "./src/loader.ts"
   },
   "peerDependencies": {
-    "three": "^0.180.0"
+    "three": "^0.180.0",
+    "vite": "^6.4.3"
   },
   "scripts": {
+    "build": "node scripts/build-serving.mjs",
+    "prepack": "npm run build",
     "typecheck": "tsc -p tsconfig.json"
   },
+  "vgai": {
+    "contributions": [
+      "./contributions/animation-mixers.service.ts"
+    ],
+    "serving": "./dist-node/serving.mjs"
+  },
   "dependencies": {
-    "@volter/editor-project": "0.5.64",
+    "@volter/editor-project": "0.5.66",
     "@sparkjsdev/spark": "^2.1.0",
     "three.quarks": "^0.16.0",
-    "zod": "^4.3.6"
+    "zod": "^4.3.6",
+    "typescript": "5.9.3",
+    "@volter/editor-sdk": "0.5.66"
+  },
+  "devDependencies": {
+    "esbuild": "0.25.12"
   }
 }

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)];
+};