@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

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

@@ -0,0 +1,107 @@
+import type { OnlineAsset } from '../editor-api';
+
+const LIBRARY_STATE_KEY = 'vgai:asset-library:v2';
+
+export function assetLibraryStateKey(projectId: string): string {
+  return `${LIBRARY_STATE_KEY}:${projectId}`;
+}
+
+export type AssetLibrarySort =
+  | 'relevance'
+  | 'name'
+  | 'source'
+  | 'size'
+  | 'recently-added'
+  | 'recently-used';
+
+export interface AssetLibraryFilters {
+  readonly licenses: ReadonlySet<string>;
+  readonly deliveryKinds: ReadonlySet<string>;
+  readonly health: ReadonlySet<string>;
+  readonly animatedOnly: boolean;
+  readonly runtimeReadyOnly: boolean;
+  readonly downloaded: 'all' | 'downloaded' | 'not-downloaded';
+  readonly favoritesOnly: boolean;
+}
+
+export interface AssetLibraryQueryContext {
+  readonly favorites: ReadonlySet<string>;
+  readonly recent: readonly string[];
+  isDownloaded(asset: OnlineAsset): boolean;
+}
+
+export function onlineAssetKey(asset: Pick<OnlineAsset, 'source' | 'id'>): string {
+  return `${asset.source}:${asset.id}`;
+}
+
+function optionalSetMatches(values: ReadonlySet<string>, value: string): boolean {
+  return values.size === 0 || values.has(value);
+}
+
+function deliveryMatches(values: ReadonlySet<string>, asset: OnlineAsset): boolean {
+  return values.size === 0 || Boolean(asset.deliveryKinds?.some((value) => values.has(value)));
+}
+
+function downloadedMatches(
+  filter: AssetLibraryFilters['downloaded'],
+  downloaded: boolean,
+): boolean {
+  return filter === 'all' || (filter === 'downloaded' ? downloaded : !downloaded);
+}
+
+function assetMatches(
+  asset: OnlineAsset,
+  filters: AssetLibraryFilters,
+  context: AssetLibraryQueryContext,
+): boolean {
+  const favorite = context.favorites.has(onlineAssetKey(asset));
+  return (
+    (!filters.favoritesOnly || favorite) &&
+    (!filters.runtimeReadyOnly || Boolean(asset.capabilities?.runtimeReady)) &&
+    (!filters.animatedOnly || Boolean(asset.capabilities?.animated)) &&
+    optionalSetMatches(filters.licenses, asset.license ?? 'Unknown') &&
+    optionalSetMatches(filters.health, asset.capabilities?.health ?? 'unsupported') &&
+    deliveryMatches(filters.deliveryKinds, asset) &&
+    downloadedMatches(filters.downloaded, context.isDownloaded(asset))
+  );
+}
+
+function compareAssetSort(
+  left: OnlineAsset,
+  right: OnlineAsset,
+  sort: AssetLibrarySort,
+  recentRank: ReadonlyMap<string, number>,
+): number {
+  switch (sort) {
+    case 'source':
+      return left.source.localeCompare(right.source);
+    case 'size':
+      return (right.sizeBytes ?? -1) - (left.sizeBytes ?? -1);
+    case 'recently-added':
+      return (right.addedAt ?? '').localeCompare(left.addedAt ?? '');
+    case 'recently-used':
+      return (
+        (recentRank.get(onlineAssetKey(left)) ?? Number.MAX_SAFE_INTEGER) -
+        (recentRank.get(onlineAssetKey(right)) ?? Number.MAX_SAFE_INTEGER)
+      );
+    default:
+      return 0;
+  }
+}
+
+export function queryAssetLibrary(
+  assets: readonly OnlineAsset[],
+  filters: AssetLibraryFilters,
+  sort: AssetLibrarySort,
+  context: AssetLibraryQueryContext,
+): OnlineAsset[] {
+  const recentRank = new Map(context.recent.map((key, index) => [key, index]));
+  const filtered = assets.filter((asset) => assetMatches(asset, filters, context));
+
+  if (sort === 'relevance') return filtered;
+  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);
+  });
+}

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

