@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/workspace-document-registry.ts

@@ -0,0 +1,367 @@
+/**
+ * Workspace DOCUMENT registry (W0, docs/EDITOR-WORKSPACE-SHELL-TODO.md §7/§7.1
+ * — the shell-contract slice of §9 W0). The missing central-document concept:
+ * every authored subject (Three scene, prefab, Game preview, React story,
+ * asset preview, data asset, Build Profiles — the real
+ * first-party implementers §7.1 names) becomes an OPEN DOCUMENT here, and
+ * the center workspace (W1) renders the open set as tabs. Live-observation
+ * instruments such as Profiler, State Watch, Network, and XState stay in the
+ * Debugger so they never replace the subject they observe.
+ *
+ * `components/WorkspaceDock.tsx` consumes this registry and maps open
+ * subjects to Dockview panels with always-mounted content.
+ * `components/CenterDocuments.tsx` opens the first two
+ * document implementers (active Three scene, Game preview) and bridges
+ * open/activate to the store's `activeViewportTab` (the T6.3 input-gate
+ * predicate). W2/W3 migrate the remaining surfaces listed in
+ * docs/workspace-shell/W0-INVENTORY.md.
+ *
+ * Idioms mirror `inspector-section-registry.ts` one-for-one: module-scope
+ * state, `useSyncExternalStore`-shaped subscribe + monotonic version,
+ * `__resetForTest`, pure-logic headless tests (no jsdom — `Content` /
+ * `Toolbar` are never rendered by the registry itself). The shell must not
+ * switch on implementation technology for placement (§7.3 / CLAUDE.md):
+ * `kind` here is SEMANTIC metadata (what the document is to the author, per
+ * §8's naming rules), never a technology dispatch key — kind-specific
+ * behavior lives inside each descriptor's own `Content`/`Toolbar`.
+ */
+
+import type { AuthoringAdapter } from '@engine/adapter';
+import type { ComponentType } from 'react';
+
+/**
+ * Semantic document kinds — §7.1 "title, semantic kind, and optional
+ * source/provenance metadata". One entry per real first-party implementer
+ * §7.1 enumerates, plus `'tool'` for project-authored document-placement
+ * tools (§7.2). Extend the union when a new document kind genuinely ships;
+ * the registry itself never branches on it.
+ */
+export type WorkspaceDocumentKind =
+  | 'scene' // active Three scene (center document named for the scene, §5)
+  | 'prefab' // isolated prefab editor (§5.1)
+  | 'game' // the live player-facing Game preview (§8)
+  | 'world' // one manifest root's isolated edit-time authoring surface
+  | 'story' // React CSF story document (§4.2)
+  | 'asset' // model/image/audio/input-map/data-file viewer or editor (§5.1)
+  | 'data' // data asset form/table document (§5)
+  | 'content-browser' // optional thumbnail-heavy browser (§5)
+  | 'build-profiles' // build configuration (§8: 'Build Profiles')
+  | 'operation' // project-local validated tooling operation
+  | 'tool'; // project-authored document-placement tool (§7.2)
+
+/** Where a document came from — §7.1 "optional source/provenance metadata".
+ *  All fields optional: a Game preview has none; a scene has a `sourcePath`;
+ *  a live XState graph may have only an `origin`. */
+export interface WorkspaceDocumentProvenance {
+  /** Project-relative source file (e.g. `scenes/Default.vscn.json`). */
+  readonly sourcePath?: string;
+  /** Owning adapter root id (D20 — `docs/AUTHORING-ROOT-PROJECTION-DESIGN.md`). */
+  readonly rootId?: string;
+  /** Free-form origin for non-file documents (e.g. a live machine id). */
+  readonly origin?: string;
+}
+
+/** Props the W1 host will pass to a document's `Content`/`Toolbar`. */
+export interface WorkspaceDocumentContentProps {
+  /** The open document's stable id (== its descriptor's `id`). */
+  readonly documentId: string;
+  /** Whether this document is the active center tab. Hosts keep inactive
+   *  documents MOUNTED where lifecycle requires it (W1 proof bar) — content
+   *  uses this to gate work, not to exist. */
+  readonly active: boolean;
+}
+
+/** §7.1 "optional selection/Inspector context": what the Inspector should
+ *  treat as selected while this document is active. Shape matches
+ *  `inspector-section-registry.ts`'s `InspectorSectionProps` inputs. */
+export interface WorkspaceDocumentSelection {
+  readonly adapter: AuthoringAdapter;
+  /** Selected node id; `null` for the document/environment state. */
+  readonly nodeId: string | null;
+}
+
+/**
+ * The §7.1 document contract. Descriptors are definitions (immutable by
+ * convention); per-open-document RUNTIME state (dirty) lives on
+ * {@link OpenWorkspaceDocument} and is mutated through the registry.
+ */
+export interface WorkspaceDocumentDescriptor {
+  /** Stable identity scoped to project/session (§7.1) — dedupe key: opening
+   *  an id that is already open activates the existing document. */
+  readonly id: string;
+  /** Source-owned display title (§8 — `Default.vscn`, `Playing`, never a
+   *  technology bucket like `Viewport`). */
+  readonly title: string;
+  readonly kind: WorkspaceDocumentKind;
+  readonly provenance?: WorkspaceDocumentProvenance;
+  /** React content host (§7.1). Never rendered by the registry itself. */
+  readonly Content: ComponentType<WorkspaceDocumentContentProps>;
+  /** Optional document-local toolbar contribution (§7.1; §4.1 "Document tabs
+   *  and their local toolbar occupy only the center workspace"). */
+  readonly Toolbar?: ComponentType<WorkspaceDocumentContentProps>;
+  /** `false` pins the document (Scene/Game in W1). Default `true`. */
+  readonly closeable?: boolean;
+  /** Optional read-only state (§7.1). */
+  readonly readOnly?: boolean;
+  /** Optional inspect-only state (§7.1) for read-only authored resources. */
+  readonly inspectOnly?: boolean;
+  /** Optional selection/Inspector context while this document is active. */
+  readonly selection?: () => WorkspaceDocumentSelection | null;
+  /** Called when this document becomes the active document. */
+  readonly onActivate?: (documentId: string) => void;
+  /** Called when this document stops being the active document. */
+  readonly onDeactivate?: (documentId: string) => void;
+  /** Called when this document is removed from the workspace (close /
+   *  close-all) — release adapters, mounts, subscriptions here. */
+  readonly onDispose?: (documentId: string) => void;
+}
+
+/** One open document: its immutable descriptor + registry-owned state. */
+export interface OpenWorkspaceDocument {
+  readonly descriptor: WorkspaceDocumentDescriptor;
+  /** §7.1 optional dirty state — set via {@link setWorkspaceDocumentDirty}. */
+  readonly dirty: boolean;
+  /** Live display title — initialized from `descriptor.title`, updated via
+   *  {@link setWorkspaceDocumentTitle}. Registry-owned RUNTIME state (like
+   *  `dirty`), because a document's source-owned name can change while it is
+   *  open (W1: the scene document tracks the active scene's §8 name — e.g.
+   *  the async initial-scene load lands after the document is opened, and a
+   *  root activation switches the active `.vscn` in place). */
+  readonly title: string;
+}
+
+/** A mounted document editor's live save callback. `true` means the write
+ * completed; `false` means validation/persistence rejected it and the caller
+ * must keep the document open. */
+export type WorkspaceDocumentSaveHandler = () => boolean | Promise<boolean>;
+
+// --- Module-scope state (mirrors inspector-section-registry.ts) -----------
+
+let _open: OpenWorkspaceDocument[] = [];
+let _activeId: string | null = null;
+let _version = 0;
+const _listeners = new Set<() => void>();
+/** Ids currently mid-close (between the neighbor `setActive` and the
+ *  filter+`onDispose` below) — see {@link closeWorkspaceDocument}'s
+ *  re-entrancy guard. */
+const _closingIds = new Set<string>();
+const _saveHandlers = new Map<string, WorkspaceDocumentSaveHandler>();
+
+function notifyChanged(): void {
+  _version++;
+  for (const fn of _listeners) fn();
+}
+
+/** Subscribe to any open/activate/close/dirty change. Returns unsubscribe. */
+export function subscribeWorkspaceDocuments(fn: () => void): () => void {
+  _listeners.add(fn);
+  return () => {
+    _listeners.delete(fn);
+  };
+}
+
+/** Monotonic change counter — the `getSnapshot` for `useSyncExternalStore`. */
+export function workspaceDocumentRegistryVersion(): number {
+  return _version;
+}
+
+/** The open documents, in open order (stable reference between changes). */
+export function openWorkspaceDocuments(): readonly OpenWorkspaceDocument[] {
+  return _open;
+}
+
+/** The active document's id, or `null` when no document is open. */
+export function activeWorkspaceDocumentId(): string | null {
+  return _activeId;
+}
+
+/** The active open document, or `null`. */
+export function activeWorkspaceDocument(): OpenWorkspaceDocument | null {
+  return _open.find((d) => d.descriptor.id === _activeId) ?? null;
+}
+
+function setActive(nextId: string | null): void {
+  if (nextId === _activeId) return;
+  const prev = _open.find((d) => d.descriptor.id === _activeId);
+  _activeId = nextId;
+  prev?.descriptor.onDeactivate?.(prev.descriptor.id);
+  const next = _open.find((d) => d.descriptor.id === nextId);
+  next?.descriptor.onActivate?.(next.descriptor.id);
+}
+
+/**
+ * Open a document (§7.1 open semantics): appends it to the open set and
+ * makes it active. If `descriptor.id` is ALREADY open, the existing document
+ * is activated and its original descriptor kept (stable identity — a
+ * re-open never silently swaps content). Returns the id.
+ */
+export function openWorkspaceDocument(descriptor: WorkspaceDocumentDescriptor): string {
+  const existing = _open.find((d) => d.descriptor.id === descriptor.id);
+  if (!existing) {
+    _open = [..._open, { descriptor, dirty: false, title: descriptor.title }];
+    setActive(descriptor.id);
+    notifyChanged();
+    return descriptor.id;
+  }
+  // Already open: only activating (or no-op if already active) — same guard
+  // as `activateWorkspaceDocument`, no version bump/notify without a change.
+  if (_activeId !== descriptor.id) {
+    setActive(descriptor.id);
+    notifyChanged();
+  }
+  return descriptor.id;
+}
+
+/** Activate an open document. Returns `false` (no-op) for unknown ids. */
+export function activateWorkspaceDocument(id: string): boolean {
+  if (!_open.some((d) => d.descriptor.id === id)) return false;
+  if (_activeId !== id) {
+    setActive(id);
+    notifyChanged();
+  }
+  return true;
+}
+
+/**
+ * Close an open document: removes it (calling `onDeactivate` if it was
+ * active, then `onDispose`) and, when it was active, activates its left
+ * neighbor (else the right one, else none) — the standard tabbed-editor
+ * fallback. Returns `false` (no-op) for unknown ids. `closeable: false` is
+ * a HOST affordance rule (no × on the tab), not a registry invariant —
+ * programmatic close (project switch, W1 host teardown) must always work.
+ *
+ * Re-entrancy guard: the neighbor's `onActivate` (fired inside `setActive`
+ * below, while `closing` is still in `_open`) can synchronously bounce back
+ * into a close of the SAME id it is still closing — e.g. a store-notify
+ * subscriber re-derives its open set from `_open`, sees `closing` still
+ * present (the filter hasn't run yet), and calls `closeWorkspaceDocument`
+ * again for it. Without a guard that inner call would run the full close
+ * body a second time and fire `onDispose` twice for one close. `_closingIds`
+ * marks `id` in-flight for the duration of this call so the re-entrant call
+ * is a no-op (returns `false` immediately) — the outer call is the only one
+ * that ever filters `_open` / fires `onDispose`, and the pinned lifecycle
+ * order (onDeactivate → neighbor onActivate → onDispose) is unchanged.
+ */
+export function closeWorkspaceDocument(
+  id: string,
+  options: { discardDirty?: boolean } = {},
+): boolean {
+  if (_closingIds.has(id)) return false;
+  const idx = _open.findIndex((d) => d.descriptor.id === id);
+  if (idx < 0) return false;
+  const closing = _open[idx] as OpenWorkspaceDocument;
+  // A close gesture is not authorization to destroy an authored draft. The
+  // Dockview tab presents Save / Discard / Cancel and calls back with the
+  // explicit discard flag only after the user chooses it. Project teardown
+  // uses closeAllWorkspaceDocuments(), whose lifecycle semantics are separate.
+  if (closing.dirty && !options.discardDirty) return false;
+  _closingIds.add(id);
+  try {
+    const wasActive = _activeId === id;
+    if (wasActive) {
+      // Left neighbor, else right, else none — computed on the PRE-removal
+      // array so the indices are the real tab neighbors.
+      const neighbor = idx > 0 ? _open[idx - 1] : (_open[idx + 1] ?? null);
+      // `closing` must still be in `_open` here: `setActive`'s `prev` lookup
+      // finds it by `_activeId` and fires its `onDeactivate` before the
+      // neighbor's `onActivate` — firing this AFTER filtering `_open` (the
+      // former bug) made the lookup miss and silently skip onDeactivate.
+      setActive(neighbor ? neighbor.descriptor.id : null);
+    }
+    _open = _open.filter((d) => d.descriptor.id !== id);
+    _saveHandlers.delete(id);
+    closing.descriptor.onDispose?.(id);
+    notifyChanged();
+    return true;
+  } finally {
+    _closingIds.delete(id);
+  }
+}
+
+/** Close every open document (project switch / host teardown): each gets its
+ *  `onDeactivate` (active one only) + `onDispose`, in open order. */
+export function closeAllWorkspaceDocuments(): void {
+  if (_open.length === 0 && _activeId === null) return;
+  const closing = _open;
+  // Fire onDeactivate for the active document WHILE it is still in `_open`
+  // (setActive's `prev` lookup needs to find it) — clearing `_open` first
+  // (the former bug) made the lookup miss and silently skip onDeactivate.
+  setActive(null);
+  _open = [];
+  _saveHandlers.clear();
+  for (const doc of closing) doc.descriptor.onDispose?.(doc.descriptor.id);
+  notifyChanged();
+}
+
+/** Install the save capability supplied by a mounted document editor. The
+ * returned cleanup cannot remove a newer handler installed for the same id. */
+export function registerWorkspaceDocumentSaveHandler(
+  id: string,
+  handler: WorkspaceDocumentSaveHandler,
+): () => void {
+  if (!_open.some((document) => document.descriptor.id === id)) return () => {};
+  _saveHandlers.set(id, handler);
+  return () => {
+    if (_saveHandlers.get(id) === handler) _saveHandlers.delete(id);
+  };
+}
+
+/** Save one open document. `null` means that document has no document-local
+ * save capability, so callers may preserve a legacy/fallback save path. */
+export async function saveWorkspaceDocument(id: string): Promise<boolean | null> {
+  if (!_open.some((document) => document.descriptor.id === id)) return null;
+  const handler = _saveHandlers.get(id);
+  if (!handler) return null;
+  try {
+    return await handler();
+  } catch {
+    return false;
+  }
+}
+
+/** Save the active authored subject, or `null` when it has no local saver. */
+export function saveActiveWorkspaceDocument(): Promise<boolean | null> {
+  return _activeId ? saveWorkspaceDocument(_activeId) : Promise.resolve(null);
+}
+
+/** Set a document's dirty flag (§7.1 optional dirty state). Unknown ids and
+ *  no-op transitions are ignored without notification. */
+export function setWorkspaceDocumentDirty(id: string, dirty: boolean): void {
+  const idx = _open.findIndex((d) => d.descriptor.id === id);
+  if (idx < 0) return;
+  const doc = _open[idx] as OpenWorkspaceDocument;
+  if (doc.dirty === dirty) return;
+  _open = _open.map((d) => (d.descriptor.id === id ? { ...d, dirty } : d));
+  notifyChanged();
+}
+
+/** Set a document's live display title (see {@link OpenWorkspaceDocument}).
+ *  Unknown ids and no-op transitions are ignored without notification. */
+export function setWorkspaceDocumentTitle(id: string, title: string): void {
+  const doc = _open.find((d) => d.descriptor.id === id);
+  if (!doc || doc.title === title) return;
+  _open = _open.map((d) => (d.descriptor.id === id ? { ...d, title } : d));
+  notifyChanged();
+}
+
+/** A document's selection/Inspector context (guarded: a throwing `selection`
+ *  is treated as "no context" — same failure physics as tool-loader's match
+ *  guard; the shell must never crash on a contribution). */
+export function workspaceDocumentSelection(id: string): WorkspaceDocumentSelection | null {
+  const doc = _open.find((d) => d.descriptor.id === id);
+  if (!doc?.descriptor.selection) return null;
+  try {
+    return doc.descriptor.selection();
+  } catch {
+    return null;
+  }
+}
+
+/** Test-only reset (mirrors `__resetInspectorSectionRegistryForTest`) —
+ *  drops all state WITHOUT firing lifecycle hooks. */
+export function __resetWorkspaceDocumentRegistryForTest(): void {
+  _open = [];
+  _activeId = null;
+  _saveHandlers.clear();
+  notifyChanged();
+}