@vgai/editor 0.4.0 → 0.4.1

package/server/asset-library-routes.ts

@@ -10,16 +10,31 @@
 import { execFile } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { createWriteStream } from 'node:fs';
-import { copyFile, mkdir, readdir, readFile, stat, unlink, writeFile } from 'node:fs/promises';
+import {
+  copyFile,
+  mkdir,
+  mkdtemp,
+  readdir,
+  readFile,
+  rename,
+  rm,
+  stat,
+  unlink,
+  writeFile,
+} from 'node:fs/promises';
 import { basename, dirname, extname, join, relative } from 'node:path';
 import { Readable, Transform } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import type { Router } from 'express';
 import express from 'express';
+import { ProjectProvenanceDocumentSchema } from '../../vgai-sdk/src/project/provenance';
+import { AssetHistorySnapshots } from './asset-history-snapshots';
+import { type CatalogRecipeSource, writeCatalogImportRecipe } from './catalog-import-recipe';
+import { reimportLocalCatalogAsset } from './catalog-reimport';
 import {
   cloudAssetObjectUrl,
   findCloudAsset,
-  loadCloudAssetManifest,
+  findCloudAssets,
   parseCloudAssetObjectUrl,
 } from './cloud-asset-catalog';
 import { broadcast } from './editor-sse';
@@ -36,6 +51,11 @@ import {
   resolveLocalAssetThumbnail,
   searchLocalCatalog,
 } from './local-asset-catalog';
+import {
+  convertStagedModelToGlb,
+  SERVER_CONVERTIBLE_MODEL_FORMATS,
+} from './model-import-conversion';
+import { commitStagedProjectDirectory } from './project-output-writer';
 import { isAllowedAssetHost, isAllowedAssetSource, isPathInside } from './server-utils';
 
 // ---------------------------------------------------------------------------