@@ -0,0 +1,192 @@
+import { z } from 'zod';
+
+export type AssetHealthCode =
+  | 'healthy'
+  | 'source-only'
+  | 'missing-file'
+  | 'missing-dependency'
+  | 'missing-thumbnail'
+  | 'unsupported-format'
+  | 'invalid-metadata'
+  | 'stale-import'
+  | 'conversion-failed'
+  | 'missing-attribution'
+  | 'broken-scene-reference';
+
+export interface AssetHealth {
+  readonly status: 'healthy' | 'warning' | 'error';
+  readonly codes: readonly AssetHealthCode[];
+}
+
+export const AssetFileSchema = z
+  .object({
+    label: z.string().min(1),
+    path: z.string().min(1),
+    format: z.string().min(1),
+    sizeBytes: z.number().int().nonnegative(),
+    dependencies: z.array(z.string().min(1)).optional(),
+    sha256: z
+      .string()
+      .regex(/^[a-f0-9]{64}$/)
+      .optional(),
+  })
+  .strict();
+
+export const AssetDeliverySchema = z
+  .object({
+    id: z.string().min(1),
+    kind: z.enum(['local-ssd', 'cloud', 'remote']),
+    available: z.boolean(),
+    fileIndexes: z.array(z.number().int().nonnegative()).min(1),
+  })
+  .strict();
+
+export const AssetThumbnailSchema = z
+  .object({
+    path: z.string().min(1),
+    state: z.enum(['generated', 'upstream', 'fallback', 'unsupported', 'failed']),
+    profileVersion: z.string().min(1),
+    sourceHash: z
+      .string()
+      .regex(/^[a-f0-9]{64}$/)
+      .optional(),
+    resultHash: z
+      .string()
+      .regex(/^[a-f0-9]{64}$/)
+      .optional(),
+    issueCode: z.string().min(1).optional(),
+  })
+  .strict();
+
+export const AssetVariantSchema = z
+  .object({
+    id: z.string().regex(/^[a-f0-9]{24}$/),
+    label: z.string().min(1),
+    type: z.enum(['model', 'animation', 'source']),
+    files: z.array(AssetFileSchema).min(1),
+    deliveries: z.array(AssetDeliverySchema).min(1),
+    thumbnail: AssetThumbnailSchema,
+    animationCount: z.number().int().nonnegative().optional(),
+    clipNames: z.array(z.string()).optional(),
+  })
+  .strict();
+
+export const AssetFamilySchema = z
+  .object({
+    id: z.string().regex(/^[a-f0-9]{24}$/),
+    source: z.string().min(1),
+    name: z.string().min(1),
+    type: z.enum(['model', 'animation', 'source']),
+    categories: z.array(z.string()),
+    tags: z.array(z.string()),
+    license: z.string().min(1),
+    author: z.string().min(1),
+    sourceUrl: z.string().url(),
+    variants: z.array(AssetVariantSchema).min(1),
+  })
+  .strict();
+
+export const AssetCatalogEnvelopeSchema = z
+  .object({
+    version: z.literal(2),
+    generatedAt: z.string().datetime(),
+    families: z.array(z.unknown()),
+  })
+  .strict();
+
+export type AssetFile = z.infer<typeof AssetFileSchema>;
+export type AssetDelivery = z.infer<typeof AssetDeliverySchema>;
+export type AssetVariant = z.infer<typeof AssetVariantSchema>;
+export type AssetFamily = z.infer<typeof AssetFamilySchema>;
+
+export interface AssetCatalogIssue {
+  readonly familyIndex: number | null;
+  readonly familyId?: string;
+  readonly path: readonly (string | number)[];
+  readonly message: string;
+}
+
+export interface AssetCatalog {
+  readonly version: 2;
+  readonly generatedAt: string;
+  readonly families: readonly AssetFamily[];
+  readonly issues: readonly AssetCatalogIssue[];
+}
+
+export function parseAssetCatalog(input: unknown): AssetCatalog {
+  const envelope = AssetCatalogEnvelopeSchema.parse(input);
+  const families: AssetFamily[] = [];
+  const issues: AssetCatalogIssue[] = [];
+  for (const [familyIndex, candidate] of envelope.families.entries()) {
+    const result = AssetFamilySchema.safeParse(candidate);
+    if (result.success) {
+      families.push(result.data);
+      continue;
+    }
+    const familyId =
+      candidate &&
+      typeof candidate === 'object' &&
+      'id' in candidate &&
+      typeof candidate.id === 'string'
+        ? candidate.id
+        : undefined;
+    for (const issue of result.error.issues) {
+      issues.push({
+        familyIndex,
+        ...(familyId ? { familyId } : {}),
+        path: issue.path.map((part) => (typeof part === 'symbol' ? String(part) : part)),
+        message: issue.message,
+      });
+    }
+  }
+  return { version: 2, generatedAt: envelope.generatedAt, families, issues };
+}
+
+export const ImportRecipeSchema = z
+  .object({
+    version: z.literal(1),
+    familyId: z.string().min(1),
+    variantId: z.string().min(1),
+    deliveryId: z.string().min(1),
+    destination: z.string().min(1),
+    retainSource: z.boolean(),
+    scale: z.number().positive().default(1),
+    upAxis: z.enum(['x', 'y', 'z']).default('y'),
+    settings: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])),
+  })
+  .strict();
+
+export const ImportResultSchema = z
+  .object({
+    recipe: ImportRecipeSchema,
+    status: z.enum(['imported', 'source-only', 'failed', 'cancelled']),
+    writtenFiles: z.array(z.string()),
+    runtimeAssetPath: z.string().optional(),
+    sourceAssetPath: z.string().optional(),
+    issues: z.array(z.object({ code: z.string(), message: z.string() }).strict()),
+  })
+  .strict();
+
+export type ImportRecipe = z.infer<typeof ImportRecipeSchema>;
+export type ImportResult = z.infer<typeof ImportResultSchema>;
+
+export interface ProjectAsset {
+  readonly projectPath: string;
+  readonly source: SourceAsset | null;
+  readonly runtime: RuntimeAsset | null;
+  readonly recipe: ImportRecipe | null;
+  readonly health: AssetHealth;
+}
+
+export interface SourceAsset {
+  readonly familyId: string;
+  readonly variantId: string;
+  readonly deliveryId: string;
+  readonly originalPath: string;
+}
+
+export interface RuntimeAsset {
+  readonly projectPath: string;
+  readonly format: 'glb' | 'gltf';
+  readonly sourceHash: string;
+}

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

