@vgai/editor 0.4.0 → 0.4.1

package/src/asset-workflow/asset-capabilities.ts

@@ -22,6 +22,19 @@ export type AssetFormat =
   | 'ogg'
   | 'wav'
   | 'flac'
+  | 'ts'
+  | 'tsx'
+  | 'js'
+  | 'jsx'
+  | 'css'
+  | 'html'
+  | 'md'
+  | 'txt'
+  | 'mtl'
+  | 'csv'
+  | 'xml'
+  | 'yaml'
+  | 'yml'
   | 'vscn.json'
   | 'prefab.json'
   | 'mat.json'
@@ -64,6 +77,21 @@ const MODEL_PREVIEW_FORMATS = ['glb', 'gltf', 'fbx', 'obj', 'dae', 'stl', 'ply',
 const SOURCE_MODEL_FORMATS = ['blend', 'usd', 'usda', 'usdc'] as const;
 const IMAGE_FORMATS = ['png', 'jpg', 'jpeg', 'webp', 'gif', 'svg'] as const;
 const AUDIO_FORMATS = ['mp3', 'ogg', 'wav', 'flac'] as const;
+const TEXT_SOURCE_FORMATS = [
+  'txt',
+  'md',
+  'ts',
+  'tsx',
+  'js',
+  'jsx',
+  'css',
+  'html',
+  'mtl',
+  'csv',
+  'xml',
+  'yaml',
+  'yml',
+] as const;
 
 function row(
   format: AssetFormat,
@@ -130,6 +158,18 @@ export const ASSET_CAPABILITY_REGISTRY: ReadonlyMap<AssetFormat, AssetCapabiliti
       editor: 'audio',
     }),
   ),
