@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/components/asset-viewers/ModelViewer.tsx

@@ -1,38 +1,137 @@
-import { gltfLoader } from '@engine/loader';
 import { useEffect, useRef, useState } from 'react';
 import * as THREE from 'three';
 import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
-import { SectionHeader } from '../primitives/SectionHeader';
+import {
+  type AssetPreviewBackground,
+  captureModelAssetPreview,
+  captureObjectAssetPreview,
+  createAssetPreviewSnapshot,
+  disposeAssetPreviewSnapshot,
+  loadProjectAssetModel,
+  measureAssetPreview,
+} from '../../asset-preview';
+import {
+  type AssetEditorIssue,
+  type AssetLoadStage,
+  classifyAssetEditorError,
+} from '../../asset-workflow/asset-editor-errors';
+import {
+  cameraPresetDirection,
+  inspectModel,
+  type ModelCameraPreset,
+  type ModelDiagnosticMode,
+  type ModelInspection,
+  supportedModelDiagnosticModes,
+} from '../../asset-workflow/model-inspection';
+import {
+  loadProjectThumbnailManifest,
+  resetProjectThumbnailManifestCache,
+  THUMBNAIL_PROFILE,
+} from '../../asset-workflow/thumbnail-system';
+import {
+  Button,
+  bg,
+  Checkbox,
+  danger,
+  radius,
+  SectionHeader,
+  Select,
+  TextInput,
+  text,
+} from '../../design-system';
+import { useEditorStore } from '../../EditorContext';
+import {
+  createModelPreviewSource,
+  loadModelThumbnailObject,
+  modelThumbnailFormat,
+} from '../../model-thumbnail';
+import { AssetEditorShell } from '../AssetEditorShell';
+import { AssetImportDetails } from '../AssetImportDetails';
+import { writeProjectAsset } from '../asset-editor-persistence';
 
-const labelStyle: React.CSSProperties = { fontSize: 11, color: '#8c8c8c', marginBottom: 2 };
+interface ModelViewerProps {
+  assetPath: string | undefined;
+  entityId: string | undefined;
+  materialPath?: string | undefined;
+  displayName?: string | undefined;
+  embedded?: boolean | undefined;
+  active?: boolean | undefined;
+}
+
+interface ModelViewerRuntime {
+  camera: THREE.PerspectiveCamera | THREE.OrthographicCamera;
+  controls: OrbitControls;
+  renderer: THREE.WebGLRenderer;
+  scene: THREE.Scene;
+  model: THREE.Object3D;
+  helpers: THREE.Object3D[];
+  mixer: THREE.AnimationMixer | null;
+  clock: THREE.Clock;
+}
 
