@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/ingest-siblings.ts

@@ -2,7 +2,7 @@
  * Composite sibling mounts — D-V2/D-V3/D-V4/D-V7
  * (docs/WAVE5-MULTIWORLD-INGEST-DESIGN.md, F24 residual), extended by D-B1/
  * D-B3 (docs/WAVE6-DOCTOR-DESIGN.md Slice B, wave-5 residual closure): when a
- * manifest declares exactly one `{ ingest }` world alongside OTHER worlds
+ * manifest declares exactly one `{ ingest }` world alongside OTHER roots
  * ("siblings"), `ingest-mode.ts`'s composite routes mount the ingest world
  * through their existing enter path and then call {@link mountIngestSiblings}
  * here to mount every OTHER world in manifest order (already z-sorted by the
@@ -20,7 +20,7 @@
  *    structurally unreachable here, D-V2 already fails the whole route
  *    before any sibling loop runs, so `resolveAllWorlds`'s one-element call
  *    below never hits its `MULTI_WORLD_ALLOWED_IDENTITIES` guard, which only
- *    applies for `worlds.length > 1`) — a SCOPED single-world runtime, D-V4:
+ *    applies for `roots.length > 1`) — a SCOPED single-world runtime, D-V4:
  *    the exact resolve+mount `module-mode.ts`'s `enterModuleModeWorldsPath`
  *    proves out, reused via `mountModuleWorldRuntime`, but with NONE of that
  *    route's global side effects (no `setActiveAuthoring`/`setActiveSystems`,
@@ -45,14 +45,14 @@
  */
 
 import type { AuthoringAdapter } from '@engine/adapter';
-import type { ResolvedGameManifest, ResolvedWorldEntry } from '@engine/manifest/load';
+import type { ResolvedAdapterRoot, ResolvedGameManifest } from '@engine/manifest/load';
 import type { Overlay2D } from '@engine/world2d/authoring-2d';
 import { createPhysics2DRegistry } from '@engine/world2d/physics2d-registry';
 import { createPhysicsAdapter2D } from '@engine/world2d/system-adapters-2d';
 import { Component, createElement, type ReactNode } from 'react';
 import { flushSync } from 'react-dom';
 import { createRoot } from 'react-dom/client';
-import { resolveReactWorldEntryComponent } from './adapter-resolver';
+import { resolveReactAdapterRootComponent } from './adapter-resolver';
 import { makeEmbedOnlyAdapter } from './authoring/embed-only-adapter';
 import { IngestAuthoringAdapter } from './authoring/ingest-authoring-adapter';
 import type { IngestOverlay } from './authoring/ingest-overlay';
@@ -62,7 +62,6 @@ import {
   type ReactDomOverlay,
 } from './authoring/react-dom-authoring-adapter';
 import { ReactWorldAuthoringAdapter, walkOidTree } from './authoring/react-world-authoring-adapter';
-import { unregisterUndoAdapter } from './authoring/undo-timeline';
 import { loadWorldOverlay, saveWorldOverlay, worldOverlayPath } from './authoring/world-overlay';
 import { World2DAuthoringAdapter } from './authoring/world2d-authoring-adapter';
 import { editorConsole } from './editor-console';
