@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/components/core-utilities.tsx

@@ -0,0 +1,75 @@
+/**
+ * The editor's built-in DRAWER utilities, registered through the same
+ * W0 workspace-utility registry every other utility uses, so Dockview's
+ * bottom edge group is registry-driven end to end:
+ *
+ *  - **Console** (B3): always available; its error/warn count becomes the
+ *    registry `badge()` (rendered on the collapsed tab — the badge, never
+ *    an auto-open, is how log entries call for attention; only actionable
+ *    save failures reveal it automatically).
+ *  - **Debugger**: persistent instrument container. Profiler, State,
+ *    Network, Machines, and Commands remain discoverable; views without a
+ *    live source show an honest empty state.
+ *
+ * PROBLEMS (§4.1 mock's `Problems` tab) is deliberately NOT registered —
+ * the W4 decision, recorded in the inventory: no truthful problem SOURCE
+ * exists today (there is no in-editor typecheck surface; scene-validation
+ * failures already surface as console errors + the MountFailureBanner), and
+ * §4.3's spirit forbids fabricating a surface with nothing real to feed it.
+ * The status bar's error count (`status-contributions.tsx`) reads the
+ * console counts — the truthful signal that does exist. A real Problems
+ * utility lands when a real diagnostics source does.
+ *
+ * Idempotent-ensure idiom mirrors `build-documents.tsx`'s
+ * `ensureBuildContributionsRegistered`.
+ */
+
+import { editorConsole } from '../editor-console';
+import { createHmrRegistrationGroup } from '../hmr-registration-group';
+import {
+  registerWorkspaceUtility,
+  type WorkspaceUtilityBadge,
+} from '../workspace-utility-registry';
+import { ConsolePanel } from './ConsolePanel';
+import { DebuggerPanel } from './DebuggerPanel';
+
+const registrationGroup = createHmrRegistrationGroup(import.meta.hot, 'core-utilities');
+
+/** The Console tab's attention badge: error count (error severity) else
+ *  warn count (warn severity) else none. Exported for tests. */
+export function consoleUtilityBadge(): WorkspaceUtilityBadge | null {
+  const { error, warn } = editorConsole.counts;
+  if (error > 0) return { count: error + warn, severity: 'error' };
+  if (warn > 0) return { count: warn, severity: 'warn' };
+  return null;
+}
+
+/** Idempotent one-time registration of the built-in workspace utilities. */
+export function ensureCoreUtilitiesRegistered(): void {
+  registrationGroup.ensure((track) => {
+    track(
+      registerWorkspaceUtility({
+        id: 'console',
+        title: 'Console',
+        order: -100, // first utility tab, matching the §4.1 mock's tab order
+        Content: ConsolePanel,
+        badge: consoleUtilityBadge,
+        subscribeBadge: editorConsole.subscribe,
+        badgeSnapshot: editorConsole.getSnapshot,
+      }),
+    );
+    track(
+      registerWorkspaceUtility({
+        id: 'debugger',
+        title: 'Debugger',
+        order: 20,
+        Content: DebuggerPanel,
+      }),
+    );
+  });
+}
+
+/** Test-only: allow re-registration after a registry reset. */
+export function __resetCoreUtilitiesForTest(): void {
+  registrationGroup.reset();
+}

package/src/components/data-documents.tsx

