@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/asset-selection.ts

@@ -0,0 +1,121 @@
+/**
+ * Asset SELECTION state (W2, docs/EDITOR-WORKSPACE-SHELL-TODO.md §5.1) — the
+ * "single click selects" half of the selection-vs-open contract:
+ *
+ *   - single click in the Project/Assets browser SELECTS the asset and shows
+ *     compact preview/metadata in the Inspector (the registered
+ *     `components/asset-selection-section.tsx` section reads this store);
+ *   - double click / Enter OPENS the full viewer as a center document
+ *     (`components/asset-documents.tsx`);
+ *   - drag remains a placement gesture and never touches this store.
+ *
+ * A tiny module-scope store in the house `useSyncExternalStore` shape
+ * (mirrors `inspector-section-registry.ts`): version counter + subscribe +
+ * `__resetForTest`. It deliberately does NOT touch the EditorStore's entity
+ * selection — clicking an asset must never deselect/reselect scene entities
+ * (§6.1 "selection never unexpectedly..."); instead the Inspector section
+ * simply appears for the selected asset, and the selection is auto-cleared
+ * when the ENTITY selection changes (the user moved on — see
+ * `installAssetSelectionAutoClear`).
+ */
+
+import type { AssetCapabilities } from './asset-workflow/asset-capabilities';
+import type { AssetKind } from './editor-store';
+
+/** The §5.1 compact-selection payload — enough for the Inspector section to
+ *  render preview + metadata without re-deriving browser state. */
+export interface SelectedAsset {
+  /** Serving path (`/textures/crate.png`) — doubles as the open-document key. */
+  readonly path: string;
+  /** Source-owned file name as authored (§8 — `crate.png`). */
+  readonly name: string;
+  readonly kind: AssetKind | 'folder' | 'unknown';
+  /** File size in bytes when the browser knows it. */
+  readonly sizeBytes?: number;
+  readonly capabilities?: AssetCapabilities;
+  readonly health?: 'healthy' | 'source-only' | 'unsupported' | 'stale-import';
+  readonly sourcePath?: string;
+  readonly selectionCount?: number;
+  readonly dependencies?: readonly string[];
+  readonly references?: readonly { ownerPath: string; jsonPath: string }[];
+  readonly healthCodes?: readonly string[];
+}
+
+let _selected: SelectedAsset | null = null;
+let _version = 0;
+const _listeners = new Set<() => void>();
+
+function notifyChanged(): void {
+  _version++;
+  for (const fn of _listeners) fn();
+}
+
+/** Subscribe to selection changes. Returns an unsubscribe function. */
+export function subscribeAssetSelection(fn: () => void): () => void {
+  _listeners.add(fn);
+  return () => {
+    _listeners.delete(fn);
+  };
+}
+
+/** Monotonic change counter — the `getSnapshot` for `useSyncExternalStore`. */
+export function assetSelectionVersion(): number {
+  return _version;
+}
+
+/** The currently selected asset, or `null`. */
+export function getSelectedAsset(): SelectedAsset | null {
+  return _selected;
+}
+
+/** Select an asset (single-click). Idempotent on the same path. */
+export function setSelectedAsset(asset: SelectedAsset): void {
+  if (_selected && JSON.stringify(_selected) === JSON.stringify(asset)) return;
+  _selected = asset;
+  notifyChanged();
+}
+
+/** Clear the asset selection (no-op when already clear). */
+export function clearSelectedAsset(): void {
+  if (_selected === null) return;
+  _selected = null;
+  notifyChanged();
+}
+
+/** The narrow store surface the auto-clear needs (testable with a fake). */
+export interface AssetSelectionAutoClearStore {
+  subscribe(listener: () => void): () => void;
+  readonly selectedEntityIds: ReadonlySet<string>;
+}
+
+function entitySelectionKey(store: AssetSelectionAutoClearStore): string {
+  return [...store.selectedEntityIds].sort().join('\n');
+}
+
+/**
+ * Auto-clear wiring (installed once per editor session by the layout): when
+ * the ENTITY selection changes while an asset is selected, the user has moved
+ * on — drop the asset selection so the Inspector goes back to being purely
+ * entity-contextual. The entity-selection snapshot is captured on every asset
+ * selection SET (not at install time), so only a change that happens AFTER
+ * the asset click clears it.
+ */
+export function installAssetSelectionAutoClear(store: AssetSelectionAutoClearStore): () => void {
+  let snapshot = entitySelectionKey(store);
+  const unsubscribeSelf = subscribeAssetSelection(() => {
+    if (_selected) snapshot = entitySelectionKey(store);
+  });
+  const unsubscribeStore = store.subscribe(() => {
+    if (_selected && entitySelectionKey(store) !== snapshot) clearSelectedAsset();
+  });
+  return () => {
+    unsubscribeSelf();
+    unsubscribeStore();
+  };
+}
+
+/** Test-only reset (mirrors `__resetInspectorSectionRegistryForTest`). */
+export function __resetAssetSelectionForTest(): void {
+  _selected = null;
+  notifyChanged();
+}

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