@@ -103,6 +123,64 @@ interface CacheEntry<T> {
 
 const cache = new Map<string, CacheEntry<unknown>>();
 
+export async function beginAssetStaging(destination: string): Promise<string> {
+  await mkdir(dirname(destination), { recursive: true });
+  const exists = await stat(destination).then(
+    () => true,
+    (error: NodeJS.ErrnoException) => {
+      if (error.code === 'ENOENT') return false;
+      throw error;
+    },
+  );
+  if (exists) throw new Error(`Destination already exists and was not overwritten: ${destination}`);
+  return mkdtemp(join(dirname(destination), `.${basename(destination)}.staging-`));
+}
+
+export async function commitAssetStaging(staging: string, destination: string): Promise<void> {
+  await rename(staging, destination);
+}
+
+async function commitCatalogAsset(
+  publicRoot: string,
+  staging: string,
+  destination: string,
+  input: Record<string, unknown>,
+) {
+  return commitStagedProjectDirectory({
+    projectRoot: dirname(publicRoot),
+    stagedDirectory: staging,
+    destination,
+    provenance: {
+      operationName: 'catalog.asset.acquire',
+      operationSource: 'vgai-catalog',
+      input,
+    },
+  });
+}
+
+async function centralCatalogIds(projectRoot: string): Promise<Map<string, string>> {
+  try {
+    const document = ProjectProvenanceDocumentSchema.parse(
+      JSON.parse(await readFile(join(projectRoot, '.vgai', 'provenance.json'), 'utf8')),
+    );
+    const ids = new Map<string, string>();
+    for (const operation of Object.values(document.operations)) {
+      if (operation.operation.name !== 'catalog.asset.acquire') continue;
+      const input = operation.input;
+      if (!input || typeof input !== 'object' || Array.isArray(input)) continue;
+      const id = input['id'];
+      if (typeof id !== 'string') continue;
+      for (const output of operation.outputs) {
+        const match = /^public\/asset-library\/([^/]+)\/([^/]+)\//.exec(output.path);
+        if (match?.[1] && match[2]) ids.set(`${match[1]}/${match[2]}`, id);
+      }
+    }
+    return ids;
+  } catch {
+    return new Map();
+  }
+}
+
 const LOCAL_ASSET_PLACEHOLDER_SVG =
   '<svg xmlns="http://www.w3.org/2000/svg" width="256" height="256" viewBox="0 0 256 256"><rect width="256" height="256" fill="#181818"/><path d="M64 82l64-36 64 36v76l-64 38-64-38z" fill="#252a31" stroke="#579eff" stroke-width="8"/><path d="M64 82l64 38 64-38M128 120v76" fill="none" stroke="#579eff" stroke-width="8"/><text x="128" y="226" text-anchor="middle" fill="#9aa4b2" font-family="sans-serif" font-size="18">PREVIEW PENDING</text></svg>';
 
@@ -110,6 +188,15 @@ function sendLocalPlaceholder(res: import('express').Response): void {
   res.set('Cache-Control', 'no-store').type('image/svg+xml').send(LOCAL_ASSET_PLACEHOLDER_SVG);
 }
 
+function dependencyRole(path: string): 'dependency' | 'material' | 'texture' {
+  const extension = extname(path).toLowerCase();
+  if (extension === '.mtl') return 'material';
+  if (['.png', '.jpg', '.jpeg', '.webp', '.ktx', '.ktx2', '.dds', '.tga'].includes(extension)) {
+    return 'texture';
+  }
+  return 'dependency';
+}
+
 function getCached<T>(key: string): T | null {
   const entry = cache.get(key);
   if (!entry) return null;
@@ -353,6 +440,59 @@ function getAmbientCGFiles(id: string): AssetFileOption[] {
 
 export function createAssetLibraryRouter(getPublicRoot: () => string): Router {
   const router = express.Router();
+  const historySnapshots = new Map<string, AssetHistorySnapshots>();
+  const assetHistory = () => {
+    const publicRoot = getPublicRoot();
+    const existing = historySnapshots.get(publicRoot);
+    if (existing) return existing;
+    const created = new AssetHistorySnapshots(publicRoot);
+    historySnapshots.set(publicRoot, created);
+    return created;
+  };
+  const captureCommittedHistory = async (assetPath: string, beforeToken: string) => {
+    try {
+      return {
+        assetPath,
+        beforeToken,
+        afterToken: await assetHistory().capture(assetPath),
+      };
+    } catch (error) {
+      await assetHistory().restore(assetPath, beforeToken);
+      throw error;
+    }
+  };
+
+  router.post('/history/capture', async (req, res) => {
+    const assetPath = (req.body as { assetPath?: unknown }).assetPath;
+    if (typeof assetPath !== 'string') {
+      res.status(400).json({ error: 'Asset history capture requires an asset path.' });
+      return;
+    }
+    try {
+      res.json({ ok: true, token: await assetHistory().capture(assetPath) });
+    } catch (error) {
+      res.status(400).json({
+        error: `Asset history capture failed: ${error instanceof Error ? error.message : String(error)}`,
+      });
+    }
+  });
+
+  router.post('/history/restore', async (req, res) => {
+    const body = req.body as { assetPath?: unknown; token?: unknown };
+    if (typeof body.assetPath !== 'string' || typeof body.token !== 'string') {
+      res.status(400).json({ error: 'Asset history restore requires an asset path and token.' });
+      return;
+    }
+    try {
+      await assetHistory().restore(body.assetPath, body.token);
+      broadcast('assets-changed', {});
+      res.json({ ok: true });
+    } catch (error) {
+      res.status(400).json({
+        error: `Asset history restore failed: ${error instanceof Error ? error.message : String(error)}`,
+      });
+    }
+  });
   router.use(express.json());
 
   // ---- Search ----
@@ -374,8 +514,6 @@ export function createAssetLibraryRouter(getPublicRoot: () => string): Router {
 
       if (source === 'local') {
         const catalog = await loadLocalAssetCatalog();
-        const cloudManifest = await loadCloudAssetManifest();
-        const cloudIds = new Set(cloudManifest?.assets.map((asset) => asset.id) ?? []);
         const localResult = searchLocalCatalog(catalog, {
           q,
           type,
@@ -383,6 +521,10 @@ export function createAssetLibraryRouter(getPublicRoot: () => string): Router {
           limit,
           ...(category ? { category } : {}),
         });
+        const cloudAssets = await findCloudAssets(
+          localResult.assets.flatMap((asset) => asset.variants.map((variant) => variant.id)),
+        );
+        const cloudIds = new Set(cloudAssets.map((asset) => asset.id));
         result = {
           total: localResult.total,
           assets: localResult.assets.map((asset) => ({
@@ -530,10 +672,14 @@ export function createAssetLibraryRouter(getPublicRoot: () => string): Router {
         return;
       }
       const sourceDirectory = dirname(file.path);
-      const allowedPath = [file.path, ...(file.dependencies ?? [])].find(
+      const exactPath = [file.path, ...(file.dependencies ?? [])].find(
         (candidate) =>
           relative(sourceDirectory, candidate).replaceAll('\\', '/') === requestedRelativePath,
       );
+      const basenameMatches = (file.dependencies ?? []).filter(
+        (candidate) => basename(candidate) === basename(requestedRelativePath),
+      );
+      const allowedPath = exactPath ?? (basenameMatches.length === 1 ? basenameMatches[0] : null);
       if (!allowedPath) {
         res.status(404).json({ error: 'Catalog preview dependency not found.' });
         return;
@@ -639,9 +785,34 @@ export function createAssetLibraryRouter(getPublicRoot: () => string): Router {
       name: string;
       url: string;
       format: string;
+      jobId?: string;
       includes?: { relativePath: string; url: string; size: number }[];
     };
     const { source, id, name, url, format } = body;
+    const cancellation = new AbortController();
+    req.once('aborted', () =>
+      cancellation.abort(new DOMException('Import cancelled', 'AbortError')),
+    );
+    res.once('close', () => {
+      if (!res.writableEnded)
+        cancellation.abort(new DOMException('Import cancelled', 'AbortError'));
+    });
+    const throwIfCancelled = () => cancellation.signal.throwIfAborted();
+    const progress = (
+      stage: 'fetch' | 'convert' | 'validate' | 'commit',
+      loaded: number,
+      total: number,
+      message?: string,
+    ) => {
+      if (!body.jobId) return;
+      broadcast('asset-import-progress', {
+        jobId: body.jobId,
+        stage,
+        loaded,
+        total,
+        ...(message ? { message } : {}),
+      });
+    };
     const includes = body.includes ?? [];
 
     if (!source || !id || !url) {
@@ -656,6 +827,7 @@ export function createAssetLibraryRouter(getPublicRoot: () => string): Router {
     }
 
     if (source === 'local') {
+      let stagingDir: string | null = null;
       try {
         const family = await findLocalAssetFamily(id);
         const asset = family ? await findLocalAsset(family.id) : null;
@@ -680,8 +852,11 @@ export function createAssetLibraryRouter(getPublicRoot: () => string): Router {
             res.status(404).json({ error: 'Cloud asset file not found.' });
             return;
           }
-          const mainDestination = join(destDir, cloudFile.main.relativePath);
-          if (!isPathInside(destDir, mainDestination)) {
+          stagingDir = await beginAssetStaging(destDir);
+          const mainDestination = join(stagingDir, cloudFile.main.relativePath);
+          if (!isPathInside(stagingDir, mainDestination)) {
+            await rm(stagingDir, { recursive: true, force: true });
+            stagingDir = null;
             res.status(400).json({ error: 'Invalid cloud asset path.' });
             return;
           }
@@ -690,10 +865,14 @@ export function createAssetLibraryRouter(getPublicRoot: () => string): Router {
             mainDestination,
             cloudFile.main.sha256,
             cloudFile.main.sizeBytes,
+            (loaded, total) => progress('fetch', loaded, total),
+            cancellation.signal,
           );
           for (const [dependencyIndex, dependency] of cloudFile.dependencies.entries()) {
-            const destination = join(destDir, dependency.relativePath);
-            if (!isPathInside(destDir, destination)) {
+            const destination = join(stagingDir, dependency.relativePath);
+            if (!isPathInside(stagingDir, destination)) {
+              await rm(stagingDir, { recursive: true, force: true });
+              stagingDir = null;
               res
                 .status(400)
                 .json({ error: `Invalid dependency path: ${dependency.relativePath}` });
@@ -704,10 +883,51 @@ export function createAssetLibraryRouter(getPublicRoot: () => string): Router {
               destination,
               dependency.sha256,
               dependency.sizeBytes,
+              (loaded, total) =>
+                progress('fetch', loaded, total, `Dependency ${dependencyIndex + 1}`),
+              cancellation.signal,
             );
           }
-          await copyLocalAssetThumbnail(asset, destDir);
-          await writeAssetProvenance(destDir, {
+          const cloudSources: CatalogRecipeSource[] = [
+            {
+              stagedPath: mainDestination,
+              path: cloudFile.main.relativePath,
+              url,
+              role: 'primary' as const,
+            },
+            ...cloudFile.dependencies.map((dependency, dependencyIndex) => ({
+              stagedPath: join(stagingDir!, dependency.relativePath),
+              path: dependency.relativePath,
+              url: cloudAssetObjectUrl(id, cloudRoute.fileIndex, dependencyIndex),
+              role: dependencyRole(dependency.relativePath),
+            })),
+          ];
+          const cloudResultPath = `asset-library/local/${assetSlug}/${cloudFile.main.relativePath}`;
+          await writeCatalogImportRecipe({
+            stagingDirectory: stagingDir,
+            source: 'local',
+            familyId: family.id,
+            variantId: cloudAsset.id,
+            deliveryId: `cloud:${cloudAsset.id}`,
+            displayName: asset.name,
+            destination: cloudResultPath,
+            recipeRelativePath: `${cloudFile.main.relativePath}.vgai-import.json`,
+            sources: cloudSources,
+            contentKind: cloudFile.format.toLowerCase() === 'bvh' ? 'animation-only' : 'model',
+            runtimeReady: ['glb', 'gltf'].includes(cloudFile.format.toLowerCase()),
+            backend: 'native',
+            attribution: {
+              sourceUrl: asset.sourceUrl,
+              author: asset.author,
+              license: asset.license,
+              text: cloudAsset.attribution ?? `${asset.name} by ${asset.author} (${asset.license})`,
+            },
+          });
+          progress('validate', cloudFile.main.sizeBytes, cloudFile.main.sizeBytes);
+          throwIfCancelled();
+          await copyLocalAssetThumbnail(asset, stagingDir);
+          const beforeToken = await assetHistory().capture(cloudResultPath);
+          const committed = await commitCatalogAsset(publicRoot, stagingDir, destDir, {
             id: family.id,
             variantId: cloudVariantId,
             name: asset.name,
@@ -719,9 +939,17 @@ export function createAssetLibraryRouter(getPublicRoot: () => string): Router {
             attribution: cloudAsset.attribution,
             sha256: cloudFile.main.sha256,
           });
-          const resultPath = `asset-library/local/${assetSlug}/${cloudFile.main.relativePath}`;
+          progress('commit', 1, 1);
+          stagingDir = null;
+          const resultPath = cloudResultPath;
+          const history = await captureCommittedHistory(resultPath, beforeToken);
           broadcast('assets-changed', {});
-          res.json({ ok: true, path: resultPath });
+          res.json({
+            ok: true,
+            path: resultPath,
+            provenanceOperationId: committed.provenanceOperationId,
+            history,
+          });
           return;
         }
 
@@ -738,18 +966,75 @@ export function createAssetLibraryRouter(getPublicRoot: () => string): Router {
         const libraryRoot = getLocalAssetLibraryRoot();
         const mainSource = resolveCatalogFile(libraryRoot, selectedFile.path);
         const sourceDirectory = dirname(mainSource);
-        await mkdir(destDir, { recursive: true });
-        await copyFile(mainSource, join(destDir, basename(mainSource)));
+        stagingDir = await beginAssetStaging(destDir);
+        const primaryRelative = basename(mainSource);
+        const stagedPrimary = join(stagingDir, primaryRelative);
+        progress('fetch', 0, selectedFile.sizeBytes);
+        await copyFile(mainSource, stagedPrimary);
+        progress('fetch', selectedFile.sizeBytes, selectedFile.sizeBytes);
+        throwIfCancelled();
+        const recipeSources: CatalogRecipeSource[] = [
+          {
+            stagedPath: stagedPrimary,
+            path: primaryRelative,
+            url,
+            role: 'primary' as const,
+          },
+        ];
         for (const dependency of selectedFile.dependencies ?? []) {
           const dependencySource = resolveCatalogFile(libraryRoot, dependency);
-          const dependencyRelative = relative(sourceDirectory, dependencySource);
-          if (dependencyRelative.startsWith('..')) continue;
-          const dependencyDestination = join(destDir, dependencyRelative);
+          const sourceRelative = relative(sourceDirectory, dependencySource);
+          const dependencyRelative = sourceRelative.startsWith('..')
+            ? basename(dependencySource)
+            : sourceRelative;
+          const dependencyDestination = join(stagingDir, dependencyRelative);
           await mkdir(dirname(dependencyDestination), { recursive: true });
           await copyFile(dependencySource, dependencyDestination);
+          recipeSources.push({
+            stagedPath: dependencyDestination,
+            path: dependencyRelative.replaceAll('\\', '/'),
+            url: `catalog:${dependency}`,
+            role: dependencyRole(dependency),
+          });
+        }
+        let resultFile = primaryRelative;
+        let backend: 'native' | 'threejs' = 'native';
+        const format = selectedFile.format.toLowerCase();
+        if (SERVER_CONVERTIBLE_MODEL_FORMATS.has(format)) {
+          progress('convert', 0, 1);
+          resultFile = `${basename(primaryRelative, extname(primaryRelative))}.glb`;
+          const converted = await convertStagedModelToGlb(stagedPrimary, format);
+          await writeFile(join(stagingDir, resultFile), converted);
+          backend = 'threejs';
+          progress('convert', 1, 1);
+          throwIfCancelled();
         }
-        await copyLocalAssetThumbnail(asset, destDir);
-        await writeAssetProvenance(destDir, {
+        const resultPath = `asset-library/local/${assetSlug}/${resultFile}`;
+        await writeCatalogImportRecipe({
+          stagingDirectory: stagingDir,
+          source: 'local',
+          familyId: family.id,
+          variantId: selectedAsset.id,
+          deliveryId: `local:${selectedAsset.id}`,
+          displayName: asset.name,
+          destination: resultPath,
+          sources: recipeSources,
+          contentKind: format === 'bvh' ? 'animation-only' : 'model',
+          generatedFiles: backend === 'threejs' ? [resultPath] : [],
+          runtimeReady: ['glb', 'gltf'].includes(format) || backend === 'threejs',
+          backend,
+          attribution: {
+            sourceUrl: asset.sourceUrl,
+            author: asset.author,
+            license: asset.license,
+            text: `${asset.name} by ${asset.author} (${asset.license})`,
+          },
+        });
+        progress('validate', 1, 1);
+        throwIfCancelled();
+        await copyLocalAssetThumbnail(asset, stagingDir);
+        const beforeToken = await assetHistory().capture(resultPath);
+        const committed = await commitCatalogAsset(publicRoot, stagingDir, destDir, {
           id: family.id,
           variantId: selectedAsset.id,
           name: asset.name,
@@ -760,11 +1045,18 @@ export function createAssetLibraryRouter(getPublicRoot: () => string): Router {
           delivery: 'local-ssd',
           originalPath: selectedFile.path,
         });
-
-        const resultPath = `asset-library/local/${assetSlug}/${basename(mainSource)}`;
+        progress('commit', 1, 1);
+        stagingDir = null;
+        const history = await captureCommittedHistory(resultPath, beforeToken);
         broadcast('assets-changed', {});
-        res.json({ ok: true, path: resultPath });
+        res.json({
+          ok: true,
+          path: resultPath,
+          provenanceOperationId: committed.provenanceOperationId,
+          history,
+        });
       } catch (error) {
+        if (stagingDir) await rm(stagingDir, { recursive: true, force: true }).catch(() => {});
         res.status(500).json({ error: `Local asset copy failed: ${error}` });
       }
       return;
@@ -808,73 +1100,124 @@ export function createAssetLibraryRouter(getPublicRoot: () => string): Router {
       // Doesn't exist yet — continue
     }
 
+    let stagingDir: string | null = null;
     try {
-      await mkdir(destDir, { recursive: true });
+      stagingDir = await beginAssetStaging(destDir);
 
       /** Download a single file to a destination path. */
-      async function downloadFile(fileUrl: string, destPath: string): Promise<void> {
+      async function downloadFile(
+        fileUrl: string,
+        destPath: string,
+        expectedBytes?: number,
+      ): Promise<void> {
         await mkdir(join(destPath, '..'), { recursive: true });
-        const response = await fetch(fileUrl);
+        const response = await fetch(fileUrl, { signal: cancellation.signal });
         if (!response.ok || !response.body) {
           throw new Error(`Download failed: ${response.status} for ${fileUrl}`);
         }
         const nodeStream = Readable.fromWeb(response.body as import('stream/web').ReadableStream);
-        await pipeline(nodeStream, createWriteStream(destPath));
+        const total =
+          expectedBytes ?? Number.parseInt(response.headers.get('content-length') ?? '0', 10);
+        let loaded = 0;
+        const reporter = new Transform({
+          transform(chunk: Buffer, _encoding, callback) {
+            loaded += chunk.length;
+            progress('fetch', loaded, total);
+            callback(null, chunk);
+          },
+        });
+        await pipeline(nodeStream, reporter, createWriteStream(destPath));
       }
 
       const isZip = format === 'zip' || url.endsWith('.zip');
       const ext = isZip ? 'zip' : url.split('.').pop() || format || 'bin';
       const fileName = `${slug}.${ext}`;
-      const filePath = join(destDir, fileName);
+      const filePath = join(stagingDir, fileName);
 
       // Download main file
       await downloadFile(url, filePath);
 
       // Download included files (GLTF bin + textures)
       for (const inc of includes) {
-        const incPath = join(destDir, inc.relativePath);
+        const incPath = join(stagingDir, inc.relativePath);
         // S1: ensure each relativePath stays inside destDir (reject `..` escapes).
-        if (!isPathInside(destDir, incPath)) {
+        if (!isPathInside(stagingDir, incPath)) {
+          await rm(stagingDir, { recursive: true, force: true });
+          stagingDir = null;
           res.status(400).json({ error: `Invalid include path: ${inc.relativePath}` });
           return;
         }
-        await downloadFile(inc.url, incPath);
+        await downloadFile(inc.url, incPath, inc.size);
       }
 
       let resultPath = `asset-library/${source}/${slug}/${fileName}`;
 
       // Extract ZIPs
       if (isZip) {
+        progress('convert', 0, 1);
         await new Promise<void>((resolve, reject) => {
-          execFile('unzip', ['-o', filePath, '-d', destDir], (err) => {
+          execFile('unzip', ['-o', filePath, '-d', stagingDir!], (err) => {
             if (err) reject(err);
             else resolve();
           });
         });
         await unlink(filePath).catch(() => {});
-        const extracted = await readdir(destDir);
+        const extracted = await readdir(stagingDir);
         const mainFile = extracted.find((f) => !f.endsWith('.zip')) ?? extracted[0];
         if (mainFile) {
           resultPath = `asset-library/${source}/${slug}/${mainFile}`;
         }
+        progress('convert', 1, 1);
       }
 
-      await writeAssetProvenance(destDir, {
+      progress('validate', 1, 1);
+      throwIfCancelled();
+      const beforeToken = await assetHistory().capture(resultPath);
+      const committed = await commitCatalogAsset(publicRoot, stagingDir, destDir, {
         id,
         name,
         source,
         sourceUrl: url,
         delivery: source,
       });
-
+      progress('commit', 1, 1);
+      stagingDir = null;
+      const history = await captureCommittedHistory(resultPath, beforeToken);
       broadcast('assets-changed', {});
 
-      res.json({ ok: true, path: resultPath });
+      res.json({
+        ok: true,
+        path: resultPath,
+        provenanceOperationId: committed.provenanceOperationId,
+        history,
+      });
     } catch (err) {
+      if (stagingDir) await rm(stagingDir, { recursive: true, force: true }).catch(() => {});
       res.status(500).json({ error: `Download failed: ${err}` });
     }
   });
 
+  router.post('/reimport', async (req, res) => {
+    const body = req.body as { assetPath?: unknown; plan?: unknown };
+    if (typeof body.assetPath !== 'string' || !body.plan) {
+      res.status(400).json({ error: 'Reimport requires an asset path and saved import plan.' });
+      return;
+    }
+    try {
+      const result = await reimportLocalCatalogAsset(
+        getPublicRoot(),
+        body.assetPath,
+        body.plan as Parameters<typeof reimportLocalCatalogAsset>[2],
+      );
+      broadcast('assets-changed', {});
+      res.json({ ok: true, ...result });
+    } catch (error) {
+      res.status(500).json({
+        error: `Reimport failed: ${error instanceof Error ? error.message : String(error)}`,
+      });
+    }
+  });
+
   // ---- Categories for Poly Haven ----
   router.get('/categories', async (req, res) => {
     const source = req.query['source'] as string | undefined;
@@ -951,6 +1294,7 @@ export function createAssetLibraryRouter(getPublicRoot: () => string): Router {
     const publicRoot = getPublicRoot();
     const libraryDir = join(publicRoot, 'asset-library');
     const downloaded: { source: string; id: string; path: string }[] = [];
+    const centralIds = await centralCatalogIds(dirname(publicRoot));
 
     try {
       const sources = await readdir(libraryDir).catch(() => [] as string[]);
@@ -969,9 +1313,15 @@ export function createAssetLibraryRouter(getPublicRoot: () => string): Router {
           const provenance = await readFile(join(slugDir, '_VGAI_ASSET.json'), 'utf8')
             .then((text) => JSON.parse(text) as { id?: unknown })
             .catch(() => null);
-          const id = typeof provenance?.id === 'string' ? provenance.id : slug;
+          const id =
+            centralIds.get(`${source}/${slug}`) ??
+            (typeof provenance?.id === 'string' ? provenance.id : slug);
           // Find the main asset file
-          const mainFile = files.find((f) => /\.(gltf|glb|hdr|exr)$/i.test(f)) ?? files[0];
+          const assetFiles = files.filter(
+            (file) => file !== '_VGAI_ASSET.json' && file !== '.vgai-thumbnail.webp',
+          );
+          const mainFile =
+            assetFiles.find((file) => /\.(gltf|glb|hdr|exr)$/i.test(file)) ?? assetFiles[0];
           if (mainFile) {
             downloaded.push({
               source,
@@ -996,9 +1346,15 @@ export async function downloadRemoteFile(
   destination: string,
   expectedSha256: string,
   expectedSizeBytes: number,
+  onProgress?: (loaded: number, total: number) => void,
+  signal?: AbortSignal,
 ): Promise<void> {
   await mkdir(dirname(destination), { recursive: true });
-  const response = await fetch(url, { signal: AbortSignal.timeout(120_000) });
+  const response = await fetch(url, {
+    signal: signal
+      ? AbortSignal.any([signal, AbortSignal.timeout(120_000)])
+      : AbortSignal.timeout(120_000),
+  });
   if (!response.ok || !response.body) {
     throw new Error(`Download failed: ${response.status} for ${url}`);
   }
@@ -1006,9 +1362,15 @@ export async function downloadRemoteFile(
   let sizeBytes = 0;
   const verifier = new Transform({
     transform(chunk: Buffer, _encoding, callback) {
-      hash.update(chunk);
-      sizeBytes += chunk.length;
-      callback(null, chunk);
+      try {
+        signal?.throwIfAborted();
+        hash.update(chunk);
+        sizeBytes += chunk.length;
+        onProgress?.(sizeBytes, expectedSizeBytes);
+        callback(null, chunk);
+      } catch (error) {
+        callback(error as Error);
+      }
     },
   });
   const nodeStream = Readable.fromWeb(response.body as import('stream/web').ReadableStream);
@@ -1026,17 +1388,6 @@ export async function downloadRemoteFile(
   }
 }
 
-async function writeAssetProvenance(
-  destination: string,
-  provenance: Record<string, unknown>,
-): Promise<void> {
-  await mkdir(destination, { recursive: true });
-  await writeFile(
-    join(destination, '_VGAI_ASSET.json'),
-    `${JSON.stringify(provenance, null, 2)}\n`,
-  );
-}
-
 async function copyLocalAssetThumbnail(
   asset: NonNullable<Awaited<ReturnType<typeof findLocalAsset>>>,
   destination: string,