@@ -0,0 +1,364 @@
+import { themeVars } from '../design-system';
+/**
+ * Data DOCUMENTS (W3, docs/EDITOR-WORKSPACE-SHELL-TODO.md §5/§9 W3 —
+ * inventory row B5): each `src/data/*.data.json` opens as a NAMED center
+ * form/table document (kind `'data'`, title = the file's own name per §8,
+ * e.g. `tuning.data.json`), replacing the permanent bottom DATA tab. The
+ * editing machinery itself is unchanged (`data-editor.tsx`, formerly
+ * `DataPanel.tsx`) — same emitted-schema widget pipeline, same D1
+ * write-immediately semantics through the SAME write path (history-service
+ * `write` when available, raw `/__editor/data-file` POST otherwise), same
+ * `$schema`-first key-order-preserving serialization. DATA-TOOLS-DESIGN's
+ * transaction rules stay authoritative.
+ *
+ * DISCOVERY (the B5 "record which" decision): the old tab's master file list
+ * folds into existing navigation — the COMMAND PALETTE lists one
+ * `Open Data Asset: <name>` action per discovered file (live folder-scan
+ * store, refreshed at editor init + on W6a's add/unlink SSE events), plus a
+ * static `Data Assets` action opening a small navigation/teaching document
+ * (the file list; the W6d empty state when the project has none). Data is a
+ * typed project resource, not a permanent navigator tab; these named center
+ * documents remain its authoring surface.
+ *
+ * Loaded-file state is a module-scope store (house `useSyncExternalStore`
+ * shape) rather than per-component state so every data document, the guide
+ * document, and the palette actions read ONE folder-scan truth — exactly the
+ * D3 "discovery IS the folder scan" physics the panel had, shared.
+ *
+ * Selected-row-details-in-Inspector (§5's "may") is deliberately NOT built
+ * this wave — the wide center grid already gives every cell a real widget;
+ * a second Inspector-hosted detail form would be a new master-detail
+ * mechanism with no demand signal yet. Recorded as a deferral, not a gap.
+ */
+
+import { useEffect, useSyncExternalStore } from 'react';
+import type { EditorAction } from '../action-registry';
+import { connectDataFileEvents } from '../asset-events';
+import { EditorListButton } from '../design-system';
+import { getProjectFileHistory, type ProjectFileHistory } from '../history/project-file-history';
+import { getDataHistoryBackend } from '../history/project-root-history-backends';
+import {
+  openWorkspaceDocument,
+  type WorkspaceDocumentContentProps,
+} from '../workspace-document-registry';
+import {
+  DataEmptyState,
+  DataFileEditor,
+  type LoadedDataFile,
+  nextKeyOrder,
+  parseServerFile,
+  RefOptionsContext,
+  type ServerDataFile,
+  serializeDataFile,
+} from './data-editor';
+import { workspaceHistoryService } from './workspace-history';
+
+// --- The shared loaded-files store (one folder-scan truth) -----------------
+
+let _files: LoadedDataFile[] = [];
+let _version = 0;
+const _listeners = new Set<() => void>();
+
+function notifyChanged(): void {
+  _version++;
+  for (const fn of _listeners) fn();
+}
+
+/** Subscribe to loaded-data-file changes. Returns unsubscribe. */
+export function subscribeDataFiles(fn: () => void): () => void {
+  _listeners.add(fn);
+  return () => {
+    _listeners.delete(fn);
+  };
+}
+
+/** Monotonic change counter — the `getSnapshot` for `useSyncExternalStore`. */
+export function dataFilesVersion(): number {
+  return _version;
+}
+
+/** The currently loaded data files (stable reference between changes). */
+export function loadedDataFiles(): readonly LoadedDataFile[] {
+  return _files;
+}
+
+/** Re-run the folder scan (`GET /__editor/data-files`) — D3: discovery IS
+ *  the folder scan, never a cached manifest. Server unreachable keeps the
+ *  last snapshot (same physics as the old panel's `refresh`). */
+export async function refreshDataFiles(): Promise<void> {
+  try {
+    const res = await fetch('/__editor/data-files');
+    if (!res.ok) return;
+    const { files: raw } = (await res.json()) as { files: ServerDataFile[] };
+    _files = raw.map(parseServerFile);
+    notifyChanged();
+  } catch {
+    /* server unreachable — keep whatever we last had */
+  }
+}
+
+/**
+ * Editor-init discovery lifecycle (same B13 physics as project-tool
+ * discovery): initial scan + re-scan on W6a's add/unlink SSE events (a
+ * `change` event is deliberately not broadcast by the server — it would echo
+ * this module's own POST writes back into a refetch, clobbering in-flight
+ * drafts). Returns a cleanup that detaches the SSE listener.
+ */
+export function startDataAssetDiscovery(): () => void {
+  void refreshDataFiles();
+  return connectDataFileEvents(() => void refreshDataFiles());
+}
+
+/** Test-only reset. */
+export function __resetDataFilesForTest(): void {
+  _files = [];
+  notifyChanged();
+}
+
+// --- Writes (the D1 path, verbatim from the old panel) ---------------------
+
+/**
+ * D1 (spec §2.5): commit → write the file IMMEDIATELY, no buffering. The
+ * local store copy is updated in the same tick so widgets stay live; disk is
+ * the document. D5 resolution: this deliberately BYPASSES the play-mode
+ * overlay (scene-entity-only) — a running game receives the change through
+ * the shipped `.data.json` HMR path instead. `nextKeyOrder` folds the
+ * commit's keys into the file's current on-disk order once, and the result
+ * becomes this file's `keyOrder` going forward, so a whole session of edits
+ * keeps the original key order (integer-like keys included) stable.
+ */
+export function commitDataFile(
+  file: LoadedDataFile,
+  nextData: Record<string, unknown>,
+  fileHistory: ProjectFileHistory | null,
+): void {
+  const order = nextKeyOrder(file.keyOrder, nextData);
+  const content = serializeDataFile(nextData, order);
+  _files = _files.map((f) =>
+    f.path === file.path ? { ...f, data: nextData, keyOrder: order } : f,
+  );
+  notifyChanged();
+  if (!fileHistory) {
+    void fetch('/__editor/data-file', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ path: file.path, content }),
+    });
+    return;
+  }
+  void fileHistory
+    .write(file.path, content, {
+      label: `Edit ${file.path.split('/').pop() ?? 'Data'}`,
+      kind: 'data',
+      contentType: 'application/json',
+    })
+    .catch(() => void refreshDataFiles());
+}
+
+// --- Documents --------------------------------------------------------------
+
+/** The narrow store surface data documents need (T6.3 gate hand-off — same
+ *  contract as `asset-documents.tsx`). */
+export interface DataDocumentStore {
+  setActiveViewportTab(tab: 'scene' | 'game'): void;
+}
+
+/** Stable §7.1 identity for one data-asset document. */
+export function dataDocumentId(path: string): string {
+  return `data:${path}`;
+}
+
+/** The navigation/teaching `Data Assets` document's id. */
+export const DATA_ASSETS_DOCUMENT_ID = 'workspace:data-assets';
+
+/** §8 source-owned title: the file's own basename (`tuning.data.json`). */
+export function dataDocumentTitle(path: string): string {
+  return path.split('/').pop() ?? path;
+}
+
+/**
+ * Open (or activate) the center form/table document for one data asset.
+ * Never fabricates: the document renders a plain "no longer on disk" message
+ * if the file disappears after opening (delete/rename — the SSE rescan
+ * updates the store; the document does not pretend the file still exists).
+ */
+export function openDataDocument(store: DataDocumentStore, path: string): string {
+  return openWorkspaceDocument({
+    id: dataDocumentId(path),
+    title: dataDocumentTitle(path),
+    kind: 'data',
+    provenance: { sourcePath: path },
+    Content: DataDocumentContent,
+    closeable: true,
+    onActivate: () => store.setActiveViewportTab('scene'),
+  });
+}
+
+/** Open the `Data Assets` navigation/teaching document (file list, or the
+ *  W6d empty state when the project has no data assets yet). */
+export function openDataAssetsDocument(store: DataDocumentStore): string {
+  return openWorkspaceDocument({
+    id: DATA_ASSETS_DOCUMENT_ID,
+    title: 'Data Assets',
+    kind: 'data',
+    Content: DataAssetsDocumentContent,
+    closeable: true,
+    onActivate: () => store.setActiveViewportTab('scene'),
+  });
+}
+
+/**
+ * Command-palette discovery (the B5 fold): one `Open Data Asset` action per
+ * discovered file plus the static `Data Assets` navigation document. Reads
+ * the live store snapshot — the palette rebuilds its list on every open.
+ */
+export function buildDataAssetActions(store: DataDocumentStore): EditorAction[] {
+  const perFile: EditorAction[] = _files.map((f) => ({
+    id: `data-asset:${f.path}`,
+    label: `Open Data Asset: ${dataDocumentTitle(f.path)}`,
+    category: 'action' as const,
+    execute: () => void openDataDocument(store, f.path),
+  }));
+  return [
+    {
+      id: 'data.assets',
+      label: 'Data Assets',
+      category: 'action' as const,
+      execute: () => void openDataAssetsDocument(store),
+    },
+    ...perFile,
+  ];
+}
+
+// --- Content hosts ----------------------------------------------------------
+
+/** `'ref'` widget picker options (§2.2): loaded files reduced to
+ *  `stem -> key[]` — same derivation the old panel memoized. */
+function refOptionsByStem(files: readonly LoadedDataFile[]): ReadonlyMap<string, string[]> {
+  const map = new Map<string, string[]>();
+  for (const f of files) {
+    if (!f.data) continue;
+    const stem = f.path.replace(/^src\/data\//, '').replace(/\.data\.json$/, '');
+    map.set(
+      stem,
+      Object.keys(f.data).filter((k) => k !== '$schema'),
+    );
+  }
+  return map;
+}
+
+/** Shared per-content wiring: live store + history-aware commit + a refresh
+ *  on history writes from OTHER surfaces (undo/redo, project-tool
+ *  `writeData`) — the same subscription the old panel held. */
+function useDataFilesWithHistory(): {
+  files: readonly LoadedDataFile[];
+  writeFile: (file: LoadedDataFile, nextData: Record<string, unknown>) => void;
+} {
+  useSyncExternalStore(subscribeDataFiles, dataFilesVersion);
+  // The session history service arrives through the workspace-history bridge
+  // (NOT EditorContext — see workspace-history.ts's doc comment); the
+  // per-(service, namespace) manager is cached inside getProjectFileHistory.
+  const history = workspaceHistoryService();
+  const fileHistory = history
+    ? getProjectFileHistory(history, getDataHistoryBackend(), 'project-data')
+    : null;
+  useEffect(() => {
+    void refreshDataFiles();
+    return (
+      fileHistory?.subscribeAll((path) => {
+        if (path.startsWith('src/data/') && path.endsWith('.data.json')) {
+          void refreshDataFiles();
+        }
+      }) ?? (() => {})
+    );
+  }, [fileHistory]);
+  return {
+    files: _files,
+    writeFile: (file, nextData) => commitDataFile(file, nextData, fileHistory),
+  };
+}
+
+/** One data asset's center form/table document. */
+export function DataDocumentContent({ documentId }: WorkspaceDocumentContentProps) {
+  const { files, writeFile } = useDataFilesWithHistory();
+  const path = documentId.startsWith('data:') ? documentId.slice('data:'.length) : documentId;
+  const file = files.find((f) => f.path === path) ?? null;
+  return (
+    <div
+      data-testid={`data-document:${path}`}
+      style={{
+        flex: 1,
+        minHeight: 0,
+        overflow: 'auto',
+        pointerEvents: 'auto',
+        padding: 12,
+      }}
+    >
+      {file ? (
+        <RefOptionsContext.Provider value={refOptionsByStem(files)}>
+          <DataFileEditor file={file} writeFile={writeFile} />
+        </RefOptionsContext.Provider>
+      ) : (
+        <div style={{ fontSize: 12, color: themeVars.content.muted, maxWidth: 480 }}>
+          {path} is no longer on disk (deleted or renamed) — close this document.
+        </div>
+      )}
+    </div>
+  );
+}
+
+/** The `Data Assets` navigation/teaching document: the discovered file list
+ *  (click → open that asset's document), or the W6d empty state. */
+export function DataAssetsDocumentContent(_props: WorkspaceDocumentContentProps) {
+  const { files } = useDataFilesWithHistory();
+  const store = useDataDocumentStoreBridge();
+  if (files.length === 0) {
+    return (
+      <div style={{ flex: 1, minHeight: 0, overflow: 'auto', pointerEvents: 'auto' }}>
+        <DataEmptyState />
+      </div>
+    );
+  }
+  return (
+    <div
+      data-testid="data-assets-document"
+      style={{ flex: 1, minHeight: 0, overflow: 'auto', pointerEvents: 'auto', padding: 12 }}
+    >
+      <div style={{ fontSize: 11, color: themeVars.content.muted, marginBottom: 8 }}>
+        Each data asset opens as its own center document (docs/DATA-TOOLS-DESIGN.md §2).
+      </div>
+      <div style={{ maxWidth: 360, border: `1px solid ${themeVars.boundary.default}` }}>
+        {files.map((f) => (
+          <EditorListButton
+            key={f.path}
+            data-testid={`data-asset-row-${dataDocumentTitle(f.path)}`}
+            onClick={() => void openDataDocument(store, f.path)}
+            title={f.path}
+            style={{ padding: '5px 10px', fontSize: 12 }}
+          >
+            {dataDocumentTitle(f.path)}
+          </EditorListButton>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+// The guide document's rows open sibling documents; they only need the T6.3
+// tab hand-off. Route through the SAME store contract the open functions
+// take — supplied by the layout via `configureDataDocumentStore` (set once,
+// alongside `startDataAssetDiscovery`).
+let _storeBridge: DataDocumentStore | null = null;
+
+/** Wire the store the guide document's rows open sibling documents through.
+ *  Returns a cleanup that clears it. */
+export function configureDataDocumentStore(store: DataDocumentStore): () => void {
+  _storeBridge = store;
+  return () => {
+    if (_storeBridge === store) _storeBridge = null;
+  };
+}
+
+function useDataDocumentStoreBridge(): DataDocumentStore {
+  return _storeBridge ?? { setActiveViewportTab: () => {} };
+}