@@ -141,13 +140,13 @@ class SiblingErrorBoundary extends Component<
 /** Position/size/z-order every sibling layer shares — same absolute-fill
  *  convention `create-runtime.ts`'s own react-world DOM layer uses
  *  (`mountOneReactWorld`), so a sibling stacks exactly like a native world
- *  would have. `pointerEvents` differs per sibling kind below (module worlds
+ *  would have. `pointerEvents` differs per sibling kind below (module roots
  *  own real canvases that need real hit-testing; the react sibling's layer
  *  stays `none` by the same HUD-overlay convention `mountOneReactWorld` uses,
  *  its rendered content opts back in per-element). */
 function styleSiblingLayer(
   layer: HTMLElement,
-  world: ResolvedWorldEntry,
+  world: ResolvedAdapterRoot,
   pointerEvents: string,
 ): void {
   layer.style.position = 'absolute';
@@ -163,7 +162,7 @@ function styleSiblingLayer(
  * D-V3: mount a `default-react` sibling as a bare DOM layer — no
  * `<GameProvider>` wrap (anti-shim: there is no native `Game` to hand it).
  * Reuses `adapter-resolver.ts`'s exact entry-loading step
- * (`resolveReactWorldEntryComponent` — the same D4 `scene`-forbidden/
+ * (`resolveReactAdapterRootComponent` — the same D4 `scene`-forbidden/
  * `entry`-required checks and default-export validation
  * `resolveDefaultReactAdapter` itself uses) rather than duplicating it.
  *
@@ -176,12 +175,12 @@ function styleSiblingLayer(
  * other sibling failure — the ingest world stays mounted regardless.
  */
 async function mountDefaultReactSibling(
-  world: ResolvedWorldEntry,
+  world: ResolvedAdapterRoot,
   gameContainer: HTMLElement,
   projectRoot: string,
   store: EditorStore | undefined,
 ): Promise<SiblingMount> {
-  const Entry = await resolveReactWorldEntryComponent(world, projectRoot);
+  const Entry = await resolveReactAdapterRootComponent(world, projectRoot);
 
   const layer = document.createElement('div');
   styleSiblingLayer(layer, world, 'none');
@@ -254,15 +253,6 @@ async function mountDefaultReactSibling(
     worldId: world.id,
     ...(authoring ? { authoring } : {}),
     dispose(): void {
-      // D-M3: both branches above self-register with the global undo
-      // timeline at construction (`registerUndoAdapter`, in each adapter's
-      // own constructor) — drop it here so any of its entries still on the
-      // global stack are dropped (with a warn) rather than misapplied to a
-      // torn-down layer, mirroring every other undo-registering adapter's
-      // teardown in this codebase (`disposeReactSession`/`disposeThreejsSession`
-      // in `ingest-mode.ts`, the scene-UI child's `UIEditStore` unregister
-      // in `edit-mode-authoring.ts`'s `exitEditModeAuthoring`).
-      if (authoring) unregisterUndoAdapter(authoring);
       root.unmount();
       layer.remove();
     },
@@ -283,8 +273,8 @@ async function mountDefaultReactSibling(
  *
  * `mountModuleWorldRuntime` is kind-agnostic BY CONSTRUCTION here, not just
  * for `{ module }` adapters: it calls `resolveAllWorlds` with a ONE-element
- * `worlds` array, and `resolveAllWorlds`'s `MULTI_WORLD_ALLOWED_IDENTITIES`
- * scope guard only fires for `worlds.length > 1` — so `resolveWorldAdapter`'s
+ * `roots` array, and `resolveAllWorlds`'s `MULTI_WORLD_ALLOWED_IDENTITIES`
+ * scope guard only fires for `roots.length > 1` — so `resolveRootAdapter`'s
  * full identity switch (including `default-three`/`default-pixi`) is reached
  * directly, unmodified, with the guard never consulted (D-B3's ground-truth
  * finding; `MULTI_WORLD_ALLOWED_IDENTITIES` itself stays byte-identical).
@@ -326,7 +316,7 @@ async function mountDefaultReactSibling(
  */
 async function mountScopedRuntimeSibling(
   manifest: ResolvedGameManifest,
-  world: ResolvedWorldEntry,
+  world: ResolvedAdapterRoot,
   gameContainer: HTMLElement,
   projectRoot: string,
   store: EditorStore | undefined,
@@ -339,10 +329,10 @@ async function mountScopedRuntimeSibling(
     const w = gameContainer.clientWidth || 800;
     const h = gameContainer.clientHeight || 600;
     const { session } = await mountModuleWorldRuntime(manifest, world, projectRoot, layer, w, h);
-    // D-G1: `session.game.worlds[0]` is the SAME `WorldInstance` shape
+    // D-G1: `session.game.roots[0]` is the SAME `WorldInstance` shape
     // play-mode iterates (`kind`, `threeRoot()`, `pixiRoot()`, `physics2d`) —
     // a single-element `resolveAllWorlds` call always registers exactly one.
-    const worldInstance = session.game.worlds[0]!;
+    const worldInstance = session.game.roots[0]!;
     const mountedAuthoring = worldInstance.mounted.authoring;
     let authoring: AuthoringAdapter | undefined;
     if (store) {
@@ -399,9 +389,9 @@ async function mountScopedRuntimeSibling(
  * unreachable here — D-V2's route-level guard already fails the whole
  * composite before any sibling loop runs.)
  */
-function rejectUnmountableSibling(world: ResolvedWorldEntry): never {
+function rejectUnmountableSibling(world: ResolvedAdapterRoot): never {
   throw new Error(
-    `sibling world "${world.id}" (kind: ${world.kind}, adapter identity: ` +
+    `sibling world "${world.id}" (kind: ${world.surface}, adapter identity: ` +
       `"${world.adapter.identity}") has no known composite-sibling mount path — every ` +
       'currently-resolvable identity (default-three/default-pixi/default-react/module) is ' +
       'routed above; this is reached only for a genuinely unroutable shape ' +
@@ -411,26 +401,26 @@ function rejectUnmountableSibling(world: ResolvedWorldEntry): never {
 
 async function mountOneIngestSibling(
   manifest: ResolvedGameManifest,
-  world: ResolvedWorldEntry,
+  world: ResolvedAdapterRoot,
   gameContainer: HTMLElement,
   projectRoot: string,
   store: EditorStore | undefined,
 ): Promise<SiblingMount> {
   if (
     world.adapter.type === 'module' ||
-    world.adapter.identity === 'default-three' ||
-    world.adapter.identity === 'default-pixi'
+    world.adapter.identity === 'threejs' ||
+    world.adapter.identity === 'pixijs'
   ) {
     return mountScopedRuntimeSibling(manifest, world, gameContainer, projectRoot, store);
   }
-  if (world.adapter.identity === 'default-react') {
+  if (world.adapter.identity === 'react') {
     return mountDefaultReactSibling(world, gameContainer, projectRoot, store);
   }
   rejectUnmountableSibling(world);
 }
 
 /**
- * D-V2: mount every world in `manifest.worlds` OTHER than the primary ingest
+ * D-V2: mount every world in `manifest.roots` OTHER than the primary ingest
  * world (`ingestWorldId`), in manifest order (already z-sorted by the
  * loader). A failing sibling never unmounts the ingest world or stops the
  * loop — it is caught, reported (D-V5's multi-entry mount-failure report,
@@ -448,7 +438,7 @@ export async function mountIngestSiblings(
   store?: EditorStore,
 ): Promise<SiblingMount[]> {
   const mounted: SiblingMount[] = [];
-  for (const world of manifest.worlds) {
+  for (const world of manifest.roots) {
     if (world.id === ingestWorldId) continue;
     try {
       mounted.push(await mountOneIngestSibling(manifest, world, gameContainer, projectRoot, store));
@@ -456,7 +446,7 @@ export async function mountIngestSiblings(
       editorConsole.error(`Composite sibling "${world.id}" failed to mount: ${err}`, 'ingest');
       addMountFailureReport({
         worldId: world.id,
-        kind: world.kind,
+        kind: world.surface,
         identity: world.adapter.identity,
         message: formatMountFailureMessage(err),
       });

package/src/initial-scene.ts

@@ -124,8 +124,7 @@ export async function loadInitialScene(store: EditorStore): Promise<void> {
   }
 
   // A KNOWN project (readProjectView resolved it — see project-view.ts) that
-  // declares NO scene at all (its `defaultScene` is explicit `null`, or —
-  // legacy `project.json` verbatim pass-through — the key is simply absent)
+  // declares NO scene at all (its `defaultScene` is explicit `null`)
   // is a legal shape (an entry-only first world). NEVER guess a path or probe
   // the network for one here: that is exactly what silently WROTE a
   // placeholder 'scenes/untitled.vscn.json' for a project the user never

package/src/main.tsx

@@ -1,5 +1,10 @@
-import { registerSceneUIRenderer } from '@vgai/scene-ui/register-scene-ui';
 import { createRoot } from 'react-dom/client';
+// W2 (§5.1/§4.2) — the asset-selection Inspector section and the
+// story-document contributions (Story Args section + Actions/Interactions
+// utilities) register at import time; imported FIRST so they render ABOVE
+// the adapter contributions below when matched.
+import './components/asset-selection-section';
+import './components/story-documents-register';
 // Adapter-module contribution-seam registrations (side-effect imports only):
 // the permanent escape hatch for first-party UI that isn't yet contract-
 // expressible (A2's hierarchy-menu-registry.ts: prefab Unpack/Open/Save-as
@@ -11,13 +16,16 @@ import { createRoot } from 'react-dom/client';
 import './authoring/first-party-hierarchy-menu';
 import './authoring/first-party-inspector/register';
 import './authoring/react-inspector-section';
-import './authoring/ui-hierarchy-menu';
-import './authoring/ui-inspector-sections';
-import './scene-ui-mode/ui-prefab-hierarchy-menu';
 import { AppRoot } from './components/AppRoot';
+import { ensureEditorTheme } from './theme-css';
+import { installEditorTheme } from './theme-preference';
 
-// Wire the React UI runtime into the engine's scene-UI bridge so a scene's `ui`
-// tree renders at game-time (B1) — the engine itself stays React-free.
-registerSceneUIRenderer();
+// Install the shared design-token stylesheet (editor-style-polish U0) before
+// the editor chrome mounts, so any `.vgai-*` classes it renders are styled
+// from the first paint.
+ensureEditorTheme();
 
-createRoot(document.getElementById('editor-root')!).render(<AppRoot />);
+const editorRoot = document.getElementById('editor-root')!;
+const editorChromeRoot = document.getElementById('editor-chrome-root')!;
+installEditorTheme(editorChromeRoot);
+createRoot(editorRoot).render(<AppRoot />);

package/src/manifest-project.ts

@@ -4,8 +4,8 @@
  *
  * The dev server serves the project's RAW `vgai.game.json` at `/vgai.game.json`
  * (editor-server.ts's project-file-serving middleware, mirroring how it
- * special-cases `/project.json`) with no view synthesis — the browser parses
- * it itself through the PURE half of the manifest loader (`loadGameManifest`,
+ * with no view synthesis — the browser parses it itself through the PURE half
+ * of the manifest loader (`loadGameManifest`,
  * `@engine/manifest/load`), never `load-file.ts` (that needs `node:fs`, which
  * has no place in a browser bundle).
  */
@@ -13,15 +13,13 @@
 import { loadGameManifest, type ResolvedGameManifest } from '@engine/manifest/load';
 
 /**
- * Fetch + parse the current project's manifest, or `null` if it has none
- * (legacy `project.json`-only project — the raw-manifest route 404s, same as
- * any other missing project-root file per editor-server.ts). A manifest that
- * EXISTS but fails validation still throws (same fail-loud contract
- * `loadGameManifest` always has) — never silently falls back.
+ * Fetch + parse the current project's sole v2 config. Bundled examples use
+ * their staged manifest URL. Missing and invalid manifests both fail loudly.
  */
-export async function fetchGameManifest(): Promise<ResolvedGameManifest | null> {
-  const res = await fetch('/vgai.game.json');
-  if (!res.ok) return null;
+export async function fetchGameManifest(exampleId?: string): Promise<ResolvedGameManifest> {
+  const url = exampleId ? `/examples/${exampleId}/vgai.game.json` : '/vgai.game.json';
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`Failed to load ${url}: ${res.status} ${res.statusText}`);
   return loadGameManifest(await res.json());
 }
 
@@ -30,10 +28,10 @@ export async function fetchGameManifest(): Promise<ResolvedGameManifest | null>
  * — or `null` when the project genuinely has none (the route 404s). Unlike
  * {@link fetchGameManifest}, this NEVER throws on a schema violation: edit mode
  * must tolerate a manifest with ONE bad world (e.g. an unknown `kind`) by
- * surfacing that world as an error node (#18) while the VALID worlds declared
+ * surfacing that world as an error node (#18) while the VALID roots declared
  * alongside it still open — strict `loadGameManifest` would reject the whole
  * file and make every declared world vanish. The caller (`edit-mode-authoring
- * .ts`) reads `worlds[]` leniently; a genuinely absent manifest (this returns
+ * .ts`) reads `roots[]` leniently; a genuinely absent manifest (this returns
  * `null`) is the only case that synthesizes a single-world game.
  */
 export async function fetchRawGameManifest(): Promise<unknown | null> {

package/src/model-thumbnail.ts

@@ -1,5 +1,5 @@
 /**
- * Offscreen Three.js renderer that generates thumbnail images for .glb/.gltf models.
+ * Offscreen Three.js renderer that generates thumbnail images for supported 3D source formats.
  *
  * Usage:
  *   const renderer = getModelThumbnailRenderer();
@@ -9,27 +9,67 @@
  * - Singleton: one renderer is shared across all callers.
  * - Deduplicating: concurrent requests for the same URL share one render pass.
  * - Cached: once rendered, the data URL is returned immediately.
- * - Self-cleaning: each loaded GLTF is disposed after the thumbnail is captured.
+ * - Self-cleaning: each loaded object is disposed after the thumbnail is captured.
  */
 
 import { gltfLoader } from '@engine/loader';
 import * as THREE from 'three';
+import { BVHLoader } from 'three/addons/loaders/BVHLoader.js';
+import { ColladaLoader } from 'three/addons/loaders/ColladaLoader.js';
+import { FBXLoader } from 'three/addons/loaders/FBXLoader.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';
 
 const SIZE = 128;
 
 let instance: ModelThumbnailRenderer | null = null;
 
-class ModelThumbnailRenderer {
+export type ModelThumbnailFormat =
+  | 'glb'
+  | 'gltf'
+  | 'fbx'
+  | 'obj'
+  | 'dae'
+  | 'stl'
+  | 'ply'
+  | 'bvh'
+  | '3ds';
+
+export interface ModelThumbnailSpec {
+  url: string;
+  format?: ModelThumbnailFormat;
+  materialUrl?: string;
+  background?: 'transparent' | 'neutral';
+  output?: 'png' | 'webp';
+}
+
+const MODEL_THUMBNAIL_FORMATS = new Set<ModelThumbnailFormat>([
+  'glb',
+  'gltf',
+  'fbx',
+  'obj',
+  'dae',
+  'stl',
+  'ply',
+  'bvh',
+  '3ds',
+]);
+
+export function modelThumbnailFormat(url: string): ModelThumbnailFormat | undefined {
+  const pathname = url.split(/[?#]/, 1)[0]!.toLowerCase();
+  const extension = pathname.slice(pathname.lastIndexOf('.') + 1) as ModelThumbnailFormat;
+  return MODEL_THUMBNAIL_FORMATS.has(extension) ? extension : undefined;
+}
+
+export class ModelThumbnailRenderer {
   private renderer: THREE.WebGLRenderer;
   private scene: THREE.Scene;
   private camera: THREE.PerspectiveCamera;
   private cache = new Map<string, string>();
   private pending = new Map<string, Promise<string>>();
-  // Shared, DRACO-wired GLTFLoader (A2 / CB2). One-off previews call `.load()`
-  // directly (no caching/cloning) and dispose the result after capture, which is
-  // safe — each parse is independent of the shared asset-loaders GLTF cache.
-  private loader = gltfLoader;
-
   constructor() {
     const canvas = document.createElement('canvas');
     canvas.width = SIZE;
@@ -66,32 +106,43 @@ class ModelThumbnailRenderer {
   }
 
   /** Render a thumbnail for the given model URL. Returns a PNG data-URL. */
-  async render(url: string): Promise<string> {
-    const cached = this.cache.get(url);
+  async render(input: string | ModelThumbnailSpec): Promise<string> {
+    const spec: ModelThumbnailSpec = typeof input === 'string' ? { url: input } : input;
+    const format = spec.format ?? modelThumbnailFormat(spec.url);
+    if (!format) throw new Error(`No thumbnail loader for ${spec.url}`);
+    const resolved: ModelThumbnailSpec & { format: ModelThumbnailFormat } = { ...spec, format };
+    const key = JSON.stringify(resolved);
+    const cached = this.cache.get(key);
     if (cached) return cached;
 
     // Deduplicate concurrent requests for the same URL
-    const inflight = this.pending.get(url);
+    const inflight = this.pending.get(key);
     if (inflight) return inflight;
 
-    const promise = this._render(url);
-    this.pending.set(url, promise);
+    const promise = this._render(resolved);
+    this.pending.set(key, promise);
     try {
-      return await promise;
+      const dataUrl = await promise;
+      this.cache.set(key, dataUrl);
+      return dataUrl;
     } finally {
-      this.pending.delete(url);
+      this.pending.delete(key);
     }
   }
 
-  private async _render(url: string): Promise<string> {
-    const group = await new Promise<THREE.Group>((resolve, reject) => {
-      this.loader.load(url, (gltf) => resolve(gltf.scene), undefined, reject);
-    });
+  private async _render(
+    spec: ModelThumbnailSpec & { format: ModelThumbnailFormat },
+  ): Promise<string> {
+    const group = createModelPreviewSource(await loadModelThumbnailObject(spec));
 
     this.scene.add(group);
 
     // Auto-frame the camera around the model
     const box = new THREE.Box3().setFromObject(group);
+    if (box.isEmpty()) {
+      this.scene.remove(group);
+      throw new Error('Model contains no previewable geometry.');
+    }
     const center = box.getCenter(new THREE.Vector3());
     const size = box.getSize(new THREE.Vector3());
     const maxDim = Math.max(size.x, size.y, size.z) || 1;
@@ -110,18 +161,25 @@ class ModelThumbnailRenderer {
     this.camera.updateProjectionMatrix();
 
     // Render
-    this.renderer.setClearColor(0x000000, 0);
+    if (spec.background === 'neutral') this.renderer.setClearColor(0x20242a, 1);
+    else this.renderer.setClearColor(0x000000, 0);
     this.renderer.clear();
     this.renderer.render(this.scene, this.camera);
-    const dataUrl = this.renderer.domElement.toDataURL('image/png');
+    const dataUrl =
+      spec.output === 'webp'
+        ? this.renderer.domElement.toDataURL('image/webp', 0.86)
+        : this.renderer.domElement.toDataURL('image/png');
 
     // Clean up the loaded GLTF to free GPU memory
     this.scene.remove(group);
+    // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: Disposal enumerates the texture slots used by the supported Three.js materials.
     group.traverse((obj) => {
-      const mesh = obj as THREE.Mesh;
-      if (mesh.geometry) mesh.geometry.dispose();
-      if (mesh.material) {
-        const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+      const renderable = obj as THREE.Mesh | THREE.Line | THREE.Points;
+      if (renderable.geometry) renderable.geometry.dispose();
+      if (renderable.material) {
+        const materials = Array.isArray(renderable.material)
+          ? renderable.material
+          : [renderable.material];
         for (const mat of materials) {
           // Dispose any textures attached to the material
           if ('map' in mat && mat.map instanceof THREE.Texture) mat.map.dispose();
@@ -138,19 +196,196 @@ class ModelThumbnailRenderer {
       }
     });
 
-    this.cache.set(url, dataUrl);
     return dataUrl;
   }
 
   dispose() {
     this.renderer.dispose();
+    this.renderer.forceContextLoss();
     this.cache.clear();
     instance = null;
   }
 }
 
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: This format dispatcher keeps each Three.js loader path visible in one place.
+export async function loadModelThumbnailObject(
+  spec: ModelThumbnailSpec & { format: ModelThumbnailFormat },
+): Promise<THREE.Object3D> {
+  switch (spec.format) {
+    case 'glb':
+    case 'gltf':
+      return (await gltfLoader.loadAsync(spec.url)).scene;
+    case 'fbx':
+      return new FBXLoader().loadAsync(spec.url);
+    case 'obj': {
+      const materialUrl = spec.materialUrl ?? (await discoverObjMaterial(spec.url));
+      const loader = new OBJLoader();
+      if (materialUrl) {
+        const materials = await new MTLLoader().loadAsync(materialUrl);
+        materials.preload();
+        loader.setMaterials(materials);
+      }
+      return loader.loadAsync(spec.url);
+    }
+    case 'dae':
+      return (await new ColladaLoader().loadAsync(spec.url)).scene;
+    case 'stl': {
+      const geometry = await new STLLoader().loadAsync(spec.url);
+      return new THREE.Mesh(
+        geometry,
+        new THREE.MeshStandardMaterial({ color: 0x75a7d8, roughness: 0.75 }),
+      );
+    }
+    case 'ply': {
+      const geometry = await new PLYLoader().loadAsync(spec.url);
+      if (geometry.index || geometry.hasAttribute('normal')) {
+        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,
+          }),
+        );
+      }
+      geometry.computeBoundingBox();
+      const diagonal = geometry.boundingBox?.getSize(new THREE.Vector3()).length() ?? 1;
+      return new THREE.Points(
+        geometry,
+        new THREE.PointsMaterial({
+          color: geometry.hasAttribute('color') ? 0xffffff : 0xb8d09b,
+          vertexColors: geometry.hasAttribute('color'),
+          size: Math.max(diagonal / 220, 0.0001),
+          sizeAttenuation: true,
+        }),
+      );
+    }
+    case 'bvh': {
+      const result = await new BVHLoader().loadAsync(spec.url);
+      const root = result.skeleton.bones[0];
+      if (!root) throw new Error('BVH contains no skeleton root.');
+      const group = new THREE.Group();
+      group.add(root);
+      const helper = new THREE.SkeletonHelper(root);
+      group.add(helper);
+      const mixer = new THREE.AnimationMixer(root);
+      mixer.clipAction(result.clip).play();
+      mixer.setTime(result.clip.duration * 0.35);
+      group.updateWorldMatrix(true, true);
+      helper.updateMatrixWorld(true);
+      return group;
+    }
+    case '3ds':
+      return new TDSLoader().loadAsync(spec.url);
+  }
+}
+
+/**
+ * Give animation-only model files an honest renderable representation.
+ * FBX/glTF animation exports commonly contain a complete bone hierarchy and
+ * clips but no mesh. They are valid assets, so Asset Editor visualizes their
+ * current skeleton instead of misreporting them as an empty source.
+ */
+export function createModelPreviewSource(model: THREE.Object3D): THREE.Object3D {
+  if (hasRenderableModelContent(model)) return model;
+
+  model.updateWorldMatrix(true, true);
+  const helper = new THREE.SkeletonHelper(model);
+  const positions = helper.geometry.getAttribute('position');
+  if (!positions || positions.count === 0) {
+    helper.dispose();
+    return model;
+  }
+
+  helper.name = 'Asset Editor skeleton preview';
+  helper.frustumCulled = false;
+  const previewRoot = new THREE.Group();
+  previewRoot.name = model.name;
+  previewRoot.animations = [...model.animations];
+  previewRoot.add(model, helper);
+  previewRoot.updateWorldMatrix(true, true);
+  // SkeletonHelper updates its dynamic line vertices from updateMatrixWorld,
+  // while the read-only preview measurer intentionally calls updateWorldMatrix.
+  // Materialize the current pose once so framing sees the real skeleton span.
+  helper.updateMatrixWorld(true);
+  return previewRoot;
+}
+
+function hasRenderableModelContent(model: THREE.Object3D): boolean {
+  let renderable = false;
+  model.traverseVisible((object) => {
+    if (!renderable && objectHasRenderableModelContent(object)) renderable = true;
+  });
+  return renderable;
+}
+
+function objectHasRenderableModelContent(object: THREE.Object3D): boolean {
+  const sprite = object as THREE.Sprite;
+  if (sprite.isSprite) return sprite.material.visible;
+  const mesh = object as THREE.Mesh;
+  const line = object as THREE.Line;
+  const points = object as THREE.Points;
+  if (!mesh.isMesh && !line.isLine && !points.isPoints) return false;
+  const drawable = object as THREE.Mesh;
+  const instanced = object as THREE.InstancedMesh;
+  if (instanced.isInstancedMesh && instanced.count === 0) return false;
+  const materials = Array.isArray(drawable.material) ? drawable.material : [drawable.material];
+  if (materials.length === 0 || materials.every((material) => !material?.visible)) return false;
+  const positions = drawable.geometry?.getAttribute('position');
+  return Boolean(positions && positions.count > 0 && drawable.geometry.drawRange.count !== 0);
+}
+
+async function discoverObjMaterial(url: string): Promise<string | undefined> {
+  const pathname = url.split(/[?#]/, 1)[0]!;
+  const materialUrl = `${pathname.slice(0, pathname.lastIndexOf('.'))}.mtl`;
+  try {
+    const response = await fetch(materialUrl, { method: 'HEAD' });
+    return response.ok ? materialUrl : undefined;
+  } catch {
+    return 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();
   return instance;
 }
+
+// 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.
+if (import.meta.hot) {
+  import.meta.hot.dispose(() => instance?.dispose());
+}