@volter/editor-core 0.5.57

package/src/asset-selection-viewer-registry.ts

@@ -0,0 +1,113 @@
+/**
+ * WHO DRAWS *THIS* SELECTED ASSET — the tenth registry in the family of
+ * `workspace-document-restore.ts` (a kind owns its persisted state),
+ * `document-open-registry.ts` (a kind owns how it opens),
+ * `chrome-slot-registry.ts` (the host owns the place, a package owns what
+ * sits there), `content-entry-source-registry.ts` (the host owns the Content
+ * scope, a package owns why a component is content),
+ * `authoring/design-time-mount-registry.ts`, `component-board-registry.ts`,
+ * `component-states-registry.ts` and `static-panel-presentation-registry.ts`.
+ * Here: the host owns the Inspector's asset SECTION — the thumbnail, the
+ * metadata rows, the tool sections, the empty state — and a package owns the
+ * body for an asset the host has no way to draw.
+ *
+ * WHY IT EXISTS. `components/asset-selection-section.tsx` opened with
+ * `if (asset.online) { … <OnlineAssetDetail/> … }` — the Inspector knowing
+ * that an asset can come from an external catalog, and importing that
+ * catalog's whole detail view (421 lines, plus the import-job ledger it
+ * writes) into every editor boot, a `models` build that has no catalog
+ * included (WORK.md §The open-source launch, the final audit's online-library
+ * row). The sibling of `contentEntryForComponent`: one question — "is there a
+ * registered body for this subject, and what is it" — asked of a registry
+ * instead of answered by a branch.
+ *
+ * THE SHAPE is transcribed from `content-entry-source-registry.ts` (register /
+ * list / subscribe, owner-replaces-owner for an HMR re-evaluation, a stable
+ * EMPTY array so a reader's `useSyncExternalStore` snapshot is stable). TWO
+ * deliberate differences:
+ *  - NO per-registration `subscribe` to re-fan. A content SOURCE has a ledger
+ *    that settles asynchronously; a viewer is a pure function of the asset
+ *    the host already re-renders on. The registry's own change signal is all
+ *    a reader needs, and a hook with nothing to subscribe to is a name that
+ *    got built because it was named.
+ *  - `match(asset)` IS THE WHOLE DISCRIMINATOR. The host never asks "is this
+ *    online" again; it asks who claims the asset. First match wins, in
+ *    registration order, so a build with no catalog package falls through to
+ *    the host's own generic body — which is the answer it always gave for
+ *    every asset that was not online.
+ *
+ * NOTHING REGISTERED IS A REAL ANSWER: the generic body, exactly as before.
+ */
+
+import type { ComponentType } from 'react';
+import type { SelectedAsset } from './asset-selection';
+
+export interface AssetSelectionViewerProps {
+  readonly asset: SelectedAsset;
+}
+
+export interface AssetSelectionViewer {
+  /** The viewer's id, in its own vocabulary. */
+  readonly id: string;
+  /** Which module registered it. Re-registering the same owner+id REPLACES. */
+  readonly owner: string;
+  /** Ascending; ties keep registration order. */
+  readonly order?: number;
+  /** Does this viewer claim the selected asset? The host asks; it never
+   *  inspects the asset for a lane's own fields itself. */
+  readonly match: (asset: SelectedAsset) => boolean;
+  /** The Inspector body for a claimed asset, rendered INSTEAD of the host's
+   *  generic one — the viewer owns everything below the section's frame,
+   *  including any actions it wants. */
+  readonly View: ComponentType<AssetSelectionViewerProps>;
+}
+
+const _viewers: AssetSelectionViewer[] = [];
+const listeners = new Set<() => void>();
+let version = 0;
+
+function publish(): void {
+  version++;
+  for (const listener of listeners) listener();
+}
+
+/** Install a viewer. Returns the teardown. */
+export function registerAssetSelectionViewer(viewer: AssetSelectionViewer): () => void {
+  const stale = _viewers.findIndex((item) => item.owner === viewer.owner && item.id === viewer.id);
+  if (stale >= 0) _viewers.splice(stale, 1);
+  _viewers.push(viewer);
+  _viewers.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+  publish();
+  return () => {
+    const at = _viewers.indexOf(viewer);
+    if (at < 0) return;
+    _viewers.splice(at, 1);
+    publish();
+  };
+}
+
+/** The first registered viewer that claims this asset, or `null` — "nobody
+ *  registered a body for it", which is a real answer and never an error. */
+export function assetSelectionViewerFor(asset: SelectedAsset): AssetSelectionViewer | null {
+  for (const viewer of _viewers) if (viewer.match(asset)) return viewer;
+  return null;
+}
+
+/** ONE subscription for the Inspector section. */
+export function subscribeAssetSelectionViewers(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function assetSelectionViewersVersion(): number {
+  return version;
+}
+
+/** Test-only reset (mirrors the restore, open, chrome-slot, content-source,
+ *  design-time-mount, component-board and static-panel registries'). */
+export function __resetAssetSelectionViewersForTest(): void {
+  _viewers.length = 0;
+  publish();
+}

package/src/asset-selection.ts

@@ -0,0 +1,133 @@
+/**
+ * Asset SELECTION state (W2) — 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 EditorShellStore's entity
+ * selection — clicking an asset must never deselect/reselect scene entities
+ * (§6.1 "selection never unexpectedly..."); instead the Inspector gives the
+ * asset domain precedence while retaining that entity selection, and the asset 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, OnlineAssetInfo } from './editor-shell-store';
+
+/** The §5.1 compact-selection payload — enough for the Inspector section to
+ *  render preview + metadata without re-deriving browser state. */
+export interface SelectedAsset {
+  /** Project serving path, or a stable `online:<source>:<id>` document key. */
+  readonly path: string;
+  /** Source-owned file name as authored (§8 — `crate.png`). */
+  readonly name: string;
+  readonly kind: AssetKind | 'component' | 'folder' | 'unknown';
+  /** Portable-CSF preview identity for a source-owned prefab/component. */
+  readonly componentPreview?: {
+    readonly surface: 'three' | 'canvas' | 'dom' | 'unknown';
+    readonly sourcePath: string;
+  };
+  /** File size in bytes when the browser knows it. */
+  readonly sizeBytes?: number;
+  readonly capabilities?: AssetCapabilities;
+  readonly health?: 'healthy' | 'source-only' | 'unsupported';
+  readonly sourcePath?: string;
+  readonly selectionCount?: number;
+  readonly selectionTotalBytes?: number;
+  readonly selectionFormats?: readonly string[];
+  readonly dependencies?: readonly string[];
+  readonly references?: readonly { ownerPath: string; jsonPath: string }[];
+  readonly healthCodes?: readonly string[];
+  /** Selection came from the external acquisition Library rather than the
+   * project's owned file tree. `online` carries the provider identity and is
+   * intentionally absent from project assets. */
+  readonly origin?: 'project' | 'library';
+  readonly online?: OnlineAssetInfo;
+}
+
+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,344 @@
+export type AssetFormat =
+  | 'glb'
+  | 'gltf'
+  | 'fbx'
+  | 'obj'
+  | 'dae'
+  | 'stl'
+  | 'ply'
+  | 'spz'
+  | '3ds'
+  | 'bvh'
+  | 'blend'
+  | 'usd'
+  | 'usda'
+  | 'usdc'
+  | 'png'
+  | 'jpg'
+  | 'jpeg'
+  | 'webp'
+  | 'gif'
+  | 'svg'
+  | 'hdr'
+  | 'exr'
+  | 'mp4'
+  | 'webm'
+  | 'mp3'
+  | 'ogg'
+  | 'wav'
+  | 'flac'
+  | 'cube'
+  | 'glsl'
+  | 'vert'
+  | 'frag'
+  | 'ts'
+  | 'tsx'
+  | 'js'
+  | 'jsx'
+  | 'css'
+  | 'html'
+  | 'md'
+  | 'txt'
+  | 'mtl'
+  | 'csv'
+  | 'xml'
+  | 'yaml'
+  | 'yml'
+  | 'inputmap.json'
+  | 'data.json'
+  | 'json'
+  | 'unknown';
+
+export type AssetImportStrategy =
+  | 'copy-runtime'
+  | 'convert-model'
+  | 'animation-source'
+  | 'copy-project'
+  | 'unsupported';
+
+export type AssetCapabilityKind =
+  | 'model'
+  | 'image'
+  | 'video'
+  | 'audio'
+  | 'json'
+  | 'prefab'
+  | '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'
+    | 'environment'
+    | 'video'
+    | 'audio'
+    | 'data'
+    | '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 HIGH_DYNAMIC_RANGE_FORMATS = ['hdr', 'exr'] as const;
+const AUDIO_FORMATS = ['mp3', 'ogg', 'wav', 'flac'] as const;
+/** Clip formats a browser plays natively. Reference material (a generated
+ *  motion study, a captured plate) is the common case, and a video is NOT a
+ *  runtime-ready game asset: nothing in a scene places one, so `placeable`
+ *  and `runtimeReady` stay false and the row's whole job is to be seen. */
+const VIDEO_FORMATS = ['mp4', 'webm'] as const;
+const COLOR_GRADE_FORMATS = ['cube'] as const;
+const SHADER_SOURCE_FORMATS = ['glsl', 'vert', 'frag'] 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,
+  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('spz', {
+    kind: 'model',
+    previewable: true,
+    importable: true,
+    runtimeReady: true,
+    placeable: true,
+    animated: false,
+    importStrategy: 'copy-runtime',
+    editor: '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',
+    }),
+  ),
+  ...HIGH_DYNAMIC_RANGE_FORMATS.map((format) =>
+    row(format, {
+      kind: 'image',
+      previewable: true,
+      importable: true,
+      runtimeReady: true,
+      placeable: false,
+      animated: false,
+      importStrategy: 'copy-project',
+      editor: 'environment',
+    }),
+  ),
+  ...AUDIO_FORMATS.map((format) =>
+    row(format, {
+      kind: 'audio',
+      previewable: true,
+      importable: true,
+      runtimeReady: true,
+      placeable: false,
+      animated: false,
+      importStrategy: 'copy-project',
+      editor: 'audio',
+    }),
+  ),
+  ...VIDEO_FORMATS.map((format) =>
+    row(format, {
+      kind: 'video',
+      previewable: true,
+      importable: true,
+      runtimeReady: false,
+      placeable: false,
+      animated: true,
+      importStrategy: 'copy-project',
+      editor: 'video',
+    }),
+  ),
+  ...COLOR_GRADE_FORMATS.map((format) =>
+    row(format, {
+      kind: 'source',
+      previewable: true,
+      importable: true,
+      runtimeReady: true,
+      placeable: false,
+      animated: false,
+      importStrategy: 'copy-project',
+      editor: 'source',
+    }),
+  ),
+  ...SHADER_SOURCE_FORMATS.map((format) =>
+    row(format, {
+      kind: 'source',
+      previewable: true,
+      importable: true,
+      runtimeReady: true,
+      placeable: false,
+      animated: false,
+      importStrategy: 'copy-project',
+      editor: 'source',
+    }),
+  ),
+  ...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('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 ['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' | 'video' | 'audio' | 'json' | 'source' | null {
+  switch (capability.editor) {
+    case 'model':
+      return 'model';
+    case 'image':
+      return 'image';
+    case 'environment':
+      // Workspace persistence needs only the broad asset kind. The path and
+      // capability registry recover the native HDR/EXR viewer on restore.
+      return 'image';
+    case 'video':
+      return 'video';
+    case 'audio':
+      return 'audio';
+    case 'data':
+      return 'json';
+    case 'source':
+      return 'source';
+    default:
+      return null;
+  }
+}

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

@@ -0,0 +1,106 @@
+import { connectEvents } from '../editor-api';
+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 {
+  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();
+  };
+}