@vgai/editor 0.4.0 → 0.4.1-canary.20260715.0

package/server/catalog-import-recipe.ts

@@ -0,0 +1,97 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import {
+  type AssetImportPlan,
+  assetImportPlanSchema,
+  importRecipePath,
+} from '../src/asset-workflow/import-contract';
+
+export interface CatalogRecipeSource {
+  stagedPath: string;
+  path: string;
+  url: string;
+  role: 'primary' | 'dependency' | 'material' | 'texture';
+}
+
+export async function writeCatalogImportRecipe(input: {
+  stagingDirectory: string;
+  source: string;
+  familyId: string;
+  variantId: string;
+  deliveryId: string;
+  displayName: string;
+  destination: string;
+  recipeRelativePath?: string;
+  sources: readonly CatalogRecipeSource[];
+  generatedFiles?: readonly string[];
+  contentKind?: AssetImportPlan['contentKind'];
+  targetSkeleton?: string;
+  runtimeReady: boolean;
+  backend: AssetImportPlan['backend'];
+  attribution: AssetImportPlan['attribution'];
+  settings?: Partial<AssetImportPlan['settings']>;
+}): Promise<AssetImportPlan> {
+  const sourceFiles = await Promise.all(
+    input.sources.map(async (file) => {
+      const [bytes, info] = await Promise.all([readFile(file.stagedPath), stat(file.stagedPath)]);
+      return {
+        path: file.path,
+        url: file.url,
+        hash: createHash('sha256').update(bytes).digest('hex'),
+        size: info.size,
+        role: file.role,
+      };
+    }),
+  );
+  const sourceHash = createHash('sha256')
+    .update(
+      JSON.stringify(
+        sourceFiles
+          .map(({ path, hash, size }) => ({ path, hash, size }))
+          .sort((left, right) => left.path.localeCompare(right.path)),
+      ),
+    )
+    .digest('hex');
+  const plan = assetImportPlanSchema.parse({
+    version: 1,
+    id: randomUUID(),
+    identity: {
+      familyId: input.familyId,
+      variantId: input.variantId,
+      deliveryId: input.deliveryId,
+      source: input.source,
+      displayName: input.displayName,
+    },
+    sourceFiles,
+    generatedFiles: [...(input.generatedFiles ?? [])],
+    destination: input.destination,
+    contentKind: input.contentKind ?? 'model',
+    ...(input.targetSkeleton ? { targetSkeleton: input.targetSkeleton } : {}),
+    settings: {
+      scale: 1,
+      sourceUnits: 'auto',
+      upAxis: 'auto',
+      forwardAxis: 'auto',
+      normals: 'preserve',
+      tangents: 'preserve',
+      materials: 'import',
+      textures: 'copy',
+      animations: [],
+      meshOptimization: 'safe',
+      retainSource: true,
+      ...input.settings,
+    },
+    conflicts: [],
+    attribution: input.attribution,
+    sourceHash,
+    runtimeReady: input.runtimeReady,
+    backend: input.backend,
+    createdAt: new Date().toISOString(),
+  });
+  const recipeFile = input.recipeRelativePath ?? basename(importRecipePath(input.destination));
+  const recipePath = join(input.stagingDirectory, recipeFile);
+  await mkdir(dirname(recipePath), { recursive: true });
+  await writeFile(recipePath, `${JSON.stringify(plan, null, 2)}\n`);
+  return plan;
+}

package/server/catalog-reimport.ts