@@ -0,0 +1,259 @@
+export type AssetFormat =
+  | 'glb'
+  | 'gltf'
+  | 'fbx'
+  | 'obj'
+  | 'dae'
+  | 'stl'
+  | 'ply'
+  | '3ds'
+  | 'bvh'
+  | 'blend'
+  | 'usd'
+  | 'usda'
+  | 'usdc'
+  | 'png'
+  | 'jpg'
+  | 'jpeg'
+  | 'webp'
+  | 'gif'
+  | 'svg'
+  | 'mp3'
+  | 'ogg'
+  | 'wav'
+  | 'flac'
+  | 'vscn.json'
+  | 'prefab.json'
+  | 'mat.json'
+  | 'inputmap.json'
+  | 'data.json'
+  | 'json'
+  | 'unknown';
+
+export type AssetImportStrategy =
+  | 'copy-runtime'
+  | 'convert-model'
+  | 'animation-source'
+  | 'copy-project'
+  | 'unsupported';
+
+export type AssetCapabilityKind =
+  | 'model'
+  | 'image'
+  | 'audio'
+  | 'json'
+  | 'scene'
+  | 'prefab'
+  | 'material'
+  | 'source'
+  | 'unknown';
+
+export interface AssetCapabilities {
+  readonly format: AssetFormat;
+  readonly kind: AssetCapabilityKind;
+  readonly previewable: boolean;
+  readonly importable: boolean;
+  readonly runtimeReady: boolean;
+  readonly placeable: boolean;
+  readonly animated: boolean;
+  readonly importStrategy: AssetImportStrategy;
+  readonly editor: 'model' | 'image' | 'audio' | 'material' | 'data' | 'scene' | 'source' | 'none';
+}
+
+const MODEL_PREVIEW_FORMATS = ['glb', 'gltf', 'fbx', 'obj', 'dae', 'stl', 'ply', '3ds'] as const;
+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;
+
+function row(
+  format: AssetFormat,
+  values: Omit<AssetCapabilities, 'format'>,
+): readonly [AssetFormat, AssetCapabilities] {
+  return [format, { format, ...values }];
+}
+
+const MODEL_SOURCE_BASE = {
+  kind: 'source',
+  previewable: true,
+  importable: true,
+  runtimeReady: false,
+  placeable: false,
+  animated: false,
+  importStrategy: 'convert-model',
+  editor: 'model',
+} as const;
+
+export const ASSET_CAPABILITY_REGISTRY: ReadonlyMap<AssetFormat, AssetCapabilities> = new Map([
+  ...MODEL_PREVIEW_FORMATS.map((format) =>
+    row(format, {
+      ...MODEL_SOURCE_BASE,
+      kind: format === 'glb' || format === 'gltf' ? 'model' : 'source',
+      runtimeReady: format === 'glb' || format === 'gltf',
+      placeable: format === 'glb' || format === 'gltf',
+      importStrategy: format === 'glb' || format === 'gltf' ? 'copy-runtime' : 'convert-model',
+    }),
+  ),
+  row('bvh', {
+    kind: 'source',
+    previewable: true,
+    importable: true,
+    runtimeReady: false,
+    placeable: false,
+    animated: true,
+    importStrategy: 'animation-source',
+    editor: 'model',
+  }),
+  ...SOURCE_MODEL_FORMATS.map((format) =>
+    row(format, { ...MODEL_SOURCE_BASE, previewable: false, editor: 'source' }),
+  ),
+  ...IMAGE_FORMATS.map((format) =>
+    row(format, {
+      kind: 'image',
+      previewable: true,
+      importable: true,
+      runtimeReady: true,
+      placeable: false,
+      animated: format === 'gif',
+      importStrategy: 'copy-project',
+      editor: 'image',
+    }),
+  ),
+  ...AUDIO_FORMATS.map((format) =>
+    row(format, {
+      kind: 'audio',
+      previewable: true,
+      importable: true,
+      runtimeReady: true,
+      placeable: false,
+      animated: false,
+      importStrategy: 'copy-project',
+      editor: 'audio',
+    }),
+  ),
+  row('vscn.json', {
+    kind: 'scene',
+    previewable: false,
+    importable: true,
+    runtimeReady: true,
+    placeable: false,
+    animated: false,
+    importStrategy: 'copy-project',
+    editor: 'scene',
+  }),
+  row('prefab.json', {
+    kind: 'prefab',
+    previewable: true,
+    importable: true,
+    runtimeReady: true,
+    placeable: true,
+    animated: false,
+    importStrategy: 'copy-project',
+    editor: 'scene',
+  }),
+  row('mat.json', {
+    kind: 'material',
+    previewable: true,
+    importable: true,
+    runtimeReady: true,
+    placeable: false,
+    animated: false,
+    importStrategy: 'copy-project',
+    editor: 'material',
+  }),
+  row('inputmap.json', {
+    kind: 'json',
+    previewable: true,
+    importable: true,
+    runtimeReady: true,
+    placeable: false,
+    animated: false,
+    importStrategy: 'copy-project',
+    editor: 'data',
+  }),
+  row('data.json', {
+    kind: 'json',
+    previewable: true,
+    importable: true,
+    runtimeReady: true,
+    placeable: false,
+    animated: false,
+    importStrategy: 'copy-project',
+    editor: 'data',
+  }),
+  row('json', {
+    kind: 'json',
+    previewable: true,
+    importable: true,
+    runtimeReady: false,
+    placeable: false,
+    animated: false,
+    importStrategy: 'copy-project',
+    editor: 'data',
+  }),
+]);
+
+const UNKNOWN_CAPABILITIES: AssetCapabilities = {
+  format: 'unknown',
+  kind: 'unknown',
+  previewable: false,
+  importable: false,
+  runtimeReady: false,
+  placeable: false,
+  animated: false,
+  importStrategy: 'unsupported',
+  editor: 'none',
+};
+
+export function assetFormatFromPath(path: string): AssetFormat {
+  const clean = path.split(/[?#]/, 1)[0]!.toLowerCase();
+  for (const compound of [
+    'vscn.json',
+    'prefab.json',
+    'mat.json',
+    'inputmap.json',
+    'data.json',
+  ] as const) {
+    if (clean.endsWith(`.${compound}`)) return compound;
+  }
+  const dot = clean.lastIndexOf('.');
+  const extension = dot >= 0 ? clean.slice(dot + 1) : '';
+  return ASSET_CAPABILITY_REGISTRY.has(extension as AssetFormat)
+    ? (extension as AssetFormat)
+    : extension === 'json'
+      ? 'json'
+      : 'unknown';
+}
+
+export function assetCapabilities(pathOrFormat: string): AssetCapabilities {
+  const direct = ASSET_CAPABILITY_REGISTRY.get(pathOrFormat.toLowerCase() as AssetFormat);
+  if (direct) return direct;
+  return ASSET_CAPABILITY_REGISTRY.get(assetFormatFromPath(pathOrFormat)) ?? UNKNOWN_CAPABILITIES;
+}
+
+export function supportedAssetFormats(): readonly AssetFormat[] {
+  return [...ASSET_CAPABILITY_REGISTRY.keys()];
+}
+
+/** Editor document kind for a capability row; null means no honest editor exists. */
+export function assetDocumentKind(
+  capability: AssetCapabilities,
+): 'model' | 'image' | 'audio' | 'json' | 'scene' | 'prefab' | 'material' | 'source' | null {
+  switch (capability.editor) {
+    case 'model':
+      return 'model';
+    case 'image':
+      return 'image';
+    case 'audio':
+      return 'audio';
+    case 'material':
+      return 'material';
+    case 'data':
+      return 'json';
+    case 'source':
+      return 'source';
+    case 'scene':
+      return capability.kind === 'prefab' ? 'prefab' : 'scene';
+    default:
+      return null;
+  }
+}

package/src/asset-workflow/asset-editor-errors.ts

@@ -0,0 +1,46 @@
+export type AssetLoadStage =
+  | 'fetching'
+  | 'parsing'
+  | 'dependency-resolution'
+  | 'conversion'
+  | 'gpu-upload'
+  | 'rendering'
+  | 'ready';
+
+export interface AssetEditorIssue {
+  code: string;
+  stage: AssetLoadStage;
+  message: string;
+  recovery: Array<'retry' | 'reveal-source' | 'choose-variant' | 'reimport'>;
+}
+
+/** Convert loader-specific failures into actionable, stable editor diagnostics. */
+export function classifyAssetEditorError(error: unknown, stage: AssetLoadStage): AssetEditorIssue {
+  const message = error instanceof Error ? error.message : String(error);
+  const lower = message.toLowerCase();
+  if (lower.includes('404') || lower.includes('failed to fetch')) {
+    return {
+      code: 'asset.fetch.failed',
+      stage: 'fetching',
+      message,
+      recovery: ['retry', 'reveal-source'],
+    };
+  }
+  if (lower.includes('dependency') || lower.includes('buffer') || lower.includes('texture')) {
+    return {
+      code: 'asset.dependency.missing',
+      stage: 'dependency-resolution',
+      message,
+      recovery: ['reveal-source', 'reimport'],
+    };
+  }
+  if (lower.includes('bounds') || lower.includes('geometry')) {
+    return {
+      code: 'asset.render.no-geometry',
+      stage: 'rendering',
+      message: `${message} The source may be animation-only or contain hidden/zero-sized geometry.`,
+      recovery: ['choose-variant', 'reimport'],
+    };
+  }
+  return { code: `asset.${stage}.failed`, stage, message, recovery: ['retry', 'reimport'] };
+}

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

@@ -0,0 +1,176 @@
+import type { HistoryService } from '../history/history-service';
+import { getProjectFileHistory } from '../history/project-file-history';
+import { sha256Hex } from '../history/snapshot-store';
+import type { StorageBackend } from '../storage/types';
+import { recordAssetWorkflowMetric } from './asset-workflow-quality';
+import {
+  type AssetImportPlan,
+  type AssetImportProgress,
+  type AssetImportResult,
+  assetImportPlanSchema,
+  importRecipePath,
+} from './import-contract';
+
+export interface StagedImportFile {
+  path: string;
+  bytes: Uint8Array;
+}
+export interface AssetImportPipelineDependencies {
+  fetch(
+    file: AssetImportPlan['sourceFiles'][number],
+    signal: AbortSignal,
+    progress: (loaded: number, total: number) => void,
+  ): Promise<Uint8Array>;
+  convert(
+    plan: AssetImportPlan,
+    sources: readonly StagedImportFile[],
+    signal: AbortSignal,
+  ): Promise<readonly StagedImportFile[]>;
+  validate(
+    plan: AssetImportPlan,
+    files: readonly StagedImportFile[],
+    signal: AbortSignal,
+  ): Promise<void>;
+  commit(plan: AssetImportPlan, files: readonly StagedImportFile[]): Promise<boolean>;
+}
+
+function abortIfNeeded(signal: AbortSignal): void {
+  if (signal.aborted) throw signal.reason ?? new DOMException('Import cancelled', 'AbortError');
+}
+
+/** Four-stage import: no project mutation occurs until all staged bytes validate. */
+export async function runAssetImportPipeline(
+  rawPlan: AssetImportPlan,
+  dependencies: AssetImportPipelineDependencies,
+  options: { signal: AbortSignal; onProgress?: (progress: AssetImportProgress) => void },
+): Promise<AssetImportResult> {
+  const plan = assetImportPlanSchema.parse(rawPlan);
+  const stagedSources: StagedImportFile[] = [];
+  let stageStarted = performance.now();
+  const metric = (
+    stage: 'delivery' | 'conversion' | 'validation' | 'commit',
+    outcome: 'ok' | 'failed' | 'cancelled' = 'ok',
+  ) => {
+    recordAssetWorkflowMetric({ stage, durationMs: performance.now() - stageStarted, outcome });
+    stageStarted = performance.now();
+  };
+  try {
+    for (const file of plan.sourceFiles) {
+      abortIfNeeded(options.signal);
+      const bytes = await dependencies.fetch(file, options.signal, (loaded, total) =>
+        options.onProgress?.({ stage: 'fetch', item: file.path, loaded, total }),
+      );
+      stagedSources.push({ path: file.path, bytes });
+    }
+    metric('delivery');
+    abortIfNeeded(options.signal);
+    options.onProgress?.({ stage: 'convert', item: plan.destination, loaded: 0, total: 1 });
+    const outputs = await dependencies.convert(plan, stagedSources, options.signal);
+    metric('conversion');
+    abortIfNeeded(options.signal);
+    options.onProgress?.({
+      stage: 'validate',
+      item: plan.destination,
+      loaded: 0,
+      total: outputs.length,
+    });
+    await dependencies.validate(plan, outputs, options.signal);
+    metric('validation');
+    abortIfNeeded(options.signal);
+    options.onProgress?.({
+      stage: 'commit',
+      item: plan.destination,
+      loaded: 0,
+      total: outputs.length,
+    });
+    if (!(await dependencies.commit(plan, outputs)))
+      throw new Error('Atomic project commit was rejected.');
+    metric('commit');
+    return {
+      version: 1,
+      planId: plan.id,
+      status: 'imported',
+      writtenFiles: await Promise.all(
+        outputs.map(async (file) => ({
+          path: file.path,
+          hash: await sha256Hex(file.bytes),
+          size: file.bytes.byteLength,
+        })),
+      ),
+      skippedFiles: [],
+      issues: [],
+      recipePath: importRecipePath(plan.destination),
+    };
+  } catch (error) {
+    const cancelled =
+      options.signal.aborted || (error instanceof DOMException && error.name === 'AbortError');
+    metric('commit', cancelled ? 'cancelled' : 'failed');
+    return {
+      version: 1,
+      planId: plan.id,
+      status: cancelled ? 'cancelled' : 'failed',
+      writtenFiles: [],
+      skippedFiles: [],
+      issues: [
+        {
+          code: cancelled ? 'import.cancelled' : 'import.failed',
+          stage: 'staging',
+          message: error instanceof Error ? error.message : String(error),
+        },
+      ],
+    };
+  }
+}
+
+export async function commitAssetImport(
+  plan: AssetImportPlan,
+  outputs: readonly StagedImportFile[],
+  dependencies: { backend: StorageBackend; history: HistoryService },
+): Promise<boolean> {
+  const recipe = JSON.stringify(plan, null, 2);
+  const changes = [
+    ...outputs.map((file) => ({ path: file.path, data: file.bytes })),
+    { path: importRecipePath(plan.destination), data: recipe, contentType: 'application/json' },
+  ];
+  return getProjectFileHistory(dependencies.history, dependencies.backend).mutate(changes, {
+    label: `Import ${plan.identity.familyId}`,
+  });
+}
+
+export async function fetchImportFile(
+  file: AssetImportPlan['sourceFiles'][number],
+  signal: AbortSignal,
+  progress: (loaded: number, total: number) => void,
+): Promise<Uint8Array> {
+  const response = await fetch(file.url, { signal, cache: 'no-store' });
+  if (!response.ok) throw new Error(`Fetch failed with HTTP ${response.status}: ${file.url}`);
+  const bytes = new Uint8Array(await response.arrayBuffer());
+  progress(bytes.byteLength, Number(response.headers.get('content-length')) || bytes.byteLength);
+  if ((await sha256Hex(bytes)) !== file.hash)
+    throw new Error(`Source hash mismatch for ${file.path}.`);
+  return bytes;
+}
+
+export interface AttributionEntry {
+  familyId: string;
+  name: string;
+  author: string;
+  license: string;
+  sourceUrl: string;
+  text: string;
+}
+
+export function generateAttributionReports(entries: readonly AttributionEntry[]): {
+  json: string;
+  markdown: string;
+} {
+  const unique = [
+    ...new Map(
+      entries.map((entry) => [`${entry.familyId}:${entry.license}:${entry.sourceUrl}`, entry]),
+    ).values(),
+  ].sort((a, b) => a.name.localeCompare(b.name) || a.familyId.localeCompare(b.familyId));
+  return {
+    json: `${JSON.stringify({ version: 1, assets: unique }, null, 2)}\n`,
+    markdown: `# Asset attribution\n\n${unique.map((entry) => `## ${entry.name}\n\n${entry.text}\n\nAuthor: ${entry.author}  \nLicense: ${entry.license}  \nSource: ${entry.sourceUrl}`).join('\n\n')}\n`,
+  };
+}