@@ -0,0 +1,65 @@
+export const ASSET_WORKFLOW_BUDGETS = {
+  firstResultsMs: 500,
+  filterResponseMs: 50,
+  importProgressLatencyMs: 100,
+  maxMountedLibraryCards: 120,
+  maxPreviewConcurrency: 2,
+  maxActiveAssetEditorWebGlContexts: 1,
+  maxTelemetryEntries: 200,
+} as const;
+
+export type AssetMetricStage =
+  | 'query'
+  | 'thumbnail'
+  | 'preview'
+  | 'delivery'
+  | 'conversion'
+  | 'validation'
+  | 'commit';
+export interface AssetWorkflowMetric {
+  stage: AssetMetricStage;
+  durationMs: number;
+  outcome: 'ok' | 'failed' | 'cancelled';
+  issueCode?: string;
+  at: number;
+}
+
+const metrics: AssetWorkflowMetric[] = [];
+const listeners = new Set<() => void>();
+
+/** Local-only, path-free asset telemetry for the Debugger/Console. */
+export function recordAssetWorkflowMetric(metric: Omit<AssetWorkflowMetric, 'at'>): void {
+  metrics.push({ ...metric, durationMs: Math.max(0, metric.durationMs), at: Date.now() });
+  if (metrics.length > ASSET_WORKFLOW_BUDGETS.maxTelemetryEntries)
+    metrics.splice(0, metrics.length - ASSET_WORKFLOW_BUDGETS.maxTelemetryEntries);
+  for (const listener of listeners) listener();
+}
+export function assetWorkflowMetrics(): readonly AssetWorkflowMetric[] {
+  return metrics;
+}
+export function subscribeAssetWorkflowMetrics(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+export function resetAssetWorkflowMetrics(): void {
+  metrics.length = 0;
+}
+
+export const ASSET_ACTION_RISKS = {
+  delete: { destructive: true, confirmation: 'required' },
+  overwrite: { destructive: true, confirmation: 'required' },
+  'batch-import': { destructive: false, confirmation: 'summary' },
+  'external-source': { destructive: false, confirmation: 'external-origin' },
+  reveal: { destructive: false, confirmation: 'none' },
+  'license-blocked-delivery': { destructive: false, confirmation: 'refuse' },
+} as const;
+export type AssetRiskAction = keyof typeof ASSET_ACTION_RISKS;
+
+export function confirmAssetAction(action: AssetRiskAction, message: string): boolean {
+  const confirmation = ASSET_ACTION_RISKS[action].confirmation;
+  if (confirmation === 'refuse') return false;
+  if (confirmation === 'none') return true;
+  return window.confirm(message);
+}

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

@@ -0,0 +1,113 @@
+import { z } from 'zod';
+
+export const assetImportSettingsSchema = z.object({
+  scale: z.number().positive().default(1),
+  sourceUnits: z.enum(['auto', 'mm', 'cm', 'm', 'in', 'ft']).default('auto'),
+  upAxis: z.enum(['auto', 'x', 'y', 'z']).default('auto'),
+  forwardAxis: z.enum(['auto', 'x', '-x', 'y', '-y', 'z', '-z']).default('auto'),
+  normals: z.enum(['preserve', 'generate', 'recalculate']).default('preserve'),
+  tangents: z.enum(['preserve', 'generate', 'discard']).default('preserve'),
+  materials: z.enum(['import', 'discard']).default('import'),
+  textures: z.enum(['copy', 'embed', 'discard']).default('copy'),
+  animations: z.array(z.string()).default([]),
+  meshOptimization: z.enum(['none', 'safe', 'aggressive']).default('safe'),
+  retainSource: z.boolean().default(true),
+});
+export type AssetImportSettings = z.infer<typeof assetImportSettingsSchema>;
+
+const safePathSchema = z
+  .string()
+  .min(1)
+  .refine(
+    (path) => !path.startsWith('/') && !path.split(/[\\/]/).includes('..'),
+    'Path must stay within the source/project root.',
+  );
+
+const importFileSchema = z.object({
+  path: safePathSchema,
+  url: z.string().min(1),
+  hash: z.string().min(8),
+  size: z.number().int().nonnegative(),
+  role: z.enum(['primary', 'dependency', 'material', 'texture']),
+});
+
+export const assetImportPlanSchema = z
+  .object({
+    version: z.literal(1),
+    id: z.string().min(1),
+    identity: z.object({
+      familyId: z.string().min(1),
+      variantId: z.string().min(1),
+      deliveryId: z.string().min(1),
+    }),
+    sourceFiles: z.array(importFileSchema).min(1),
+    generatedFiles: z.array(safePathSchema),
+    destination: safePathSchema,
+    contentKind: z
+      .enum(['model', 'animation-only', 'image', 'audio', 'material', 'data'])
+      .default('model'),
+    targetSkeleton: z.string().optional(),
+    settings: assetImportSettingsSchema,
+    conflicts: z.array(
+      z.object({ path: z.string(), resolution: z.enum(['reuse', 'update', 'rename', 'cancel']) }),
+    ),
+    attribution: z.object({
+      sourceUrl: z.string(),
+      author: z.string(),
+      license: z.string(),
+      text: z.string(),
+    }),
+    sourceHash: z.string().min(8),
+    runtimeReady: z.boolean(),
+    backend: z.enum(['native', 'threejs', 'blender']),
+    createdAt: z.string(),
+  })
+  .superRefine((plan, context) => {
+    if (plan.contentKind === 'animation-only' && plan.runtimeReady && !plan.targetSkeleton) {
+      context.addIssue({
+        code: 'custom',
+        path: ['targetSkeleton'],
+        message: 'Runtime-ready animation-only imports require a compatible target skeleton.',
+      });
+    }
+  });
+export type AssetImportPlan = z.infer<typeof assetImportPlanSchema>;
+
+export const assetImportResultSchema = z.object({
+  version: z.literal(1),
+  planId: z.string(),
+  status: z.enum(['imported', 'skipped', 'failed', 'cancelled']),
+  writtenFiles: z.array(
+    z.object({ path: z.string(), hash: z.string(), size: z.number().int().nonnegative() }),
+  ),
+  skippedFiles: z.array(z.string()),
+  issues: z.array(z.object({ code: z.string(), stage: z.string(), message: z.string() })),
+  recipePath: z.string().optional(),
+});
+export type AssetImportResult = z.infer<typeof assetImportResultSchema>;
+
+export type AssetImportStage = 'fetch' | 'convert' | 'validate' | 'commit';
+export interface AssetImportProgress {
+  stage: AssetImportStage;
+  item: string;
+  loaded: number;
+  total: number;
+}
+
+export type AssetConflictKind =
+  | 'same-identity-same-hash'
+  | 'same-identity-updated'
+  | 'different-identity-same-name'
+  | 'user-edited-output';
+export function safeConflictResolution(
+  kind: AssetConflictKind,
+): 'reuse' | 'update' | 'rename' | 'cancel' {
+  if (kind === 'same-identity-same-hash') return 'reuse';
+  if (kind === 'same-identity-updated') return 'update';
+  if (kind === 'different-identity-same-name') return 'rename';
+  return 'cancel';
+}
+
+export function importRecipePath(destination: string): string {
+  return `${destination.replace(/^\/+/, '')}.vgai-import.json`;
+}

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

@@ -0,0 +1,126 @@
+import * as THREE from 'three';
+import { GLTFExporter } from 'three/addons/exporters/GLTFExporter.js';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { loadModelThumbnailObject, modelThumbnailFormat } from '../model-thumbnail';
+import type { StagedImportFile } from './asset-import-pipeline';
+import type { AssetImportPlan } from './import-contract';
+
+export interface ModelConversionBackend {
+  id: 'threejs' | 'blender';
+  available(): Promise<boolean>;
+  convert(
+    plan: AssetImportPlan,
+    sources: readonly StagedImportFile[],
+    signal: AbortSignal,
+  ): Promise<readonly StagedImportFile[]>;
+}
+
+export async function exportObjectToGlb(object: THREE.Object3D): Promise<Uint8Array> {
+  const animations = object.animations;
+  const output = await new Promise<ArrayBuffer>((resolve, reject) => {
+    new GLTFExporter().parse(
+      object,
+      (result) =>
+        result instanceof ArrayBuffer
+          ? resolve(result)
+          : reject(new Error('GLTF conversion produced JSON instead of a binary GLB.')),
+      reject,
+      { binary: true, animations, onlyVisible: false },
+    );
+  });
+  return new Uint8Array(output);
+}
+
+export async function convertModelWithThree(
+  plan: AssetImportPlan,
+  sources: readonly StagedImportFile[],
+  signal: AbortSignal,
+): Promise<readonly StagedImportFile[]> {
+  if (signal.aborted) throw signal.reason;
+  const primarySpec =
+    plan.sourceFiles.find((file) => file.role === 'primary') ?? plan.sourceFiles[0]!;
+  const primary = sources.find((file) => file.path === primarySpec.path);
+  if (!primary) throw new Error('Import primary source is missing from staging.');
+  const format = modelThumbnailFormat(primary.path);
+  if (!format) throw new Error(`No model conversion backend supports ${primary.path}.`);
+  if (format === 'glb') return [{ path: plan.destination, bytes: primary.bytes }];
+  if (format === 'gltf') {
+    const base = plan.destination.slice(0, plan.destination.lastIndexOf('/') + 1);
+    return sources.map((file) => ({
+      path: `${base}${file.path.split('/').pop()}`,
+      bytes: file.bytes,
+    }));
+  }
+  const urls: string[] = [];
+  try {
+    const primaryUrl = URL.createObjectURL(new Blob([Uint8Array.from(primary.bytes).buffer]));
+    urls.push(primaryUrl);
+    const material = sources.find((file) => file.path.toLowerCase().endsWith('.mtl'));
+    const materialUrl = material
+      ? URL.createObjectURL(new Blob([Uint8Array.from(material.bytes).buffer]))
+      : undefined;
+    if (materialUrl) urls.push(materialUrl);
+    const object = await loadModelThumbnailObject({
+      url: primaryUrl,
+      format,
+      ...(materialUrl ? { materialUrl } : {}),
+    });
+    object.scale.multiplyScalar(plan.settings.scale);
+    object.updateWorldMatrix(true, true);
+    const bytes = await exportObjectToGlb(object);
+    disposeConvertedObject(object);
+    return [{ path: plan.destination.replace(/\.[^.]+$/, '.glb'), bytes }];
+  } finally {
+    for (const url of urls) URL.revokeObjectURL(url);
+  }
+}
+
+export async function validateRuntimeModel(files: readonly StagedImportFile[]): Promise<void> {
+  const model = files.find((file) => file.path.toLowerCase().endsWith('.glb'));
+  if (!model) {
+    const gltf = files.find((file) => file.path.toLowerCase().endsWith('.gltf'));
+    if (!gltf) throw new Error('Conversion produced no runtime GLB or glTF output.');
+    JSON.parse(new TextDecoder().decode(gltf.bytes));
+    return;
+  }
+  const parsed = await new GLTFLoader().parseAsync(Uint8Array.from(model.bytes).buffer, '');
+  let renderable = false;
+  parsed.scene.traverse((object) => {
+    renderable ||= Boolean(
+      (object as THREE.Mesh).isMesh || (object as THREE.SkinnedMesh).isSkinnedMesh,
+    );
+  });
+  if (!renderable && parsed.animations.length === 0)
+    throw new Error('Runtime validation found neither renderable geometry nor animation clips.');
+  disposeConvertedObject(parsed.scene);
+}
+
+export async function chooseModelConversionBackend(
+  preferred: AssetImportPlan['backend'],
+  backends: readonly ModelConversionBackend[],
+): Promise<ModelConversionBackend> {
+  const preferredBackend = backends.find((backend) => backend.id === preferred);
+  if (preferredBackend && (await preferredBackend.available())) return preferredBackend;
+  const fallback = backends.find((backend) => backend.id === 'threejs');
+  if (fallback && (await fallback.available())) return fallback;
+  throw new Error(
+    'No model conversion backend is available. Install Blender for high-fidelity conversion or enable the built-in Three.js backend.',
+  );
+}
+
+function disposeConvertedObject(root: THREE.Object3D): void {
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: bounded cleanup must enumerate every geometry, material, and texture owned by the converted graph.
+  root.traverse((object) => {
+    const mesh = object as THREE.Mesh;
+    mesh.geometry?.dispose();
+    for (const material of Array.isArray(mesh.material)
+      ? mesh.material
+      : mesh.material
+        ? [mesh.material]
+        : []) {
+      for (const value of Object.values(material))
+        if (value instanceof THREE.Texture) value.dispose();
+      material.dispose();
+    }
+  });
+}