@@ -0,0 +1,141 @@
+import { copyFile, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, extname, join, relative, resolve } from 'node:path';
+import { type AssetImportPlan, assetImportPlanSchema } from '../src/asset-workflow/import-contract';
+import { type CatalogRecipeSource, writeCatalogImportRecipe } from './catalog-import-recipe';
+import {
+  findLocalAsset,
+  findLocalAssetFamily,
+  getLocalAssetLibraryRoot,
+  resolveCatalogFile,
+  resolveLocalAssetThumbnail,
+} from './local-asset-catalog';
+import {
+  convertStagedModelToGlb,
+  SERVER_CONVERTIBLE_MODEL_FORMATS,
+} from './model-import-conversion';
+import { replaceStagedProjectDirectory } from './project-output-writer';
+import { isPathInside } from './server-utils';
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: reacquisition, conversion, recipe regeneration, source-retention, and atomic replacement are one transaction boundary.
+export async function reimportLocalCatalogAsset(
+  publicRoot: string,
+  assetPath: string,
+  rawPlan: AssetImportPlan,
+): Promise<{ path: string; provenanceOperationId?: string }> {
+  const plan = assetImportPlanSchema.parse(rawPlan);
+  const normalizedAssetPath = assetPath.replace(/^\/+/, '');
+  if (normalizedAssetPath !== plan.destination || plan.identity.source !== 'local') {
+    throw new Error('Reimport identity does not match the selected local project asset.');
+  }
+  const family = await findLocalAssetFamily(plan.identity.familyId);
+  const variant = await findLocalAsset(plan.identity.variantId);
+  if (!family || !variant || variant.familyId !== family.id) {
+    throw new Error('The recorded catalog family/variant is no longer available.');
+  }
+  const sourceFile = variant.files[0];
+  if (!sourceFile) throw new Error('The recorded catalog variant has no source file.');
+  const destination = resolve(publicRoot, dirname(plan.destination));
+  if (!isPathInside(publicRoot, destination))
+    throw new Error('Reimport destination escapes public/.');
+  const staging = await mkdtemp(join(dirname(destination), `.${basename(destination)}.reimport-`));
+  try {
+    const libraryRoot = getLocalAssetLibraryRoot();
+    const primarySource = resolveCatalogFile(libraryRoot, sourceFile.path);
+    const primaryRelative = basename(primarySource);
+    const stagedPrimary = join(staging, primaryRelative);
+    await copyFile(primarySource, stagedPrimary);
+    const recipeSources: CatalogRecipeSource[] = [
+      {
+        stagedPath: stagedPrimary,
+        path: primaryRelative,
+        url: plan.sourceFiles[0]?.url ?? `vgai-local:${variant.id}:0`,
+        role: 'primary',
+      },
+    ];
+    for (const dependency of sourceFile.dependencies ?? []) {
+      const dependencySource = resolveCatalogFile(libraryRoot, dependency);
+      const sourceRelative = relative(dirname(primarySource), dependencySource);
+      const dependencyRelative = sourceRelative.startsWith('..')
+        ? basename(dependencySource)
+        : sourceRelative;
+      const destinationPath = join(staging, dependencyRelative);
+      await mkdir(dirname(destinationPath), { recursive: true });
+      await copyFile(dependencySource, destinationPath);
+      recipeSources.push({
+        stagedPath: destinationPath,
+        path: dependencyRelative.replaceAll('\\', '/'),
+        url: `catalog:${dependency}`,
+        role: dependencyRole(dependency),
+      });
+    }
+    const format = sourceFile.format.toLowerCase();
+    const resultFile = basename(plan.destination);
+    let backend: AssetImportPlan['backend'] = 'native';
+    if (SERVER_CONVERTIBLE_MODEL_FORMATS.has(format)) {
+      const output = await convertStagedModelToGlb(stagedPrimary, format, plan.settings);
+      await writeFile(join(staging, resultFile), output);
+      backend = 'threejs';
+    } else if (resultFile !== primaryRelative) {
+      await copyFile(stagedPrimary, join(staging, resultFile));
+    }
+    try {
+      const thumbnail = resolveLocalAssetThumbnail(libraryRoot, variant);
+      await copyFile(thumbnail, join(staging, '.vgai-thumbnail.webp'));
+    } catch {
+      // Thumbnails are a presentation cache and never invalidate a source reimport.
+    }
+    await writeCatalogImportRecipe({
+      stagingDirectory: staging,
+      source: 'local',
+      familyId: family.id,
+      variantId: variant.id,
+      deliveryId: plan.identity.deliveryId,
+      displayName: plan.identity.displayName ?? family.name,
+      destination: plan.destination,
+      sources: recipeSources,
+      contentKind: plan.contentKind,
+      ...(plan.targetSkeleton ? { targetSkeleton: plan.targetSkeleton } : {}),
+      generatedFiles: backend === 'threejs' ? [plan.destination] : [],
+      runtimeReady: ['glb', 'gltf'].includes(format) || backend === 'threejs',
+      backend,
+      attribution: plan.attribution,
+      settings: plan.settings,
+    });
+    if (backend === 'threejs' && !plan.settings.retainSource) {
+      await Promise.all(recipeSources.map((source) => rm(source.stagedPath, { force: true })));
+    }
+    const result = await replaceStagedProjectDirectory({
+      projectRoot: dirname(publicRoot),
+      stagedDirectory: staging,
+      destination,
+      provenance: {
+        operationName: 'catalog.asset.reimport',
+        operationSource: 'vgai-catalog',
+        input: {
+          familyId: family.id,
+          variantId: variant.id,
+          sourceHash: plan.sourceHash,
+          settings: plan.settings,
+        },
+      },
+    });
+    return {
+      path: plan.destination,
+      ...(result.provenanceOperationId
+        ? { provenanceOperationId: result.provenanceOperationId }
+        : {}),
+    };
+  } catch (error) {
+    await rm(staging, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+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';
+}

package/server/cloud-asset-catalog.ts

@@ -1,7 +1,7 @@
 export const DEFAULT_CLOUD_ASSET_BASE_URL = 'https://vgai-asset-library.aaron-0ed.workers.dev';
 
 export interface CloudAssetObject {
-  key: string;
+  key?: string;
   sha256: string;
   sizeBytes: number;
   contentType: string;
@@ -17,6 +17,8 @@ export interface CloudAssetFile {
 
 export interface CloudAssetRecord {
   id: string;
+  familyId?: string;
+  label?: string;
   status: 'validated';
   source: string;
   name: string;
@@ -25,17 +27,24 @@ export interface CloudAssetRecord {
   author: string;
   sourceUrl: string;
   attribution: string;
+  categories?: string[];
+  tags?: string[];
   files: CloudAssetFile[];
 }
 
 interface CloudAssetManifest {
-  version: 1;
+  version: 1 | 2;
   generatedAt: string;
   assets: CloudAssetRecord[];
 }
 
 let cachedManifest: { value: CloudAssetManifest; url: string; loadedAt: number } | undefined;
 const CACHE_MS = 5 * 60 * 1000;
+const GRAPHQL_ID_BATCH = 500;
+const graphqlAssetCache = new Map<
+  string,
+  { baseUrl: string; value: CloudAssetRecord | null; loadedAt: number }
+>();
 
 export function getCloudAssetBaseUrl(): string {
   return (process.env['VGAI_CLOUD_ASSET_URL'] ?? DEFAULT_CLOUD_ASSET_BASE_URL).replace(/\/+$/, '');
@@ -54,7 +63,7 @@ export async function loadCloudAssetManifest(): Promise<CloudAssetManifest | nul
     const response = await fetch(`${baseUrl}/v1/manifest`, { signal: AbortSignal.timeout(5_000) });
     if (!response.ok) return null;
     const value = (await response.json()) as CloudAssetManifest;
-    if (value.version !== 1 || !Array.isArray(value.assets)) return null;
+    if ((value.version !== 1 && value.version !== 2) || !Array.isArray(value.assets)) return null;
     cachedManifest = { value, url: baseUrl, loadedAt: Date.now() };
     return value;
   } catch {
@@ -63,8 +72,65 @@ export async function loadCloudAssetManifest(): Promise<CloudAssetManifest | nul
 }
 
 export async function findCloudAsset(id: string): Promise<CloudAssetRecord | null> {
-  const manifest = await loadCloudAssetManifest();
-  return manifest?.assets.find((asset) => asset.id === id) ?? null;
+  return (await findCloudAssets([id]))[0] ?? null;
+}
+
+async function queryCloudAssets(ids: readonly string[]): Promise<CloudAssetRecord[] | null> {
+  if (ids.length === 0) return [];
+  const response = await fetch(`${getCloudAssetBaseUrl()}/graphql`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      query: `query CloudAssets($ids: [ID!]!) {
+        assetsByIds(ids: $ids) {
+          id familyId label status source name type license author sourceUrl attribution categories tags
+          files: deliveries {
+            label format
+            main { sha256 sizeBytes contentType relativePath }
+            dependencies { sha256 sizeBytes contentType relativePath }
+          }
+        }
+      }`,
+      variables: { ids },
+    }),
+    signal: AbortSignal.timeout(5_000),
+  });
+  if (!response.ok) return null;
+  const body = (await response.json()) as {
+    data?: { assetsByIds?: CloudAssetRecord[] };
+    errors?: unknown[];
+  };
+  return body.errors || !Array.isArray(body.data?.assetsByIds) ? null : body.data.assetsByIds;
+}
+
+/** Resolve exact hosted variants through GraphQL; REST manifest is rollout fallback only. */
+export async function findCloudAssets(ids: readonly string[]): Promise<CloudAssetRecord[]> {
+  const uniqueIds = [...new Set(ids)];
+  const baseUrl = getCloudAssetBaseUrl();
+  const now = Date.now();
+  const unresolved = uniqueIds.filter((id) => {
+    const cached = graphqlAssetCache.get(id);
+    return !cached || cached.baseUrl !== baseUrl || now - cached.loadedAt >= CACHE_MS;
+  });
+  try {
+    for (let offset = 0; offset < unresolved.length; offset += GRAPHQL_ID_BATCH) {
+      const batch = unresolved.slice(offset, offset + GRAPHQL_ID_BATCH);
+      const found = await queryCloudAssets(batch);
+      if (!found) throw new Error('GraphQL catalog unavailable.');
+      const byId = new Map(found.map((asset) => [asset.id, asset]));
+      for (const id of batch) {
+        graphqlAssetCache.set(id, { baseUrl, value: byId.get(id) ?? null, loadedAt: now });
+      }
+    }
+    return uniqueIds.flatMap((id) => {
+      const asset = graphqlAssetCache.get(id)?.value;
+      return asset ? [asset] : [];
+    });
+  } catch {
+    const manifest = await loadCloudAssetManifest();
+    const requested = new Set(uniqueIds);
+    return manifest?.assets.filter((asset) => requested.has(asset.id)) ?? [];
+  }
 }
 
 export function cloudAssetObjectUrl(

package/server/editor-server.ts

@@ -19,6 +19,13 @@ import express from 'express';
 import { GAME_MANIFEST_VERSION } from '../../engine/src/manifest/schema';
 import { applyAssetRename } from '../../engine/src/scene/asset-paths';
 import type { SceneFile } from '../../engine/src/scene/scene-types';
+import {
+  deriveProjectAttributionReport,
+  emptyProjectProvenanceDocument,
+  formatProjectAttributionMarkdown,
+  PROJECT_PROVENANCE_PATH,
+  ProjectProvenanceDocumentSchema,
+} from '../../vgai-sdk/src/project/provenance';
 import {
   assertEditorCompatibility,
   assertProjectCompatibility,
@@ -70,6 +77,7 @@ interface AssetEntry {
   name: string;
   type: 'file' | 'directory';
   size: number;
+  mtime: number;
 }
 
 interface RecentProject {
@@ -852,6 +860,55 @@ export function createEditorServer(options: EditorServerOptions): EditorServerRo
     createAssetLibraryRouter(() => publicRoot),
   );
 
+  // Derived credits view. The sole durable source is central project provenance.
+  router.get('/__editor/project-attribution', async (req: Request, res: Response) => {
+    if (projectRoot === engineRoot) {
+      res.status(400).json({ error: 'No project is open.' });
+      return;
+    }
+    try {
+      const raw = await readFile(join(projectRoot, PROJECT_PROVENANCE_PATH), 'utf8').catch(
+        (error: NodeJS.ErrnoException) => {
+          if (error.code === 'ENOENT') return null;
+          throw error;
+        },
+      );
+      const provenance = raw
+        ? ProjectProvenanceDocumentSchema.parse(JSON.parse(raw))
+        : emptyProjectProvenanceDocument();
+      const activeOperations = Object.fromEntries(
+        (
+          await Promise.all(
+            Object.entries(provenance.operations).map(async ([operationId, operation]) => {
+              const present = await Promise.all(
+                operation.outputs.map(async (output) => {
+                  const absolute = resolve(projectRoot, output.path);
+                  if (!isPathInside(projectRoot, absolute)) return false;
+                  return stat(absolute).then(
+                    (info) => info.isFile(),
+                    () => false,
+                  );
+                }),
+              );
+              return present.some(Boolean) ? ([operationId, operation] as const) : null;
+            }),
+          )
+        ).filter((entry): entry is readonly [string, (typeof provenance.operations)[string]] =>
+          Boolean(entry),
+        ),
+      );
+      const report = deriveProjectAttributionReport({ version: 1, operations: activeOperations });
+      const format = typeof req.query['format'] === 'string' ? req.query['format'] : 'json';
+      if (format === 'markdown' || req.accepts(['json', 'text/markdown']) === 'text/markdown') {
+        res.type('text/markdown').send(formatProjectAttributionMarkdown(report));
+        return;
+      }
+      res.json(report);
+    } catch (error) {
+      res.status(500).json({ error: `Project attribution failed: ${error}` });
+    }
+  });
+
   // ---- Project file serving middleware ----
   // Serves the v2 manifest from root and static files from project's public/
   router.use((req: Request, res: Response, next) => {
@@ -1253,11 +1310,11 @@ export function createEditorServer(options: EditorServerOptions): EditorServerRo
       for (const d of dirents) {
         if (d.name.startsWith('.')) continue;
         const entryPath = join(absDir, d.name);
+        const s = await stat(entryPath);
         if (d.isDirectory()) {
-          entries.push({ name: d.name, type: 'directory', size: 0 });
+          entries.push({ name: d.name, type: 'directory', size: 0, mtime: s.mtimeMs });
         } else if (d.isFile()) {
-          const s = await stat(entryPath);
-          entries.push({ name: d.name, type: 'file', size: s.size });
+          entries.push({ name: d.name, type: 'file', size: s.size, mtime: s.mtimeMs });
         }
       }
 
@@ -2251,6 +2308,7 @@ export function createEditorServer(options: EditorServerOptions): EditorServerRo
   // ---- Play-mode console log persistence ----
   const MAX_LOG_FILES = 20;
   let activeLogFile: string | null = null;
+  let logSessionSequence = 0;
 
   router.post('/__editor/log-session', async (req: Request, res: Response) => {
     const body = req.body as { action: 'start' | 'end' };
@@ -2273,8 +2331,12 @@ export function createEditorServer(options: EditorServerOptions): EditorServerRo
       }
 
       const now = new Date();
-      const ts = now.toISOString().replace(/[:.]/g, '-').slice(0, 19);
-      const filename = `play-${ts}.jsonl`;
+      // Milliseconds plus a process-local sequence make restart artifacts
+      // distinct even when two sessions begin inside the same millisecond.
+      // Lexicographic order remains chronological for pruning/tail tooling.
+      const ts = now.toISOString().replace(/[:.]/g, '-');
+      const sequence = String(++logSessionSequence).padStart(4, '0');
+      const filename = `play-${ts}-${sequence}.jsonl`;
       activeLogFile = join(logsDir, filename);
       res.json({ ok: true, file: filename });
     } else {