+  ...TEXT_SOURCE_FORMATS.map((format) =>
+    row(format, {
+      kind: 'source',
+      previewable: true,
+      importable: true,
+      runtimeReady: false,
+      placeable: false,
+      animated: false,
+      importStrategy: 'copy-project',
+      editor: 'source',
+    }),
+  ),
   row('vscn.json', {
     kind: 'scene',
     previewable: false,

package/src/asset-workflow/asset-import-jobs.ts

@@ -0,0 +1,108 @@
+import { connectEvents } from '../editor-api';
+import { getEditorMode } from '../editor-mode';
+import type { AssetImportStage } from './import-contract';
+
+export interface AssetImportJob {
+  id: string;
+  label: string;
+  stage: AssetImportStage;
+  loaded: number;
+  total: number;
+  status: 'running' | 'imported' | 'skipped' | 'failed' | 'cancelled';
+  message?: string;
+  controller: AbortController;
+  retry?: () => void;
+}
+
+const jobs = new Map<string, AssetImportJob>();
+const listeners = new Set<() => void>();
+let version = 0;
+function notify(): void {
+  version++;
+  for (const listener of listeners) listener();
+}
+export function assetImportJobsVersion(): number {
+  return version;
+}
+export function subscribeAssetImportJobs(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+export function assetImportJobs(): readonly AssetImportJob[] {
+  return [...jobs.values()];
+}
+
+export function beginAssetImportJob(id: string, label: string): AssetImportJob {
+  const existing = jobs.get(id);
+  if (existing?.status === 'running') return existing;
+  const job: AssetImportJob = {
+    id,
+    label,
+    stage: 'fetch',
+    loaded: 0,
+    total: 0,
+    status: 'running',
+    controller: new AbortController(),
+  };
+  jobs.set(id, job);
+  notify();
+  return job;
+}
+export function updateAssetImportJob(
+  id: string,
+  patch: Partial<Omit<AssetImportJob, 'id' | 'controller'>>,
+): void {
+  const job = jobs.get(id);
+  if (!job) return;
+  Object.assign(job, patch);
+  notify();
+}
+export function cancelAssetImportJob(id: string): void {
+  const job = jobs.get(id);
+  if (!job || job.status !== 'running') return;
+  job.controller.abort(new DOMException('Import cancelled', 'AbortError'));
+  job.status = 'cancelled';
+  job.message = 'Cancelled before project commit.';
+  notify();
+}
+export function clearFinishedAssetImportJobs(): void {
+  for (const [id, job] of jobs) if (job.status !== 'running') jobs.delete(id);
+  notify();
+}
+export function resetAssetImportJobs(): void {
+  jobs.clear();
+  notify();
+}
+
+/** Keep jobs progressing independently of whether the Library document is mounted. */
+export function connectAssetImportProgressEvents(): () => void {
+  if (getEditorMode() === 'browser') return () => {};
+  const source = connectEvents();
+  const listener = (event: MessageEvent) => {
+    try {
+      const update = JSON.parse(event.data as string) as {
+        jobId?: string;
+        stage?: AssetImportStage;
+        loaded?: number;
+        total?: number;
+        message?: string;
+      };
+      if (!update.jobId || !update.stage) return;
+      updateAssetImportJob(update.jobId, {
+        stage: update.stage,
+        loaded: Math.max(0, update.loaded ?? 0),
+        total: Math.max(0, update.total ?? 0),
+        ...(update.message ? { message: update.message } : {}),
+      });
+    } catch {
+      // Optional progress cannot break a running import.
+    }
+  };
+  source.addEventListener('asset-import-progress', listener);
+  return () => {
+    source.removeEventListener('asset-import-progress', listener);
+    source.close();
+  };
+}

package/src/asset-workflow/asset-library-query.ts

@@ -89,6 +89,10 @@ function compareAssetSort(
   }
 }
 
+function compareText(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
 export function queryAssetLibrary(
   assets: readonly OnlineAsset[],
   filters: AssetLibraryFilters,
@@ -102,6 +106,9 @@ export function queryAssetLibrary(
   return [...filtered].sort((left, right) => {
     const order = compareAssetSort(left, right, sort, recentRank);
     if (order !== 0) return order;
-    return left.name.localeCompare(right.name) || left.id.localeCompare(right.id);
+    // Catalog identifiers and authored names are already Unicode strings. A
+    // locale collation here is both surprising (the order changes with the
+    // host locale) and disproportionately expensive across 12k+ entries.
+    return compareText(left.name, right.name) || compareText(left.id, right.id);
   });
 }

package/src/asset-workflow/asset-workflow-quality.ts

@@ -1,10 +1,12 @@
 export const ASSET_WORKFLOW_BUDGETS = {
   firstResultsMs: 500,
   filterResponseMs: 50,
+  scrollFrameMs: 16.7,
   importProgressLatencyMs: 100,
   maxMountedLibraryCards: 120,
   maxPreviewConcurrency: 2,
   maxActiveAssetEditorWebGlContexts: 1,
+  maxRetainedAssetEditorResources: 0,
   maxTelemetryEntries: 200,
 } as const;
 

package/src/asset-workflow/import-contract.ts

@@ -39,6 +39,8 @@ export const assetImportPlanSchema = z
       familyId: z.string().min(1),
       variantId: z.string().min(1),
       deliveryId: z.string().min(1),
+      source: z.string().min(1).optional(),
+      displayName: z.string().min(1).optional(),
     }),
     sourceFiles: z.array(importFileSchema).min(1),
     generatedFiles: z.array(safePathSchema),

package/src/asset-workflow/model-inspection.ts

@@ -16,6 +16,22 @@ export interface ModelInspection {
   hierarchy: Array<{ id: string; name: string; type: string; depth: number }>;
   materialNames: string[];
   textureNames: string[];
+  materialSlots: Array<{
+    id: string;
+    name: string;
+    type: string;
+    textureSlots: string[];
+  }>;
+  textureBindings: Array<{
+    materialId: string;
+    materialName: string;
+    slot: string;
+    textureName: string;
+    width: number | null;
+    height: number | null;
+    format: number;
+    colorSpace: string;
+  }>;
 }
 
 const textureKeys = [
@@ -37,6 +53,8 @@ const textureKeys = [
 export function inspectModel(root: THREE.Object3D): ModelInspection {
   const materials = new Set<THREE.Material>();
   const textures = new Set<THREE.Texture>();
+  const materialSlots = new Map<THREE.Material, string[]>();
+  const textureBindings: ModelInspection['textureBindings'] = [];
   const hierarchy: ModelInspection['hierarchy'] = [];
   let nodes = 0;
   let meshes = 0;
@@ -83,10 +101,31 @@ export function inspectModel(root: THREE.Object3D): ModelInspection {
         : [];
     for (const material of objectMaterials) {
       materials.add(material);
+      const slots = materialSlots.get(material) ?? [];
       for (const key of textureKeys) {
         const texture = (material as THREE.Material & Record<string, unknown>)[key];
-        if (texture instanceof THREE.Texture) textures.add(texture);
+        if (!(texture instanceof THREE.Texture)) continue;
+        textures.add(texture);
+        if (!slots.includes(key)) slots.push(key);
+        const image = texture.image as { width?: number; height?: number } | undefined;
+        if (
+          !textureBindings.some(
+            (binding) => binding.materialId === material.uuid && binding.slot === key,
+          )
+        ) {
+          textureBindings.push({
+            materialId: material.uuid,
+            materialName: material.name || material.type,
+            slot: key,
+            textureName: texture.name || texture.source.data?.src || 'Texture',
+            width: image?.width ?? null,
+            height: image?.height ?? null,
+            format: texture.format,
+            colorSpace: texture.colorSpace || 'none',
+          });
+        }
       }
+      materialSlots.set(material, slots);
     }
   });
   for (const texture of textures) {
@@ -113,6 +152,13 @@ export function inspectModel(root: THREE.Object3D): ModelInspection {
     textureNames: [...textures].map(
       (texture) => texture.name || texture.source.data?.src || 'Texture',
     ),
+    materialSlots: [...materials].map((material) => ({
+      id: material.uuid,
+      name: material.name || material.type,
+      type: material.type,
+      textureSlots: materialSlots.get(material) ?? [],
+    })),
+    textureBindings,
   };
 }
 
@@ -183,3 +229,48 @@ export function supportedModelDiagnosticModes(root: THREE.Object3D): Array<{
     { mode: 'lod', available: lod, ...(!lod ? { reason: 'No LOD groups' } : {}) },
   ];
 }
+
+/** Extract an animation clip's authored root translation samples for diagnostics. */
+export function rootMotionTrailPoints(clip: THREE.AnimationClip): THREE.Vector3[] {
+  const positionTracks = clip.tracks.filter(
+    (track): track is THREE.VectorKeyframeTrack =>
+      track instanceof THREE.VectorKeyframeTrack && track.name.toLowerCase().endsWith('.position'),
+  );
+  const track =
+    positionTracks.find((candidate) => /(^|[./])(root|hips|armature)[./]/i.test(candidate.name)) ??
+    positionTracks[0];
+  if (!track || track.values.length < 6) return [];
+  const points: THREE.Vector3[] = [];
+  for (let offset = 0; offset + 2 < track.values.length; offset += 3) {
+    points.push(
+      new THREE.Vector3(
+        track.values[offset]!,
+        track.values[offset + 1]!,
+        track.values[offset + 2]!,
+      ),
+    );
+  }
+  return points;
+}
+
+/** Resolve a hierarchy/material row to the preview objects it represents. */
+export function modelSelectionObjects(
+  root: THREE.Object3D,
+  selection: { kind: 'node' | 'material'; id: string },
+): THREE.Object3D[] {
+  if (selection.kind === 'node') {
+    const object = root.getObjectByProperty('uuid', selection.id);
+    return object ? [object] : [];
+  }
+  const selected: THREE.Object3D[] = [];
+  root.traverse((object) => {
+    const mesh = object as THREE.Mesh;
+    const materials = Array.isArray(mesh.material)
+      ? mesh.material
+      : mesh.material
+        ? [mesh.material]
+        : [];
+    if (materials.some((material) => material.uuid === selection.id)) selected.push(mesh);
+  });
+  return selected;
+}

package/src/asset-workflow/preview-resource-lifetime.ts

@@ -0,0 +1,44 @@
+export type PreviewResourceKind =
+  | 'webglContext'
+  | 'animationFrame'
+  | 'resizeObserver'
+  | 'objectUrl';
+
+export interface PreviewResourceSnapshot {
+  webglContext: number;
+  animationFrame: number;
+  resizeObserver: number;
+  objectUrl: number;
+  peaks: Record<PreviewResourceKind, number>;
+}
+
+const current: Record<PreviewResourceKind, number> = {
+  webglContext: 0,
+  animationFrame: 0,
+  resizeObserver: 0,
+  objectUrl: 0,
+};
+const peaks = { ...current };
+
+/** Local diagnostic counter used by stress tests and the Debugger; never uploads identifiers. */
+export function registerPreviewResource(kind: PreviewResourceKind): () => void {
+  current[kind]++;
+  peaks[kind] = Math.max(peaks[kind], current[kind]);
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    current[kind] = Math.max(0, current[kind] - 1);
+  };
+}
+
+export function previewResourceSnapshot(): PreviewResourceSnapshot {
+  return { ...current, peaks: { ...peaks } };
+}
+
+export function resetPreviewResourceCounters(): void {
+  for (const key of Object.keys(current) as PreviewResourceKind[]) {
+    current[key] = 0;
+    peaks[key] = 0;
+  }
+}

package/src/asset-workflow/project-asset-commands.ts

@@ -1,6 +1,7 @@
 export const PROJECT_ASSET_COMMANDS = {
   open: { id: 'project-asset.open', shortcut: 'Enter' },
   rename: { id: 'project-asset.rename', shortcut: 'F2' },
+  move: { id: 'project-asset.move', shortcut: null },
   duplicate: { id: 'project-asset.duplicate', shortcut: 'Mod+D' },
   delete: { id: 'project-asset.delete', shortcut: 'Delete' },
   copyPath: { id: 'project-asset.copy-path', shortcut: 'Mod+Shift+C' },

package/src/asset-workflow/project-asset-health.ts

@@ -73,12 +73,9 @@ export function inspectProjectAssetHealth(input: {
 
   const dependencies = externalDependencies(assetPath, asset?.text);
   if (dependencies.some((path) => !byPath.has(path))) codes.add('missing-dependency');
-  if (
-    assetPath.startsWith('asset-library/local/') &&
-    !byPath.has(`${assetPath.slice(0, assetPath.lastIndexOf('/') + 1)}_VGAI_ASSET.json`)
-  ) {
-    codes.add('missing-attribution');
-  }
+  // Catalog attribution is project-authoring state in .vgai/provenance.json,
+  // outside this public/-rooted storage snapshot. Do not infer it is missing
+  // from the deliberate absence of a legacy per-directory sidecar.
   if (input.recipe && input.recipe.recordedSourceHash !== input.recipe.currentSourceHash) {
     codes.add('stale-import');
   }

package/src/asset-workflow/project-asset-operations.ts

@@ -1,3 +1,5 @@
+import { applyAssetRename } from '@engine/scene/asset-paths';
+import { parsePrefabFile, parseSceneFile } from '@engine/scene/parse';
 import type { HistoryService } from '../history/history-service';
 import { getProjectFileHistory } from '../history/project-file-history';
 import type { StorageBackend } from '../storage/types';
@@ -6,6 +8,10 @@ export type ProjectAssetOperation =
   | { readonly type: 'create-folder'; readonly path: string }
   | { readonly type: 'duplicate'; readonly source: string; readonly destination: string }
   | { readonly type: 'move'; readonly source: string; readonly destination: string }
+  | {
+      readonly type: 'move-many';
+      readonly moves: readonly { readonly source: string; readonly destination: string }[];
+    }
   | { readonly type: 'delete'; readonly paths: readonly string[] }
   | { readonly type: 'import'; readonly files: readonly { path: string; bytes: Uint8Array }[] }
   | { readonly type: 'reimport'; readonly files: readonly { path: string; bytes: Uint8Array }[] };
@@ -42,6 +48,62 @@ async function assertDestinationsFree(backend: StorageBackend, paths: readonly s
   }
 }
 
+async function listAssetReferenceDocuments(
+  backend: StorageBackend,
+  directory = '',
+): Promise<string[]> {
+  const documents: string[] = [];
+  for (const entry of await backend.list(directory)) {
+    if (entry.type === 'dir') {
+      documents.push(...(await listAssetReferenceDocuments(backend, entry.path)));
+    } else if (entry.path.endsWith('.vscn.json') || entry.path.endsWith('.prefab.json')) {
+      documents.push(entry.path);
+    }
+  }
+  return documents;
+}
+
+function rewriteAssetReferenceDocument(
+  path: string,
+  raw: string,
+  moves: readonly { source: string; destination: string }[],
+): string {
+  if (path.endsWith('.prefab.json')) {
+    const prefab = parsePrefabFile(JSON.parse(raw), path);
+    let scene = parseSceneFile(
+      { version: prefab.version, name: prefab.name, entities: [prefab.root] },
+      path,
+    );
+    for (const move of moves) scene = applyAssetRename(scene, move.source, move.destination);
+    const root = scene.entities[0];
+    if (!root) throw new Error('Prefab reference rewrite produced no root entity.');
+    const renamed = { ...prefab, root };
+    return JSON.stringify(renamed, null, 2);
+  }
+  let scene = parseSceneFile(JSON.parse(raw), path);
+  for (const move of moves) scene = applyAssetRename(scene, move.source, move.destination);
+  return JSON.stringify(scene, null, 2);
+}
+
+async function assetReferenceUpdates(
+  backend: StorageBackend,
+  moves: readonly { source: string; destination: string }[],
+): Promise<{ path: string; data: string }[]> {
+  const updates: { path: string; data: string }[] = [];
+  for (const path of await listAssetReferenceDocuments(backend)) {
+    const raw = await backend.read(path);
+    if (!moves.some((move) => raw.includes(move.source))) continue;
+    try {
+      updates.push({ path, data: rewriteAssetReferenceDocument(path, raw, moves) });
+    } catch (error) {
+      throw new Error(
+        `Cannot move an asset while referenced document ${path} is invalid: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+  return updates;
+}
+
 /** Executes all writes through exact-byte project history; no UI owns filesystem mutation. */
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: the tagged operation union is intentionally centralized so every project mutation shares one atomic history boundary.
 export async function executeProjectAssetOperation(
@@ -69,16 +131,69 @@ export async function executeProjectAssetOperation(
       const destination = validPath(operation.destination);
       await assertDestinationsFree(dependencies.backend, [destination]);
       const bytes = await dependencies.backend.readBytes(source);
+      const references = await assetReferenceUpdates(dependencies.backend, [
+        { source, destination },
+      ]);
+      const changes = new Map<string, string | Uint8Array | null>([
+        [destination, bytes],
+        [source, null],
+      ]);
+      for (const reference of references) {
+        const referencePath = reference.path === source ? destination : reference.path;
+        changes.set(referencePath, reference.data);
+      }
       const changed = await files.mutate(
-        [
-          { path: destination, data: bytes },
-          { path: source, data: null },
-        ],
+        [...changes].map(([path, data]) => ({ path, data })),
         { label: `Move ${source}` },
       );
       if (changed) emitAssetMutation({ type: 'move', oldPath: source, newPath: destination });
       return changed;
     }
+    case 'move-many': {
+      const moves = operation.moves.map((move) => ({
+        source: validPath(move.source),
+        destination: validPath(move.destination),
+      }));
+      if (moves.length === 0) return false;
+      const sources = new Set(moves.map((move) => move.source));
+      const destinations = moves.map((move) => move.destination);
+      if (new Set(destinations).size !== destinations.length) {
+        throw new Error('Batch move destinations must be unique.');
+      }
+      for (const destination of destinations) {
+        if (!sources.has(destination) && (await dependencies.backend.exists(destination))) {
+          throw new Error(`An asset already exists at ${destination}.`);
+        }
+      }
+      const payloads = await Promise.all(
+        moves.map(async (move) => ({
+          ...move,
+          bytes: await dependencies.backend.readBytes(move.source),
+        })),
+      );
+      const references = await assetReferenceUpdates(dependencies.backend, moves);
+      const destinationBySource = new Map(
+        moves.map(({ source, destination }) => [source, destination] as const),
+      );
+      const changes = new Map<string, string | Uint8Array | null>();
+      for (const { destination, bytes } of payloads) changes.set(destination, bytes);
+      for (const { source } of payloads) {
+        if (!destinations.includes(source)) changes.set(source, null);
+      }
+      for (const reference of references) {
+        changes.set(destinationBySource.get(reference.path) ?? reference.path, reference.data);
+      }
+      const changed = await files.mutate(
+        [...changes].map(([path, data]) => ({ path, data })),
+        { label: `Move ${moves.length} assets` },
+      );
+      if (changed) {
+        for (const move of moves) {
+          emitAssetMutation({ type: 'move', oldPath: move.source, newPath: move.destination });
+        }
+      }
+      return changed;
+    }
     case 'delete': {
       const paths = [...new Set(operation.paths.map(validPath))];
       const changed = await files.mutate(