@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/components/asset-documents.tsx

@@ -0,0 +1,390 @@
+/**
+ * Asset DOCUMENTS (W2, docs/EDITOR-WORKSPACE-SHELL-TODO.md §5.1 / §9 W2 —
+ * inventory rows R2–R7): model/image/audio/input-map/JSON viewers open as
+ * CENTER workspace documents through `workspace-document-registry.ts`,
+ * replacing the former `RightPanel` asset-tab mechanism (`editor-store.ts`'s
+ * `AssetTab` list, deleted in this wave). The Inspector is never displaced by
+ * a viewer again (§10 acceptance #3).
+ *
+ * Identity (§7.1 stable ids): document ids keep the exact key vocabulary the
+ * old store tabs used, so the control-API surface (`open-asset-tab` /
+ * `close-asset-tab` / `active-tab` in `command-listener.ts`, `vgai
+ * open-asset`) keeps its meaning unchanged:
+ *
+ *   - project asset  → the serving path itself (`/textures/crate.png`)
+ *   - Asset Lab      → `asset-lab:entity:<entityId>`
+ *   - online asset   → `online:<source>:<id>`
+ *
+ * Titles are source-owned file names as authored (§8 — `crate.png`, never a
+ * technology bucket); the online document keeps the catalog's own asset name.
+ *
+ * Per-document RUNTIME state (an online asset resolving to a local path after
+ * download) lives in a module-scope spec map in the house
+ * `useSyncExternalStore` shape — the registry's descriptors stay immutable,
+ * and `AssetDocumentContent` re-renders from the spec map. Specs are dropped
+ * on document dispose (close / project teardown via
+ * `closeAllWorkspaceDocuments`), so nothing leaks across sessions.
+ *
+ * T6.3 interplay: activating an asset document means neither the scene
+ * viewport nor the Game preview is the active center surface, so the
+ * descriptor's `onActivate` writes the store's `'scene'` tab — the play input
+ * gate (`playState === 'playing' && activeViewportTab === 'game'`) drops
+ * without stopping play, exactly like clicking the scene tab.
+ */
+
+import { getUserData } from '@engine/scene/user-data';
+import { type ReactNode, useEffect, useSyncExternalStore } from 'react';
+import type * as THREE from 'three';
+import { bg, danger, text } from '../design-system';
+import type { AssetKind, OnlineAssetInfo } from '../editor-store';
+import {
+  openWorkspaceDocument,
+  setWorkspaceDocumentTitle,
+  type WorkspaceDocumentContentProps,
+  type WorkspaceDocumentDescriptor,
+} from '../workspace-document-registry';
+import { AssetEditorShell } from './AssetEditorShell';
+import { AssetImportDetails } from './AssetImportDetails';
+import { AudioViewer } from './asset-viewers/AudioViewer';
+import { GenericJsonViewer } from './asset-viewers/GenericJsonViewer';
+import { ImageViewer } from './asset-viewers/ImageViewer';
+import { InputMapViewer } from './asset-viewers/InputMapViewer';
+import { MaterialAssetEditor } from './asset-viewers/MaterialAssetEditor';
+import { ModelViewer } from './asset-viewers/ModelViewer';
+import { OnlineAssetDetail } from './asset-viewers/OnlineAssetDetail';
+import { SourceAssetViewer } from './asset-viewers/SourceAssetViewer';
+import './asset-workflow.css';
+
+/** What one open asset document is showing — the former `AssetTab` shape,
+ *  now keyed by workspace-document id. */
+export interface AssetDocumentSpec {
+  readonly assetPath: string;
+  readonly kind: AssetKind;
+  /** Entity source for a session-only Asset Lab document. Never serialized. */
+  readonly entityId?: string;
+  /** Present while this document shows an online (not-yet-downloaded) asset. */
+  readonly online?: OnlineAssetInfo;
+  readonly unavailableReason?: string;
+}
+
+export interface AssetDocumentMutation {
+  type: 'move' | 'delete' | 'change';
+  oldPath?: string;
+  newPath?: string;
+  paths?: readonly string[];
+}
+
+const _specs = new Map<string, AssetDocumentSpec>();
+const _pathAliases = new Map<string, string>();
+let _version = 0;
+const _listeners = new Set<() => void>();
+
+function notifyChanged(): void {
+  _version++;
+  for (const fn of _listeners) fn();
+}
+
+/** Subscribe to spec changes (online-asset resolution). Returns unsubscribe. */
+export function subscribeAssetDocuments(fn: () => void): () => void {
+  _listeners.add(fn);
+  return () => {
+    _listeners.delete(fn);
+  };
+}
+
+/** Monotonic change counter — the `getSnapshot` for `useSyncExternalStore`. */
+export function assetDocumentsVersion(): number {
+  return _version;
+}
+
+/** The spec behind an open asset document id, or `undefined`. */
+export function assetDocumentSpec(id: string): AssetDocumentSpec | undefined {
+  return _specs.get(id);
+}
+
+/** Whether `id` is one of this module's asset documents (used by
+ *  `command-listener.ts` to report the legacy `activeTabKey` facet). */
+export function isAssetDocumentId(id: string): boolean {
+  return _specs.has(id);
+}
+
+/** The narrow store surface asset documents need (T6.3 gate hand-off). */
+export interface AssetDocumentStore {
+  setActiveViewportTab(tab: 'scene' | 'game'): void;
+}
+
+/** The Asset Lab additionally needs the live object map for its §8 title. */
+export interface EntityAssetDocumentStore extends AssetDocumentStore {
+  readonly objectMap: Map<string, THREE.Object3D>;
+}
+
+function openSpecDocument(
+  store: AssetDocumentStore,
+  id: string,
+  title: string,
+  spec: AssetDocumentSpec,
+  provenance?: WorkspaceDocumentDescriptor['provenance'],
+): string {
+  if (!_specs.has(id)) {
+    _specs.set(id, spec);
+    notifyChanged();
+  }
+  const descriptor: WorkspaceDocumentDescriptor = {
+    id,
+    title,
+    kind: 'asset',
+    ...(provenance ? { provenance } : {}),
+    Content: AssetDocumentContent,
+    closeable: true,
+    onActivate: () => store.setActiveViewportTab('scene'),
+    onDispose: (documentId) => {
+      if (_specs.delete(documentId)) notifyChanged();
+    },
+  };
+  return openWorkspaceDocument(descriptor);
+}
+
+/**
+ * Open a project asset as a center document (double-click/Enter in the asset
+ * browser, `open-asset-tab` control command). Re-opening an already-open
+ * path activates the existing document (registry dedupe).
+ */
+export function openAssetDocument(
+  store: AssetDocumentStore,
+  assetPath: string,
+  kind: AssetKind,
+): string {
+  const title = assetPath.split('/').pop() ?? assetPath;
+  const id = _pathAliases.get(normalizeAssetPath(assetPath)) ?? assetPath;
+  return openSpecDocument(store, id, title, { assetPath, kind }, { sourcePath: assetPath });
+}
+
+/** Open the Asset Lab document for a live entity (`Open in Asset Lab`). */
+export function openEntityAssetDocument(store: EntityAssetDocumentStore, entityId: string): void {
+  const object = store.objectMap.get(entityId);
+  if (!object) return;
+  // NOTE: no `SceneEntity` import here (authoring-inversion ratchet —
+  // `authoring-inversion-guard.test.ts`): only the descriptor's `name` is
+  // read, structurally.
+  const entity = getUserData(object, 'entity') as { name?: string } | undefined;
+  const title = entity?.name ?? object.name ?? entityId;
+  openSpecDocument(
+    store,
+    `asset-lab:entity:${entityId}`,
+    title,
+    { assetPath: '', kind: 'model', entityId },
+    { origin: `entity:${entityId}` },
+  );
+}
+
+/** Open an online-library asset's detail/download document. */
+export function openOnlineAssetDocument(store: AssetDocumentStore, online: OnlineAssetInfo): void {
+  const kind: AssetKind =
+    online.type === 'model'
+      ? 'model'
+      : online.type === 'animation' || online.type === 'source'
+        ? 'source'
+        : 'image';
+  openSpecDocument(
+    store,
+    `online:${online.source}:${online.id}`,
+    online.name,
+    { assetPath: '', kind, online },
+    { origin: `online:${online.source}:${online.id}` },
+  );
+}
+
+/** Point an online asset document at its downloaded local file — the local
+ *  viewer takes over in place (same document id/title). */
+export function resolveOnlineAssetDocument(id: string, localPath: string): void {
+  const spec = _specs.get(id);
+  if (!spec) return;
+  const { online: _dropped, ...rest } = spec;
+  _specs.set(id, { ...rest, assetPath: localPath });
+  notifyChanged();
+}
+
+/** Test-only reset — drops all specs without touching the document registry
+ *  (pair it with `__resetWorkspaceDocumentRegistryForTest`). */
+export function __resetAssetDocumentsForTest(): void {
+  _specs.clear();
+  _pathAliases.clear();
+  notifyChanged();
+}
+
+/** Keep a live editor bound to asset identity while its source path changes. */
+export function applyAssetDocumentMutation(
+  documentId: string,
+  detail: AssetDocumentMutation,
+): void {
+  const spec = _specs.get(documentId);
+  if (!spec?.assetPath) return;
+  const current = normalizeAssetPath(spec.assetPath);
+  if (
+    detail.type === 'move' &&
+    detail.oldPath &&
+    detail.newPath &&
+    current === normalizeAssetPath(detail.oldPath)
+  ) {
+    const newPath = `/${normalizeAssetPath(detail.newPath)}`;
+    _specs.set(documentId, { ...spec, assetPath: newPath });
+    _pathAliases.set(normalizeAssetPath(newPath), documentId);
+    setWorkspaceDocumentTitle(documentId, newPath.split('/').pop() ?? newPath);
+    notifyChanged();
+  } else if (
+    detail.type === 'delete' &&
+    detail.paths?.some((path) => normalizeAssetPath(path) === current)
+  ) {
+    _specs.set(documentId, {
+      ...spec,
+      unavailableReason: `The source ${spec.assetPath} was deleted. Undo the deletion or close this editor.`,
+    });
+    notifyChanged();
+  }
+}
+
+export type AssetDocumentViewerRoute =
+  | 'online'
+  | 'model'
+  | 'image'
+  | 'audio'
+  | 'material'
+  | 'source'
+  | 'input-map'
+  | 'json'
+  | 'unsupported';
+
+/** Pure routing decision, exported so every recognized asset kind is test-pinned. */
+export function assetDocumentViewerRoute(spec: AssetDocumentSpec): AssetDocumentViewerRoute {
+  if (spec.online) return 'online';
+  if (spec.kind === 'json')
+    return spec.assetPath.split(/[?#]/, 1)[0]!.endsWith('.inputmap.json') ? 'input-map' : 'json';
+  if (['model', 'image', 'audio', 'material', 'source'].includes(spec.kind))
+    return spec.kind as AssetDocumentViewerRoute;
+  return 'unsupported';
+}
+
+/** Routes a spec to its center viewer/editor. */
+function AssetViewerBody({
+  id,
+  spec,
+  active,
+}: {
+  id: string;
+  spec: AssetDocumentSpec;
+  active: boolean;
+}) {
+  if (spec.unavailableReason) {
+    return (
+      <AssetEditorShell
+        type={spec.kind}
+        title={spec.assetPath.split('/').pop() || 'Deleted asset'}
+        status="Source unavailable"
+      >
+        <div style={{ padding: 20, color: danger }}>{spec.unavailableReason}</div>
+      </AssetEditorShell>
+    );
+  }
+  const route = assetDocumentViewerRoute(spec);
+  if (route === 'online' && spec.online) {
+    return (
+      <OnlineAssetDetail
+        online={spec.online}
+        onResolved={(localPath) => resolveOnlineAssetDocument(id, localPath)}
+      />
+    );
+  }
+  const title = spec.assetPath.split('/').pop() || spec.entityId || 'Asset';
+  if (route === 'model')
+    return (
+      <ModelViewer
+        assetPath={spec.assetPath || undefined}
+        entityId={spec.entityId}
+        active={active}
+      />
+    );
+  if (route === 'source') return <SourceAssetViewer assetPath={spec.assetPath} active={active} />;
+  let viewer: ReactNode;
+  switch (route) {
+    case 'image':
+      viewer = <ImageViewer assetPath={spec.assetPath} />;
+      break;
+    case 'audio':
+      viewer = <AudioViewer assetPath={spec.assetPath} />;
+      break;
+    case 'material':
+      viewer = <MaterialAssetEditor assetPath={spec.assetPath} documentId={id} />;
+      break;
+    case 'input-map':
+      viewer = <InputMapViewer assetPath={spec.assetPath} documentId={id} />;
+      break;
+    case 'json':
+      viewer = <GenericJsonViewer assetPath={spec.assetPath} />;
+      break;
+    default:
+      viewer = (
+        <div style={{ padding: 16, color: text[2], fontSize: 12 }}>
+          No viewer available for this asset type.
+        </div>
+      );
+  }
+  return (
+    <AssetEditorShell
+      type={route}
+      title={title}
+      details={
+        <div style={{ padding: 4 }}>
+          Source
+          <br />
+          {spec.assetPath}
+          <AssetImportDetails assetPath={spec.assetPath} />
+        </div>
+      }
+      status={`${route} · ${spec.assetPath}`}
+    >
+      {viewer}
+    </AssetEditorShell>
+  );
+}
+
+/**
+ * Full-size type-specific Asset Editor document host.
+ */
+export function AssetDocumentContent({ documentId, active }: WorkspaceDocumentContentProps) {
+  useSyncExternalStore(subscribeAssetDocuments, assetDocumentsVersion);
+  useEffect(() => {
+    const handleMutation = (rawEvent: Event) => {
+      applyAssetDocumentMutation(
+        documentId,
+        (rawEvent as CustomEvent<AssetDocumentMutation>).detail,
+      );
+    };
+    window.addEventListener('editor:asset-mutation', handleMutation);
+    return () => window.removeEventListener('editor:asset-mutation', handleMutation);
+  }, [documentId]);
+  const spec = _specs.get(documentId);
+  return (
+    <div
+      data-testid={`asset-document:${documentId}`}
+      style={{
+        flex: 1,
+        minHeight: 0,
+        overflowY: 'auto',
+        pointerEvents: 'auto',
+        background: bg[1],
+      }}
+    >
+      {spec ? (
+        <AssetViewerBody id={documentId} spec={spec} active={active} />
+      ) : (
+        <div style={{ padding: 16, color: text[2], fontSize: 12 }}>
+          This asset document is no longer available.
+        </div>
+      )}
+    </div>
+  );
+}
+
+function normalizeAssetPath(path: string): string {
+  return path.split(/[?#]/, 1)[0]!.replace(/^\/+/, '');
+}

package/src/components/asset-editor-persistence.ts

@@ -0,0 +1,44 @@
+import { getProjectFileHistory } from '../history/project-file-history';
+import type { ResourceKind } from '../history/types';
+import { getStorageBackend } from '../storage';
+import { workspaceHistoryService } from './workspace-history';
+
+/** Convert an asset's public serving URL into the StorageBackend path. */
+export function projectAssetPath(assetPath: string): string {
+  const path = assetPath.split(/[?#]/, 1)[0]!.replace(/^\/+/, '');
+  if (!path) throw new Error('Project asset path cannot be empty.');
+  return path;
+}
+
+/** Persist one authored asset through the project-wide undo history. */
+export async function writeProjectAsset(
+  assetPath: string,
+  content: string,
+  options: { label: string; kind: ResourceKind },
+): Promise<boolean> {
+  const path = projectAssetPath(assetPath);
+  const history = workspaceHistoryService();
+  const ok = history
+    ? await getProjectFileHistory(history).write(path, content, {
+        label: options.label,
+        kind: options.kind,
+        contentType: 'application/json',
+      })
+    : await getStorageBackend()
+        .write(path, content)
+        .then(() => true);
+  if (ok && typeof window !== 'undefined') {
+    window.dispatchEvent(new CustomEvent('editor:assets-changed'));
+  }
+  return ok;
+}
+
+/** Refresh an open editor after undo/redo or another surface writes its file. */
+export function subscribeProjectAsset(assetPath: string, listener: () => void): () => void {
+  const history = workspaceHistoryService();
+  if (!history) return () => {};
+  const path = projectAssetPath(assetPath);
+  return getProjectFileHistory(history).subscribeAll((changedPath) => {
+    if (changedPath === path) listener();
+  });
+}