-export function ModelViewer({ assetPath }: { assetPath: string }) {
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one viewer coordinates embedded/full chrome and both live-entity and file-backed Asset Editor sources.
+export function ModelViewer({
+  assetPath,
+  entityId,
+  materialPath,
+  displayName: suppliedDisplayName,
+  embedded = false,
+  active = true,
+}: ModelViewerProps) {
+  const store = useEditorStore();
   const containerRef = useRef<HTMLDivElement>(null);
-  const [error, setError] = useState(false);
+  const runtimeRef = useRef<ModelViewerRuntime | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [issue, setIssue] = useState<AssetEditorIssue | null>(null);
+  const [loadStage, setLoadStage] = useState<AssetLoadStage>('fetching');
+  const loadStageRef = useRef<AssetLoadStage>('fetching');
+  const [retryKey, setRetryKey] = useState(0);
   const [loading, setLoading] = useState(true);
-  const fileName = assetPath.split('/').pop() ?? assetPath;
+  const [capturing, setCapturing] = useState(false);
+  const [background, setBackground] = useState<AssetPreviewBackground>('neutral');
+  const [exposure, setExposure] = useState(1);
+  const [grid, setGrid] = useState(true);
+  const [projection, setProjection] = useState<'perspective' | 'orthographic'>('perspective');
+  const [lighting, setLighting] = useState<'studio' | 'outdoor' | 'flat'>('studio');
+  const [inspection, setInspection] = useState<ModelInspection | null>(null);
+  const [diagnosticMode, setDiagnosticMode] = useState<ModelDiagnosticMode>('lit');
+  const [playing, setPlaying] = useState(false);
+  const [loop, setLoop] = useState(true);
+  const [speed, setSpeed] = useState(1);
+  const [time, setTime] = useState(0);
+  const [selectedClip, setSelectedClip] = useState(0);
+  const playbackRef = useRef({ playing: false, speed: 1, selectedClip: 0 });
+  const [contactSheet, setContactSheet] = useState<string | null>(null);
+  const sourceObject = entityId ? store.objectMap.get(entityId) : undefined;
+  const displayName =
+    suppliedDisplayName ??
+    (assetPath
+      ? (assetPath.split('/').pop() ?? assetPath)
+      : sourceObject?.name || entityId || 'Asset Editor');
 
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: WebGL setup, async model ownership, resize, and deterministic cleanup form one resource lifetime.
   useEffect(() => {
     const container = containerRef.current;
-    if (!container) return;
+    if (!container || !active) return;
 
-    setError(false);
+    setError(null);
+    setIssue(null);
+    setLoadStage('fetching');
+    loadStageRef.current = 'fetching';
     setLoading(true);
+    setContactSheet(null);
 
     const width = container.clientWidth;
-    const height = width; // square aspect
-
-    // Renderer
+    const height = width;
     const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
     renderer.setSize(width, height);
     renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
     renderer.outputColorSpace = THREE.SRGBColorSpace;
     renderer.toneMapping = THREE.ACESFilmicToneMapping;
-    renderer.toneMappingExposure = 1.0;
+    renderer.toneMappingExposure = 1;
     renderer.setClearColor(0x1e1e1e, 1);
     container.appendChild(renderer.domElement);
 
-    // Scene
     const scene = new THREE.Scene();
     scene.add(new THREE.AmbientLight(0xffffff, 0.8));
     const key = new THREE.DirectionalLight(0xffffff, 1.5);
@@ -42,139 +141,724 @@ export function ModelViewer({ assetPath }: { assetPath: string }) {
     fill.position.set(-3, -1, 2);
     scene.add(fill);
 
-    // Camera
     const camera = new THREE.PerspectiveCamera(35, 1, 0.01, 1000);
-
-    // Controls
     const controls = new OrbitControls(camera, renderer.domElement);
     controls.enableDamping = true;
     controls.dampingFactor = 0.1;
 
-    // Animation loop
     let rafId = 0;
+    let disposed = false;
+    const modelLoadController = new AbortController();
+    let ownedModel: THREE.Object3D | null = null;
+    let ownedSnapshot: THREE.Object3D | null = null;
+    const clock = new THREE.Clock();
     const animate = () => {
       rafId = requestAnimationFrame(animate);
+      const runtime = runtimeRef.current;
+      if (runtime?.mixer && playbackRef.current.playing) {
+        runtime.mixer.update(clock.getDelta() * playbackRef.current.speed);
+        const clip = runtime.model.animations[playbackRef.current.selectedClip];
+        if (clip) setTime(runtime.mixer.time % Math.max(clip.duration, 0.001));
+      } else clock.getDelta();
       controls.update();
-      renderer.render(scene, camera);
+      renderer.render(scene, runtimeRef.current?.camera ?? camera);
     };
 
-    // Load model via the shared, DRACO-wired GLTFLoader (A2 / CB2). This is a
-    // one-off preview: `.load()` parses fresh (no caching/cloning) and the result
-    // is disposed on unmount, independent of the asset-loaders GLTF cache.
-    const loader = gltfLoader;
-    loader.load(
-      assetPath,
-      (gltf) => {
-        const model = gltf.scene;
-        scene.add(model);
-
-        // Frame camera around model
-        const box = new THREE.Box3().setFromObject(model);
-        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;
-        const fovRad = (camera.fov * Math.PI) / 180;
-        const dist = (maxDim / (2 * Math.tan(fovRad / 2))) * 1.3;
-
-        camera.position.set(center.x + dist * 0.65, center.y + dist * 0.45, center.z + dist * 0.65);
-        camera.near = dist * 0.01;
-        camera.far = dist * 20;
-        camera.updateProjectionMatrix();
-
-        controls.target.copy(center);
-        controls.update();
-
-        setLoading(false);
-        animate();
-      },
-      undefined,
-      () => {
-        setError(true);
-        setLoading(false);
-      },
-    );
+    // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: installation owns framing, inspection, animation, and bounded resource registration as one lifetime transition.
+    const install = (model: THREE.Object3D, ownsResources: boolean) => {
+      if (disposed) {
+        if (ownsResources) disposeModel(model);
+        return;
+      }
+      if (ownsResources) ownedModel = model;
+      scene.add(model);
+      loadStageRef.current = 'gpu-upload';
+      setLoadStage('gpu-upload');
+      frameInteractiveModel(model, camera, controls);
+      const nextInspection = inspectModel(model);
+      setInspection(nextInspection);
+      let mixer: THREE.AnimationMixer | null = null;
+      if (model.animations.length > 0) {
+        mixer = new THREE.AnimationMixer(model);
+        const action = mixer.clipAction(
+          model.animations[Math.min(selectedClip, model.animations.length - 1)]!,
+        );
+        action.setLoop(loop ? THREE.LoopRepeat : THREE.LoopOnce, loop ? Infinity : 1);
+        action.play();
+      }
+      runtimeRef.current = { camera, controls, renderer, scene, model, helpers: [], mixer, clock };
+      applyModelDiagnosticMode(runtimeRef.current, diagnosticMode);
+      setLoading(false);
+      loadStageRef.current = 'ready';
+      setLoadStage('ready');
+      animate();
+    };
 
-    // Handle resize if container width changes
-    const ro = new ResizeObserver((entries) => {
+    const fail = (err: unknown) => {
+      const nextIssue = classifyAssetEditorError(err, loadStageRef.current);
+      setIssue(nextIssue);
+      setError(nextIssue.message);
+      setLoading(false);
+    };
+
+    if (sourceObject) {
+      try {
+        ownedSnapshot = createAssetPreviewSnapshot(sourceObject);
+        install(ownedSnapshot, false);
+      } catch (err) {
+        if (ownedSnapshot) disposeAssetPreviewSnapshot(ownedSnapshot);
+        ownedSnapshot = null;
+        fail(err);
+      }
+    } else if (assetPath) {
+      const format = modelThumbnailFormat(assetPath);
+      loadStageRef.current =
+        format === 'gltf' || format === 'obj' ? 'dependency-resolution' : 'parsing';
+      setLoadStage(loadStageRef.current);
+      const modelPromise =
+        format && format !== 'glb' && format !== 'gltf'
+          ? loadModelThumbnailObject({
+              url: assetPath,
+              format,
+              ...(materialPath ? { materialUrl: materialPath } : {}),
+            })
+          : loadProjectAssetModel(assetPath, modelLoadController.signal);
+      void modelPromise.then(
+        // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: the completion path must dispose correctly across unmount, snapshot failure, and successful installation.
+        (loadedModel) => {
+          const model = createModelPreviewSource(loadedModel);
+          try {
+            if (disposed) {
+              disposeModel(model);
+              return;
+            }
+            ownedModel = model;
+            ownedSnapshot = createAssetPreviewSnapshot(model);
+            install(ownedSnapshot, false);
+          } catch (err) {
+            if (ownedSnapshot) disposeAssetPreviewSnapshot(ownedSnapshot);
+            ownedSnapshot = null;
+            if (ownedModel) disposeModel(ownedModel);
+            ownedModel = null;
+            fail(err);
+          }
+        },
+        (err) => {
+          if (!disposed) fail(err);
+        },
+      );
+    } else {
+      setError('Asset Editor source is no longer available.');
+      setLoading(false);
+    }
+
+    const resizeObserver = new ResizeObserver((entries) => {
       for (const entry of entries) {
-        const w = entry.contentRect.width;
-        const h = w;
-        renderer.setSize(w, h);
-        camera.aspect = 1;
-        camera.updateProjectionMatrix();
+        const nextWidth = entry.contentRect.width;
+        const nextHeight = Math.max(entry.contentRect.height, 1);
+        renderer.setSize(nextWidth, nextHeight);
+        const activeCamera = runtimeRef.current?.camera ?? camera;
+        const aspect = nextWidth / nextHeight;
+        if (activeCamera instanceof THREE.PerspectiveCamera) activeCamera.aspect = aspect;
+        else {
+          const halfHeight = (activeCamera.top - activeCamera.bottom) / 2;
+          activeCamera.left = -halfHeight * aspect;
+          activeCamera.right = halfHeight * aspect;
+        }
+        activeCamera.updateProjectionMatrix();
       }
     });
-    ro.observe(container);
+    resizeObserver.observe(container);
 
     return () => {
+      disposed = true;
+      modelLoadController.abort(new Error('Asset Editor model viewer closed.'));
       cancelAnimationFrame(rafId);
-      ro.disconnect();
+      resizeObserver.disconnect();
       controls.dispose();
+      runtimeRef.current?.mixer?.stopAllAction();
+      for (const helper of runtimeRef.current?.helpers ?? []) disposeAssetPreviewSnapshot(helper);
+      runtimeRef.current = null;
       renderer.dispose();
-      // Clean up model geometry/materials
-      scene.traverse((obj) => {
-        const mesh = obj as THREE.Mesh;
-        if (mesh.geometry) mesh.geometry.dispose();
-        if (mesh.material) {
-          const mats = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
-          for (const mat of mats) {
-            for (const val of Object.values(mat)) {
-              if (val instanceof THREE.Texture) val.dispose();
-            }
-            mat.dispose();
-          }
-        }
-      });
-      if (container.contains(renderer.domElement)) {
-        container.removeChild(renderer.domElement);
-      }
+      renderer.forceContextLoss();
+      if (ownedSnapshot) disposeAssetPreviewSnapshot(ownedSnapshot);
+      if (ownedModel) disposeModel(ownedModel);
+      if (container.contains(renderer.domElement)) container.removeChild(renderer.domElement);
     };
-  }, [assetPath]);
+  }, [active, assetPath, materialPath, retryKey, sourceObject]);
+
+  useEffect(() => {
+    playbackRef.current = { playing, speed, selectedClip };
+  }, [playing, selectedClip, speed]);
+
+  useEffect(() => {
+    const runtime = runtimeRef.current;
+    if (!runtime) return;
+    runtime.renderer.toneMappingExposure = exposure;
+    runtime.renderer.setClearColor(
+      background === 'transparent' ? 0x000000 : 0x20242a,
+      background === 'transparent' ? 0 : 1,
+    );
+    const existing = runtime.scene.getObjectByName('__asset_editor_grid');
+    if (grid && !existing) {
+      const helper = new THREE.GridHelper(10, 20, 0x51606f, 0x343b44);
+      helper.name = '__asset_editor_grid';
+      runtime.scene.add(helper);
+      runtime.helpers.push(helper);
+    } else if (!grid && existing) {
+      runtime.scene.remove(existing);
+      runtime.helpers = runtime.helpers.filter((item) => item !== existing);
+      disposeAssetPreviewSnapshot(existing);
+    }
+  }, [background, exposure, grid]);
+
+  useEffect(() => {
+    const runtime = runtimeRef.current;
+    if (!runtime) return;
+    const isPerspective = runtime.camera instanceof THREE.PerspectiveCamera;
+    if ((projection === 'perspective') === isPerspective) return;
+    const aspect =
+      Math.max(containerRef.current?.clientWidth ?? 1, 1) /
+      Math.max(containerRef.current?.clientHeight ?? 1, 1);
+    const next =
+      projection === 'perspective'
+        ? new THREE.PerspectiveCamera(35, aspect, runtime.camera.near, runtime.camera.far)
+        : new THREE.OrthographicCamera(
+            -aspect,
+            aspect,
+            1,
+            -1,
+            runtime.camera.near,
+            runtime.camera.far,
+          );
+    next.position.copy(runtime.camera.position);
+    next.quaternion.copy(runtime.camera.quaternion);
+    next.up.copy(runtime.camera.up);
+    runtime.camera = next;
+    (runtime.controls as unknown as { object: THREE.Camera }).object = next;
+    frameRuntime(runtime);
+  }, [projection]);
+
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: each named lighting preset maps all owned light types in one visible state transition.
+  useEffect(() => {
+    const runtime = runtimeRef.current;
+    if (!runtime) return;
+    const lights = runtime.scene.children.filter(
+      (child): child is THREE.Light => child instanceof THREE.Light,
+    );
+    for (const light of lights) {
+      if (light instanceof THREE.AmbientLight)
+        light.intensity = lighting === 'flat' ? 2 : lighting === 'outdoor' ? 1.15 : 0.8;
+      else
+        light.intensity =
+          lighting === 'flat'
+            ? 0
+            : lighting === 'outdoor'
+              ? 2.2
+              : light.color.getHex() === 0xffffff
+                ? 1.5
+                : 0.4;
+    }
+  }, [lighting]);
+
+  useEffect(() => {
+    if (runtimeRef.current) applyModelDiagnosticMode(runtimeRef.current, diagnosticMode);
+  }, [diagnosticMode]);
+
+  useEffect(() => {
+    const runtime = runtimeRef.current;
+    if (!runtime?.mixer || runtime.model.animations.length === 0) return;
+    runtime.mixer.stopAllAction();
+    runtime.mixer.time = 0;
+    const clip =
+      runtime.model.animations[Math.min(selectedClip, runtime.model.animations.length - 1)]!;
+    const action = runtime.mixer.clipAction(clip);
+    action.setLoop(loop ? THREE.LoopRepeat : THREE.LoopOnce, loop ? Infinity : 1);
+    action.play();
+    setTime(0);
+  }, [selectedClip, loop]);
+
+  const capture = async () => {
+    setCapturing(true);
+    setError(null);
+    try {
+      const result = assetPath
+        ? await captureModelAssetPreview(assetPath, { background })
+        : sourceObject
+          ? captureObjectAssetPreview(sourceObject, { background })
+          : null;
+      if (!result) throw new Error('Asset Editor source is no longer available.');
+      setContactSheet(`data:image/png;base64,${result.contactSheet.base64}`);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setCapturing(false);
+    }
+  };
+
+  const saveThumbnailFraming = async (reset = false) => {
+    if (!assetPath) return;
+    const manifest = (await loadProjectThumbnailManifest()) ?? {
+      version: 1 as const,
+      profile: THUMBNAIL_PROFILE.version,
+      generatedAt: new Date().toISOString(),
+      entries: {},
+    };
+    const key = assetPath.replace(/^\/+/, '');
+    const runtime = runtimeRef.current;
+    const prior = manifest.entries[key] ?? {
+      state: 'fallback' as const,
+      profileVersion: THUMBNAIL_PROFILE.version,
+      issueCode: 'thumbnail.pending-regeneration',
+    };
+    const entry =
+      reset || !runtime
+        ? { ...prior, framing: undefined }
+        : {
+            ...prior,
+            framing: {
+              position: runtime.camera.position.toArray() as [number, number, number],
+              target: runtime.controls.target.toArray() as [number, number, number],
+            },
+          };
+    const updated = {
+      ...manifest,
+      generatedAt: new Date().toISOString(),
+      entries: { ...manifest.entries, [key]: entry },
+    };
+    if (
+      await writeProjectAsset('.vgai/thumbnails.json', `${JSON.stringify(updated, null, 2)}\n`, {
+        label: `${reset ? 'Reset' : 'Save'} thumbnail framing ${assetPath}`,
+        kind: 'project-file',
+      })
+    )
+      resetProjectThumbnailManifestCache();
+  };
+
+  const viewport = (
+    <div
+      ref={containerRef}
+      data-testid="asset-editor-viewport"
+      role="region"
+      aria-label={`Interactive 3D preview: ${displayName}`}
+      aria-busy={loading}
+      style={{
+        width: '100%',
+        height: '100%',
+        minHeight: embedded ? 220 : 360,
+        background: bg.inset,
+        borderRadius: radius.sm,
+        overflow: 'hidden',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        position: 'relative',
+      }}
+    >
+      {loading && !error && (
+        <span style={{ color: text[2], fontSize: 11, position: 'absolute' }}>Loading...</span>
+      )}
+      {!active && (
+        <span style={{ color: text[2], fontSize: 11, position: 'absolute' }}>
+          Preview suspended while this editor is inactive.
+        </span>
+      )}
+      {error && (
+        <div
+          style={{ color: danger, fontSize: 11, position: 'absolute', padding: 12, maxWidth: 520 }}
+        >
+          <strong>{issue?.code ?? 'asset.rendering.failed'}</strong> · {issue?.stage ?? loadStage}
+          <br />
+          {error}
+          <br />
+          {issue?.recovery.includes('retry') && (
+            <Button type="button" onClick={() => setRetryKey((value) => value + 1)}>
+              Retry
+            </Button>
+          )}
+          {issue?.recovery.includes('reimport') && <Button type="button">Reimport</Button>}
+        </div>
+      )}
+    </div>
+  );
+
+  if (embedded) return viewport;
+
+  const pathFormat = assetPath ? modelThumbnailFormat(assetPath) : undefined;
+  const deterministicCaptureSupported = !assetPath || pathFormat === 'glb' || pathFormat === 'gltf';
+
+  const modes = runtimeRef.current ? supportedModelDiagnosticModes(runtimeRef.current.model) : [];
+  const selectedDuration = runtimeRef.current?.model.animations[selectedClip]?.duration ?? 0;
+  const hierarchy = inspection?.hierarchy ?? [];
 
   return (
-    <div style={{ padding: 8, display: 'flex', flexDirection: 'column', gap: 8 }}>
-      <div style={{ fontWeight: 600, fontSize: 12, color: '#c5c8ce', wordBreak: 'break-all' }}>
-        {fileName}
-      </div>
-      <div
-        ref={containerRef}
-        style={{
-          width: '100%',
-          aspectRatio: '1',
-          background: '#1e1e1e',
-          borderRadius: 4,
-          overflow: 'hidden',
-          display: 'flex',
-          alignItems: 'center',
-          justifyContent: 'center',
-          position: 'relative',
-        }}
-      >
-        {loading && !error && (
-          <span style={{ color: '#8c8c8c', fontSize: 11, position: 'absolute' }}>Loading...</span>
-        )}
-        {error && (
-          <span style={{ color: '#8c8c8c', fontSize: 11, position: 'absolute' }}>
-            Failed to load model
-          </span>
-        )}
-      </div>
-      <SectionHeader label="Info">
-        <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
-          <div>
-            <div style={labelStyle}>Path</div>
-            <div style={{ fontSize: 11, color: '#c5c8ce', wordBreak: 'break-all' }}>
-              {assetPath}
-            </div>
-          </div>
-          <div>
-            <div style={labelStyle}>Format</div>
-            <div style={{ fontSize: 11, color: '#c5c8ce' }}>
-              {assetPath.endsWith('.glb') ? 'GLB (Binary)' : 'glTF'}
+    <AssetEditorShell
+      type="model"
+      title={displayName}
+      toolbar={
+        <>
+          <Button type="button" onClick={() => frameRuntime(runtimeRef.current)}>
+            Frame
+          </Button>
+          {(['front', 'back', 'left', 'right', 'top', 'bottom', 'isometric'] as const).map(
+            (preset) => (
+              <Button
+                key={preset}
+                type="button"
+                onClick={() => setCameraPreset(runtimeRef.current, preset)}
+              >
+                {preset}
+              </Button>
+            ),
+          )}
+          <Select
+            aria-label="Model diagnostic view"
+            value={diagnosticMode}
+            onChange={(event) => setDiagnosticMode(event.target.value as ModelDiagnosticMode)}
+          >
+            {modes
+              .filter((mode) => mode.available)
+              .map((mode) => (
+                <option key={mode.mode} value={mode.mode}>
+                  {mode.mode}
+                </option>
+              ))}
+          </Select>
+          <Select
+            aria-label="Camera projection"
+            value={projection}
+            onChange={(event) =>
+              setProjection(event.target.value as 'perspective' | 'orthographic')
+            }
+          >
+            <option value="perspective">Perspective</option>
+            <option value="orthographic">Orthographic</option>
+          </Select>
+          <Select
+            aria-label="Lighting preset"
+            value={lighting}
+            onChange={(event) => setLighting(event.target.value as 'studio' | 'outdoor' | 'flat')}
+          >
+            <option value="studio">Studio light</option>
+            <option value="outdoor">Outdoor light</option>
+            <option value="flat">Flat light</option>
+          </Select>
+          <Select
+            aria-label="Asset preview background"
+            value={background}
+            onChange={(event) => setBackground(event.target.value as AssetPreviewBackground)}
+          >
+            <option value="neutral">Neutral</option>
+            <option value="transparent">Transparent</option>
+          </Select>
+          <label>
+            Exposure{' '}
+            <TextInput
+              aria-label="Preview exposure"
+              type="range"
+              min="0.2"
+              max="2"
+              step="0.1"
+              value={exposure}
+              onChange={(event) => setExposure(Number(event.target.value))}
+            />
+          </label>
+          <Button type="button" aria-pressed={grid} onClick={() => setGrid((value) => !value)}>
+            Grid
+          </Button>
+          <Button
+            type="button"
+            onClick={() => {
+              setExposure(1);
+              setBackground('neutral');
+              setGrid(true);
+              setProjection('perspective');
+              setLighting('studio');
+              setDiagnosticMode('lit');
+              frameRuntime(runtimeRef.current);
+            }}
+          >
+            Reset
+          </Button>
+          {assetPath && (
+            <Button type="button" onClick={() => void saveThumbnailFraming(false)}>
+              Save thumbnail view
+            </Button>
+          )}
+          {assetPath && (
+            <Button type="button" onClick={() => void saveThumbnailFraming(true)}>
+              Reset thumbnail view
+            </Button>
+          )}
+        </>
+      }
+      structure={
+        <div>
+          <SectionHeader label="Hierarchy">
+            <div role="tree" aria-label="Model hierarchy">
+              {hierarchy.map((node) => (
+                <Button
+                  type="button"
+                  role="treeitem"
+                  key={node.id}
+                  variant="ghost"
+                  size="compact"
+                  className="vgai-model-tree-item"
+                  style={{
+                    display: 'block',
+                    width: '100%',
+                    paddingLeft: node.depth * 10 + 4,
+                  }}
+                >
+                  {node.name} <small>{node.type}</small>
+                </Button>
+              ))}
             </div>
+          </SectionHeader>
+          <SectionHeader label="Materials">
+            {inspection?.materialNames.map((name, index) => (
+              <div key={`${name}:${index}`}>{name}</div>
+            ))}
+          </SectionHeader>
+        </div>
+      }
+      details={
+        <div>
+          <SectionHeader label="Statistics">
+            <ModelStatistics value={inspection} />
+          </SectionHeader>
+          <SectionHeader label="Diagnostics">
+            {modes.map((mode) => (
+              <div key={mode.mode}>
+                {mode.mode}: {mode.available ? 'available' : mode.reason}
+              </div>
+            ))}
+          </SectionHeader>
+          <SectionHeader label="Source">
+            <div style={{ wordBreak: 'break-all' }}>{assetPath ?? `Entity ${entityId}`}</div>
+          </SectionHeader>
+          {assetPath && <AssetImportDetails assetPath={assetPath} />}
+          {deterministicCaptureSupported && (
+            <SectionHeader label="Deterministic capture">
+              <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+                <Button
+                  type="button"
+                  variant="secondary"
+                  data-testid="capture-asset-preview"
+                  disabled={capturing || loading}
+                  onClick={() => void capture()}
+                >
+                  {capturing ? 'Capturing…' : 'Capture front · right · top · ¾'}
+                </Button>
+                {contactSheet && (
+                  <img
+                    src={contactSheet}
+                    data-testid="asset-preview-contact-sheet"
+                    alt="Front, right, top, and three-quarter asset preview"
+                    style={{ width: '100%', display: 'block', background: bg.inset }}
+                  />
+                )}
+              </div>
+            </SectionHeader>
+          )}
+        </div>
+      }
+      status={
+        inspection?.clips ? (
+          <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+            <Select
+              aria-label="Animation clip"
+              value={selectedClip}
+              onChange={(event) => setSelectedClip(Number(event.target.value))}
+            >
+              {runtimeRef.current?.model.animations.map((clip, index) => (
+                <option key={`${clip.name}:${index}`} value={index}>
+                  {clip.name || `Clip ${index + 1}`}
+                </option>
+              ))}
+            </Select>
+            <Button type="button" onClick={() => setPlaying((value) => !value)}>
+              {playing ? 'Pause' : 'Play'}
+            </Button>
+            <label>
+              Time{' '}
+              <TextInput
+                aria-label="Animation time"
+                type="range"
+                min={0}
+                max={selectedDuration || 1}
+                step={1 / 30}
+                value={Math.min(time, selectedDuration || 1)}
+                onChange={(event) => {
+                  const next = Number(event.target.value);
+                  runtimeRef.current?.mixer?.setTime(next);
+                  setTime(next);
+                }}
+              />
+            </label>
+            <span>
+              {time.toFixed(2)} / {selectedDuration.toFixed(2)}s
+            </span>
+            <label>
+              <Checkbox checked={loop} onChange={(event) => setLoop(event.target.checked)} /> Loop
+            </label>
+            <label>
+              Speed{' '}
+              <Select value={speed} onChange={(event) => setSpeed(Number(event.target.value))}>
+                <option value={0.25}>¼×</option>
+                <option value={0.5}>½×</option>
+                <option value={1}>1×</option>
+                <option value={2}>2×</option>
+              </Select>
+            </label>
           </div>
+        ) : (
+          `${loading ? `${loadStage}…` : error ? `${issue?.stage ?? 'rendering'} failed · ${issue?.code}` : 'Ready'} · ${inspection?.triangles.toLocaleString() ?? 0} triangles`
+        )
+      }
+    >
+      {viewport}
+    </AssetEditorShell>
+  );
+}
+
+function ModelStatistics({ value }: { value: ModelInspection | null }) {
+  if (!value) return <div>Loading inspection…</div>;
+  const rows: Array<[string, string | number]> = [
+    ['Nodes', value.nodes],
+    ['Meshes', value.meshes],
+    ['Primitives', value.primitives],
+    ['Vertices', value.vertices.toLocaleString()],
+    ['Triangles', value.triangles.toLocaleString()],
+    ['Materials', value.materials],
+    ['Textures', value.textures],
+    ['Bones', value.bones],
+    ['Clips', value.clips],
+    ['Morph targets', value.morphTargets],
+    ['GPU estimate', `${(value.memoryBytes / 1_048_576).toFixed(2)} MiB`],
+    [
+      'Bounds',
+      value.bounds
+        ? `${value.bounds.x.toFixed(2)} × ${value.bounds.y.toFixed(2)} × ${value.bounds.z.toFixed(2)} units`
+        : 'No renderable bounds',
+    ],
+  ];
+  return (
+    <dl>
+      {rows.map(([label, result]) => (
+        <div key={label} style={{ display: 'flex', justifyContent: 'space-between' }}>
+          <dt>{label}</dt>
+          <dd>{result}</dd>
         </div>
-      </SectionHeader>
-    </div>
+      ))}
+    </dl>
   );
 }
+
+export function frameInteractiveModel(
+  model: THREE.Object3D,
+  camera: THREE.PerspectiveCamera | THREE.OrthographicCamera,
+  controls: OrbitControls,
+): void {
+  const { center, size } = measureAssetPreview(model, 'perspective');
+  const maxDim = Math.max(size.x, size.y, size.z) || 1;
+  const distance =
+    camera instanceof THREE.PerspectiveCamera
+      ? (maxDim / (2 * Math.tan((camera.fov * Math.PI) / 360))) * 1.3
+      : maxDim * 2;
+  const direction = new THREE.Vector3(1, 0.72, 1).normalize();
+  camera.position.copy(center).addScaledVector(direction, distance);
+  camera.near = distance * 0.01;
+  camera.far = distance * 20;
+  if (camera instanceof THREE.OrthographicCamera) {
+    const element = controls.domElement;
+    const aspect = Math.max(element?.clientWidth ?? 1, 1) / Math.max(element?.clientHeight ?? 1, 1);
+    const halfHeight = maxDim * 0.65;
+    camera.left = -halfHeight * aspect;
+    camera.right = halfHeight * aspect;
+    camera.top = halfHeight;
+    camera.bottom = -halfHeight;
+    camera.zoom = 1;
+  }
+  camera.updateProjectionMatrix();
+  controls.target.copy(center);
+  controls.update();
+}
+
+function frameRuntime(runtime: ModelViewerRuntime | null): void {
+  if (runtime) frameInteractiveModel(runtime.model, runtime.camera, runtime.controls);
+}
+
+function setCameraPreset(runtime: ModelViewerRuntime | null, preset: ModelCameraPreset): void {
+  if (!runtime) return;
+  const { center, size } = measureAssetPreview(runtime.model, 'perspective');
+  const maxDim = Math.max(size.x, size.y, size.z) || 1;
+  const distance =
+    runtime.camera instanceof THREE.PerspectiveCamera
+      ? (maxDim / (2 * Math.tan((runtime.camera.fov * Math.PI) / 360))) * 1.3
+      : maxDim * 2;
+  runtime.camera.position.copy(center).addScaledVector(cameraPresetDirection(preset), distance);
+  runtime.camera.up.set(0, preset === 'top' ? 0 : 1, preset === 'top' ? -1 : 0);
+  runtime.camera.lookAt(center);
+  runtime.camera.updateProjectionMatrix();
+  runtime.controls.target.copy(center);
+  runtime.controls.update();
+}
+
+function applyModelDiagnosticMode(runtime: ModelViewerRuntime, mode: ModelDiagnosticMode): void {
+  for (const helper of [...runtime.helpers]) {
+    if (!helper.name.startsWith('__asset_editor_diagnostic')) continue;
+    runtime.scene.remove(helper);
+    runtime.helpers.splice(runtime.helpers.indexOf(helper), 1);
+    disposeAssetPreviewSnapshot(helper);
+  }
+  runtime.scene.overrideMaterial?.dispose();
+  runtime.scene.overrideMaterial = null;
+  if (mode === 'unlit')
+    runtime.scene.overrideMaterial = new THREE.MeshBasicMaterial({ color: 0xbec7d1 });
+  if (mode === 'wireframe')
+    runtime.scene.overrideMaterial = new THREE.MeshBasicMaterial({
+      color: 0x8ed0ff,
+      wireframe: true,
+    });
+  if (mode === 'normals') runtime.scene.overrideMaterial = new THREE.MeshNormalMaterial();
+  if (mode === 'vertex-colors')
+    runtime.scene.overrideMaterial = new THREE.MeshBasicMaterial({ vertexColors: true });
+  if (mode === 'uv') {
+    runtime.scene.overrideMaterial = new THREE.ShaderMaterial({
+      vertexShader:
+        'varying vec2 vUv; void main(){ vUv=uv; gl_Position=projectionMatrix*modelViewMatrix*vec4(position,1.0); }',
+      fragmentShader: 'varying vec2 vUv; void main(){ gl_FragColor=vec4(vUv,0.0,1.0); }',
+    });
+  }
+  if (mode === 'bounds') {
+    const helper = new THREE.BoxHelper(runtime.model, 0xffb454);
+    helper.name = '__asset_editor_diagnostic_bounds';
+    runtime.scene.add(helper);
+    runtime.helpers.push(helper);
+  }
+  if (mode === 'skeleton') {
+    const helper = new THREE.SkeletonHelper(runtime.model);
+    helper.name = '__asset_editor_diagnostic_skeleton';
+    runtime.scene.add(helper);
+    runtime.helpers.push(helper);
+  }
+}
+
+function disposeModel(root: THREE.Object3D): void {
+  disposeAssetPreviewSnapshot(root);
+  root.traverse((object) => {
+    const instanced = object as THREE.InstancedMesh;
+    if (instanced.isInstancedMesh) instanced.morphTexture?.dispose();
+    const mesh = object as THREE.Mesh;
+    mesh.geometry?.dispose();
+    if (!mesh.material) return;
+    const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+    for (const material of materials) {
+      for (const value of Object.values(material)) {
+        if (value instanceof THREE.Texture) value.dispose();
+      }
+      material.dispose();
+    }
+  });
+}