@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/asset-preview.ts

@@ -0,0 +1,906 @@
+import { gltfLoader } from '@engine/loader';
+import * as THREE from 'three';
+
+export const ASSET_PREVIEW_VIEWS = ['front', 'right', 'top', 'perspective'] as const;
+export type AssetPreviewView = (typeof ASSET_PREVIEW_VIEWS)[number];
+export type AssetPreviewBackground = 'neutral' | 'transparent';
+
+export interface AssetPreviewOptions {
+  width?: number;
+  height?: number;
+  background?: AssetPreviewBackground;
+}
+
+export interface AssetPreviewImage {
+  view: AssetPreviewView;
+  base64: string;
+  mimeType: 'image/png';
+}
+
+export interface AssetPreviewCapture {
+  width: number;
+  height: number;
+  views: AssetPreviewImage[];
+  contactSheet: {
+    width: number;
+    height: number;
+    base64: string;
+    mimeType: 'image/png';
+  };
+}
+
+export interface AssetPreviewFraming {
+  center: THREE.Vector3;
+  size: THREE.Vector3;
+  radius: number;
+}
+
+type MorphableObject = THREE.Object3D & {
+  morphTargetDictionary?: Record<string, number>;
+  morphTargetInfluences?: number[];
+};
+
+const DEFAULT_SIZE = 512;
+const MIN_SIZE = 64;
+// Four views plus the 2x2 sheet cross the editor relay as base64 JSON. At
+// 1024px even incompressible RGBA data remains below its 50 MB request limit.
+const MAX_SIZE = 1024;
+const PADDING = 1.2;
+const NEUTRAL_COLOR = 0x20242a;
+const EDITOR_LAYER = 31;
+const MODEL_FETCH_TIMEOUT_MS = 25_000;
+const MAX_MODEL_BYTES = 64 * 1024 * 1024;
+
+const LABEL_GLYPHS: Record<string, readonly string[]> = {
+  F: ['11111', '10000', '10000', '11110', '10000', '10000', '10000'],
+  R: ['11110', '10001', '10001', '11110', '10100', '10010', '10001'],
+  O: ['01110', '10001', '10001', '10001', '10001', '10001', '01110'],
+  N: ['10001', '11001', '11001', '10101', '10011', '10011', '10001'],
+  T: ['11111', '00100', '00100', '00100', '00100', '00100', '00100'],
+  I: ['11111', '00100', '00100', '00100', '00100', '00100', '11111'],
+  G: ['01110', '10001', '10000', '10111', '10001', '10001', '01110'],
+  H: ['10001', '10001', '10001', '11111', '10001', '10001', '10001'],
+  P: ['11110', '10001', '10001', '11110', '10000', '10000', '10000'],
+  '3': ['11110', '00001', '00001', '01110', '00001', '00001', '11110'],
+  '/': ['00001', '00010', '00100', '00100', '01000', '10000', '10000'],
+  '4': ['00010', '00110', '01010', '10010', '11111', '00010', '00010'],
+};
+
+function checkedDimension(value: number | undefined): number {
+  const resolved = value ?? DEFAULT_SIZE;
+  if (!Number.isInteger(resolved) || resolved < MIN_SIZE || resolved > MAX_SIZE) {
+    throw new Error(`Asset preview dimensions must be integers from ${MIN_SIZE} to ${MAX_SIZE}.`);
+  }
+  return resolved;
+}
+
+function pngBase64(canvas: HTMLCanvasElement): string {
+  const dataUrl = canvas.toDataURL('image/png');
+  const comma = dataUrl.indexOf(',');
+  return comma >= 0 ? dataUrl.slice(comma + 1) : dataUrl;
+}
+
+/**
+ * Build a render-only snapshot of an authored subtree. The source remains the
+ * live Object3D truth: it is never reparented, hidden, normalized, or edited.
+ * Skinned, morphed, and instanced render semantics are preserved while the
+ * snapshot shares immutable geometry/material resources.
+ */
+export function createAssetPreviewSnapshot(source: THREE.Object3D): THREE.Object3D {
+  // A scene entity can legally reference bones owned above/outside its selected
+  // root (for example a visual child attached beneath an entity shell). Such a
+  // partial skeleton cannot be rebound honestly inside an isolated clone, so
+  // it takes the explicit bind-geometry fallback below.
+  const sourceNodes = new Set<THREE.Object3D>();
+  let hasExternalBones = false;
+  source.traverse((object) => {
+    sourceNodes.add(object);
+  });
+  source.traverse((object) => {
+    const skinned = object as THREE.SkinnedMesh;
+    if (!skinned.isSkinnedMesh) return;
+    if (skinned.skeleton.bones.some((bone) => !bone || !sourceNodes.has(bone))) {
+      hasExternalBones = true;
+    }
+  });
+  if (hasExternalBones) {
+    throw new Error(
+      'Asset preview selection references bones outside its hierarchy. Select the complete skeleton root.',
+    );
+  }
+  const snapshot = cloneRenderableHierarchy(source);
+
+  // Preserve the selected root's authored world-space presentation even when
+  // it lives below transformed parents. Descendant local transforms are kept.
+  // Keep the exact composed matrix. Decomposing a rotated, non-uniformly
+  // scaled ancestor chain into TRS would discard shear and change geometry.
+  const exactWorldMatrix = objectWorldMatrix(source);
+  snapshot.matrix.copy(exactWorldMatrix);
+  snapshot.matrix.decompose(snapshot.position, snapshot.quaternion, snapshot.scale);
+  snapshot.matrixAutoUpdate = false;
+  snapshot.matrixWorld.copy(exactWorldMatrix);
+  snapshot.matrixWorldAutoUpdate = source.matrixWorldAutoUpdate;
+  // Isolation intentionally reveals a selected root that is hidden in the
+  // scene; descendant visibility remains authored and the source is untouched.
+  snapshot.visible = true;
+
+  // Editor-only helpers are presentation siblings/children, never asset data.
+  const helpers: THREE.Object3D[] = [];
+  snapshot.traverse((object) => {
+    if (object !== snapshot && object.userData['editorHelper']) helpers.push(object);
+  });
+  for (const helper of helpers) helper.parent?.remove(helper);
+
+  return snapshot;
+}
+
+function objectWorldMatrix(object: THREE.Object3D): THREE.Matrix4 {
+  const chain: THREE.Object3D[] = [];
+  let current: THREE.Object3D | null = object;
+  while (current) {
+    chain.push(current);
+    current = current.parent;
+  }
+  const manualBoundary = chain.findIndex((node) => !node.matrixWorldAutoUpdate);
+  const world =
+    manualBoundary >= 0 ? chain[manualBoundary]!.matrixWorld.clone() : new THREE.Matrix4();
+  const local = new THREE.Matrix4();
+  const firstLocal = manualBoundary >= 0 ? manualBoundary - 1 : chain.length - 1;
+  for (let index = firstLocal; index >= 0; index--) {
+    const node = chain[index]!;
+    if (node.matrixAutoUpdate) local.compose(node.position, node.quaternion, node.scale);
+    else local.copy(node.matrix);
+    world.multiply(local);
+  }
+  return world;
+}
+
+/**
+ * Clone a complete authored hierarchy without copying editor-only helpers or
+ * arbitrary userData. Object3D.clone JSON-serializes userData, which is unsafe
+ * for live AnimationMixer references, while SkeletonUtils.clone first invokes
+ * that same recursive clone. This direct render clone keeps Three.js object
+ * semantics and remaps complete internal skeletons after building the tree.
+ */
+function cloneRenderableHierarchy(source: THREE.Object3D): THREE.Object3D {
+  const cloneBySource = new Map<THREE.Object3D, THREE.Object3D>();
+  const skinnedPairs: Array<[THREE.SkinnedMesh, THREE.SkinnedMesh]> = [];
+
+  const cloneNode = (object: THREE.Object3D): THREE.Object3D => {
+    const clone = createRenderClone(object);
+    cloneBySource.set(object, clone);
+    copyObjectPresentation(object, clone);
+    if ((object as THREE.SkinnedMesh).isSkinnedMesh) {
+      skinnedPairs.push([object as THREE.SkinnedMesh, clone as THREE.SkinnedMesh]);
+    }
+    const sourceLod = object as THREE.LOD;
+    if (sourceLod.isLOD) {
+      const cloneLod = clone as THREE.LOD;
+      // A deterministic still preview freezes auto-updating LODs to one level.
+      // Manually controlled LODs retain their exact authored visibility, which
+      // may intentionally contain zero or several visible levels.
+      const visibleLevels = sourceLod.levels.filter((level) => level.object.visible);
+      const activeSourceLevel = visibleLevels.length === 1 ? visibleLevels[0] : sourceLod.levels[0];
+      cloneLod.autoUpdate = false;
+      const levelObjects = new Set(sourceLod.levels.map((level) => level.object));
+      for (const level of sourceLod.levels) {
+        if (isEditorPresentation(level.object)) continue;
+        const levelClone = cloneNode(level.object);
+        levelClone.visible = sourceLod.autoUpdate
+          ? level === activeSourceLevel
+          : level.object.visible;
+        cloneLod.addLevel(levelClone, level.distance, level.hysteresis);
+      }
+      for (const child of object.children) {
+        if (!levelObjects.has(child) && !isEditorPresentation(child)) clone.add(cloneNode(child));
+      }
+    } else {
+      for (const child of object.children) {
+        if (!isEditorPresentation(child)) clone.add(cloneNode(child));
+      }
+    }
+    return clone;
+  };
+
+  const root = cloneNode(source);
+  for (const [original, clone] of skinnedPairs) {
+    const skeleton = original.skeleton.clone();
+    skeleton.bones = original.skeleton.bones.map((bone) => {
+      const mapped = cloneBySource.get(bone);
+      if (!(mapped as THREE.Bone | undefined)?.isBone) {
+        throw new Error(`Asset preview could not map skeleton bone: ${bone.name || bone.uuid}`);
+      }
+      return mapped as THREE.Bone;
+    });
+    clone.skeleton = skeleton;
+    clone.bindMode = original.bindMode;
+    clone.bindMatrix.copy(original.bindMatrix);
+    clone.bindMatrixInverse.copy(original.bindMatrixInverse);
+  }
+  return root;
+}
+
+function createRenderClone(object: THREE.Object3D): THREE.Object3D {
+  const skinned = object as THREE.SkinnedMesh;
+  if (skinned.isSkinnedMesh) return new THREE.SkinnedMesh(skinned.geometry, skinned.material);
+  const instanced = object as THREE.InstancedMesh;
+  if (instanced.isInstancedMesh) {
+    const clone = new THREE.InstancedMesh(instanced.geometry, instanced.material, instanced.count);
+    clone.instanceMatrix.copy(instanced.instanceMatrix);
+    clone.instanceColor = instanced.instanceColor
+      ? (instanced.instanceColor.clone() as THREE.InstancedBufferAttribute)
+      : null;
+    clone.morphTexture = instanced.morphTexture;
+    return clone;
+  }
+  const mesh = object as THREE.Mesh;
+  if (mesh.isMesh) return new THREE.Mesh(mesh.geometry, mesh.material);
+  const line = object as THREE.Line;
+  if ((object as THREE.LineSegments).isLineSegments) {
+    return new THREE.LineSegments(line.geometry, line.material);
+  }
+  if ((object as THREE.LineLoop).isLineLoop)
+    return new THREE.LineLoop(line.geometry, line.material);
+  if (line.isLine) return new THREE.Line(line.geometry, line.material);
+  const points = object as THREE.Points;
+  if (points.isPoints) return new THREE.Points(points.geometry, points.material);
+  const sprite = object as THREE.Sprite;
+  if (sprite.isSprite) return new THREE.Sprite(sprite.material);
+  if ((object as THREE.LOD).isLOD) return new THREE.LOD();
+  if ((object as THREE.Bone).isBone) return new THREE.Bone();
+  if ((object as THREE.Group).isGroup) return new THREE.Group();
+  return new THREE.Object3D();
+}
+
+function copyObjectPresentation(source: THREE.Object3D, clone: THREE.Object3D): void {
+  clone.name = source.name;
+  clone.up.copy(source.up);
+  clone.position.copy(source.position);
+  clone.quaternion.copy(source.quaternion);
+  clone.scale.copy(source.scale);
+  clone.matrix.copy(source.matrix);
+  clone.matrixWorld.copy(source.matrixWorld);
+  clone.matrixAutoUpdate = source.matrixAutoUpdate;
+  clone.matrixWorldAutoUpdate = source.matrixWorldAutoUpdate;
+  clone.visible = source.visible;
+  clone.castShadow = source.castShadow;
+  clone.receiveShadow = source.receiveShadow;
+  // Separate preview renderers must not populate boundingSphere on geometry
+  // shared read-only with the live source. The deterministic cameras already
+  // frame the snapshot, so clone-only culling is unnecessary.
+  clone.frustumCulled = false;
+  clone.renderOrder = source.renderOrder;
+  // Asset Editor is a presentation scene with layer-0 cameras. Normalize only
+  // the clone so authored custom-layer content is visible without changing the
+  // live entity's layer assignment.
+  clone.layers.set(0);
+  clone.animations = [...source.animations];
+
+  const sourceMorph = source as MorphableObject;
+  const cloneMorph = clone as MorphableObject;
+  if (sourceMorph.morphTargetInfluences) {
+    if (sourceMorph.morphTargetDictionary) {
+      cloneMorph.morphTargetDictionary = { ...sourceMorph.morphTargetDictionary };
+    }
+    cloneMorph.morphTargetInfluences = [...sourceMorph.morphTargetInfluences];
+  }
+  const sourceSprite = source as THREE.Sprite;
+  if (sourceSprite.isSprite) (clone as THREE.Sprite).center.copy(sourceSprite.center);
+}
+
+function isEditorPresentation(object: THREE.Object3D): boolean {
+  const editorLayerMask = 1 << EDITOR_LAYER;
+  return Boolean(
+    object.userData['editorHelper'] ||
+      object.userData['editorIcon'] ||
+      (object.layers.mask & editorLayerMask) !== 0,
+  );
+}
+
+export function disposeAssetPreviewSnapshot(root: THREE.Object3D): void {
+  const skeletons = new Set<THREE.Skeleton>();
+  root.traverse((object) => {
+    const skinned = object as THREE.SkinnedMesh;
+    if (skinned.isSkinnedMesh) skeletons.add(skinned.skeleton);
+  });
+  for (const skeleton of skeletons) skeleton.dispose();
+}
+
+export function measureAssetPreview(
+  object: THREE.Object3D,
+  view: AssetPreviewView = 'front',
+): AssetPreviewFraming {
+  object.updateWorldMatrix(true, true);
+  const box = readOnlyRenderableBounds(object, view);
+  if (box.isEmpty()) throw new Error('Asset preview source has no renderable bounds.');
+  const center = box.getCenter(new THREE.Vector3());
+  const size = box.getSize(new THREE.Vector3());
+  return {
+    center,
+    size,
+    radius: Math.max(size.length() / 2, 0.001),
+  };
+}
+
+/** Read exact renderable vertices without populating shared geometry bounds. */
+function readOnlyRenderableBounds(root: THREE.Object3D, view: AssetPreviewView): THREE.Box3 {
+  const box = new THREE.Box3();
+  const vertex = new THREE.Vector3();
+  const instanceMatrix = new THREE.Matrix4();
+  const basis = assetViewBasis(view);
+  const visit = (object: THREE.Object3D): void => {
+    if (!object.visible) return;
+    const lod = object as THREE.LOD;
+    if (lod.isLOD && lod.levels.length > 0) {
+      const levelObjects = new Set(lod.levels.map((level) => level.object));
+      for (const level of lod.levels) visit(level.object);
+      for (const child of object.children) {
+        if (!levelObjects.has(child)) visit(child);
+      }
+      return;
+    }
+    const sprite = object as THREE.Sprite;
+    if (sprite.isSprite) {
+      if (sprite.material.visible) {
+        if (view === 'perspective' && !sprite.material.sizeAttenuation) {
+          throw new Error(
+            'Asset preview cannot deterministically frame a perspective Sprite with sizeAttenuation disabled.',
+          );
+        }
+        const anchor = new THREE.Vector3().setFromMatrixPosition(sprite.matrixWorld);
+        const scale = new THREE.Vector3().setFromMatrixScale(sprite.matrixWorld);
+        const cosine = Math.cos(sprite.material.rotation);
+        const sine = Math.sin(sprite.material.rotation);
+        for (const x of [-sprite.center.x, 1 - sprite.center.x]) {
+          for (const y of [-sprite.center.y, 1 - sprite.center.y]) {
+            const scaledX = x * Math.abs(scale.x);
+            const scaledY = y * Math.abs(scale.y);
+            const rotatedX = cosine * scaledX - sine * scaledY;
+            const rotatedY = sine * scaledX + cosine * scaledY;
+            box.expandByPoint(
+              anchor
+                .clone()
+                .addScaledVector(basis.right, rotatedX)
+                .addScaledVector(basis.up, rotatedY),
+            );
+          }
+        }
+      }
+    }
+    // Sprite's internal unit quad is shader-billboarded above; treating that
+    // private geometry as an ordinary world-space mesh would double-count it.
+    const geometry = sprite.isSprite
+      ? undefined
+      : (object as THREE.Mesh | THREE.Line | THREE.Points).geometry;
+    if (geometry) {
+      const position = geometry.getAttribute('position');
+      if (position) {
+        const renderedIndices = collectRenderedVertexIndices(object, geometry, position.count);
+        const instanced = object as THREE.InstancedMesh;
+        if (instanced.isInstancedMesh) {
+          const morphProbe = new THREE.Mesh(instanced.geometry, instanced.material);
+          for (let instance = 0; instance < instanced.count; instance++) {
+            instanced.getMatrixAt(instance, instanceMatrix);
+            if (instanced.morphTexture) instanced.getMorphAt(instance, morphProbe);
+            for (const index of renderedIndices) {
+              morphProbe.getVertexPosition(index, vertex);
+              vertex.applyMatrix4(instanceMatrix).applyMatrix4(instanced.matrixWorld);
+              box.expandByPoint(vertex);
+            }
+          }
+        } else {
+          const mesh = object as THREE.Mesh;
+          for (const index of renderedIndices) {
+            if (mesh.isMesh) mesh.getVertexPosition(index, vertex);
+            else getNonMeshVertexPosition(object as MorphableObject, geometry, index, vertex);
+            vertex.applyMatrix4(object.matrixWorld);
+            box.expandByPoint(vertex);
+          }
+        }
+      }
+    }
+    for (const child of object.children) visit(child);
+  };
+  visit(root);
+  return box;
+}
+
+function collectRenderedVertexIndices(
+  object: THREE.Object3D,
+  geometry: THREE.BufferGeometry,
+  positionCount: number,
+): number[] {
+  const material = (object as THREE.Mesh | THREE.Line | THREE.Points).material;
+  if (!material) return [];
+  const elementCount = geometry.index?.count ?? positionCount;
+  const drawStart = Math.max(0, geometry.drawRange.start);
+  const drawEnd = Math.min(
+    elementCount,
+    Number.isFinite(geometry.drawRange.count) ? drawStart + geometry.drawRange.count : elementCount,
+  );
+  const ranges: Array<[number, number]> = [];
+  if (Array.isArray(material)) {
+    for (const group of geometry.groups) {
+      const materialIndex = group.materialIndex ?? 0;
+      if (!material[materialIndex]?.visible) continue;
+      const start = Math.max(drawStart, group.start);
+      const end = Math.min(drawEnd, group.start + group.count);
+      if (end > start) ranges.push([start, end]);
+    }
+  } else if (material.visible && drawEnd > drawStart) {
+    ranges.push([drawStart, drawEnd]);
+  }
+  const indices: number[] = [];
+  for (const [start, end] of ranges) {
+    const count = assembledElementCount(object, end - start);
+    for (let element = start; element < start + count; element++) {
+      indices.push(geometry.index ? geometry.index.getX(element) : element);
+    }
+  }
+  return indices;
+}
+
+function assembledElementCount(object: THREE.Object3D, count: number): number {
+  if ((object as THREE.Mesh).isMesh) return count - (count % 3);
+  if ((object as THREE.LineSegments).isLineSegments) return count - (count % 2);
+  if ((object as THREE.Line).isLine) return count >= 2 ? count : 0;
+  return count;
+}
+
+function getNonMeshVertexPosition(
+  object: MorphableObject,
+  geometry: THREE.BufferGeometry,
+  index: number,
+  target: THREE.Vector3,
+): THREE.Vector3 {
+  const position = geometry.getAttribute('position');
+  target.fromBufferAttribute(position, index);
+  const morphPositions = geometry.morphAttributes['position'];
+  const influences = object.morphTargetInfluences;
+  if (!morphPositions || !influences) return target;
+  const base = target.clone();
+  const delta = new THREE.Vector3();
+  const sample = new THREE.Vector3();
+  for (let morphIndex = 0; morphIndex < morphPositions.length; morphIndex++) {
+    const influence = influences[morphIndex] ?? 0;
+    if (influence === 0) continue;
+    sample.fromBufferAttribute(morphPositions[morphIndex]!, index);
+    if (!geometry.morphTargetsRelative) sample.sub(base);
+    delta.addScaledVector(sample, influence);
+  }
+  return target.add(delta);
+}
+
+function orthographicCamera(
+  view: Exclude<AssetPreviewView, 'perspective'>,
+  framing: AssetPreviewFraming,
+  aspect: number,
+): THREE.OrthographicCamera {
+  const { center, size, radius } = framing;
+  let horizontal = size.x;
+  let vertical = size.y;
+  const basis = assetViewBasis(view);
+  const { direction, up } = basis;
+
+  if (view === 'right') {
+    horizontal = size.z;
+  } else {
+    if (view === 'top') {
+      horizontal = size.x;
+      vertical = size.z;
+    }
+  }
+
+  const halfHeight = Math.max(vertical / 2, horizontal / (2 * aspect), 0.001) * PADDING;
+  const halfWidth = halfHeight * aspect;
+  const camera = new THREE.OrthographicCamera(
+    -halfWidth,
+    halfWidth,
+    halfHeight,
+    -halfHeight,
+    0.01,
+    radius * 10 + 10,
+  );
+  camera.position.copy(center).addScaledVector(direction, radius * 3 + 1);
+  camera.up.copy(up);
+  camera.lookAt(center);
+  camera.updateProjectionMatrix();
+  camera.updateMatrixWorld(true);
+  return camera;
+}
+
+function perspectiveCamera(framing: AssetPreviewFraming, aspect: number): THREE.PerspectiveCamera {
+  const camera = new THREE.PerspectiveCamera(35, aspect, 0.01, framing.radius * 20 + 20);
+  const halfVerticalFov = THREE.MathUtils.degToRad(camera.fov / 2);
+  const halfHorizontalFov = Math.atan(Math.tan(halfVerticalFov) * aspect);
+  const { direction: viewDirection, right, up } = assetViewBasis('perspective');
+  const half = framing.size.clone().multiplyScalar(0.5);
+  let distance = 0;
+  for (const x of [-1, 1]) {
+    for (const y of [-1, 1]) {
+      for (const z of [-1, 1]) {
+        const offset = new THREE.Vector3(x * half.x, y * half.y, z * half.z);
+        const towardCamera = offset.dot(viewDirection);
+        distance = Math.max(
+          distance,
+          towardCamera + (Math.abs(offset.dot(right)) * PADDING) / Math.tan(halfHorizontalFov),
+          towardCamera + (Math.abs(offset.dot(up)) * PADDING) / Math.tan(halfVerticalFov),
+        );
+      }
+    }
+  }
+  camera.position.copy(framing.center).addScaledVector(viewDirection, Math.max(distance, 0.01));
+  camera.lookAt(framing.center);
+  camera.updateProjectionMatrix();
+  camera.updateMatrixWorld(true);
+  return camera;
+}
+
+function assetViewBasis(view: AssetPreviewView): {
+  direction: THREE.Vector3;
+  right: THREE.Vector3;
+  up: THREE.Vector3;
+} {
+  const direction =
+    view === 'front'
+      ? new THREE.Vector3(0, 0, 1)
+      : view === 'right'
+        ? new THREE.Vector3(1, 0, 0)
+        : view === 'top'
+          ? new THREE.Vector3(0, 1, 0)
+          : new THREE.Vector3(1, 0.72, 1).normalize();
+  const provisionalUp = view === 'top' ? new THREE.Vector3(0, 0, -1) : new THREE.Vector3(0, 1, 0);
+  const right = provisionalUp.clone().cross(direction).normalize();
+  const up = direction.clone().cross(right).normalize();
+  return { direction, right, up };
+}
+
+export function createAssetPreviewCamera(
+  view: AssetPreviewView,
+  framing: AssetPreviewFraming,
+  aspect: number,
+): THREE.Camera {
+  return view === 'perspective'
+    ? perspectiveCamera(framing, aspect)
+    : orthographicCamera(view, framing, aspect);
+}
+
+function createPreviewScene(snapshot: THREE.Object3D, framing: AssetPreviewFraming): THREE.Scene {
+  const scene = new THREE.Scene();
+  scene.add(snapshot);
+  scene.add(new THREE.HemisphereLight(0xffffff, 0x354052, 1.8));
+  const key = new THREE.DirectionalLight(0xffffff, 2.2);
+  key.position
+    .copy(framing.center)
+    .addScaledVector(new THREE.Vector3(1, 1.5, 1), framing.radius * 3);
+  scene.add(key);
+  const fill = new THREE.DirectionalLight(0xbfd7ff, 0.8);
+  fill.position
+    .copy(framing.center)
+    .addScaledVector(new THREE.Vector3(-1, 0.5, -0.7), framing.radius * 2);
+  scene.add(fill);
+  return scene;
+}
+
+function drawBitmapLabel(
+  context: CanvasRenderingContext2D,
+  label: string,
+  x: number,
+  y: number,
+  cellWidth: number,
+  cellHeight: number,
+): void {
+  const scale = Math.max(1, Math.floor(Math.min(cellWidth, cellHeight) / 128));
+  const padding = scale * 3;
+  const advance = scale * 6;
+  const width = label.length * advance - scale + padding * 2;
+  const height = scale * 7 + padding * 2;
+  context.fillStyle = 'rgba(0, 0, 0, 0.62)';
+  context.fillRect(x, y, width, height);
+  context.fillStyle = '#ffffff';
+  for (let glyphIndex = 0; glyphIndex < label.length; glyphIndex++) {
+    const glyph = LABEL_GLYPHS[label[glyphIndex]!]!;
+    for (let row = 0; row < glyph.length; row++) {
+      for (let column = 0; column < glyph[row]!.length; column++) {
+        if (glyph[row]![column] === '1') {
+          context.fillRect(
+            x + padding + glyphIndex * advance + column * scale,
+            y + padding + row * scale,
+            scale,
+            scale,
+          );
+        }
+      }
+    }
+  }
+}
+
+export function captureObjectAssetPreview(
+  source: THREE.Object3D,
+  options: AssetPreviewOptions = {},
+): AssetPreviewCapture {
+  const width = checkedDimension(options.width);
+  const height = checkedDimension(options.height);
+  const background = options.background ?? 'neutral';
+  const snapshot = createAssetPreviewSnapshot(source);
+  let renderer: THREE.WebGLRenderer | null = null;
+
+  try {
+    const framing = measureAssetPreview(snapshot, 'perspective');
+    const scene = createPreviewScene(snapshot, framing);
+    const activeRenderer = new THREE.WebGLRenderer({
+      antialias: true,
+      alpha: true,
+      preserveDrawingBuffer: true,
+    });
+    renderer = activeRenderer;
+    activeRenderer.setPixelRatio(1);
+    activeRenderer.outputColorSpace = THREE.SRGBColorSpace;
+    activeRenderer.toneMapping = THREE.ACESFilmicToneMapping;
+    activeRenderer.toneMappingExposure = 1;
+    activeRenderer.setClearColor(NEUTRAL_COLOR, background === 'transparent' ? 0 : 1);
+    const cameras = new Map<AssetPreviewView, THREE.Camera>();
+    for (const view of ASSET_PREVIEW_VIEWS) {
+      cameras.set(
+        view,
+        createAssetPreviewCamera(view, measureAssetPreview(snapshot, view), width / height),
+      );
+    }
+
+    const views: AssetPreviewImage[] = [];
+    const sheetWidth = width * 2;
+    const sheetHeight = height * 2;
+    const sheetCanvas = document.createElement('canvas');
+    sheetCanvas.width = sheetWidth;
+    sheetCanvas.height = sheetHeight;
+    const sheetContext = sheetCanvas.getContext('2d');
+    if (!sheetContext) throw new Error('Unable to create the asset preview contact sheet.');
+    activeRenderer.setSize(width, height, false);
+    ASSET_PREVIEW_VIEWS.forEach((view, index) => {
+      activeRenderer.render(scene, cameras.get(view)!);
+      views.push({ view, base64: pngBase64(activeRenderer.domElement), mimeType: 'image/png' });
+      const column = index % 2;
+      const rowFromTop = Math.floor(index / 2);
+      const x = column * width;
+      const y = rowFromTop * height;
+      sheetContext.drawImage(activeRenderer.domElement, x, y, width, height);
+      const label = view === 'perspective' ? '3/4' : view.toUpperCase();
+      drawBitmapLabel(sheetContext, label, x, y, width, height);
+    });
+    const contactSheet = {
+      width: sheetWidth,
+      height: sheetHeight,
+      base64: pngBase64(sheetCanvas),
+      mimeType: 'image/png' as const,
+    };
+    return { width, height, views, contactSheet };
+  } finally {
+    renderer?.dispose();
+    renderer?.forceContextLoss();
+    disposeAssetPreviewSnapshot(snapshot);
+  }
+}
+
+function projectModelUrl(assetPath: string): URL {
+  if (
+    !assetPath.startsWith('/') ||
+    assetPath.startsWith('//') ||
+    assetPath.includes('\\') ||
+    assetPath.includes('?') ||
+    assetPath.includes('#')
+  ) {
+    throw new Error('Asset Editor model paths must be absolute project-root .glb or .gltf paths.');
+  }
+  let decodedPath: string;
+  try {
+    decodedPath = decodeURIComponent(assetPath);
+  } catch {
+    throw new Error('Asset Editor model path contains invalid URL encoding.');
+  }
+  if (decodedPath.split('/').some((segment) => segment === '.' || segment === '..')) {
+    throw new Error('Asset Editor model paths cannot traverse outside the project root.');
+  }
+  const projectOrigin = globalThis.location?.origin ?? 'http://localhost';
+  const url = new URL(assetPath, projectOrigin);
+  if (url.origin !== projectOrigin || !url.pathname.toLowerCase().match(/\.gl(?:b|tf)$/)) {
+    throw new Error('Asset Editor loads bounded, same-origin project .glb or .gltf files only.');
+  }
+  return url;
+}
+
+async function boundedModelBytes(
+  url: URL,
+  signal: AbortSignal,
+  maxBytes = MAX_MODEL_BYTES,
+): Promise<ArrayBuffer> {
+  const response = await fetch(url, { signal });
+  if (!response.ok) {
+    throw new Error(`Unable to load project model (${response.status} ${response.statusText}).`);
+  }
+  const declaredLength = Number(response.headers.get('content-length'));
+  if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
+    throw new Error(
+      `Asset Editor project models must be ${MAX_MODEL_BYTES / 1024 / 1024} MiB or less.`,
+    );
+  }
+  if (!response.body) {
+    const bytes = await response.arrayBuffer();
+    if (bytes.byteLength > maxBytes) {
+      throw new Error(
+        `Asset Editor project models must be ${MAX_MODEL_BYTES / 1024 / 1024} MiB or less.`,
+      );
+    }
+    return bytes;
+  }
+
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > maxBytes) {
+        await reader.cancel();
+        throw new Error(
+          `Asset Editor project models must be ${MAX_MODEL_BYTES / 1024 / 1024} MiB or less.`,
+        );
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const combined = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    combined.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return combined.buffer;
+}
+
+function parseGltfData(
+  data: ArrayBuffer | string,
+  sourceUrl: URL,
+  signal: AbortSignal,
+): Promise<THREE.Object3D> {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (callback: () => void) => {
+      if (settled) return false;
+      settled = true;
+      signal.removeEventListener('abort', abort);
+      callback();
+      return true;
+    };
+    const abort = () => finish(() => reject(signal.reason));
+    signal.addEventListener('abort', abort, { once: true });
+    if (signal.aborted) {
+      abort();
+      return;
+    }
+    gltfLoader.parse(
+      data,
+      new URL('.', sourceUrl).href,
+      (gltf) => {
+        if (!finish(() => resolve(gltf.scene))) {
+          disposeOwnedModel(gltf.scene);
+        }
+      },
+      (error) => finish(() => reject(error)),
+    );
+  });
+}
+
+type ExternalGltfResource = { uri?: unknown; mimeType?: unknown };
+
+function projectDependencyUrl(uri: string, sourceUrl: URL): URL {
+  if (uri.includes('\\') || uri.includes('?') || uri.includes('#')) {
+    throw new Error('Asset Editor .gltf dependencies must be plain same-origin project paths.');
+  }
+  const url = new URL(uri, sourceUrl);
+  if (url.origin !== sourceUrl.origin) {
+    throw new Error('Asset Editor .gltf dependencies must stay on the project origin.');
+  }
+  return url;
+}
+
+function dependencyMimeType(resource: ExternalGltfResource, url: URL): string {
+  if (typeof resource.mimeType === 'string') return resource.mimeType;
+  const extension = url.pathname.split('.').pop()?.toLowerCase();
+  if (extension === 'png') return 'image/png';
+  if (extension === 'jpg' || extension === 'jpeg') return 'image/jpeg';
+  if (extension === 'webp') return 'image/webp';
+  return 'application/octet-stream';
+}
+
+async function inlineExternalGltfResources(
+  bytes: ArrayBuffer,
+  sourceUrl: URL,
+  signal: AbortSignal,
+): Promise<string> {
+  let document: Record<string, unknown>;
+  try {
+    document = JSON.parse(new TextDecoder().decode(bytes)) as Record<string, unknown>;
+  } catch {
+    throw new Error('Asset Editor could not parse the project .gltf JSON document.');
+  }
+  const resources = [
+    ...(Array.isArray(document['buffers']) ? (document['buffers'] as ExternalGltfResource[]) : []),
+    ...(Array.isArray(document['images']) ? (document['images'] as ExternalGltfResource[]) : []),
+  ];
+  let totalBytes = bytes.byteLength;
+  for (const resource of resources) {
+    if (typeof resource.uri !== 'string' || resource.uri.startsWith('data:')) continue;
+    const dependencyUrl = projectDependencyUrl(resource.uri, sourceUrl);
+    const dependency = await boundedModelBytes(dependencyUrl, signal, MAX_MODEL_BYTES - totalBytes);
+    totalBytes += dependency.byteLength;
+    const dependencyBytes = new Uint8Array(dependency);
+    let binary = '';
+    for (let offset = 0; offset < dependencyBytes.length; offset += 32_768) {
+      binary += String.fromCharCode(...dependencyBytes.subarray(offset, offset + 32_768));
+    }
+    resource.uri = `data:${dependencyMimeType(resource, dependencyUrl)};base64,${btoa(binary)}`;
+  }
+  return JSON.stringify(document);
+}
+
+export async function loadProjectAssetModel(
+  assetPath: string,
+  externalSignal?: AbortSignal,
+): Promise<THREE.Object3D> {
+  const url = projectModelUrl(assetPath);
+  const controller = new AbortController();
+  const abortFromCaller = () => controller.abort(externalSignal?.reason);
+  if (externalSignal?.aborted) abortFromCaller();
+  else externalSignal?.addEventListener('abort', abortFromCaller, { once: true });
+  const timeout = globalThis.setTimeout(
+    () =>
+      controller.abort(new Error('Asset Editor project model load timed out after 25 seconds.')),
+    MODEL_FETCH_TIMEOUT_MS,
+  );
+  try {
+    const bytes = await boundedModelBytes(url, controller.signal);
+    controller.signal.throwIfAborted();
+    if (url.pathname.toLowerCase().endsWith('.glb')) {
+      return await parseGltfData(bytes, url, controller.signal);
+    }
+    const json = await inlineExternalGltfResources(bytes, url, controller.signal);
+    return await parseGltfData(json, url, controller.signal);
+  } finally {
+    globalThis.clearTimeout(timeout);
+    externalSignal?.removeEventListener('abort', abortFromCaller);
+  }
+}
+
+function disposeOwnedModel(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();
+    }
+  });
+}
+
+export async function captureModelAssetPreview(
+  assetPath: string,
+  options: AssetPreviewOptions = {},
+): Promise<AssetPreviewCapture> {
+  const model = await loadProjectAssetModel(assetPath);
+  try {
+    return captureObjectAssetPreview(model, options);
+  } finally {
+    disposeOwnedModel(model);
+  }
+}