@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/server/project-view.ts

@@ -1,64 +1,22 @@
-// T3.3 slice 1 — server-side compat-view synthesis for `project.json` reads
-// (docs/CLI-ON-FOLDER-DESIGN.md §1C).
-//
-// A project folder's config view can come from two places: `project.json`
-// itself (legacy, still authoritative when present — including fields like
-// `appId` that have no manifest home) or, when that file is ABSENT, a
-// synthesized `{ name, defaultScene }` view derived from `vgai.game.json`
-// (`name` from the manifest; `defaultScene` from the first world's `scene`,
-// explicitly `null` if that world has none — e.g. an `entry`-based or ingest
-// world — NEVER omitted: a consumer that saw the key simply missing collapsed
-// "not declared" into "guess a path" via `?? 'scenes/default.vscn.json'`,
-// which is what caused `initial-scene.ts` to silently WRITE a placeholder
-// scene for a legal entry-only first world — §7.1-12 / R2b fix 1. `null` is
-// the explicit, typed "no scene declared" the consumer is forced to branch
-// on instead of defaulting through.
-//
-// This is the ONE place the project.json/manifest fallback rule lives —
-// every server route that reads project config goes through `readProjectView`
-// rather than re-implementing the fallback (editor-server.ts's static
-// `/project.json` serve, `GET /__editor/project`, `POST /__editor/open-project`'s
-// existence check, and the recent-projects existence check all call this).
+/** Server-side editor view of the single v2 project configuration. */
 
-import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { loadGameManifestFile } from '../../engine/src/manifest/load-file';
 
 export type ProjectView = Record<string, unknown>;
 
 /**
- * Read the compat project view for `root`.
- *
- * - `project.json` present -> its parsed contents verbatim (whatever fields
- *   it has, including `appId`).
- * - `project.json` absent, `vgai.game.json` present -> synthesized
- *   `{ name, defaultScene }`, where `defaultScene` is the first world's
- *   `scene` if declared, else explicit `null` (never omitted — appId is
- *   omitted, though: it has no manifest home and nothing reads it per
- *   docs/CLI-ON-FOLDER-DESIGN.md §1C).
- * - Neither present, or the manifest exists but fails to parse -> `null`.
- *   (The hard fail-loud-on-a-broken-manifest behavior lives at the CLI
- *   discovery gate, `packages/vgai-cli/src/discovery.ts` — a server route
- *   reading a broken manifest degrades to "no project" rather than crashing
- *   the request.)
+ * Read `vgai.game.json` and derive the editor's focused scene. There is no
+ * fallback config file: a missing or invalid manifest is not a project.
  */
 export async function readProjectView(root: string): Promise<ProjectView | null> {
-  try {
-    const raw = await readFile(join(root, 'project.json'), 'utf-8');
-    return JSON.parse(raw) as ProjectView;
-  } catch {
-    // project.json absent/unreadable — fall through to the manifest.
-  }
-
   try {
     const manifest = loadGameManifestFile(join(root, 'vgai.game.json'));
-    const firstWorld = manifest.worlds[0];
-    // Always set the key — explicit `null`, not an omitted property, when the
-    // first world declares no scene (e.g. `entry`-only). See the module doc
-    // comment above: an omitted key is what let a naive `?? 'scenes/
-    // default.vscn.json'` consumer silently guess a path.
-    const view: ProjectView = { name: manifest.name, defaultScene: firstWorld?.scene ?? null };
-    return view;
+    const firstSceneRoot = manifest.roots.find((candidate) => candidate.scene !== undefined);
+    return {
+      ...manifest,
+      defaultScene: firstSceneRoot?.scene ?? null,
+    };
   } catch {
     return null;
   }

package/server/server-utils.ts

@@ -203,9 +203,8 @@ export function isAllowedEditorOrigin(
  * editor server — otherwise the exact version-skew class Phase B exists to
  * kill (an editor silently serving a different engine version than the one
  * the project declares) reappears one layer down, inside script-serving.
- * `packageName`'s `exports` map must publish a `./package.json` entry (both
- * `@vgai/engine` and `@vgai/scene-ui` do, as of B1a) for `require.resolve` to
- * find it.
+ * `packageName`'s `exports` map must publish a `./package.json` entry for
+ * `require.resolve` to find it.
  *
  * Returns `null` (never throws) when `packageName` isn't resolvable from
  * `fromDir` — no project open, a pre-Phase-B project with no such
@@ -337,25 +336,85 @@ export function validateManifestWrite(
  * Which editor list a `src/**` add/unlink invalidates, or `null` if it's
  * irrelevant. Feeds the editor-server's second `src/`-scoped chokidar
  * watcher (`startWatcher()` in editor-server.ts) so a NEW
- * `src/tools/*.tool.tsx` or `src/data/*.data.json`/`*.schema.json` shows up
+ * `src/tools/*.tool.tsx`, project operations, or data/schema files show up
  * in the dock/DATA tab without a full editor reload (spec §7 W4 field note
  * c). `.schema.json` is included on the `data` side: its add/unlink flips the
  * DATA tab between the no-emitted-schema teaching message and real widgets.
+ * `stories` (C3, spec §9) is the same physics for a new/removed
+ * `*.stories.tsx`/`*.stories.ts` anywhere under `src/` — the Stories tab.
  *
  * `relPath` is project-root-relative with forward slashes (same convention
  * `/__editor/data-files` and `/__editor/tool-files` already use).
  */
-export function classifyProjectSrcPath(relPath: string): 'tools' | 'data' | null {
+export function classifyProjectSrcPath(
+  relPath: string,
+): 'tools' | 'data' | 'stories' | 'operations' | null {
   if (relPath.startsWith('src/tools/') && relPath.endsWith('.tool.tsx')) return 'tools';
+  if (
+    relPath.startsWith('src/operations/') &&
+    (relPath.endsWith('.operation.ts') || relPath.endsWith('.operation.js'))
+  ) {
+    return 'operations';
+  }
   if (
     relPath.startsWith('src/data/') &&
     (relPath.endsWith('.data.json') || relPath.endsWith('.schema.json'))
   ) {
     return 'data';
   }
+  // C3 (spec §9) — conventional CSF story files, colocated anywhere under
+  // `src/` (not confined to one subfolder like tools/data).
+  if (
+    relPath.startsWith('src/') &&
+    (relPath.endsWith('.stories.tsx') || relPath.endsWith('.stories.ts'))
+  ) {
+    return 'stories';
+  }
   return null;
 }
 
+// ---------------------------------------------------------------------------
+// Watcher polling resolution (#131)
+// ---------------------------------------------------------------------------
+
+/**
+ * Chokidar options fragment deciding whether an editor-server watcher polls.
+ *
+ * #131: on WSL drvfs mounts (`/mnt/<drive>/…`) inotify never fires, so every
+ * SSE broadcast the editor UI lives on (`scene-changed`, `asset-moved`,
+ * `tool/data/story-files-changed`, manifest validation) was structurally dead
+ * there — the owner watched an agent author a scene and the open editor never
+ * repainted until a manual browser refresh. dev.ts already auto-polls VITE's
+ * watcher on drvfs (`startProjectPollWatcher`) but deliberately never feeds
+ * these watchers (see the decoupling note at the srcWatcher construction), so
+ * they need their own decision. Chokidar's scoped `usePolling` is safe here
+ * where Vite-wide polling was not: these watchers cover only a game project's
+ * `public/`+`src/` trees and one manifest file, not the whole engine tree
+ * that made drvfs stat-flood starve the event loop (dev.ts field note
+ * 2026-07-10).
+ *
+ * Same env contract as dev.ts's poller: `VGAI_WATCH_POLL=0` forces off
+ * anywhere, `=1` forces on (default 1000ms interval), `=<ms>` forces on with
+ * that interval. Unset: auto-enable iff `root` sits on a drvfs mount
+ * (linux + `/mnt/<drive>/`). Pass `root: null` to opt out of auto-detection
+ * (engine-repo-rooted watchers, where `public/` includes the vendored-game
+ * trees and polling would be needlessly broad).
+ */
+export function resolveWatcherPollOptions(
+  root: string | null,
+  env: Record<string, string | undefined> = process.env,
+  platform: NodeJS.Platform = process.platform,
+): { usePolling: true; interval: number } | Record<string, never> {
+  const raw = env['VGAI_WATCH_POLL'];
+  if (raw !== undefined && raw !== '') {
+    if (raw === '0') return {};
+    const ms = Number(raw);
+    return { usePolling: true, interval: Number.isFinite(ms) && ms > 1 ? ms : 1000 };
+  }
+  const onDrvfs = root !== null && platform === 'linux' && /^\/mnt\/[a-z]\//i.test(root);
+  return onDrvfs ? { usePolling: true, interval: 1000 } : {};
+}
+
 // ---------------------------------------------------------------------------
 // Command-relay response shaping (SC1)
 // ---------------------------------------------------------------------------
@@ -364,15 +423,21 @@ export interface CommandResult {
   ok?: boolean;
   timedOut?: boolean;
   error?: string;
-  /** Optional payload for commands that answer with data (e.g. `capture-viewport`'s base64 PNG). */
+  /** Optional payload for commands that answer with data (e.g.
+   *  `capture-viewport`'s base64 PNG, the Wave 5 debug-seam reads). On the
+   *  failure path this carries structured markers (e.g. `{ code:
+   *  'UNKNOWN_COMMAND_TYPE' }`, registered-name lists) the SDK matches on —
+   *  never message prose. Keep in sync with `command-listener.ts`'s
+   *  `CommandResult`. */
   data?: Record<string, unknown>;
 }
 
 /** Map a relayed-command result to an HTTP status + body. A timeout (no editor
  *  connected) is a distinct 504 error rather than a fake success. (SC1)
- *  `data`, when present on a success, is spread into the response body
- *  alongside `ok: true` so callers (`HttpEditorTransport.sendCommand`) see it
- *  at the top level rather than needing a second field of indirection. */
+ *  `data` is spread into the response body at the top level — alongside
+ *  `ok: true` on success (so `HttpEditorTransport.sendCommand` sees it
+ *  without a second field of indirection) and alongside `ok: false`/`error`
+ *  on the 400 path (Wave 5: the structured error-marker channel). */
 export function commandResponseFor(result: CommandResult): {
   status: number;
   body: Record<string, unknown>;
@@ -384,7 +449,7 @@ export function commandResponseFor(result: CommandResult): {
       body: { ok: false, error: result.error ?? 'Command timed out — no editor connected.' },
     };
   }
-  return { status: 400, body: { ok: false, error: result.error } };
+  return { status: 400, body: { ok: false, error: result.error, ...(result.data ?? {}) } };
 }
 
 // ---------------------------------------------------------------------------

package/server/session-registry.ts

@@ -23,6 +23,18 @@ export interface EditorSession {
   pid: number;
   /** ISO timestamp of server start. */
   startedAt: string;
+  /**
+   * Additive (ACCEPTANCE-DRIVER-BUILD-PLAN.md Task 3.4): absent/undefined for
+   * every pre-existing editor session (an ordinary `vgai edit` dev server).
+   * `'probe'` marks a standalone game-page server booted by `vgai probe` —
+   * registered so it shows up in `vgai sessions`/dies via `vgai close`, and so
+   * a later `vgai probe` run can warm-reuse it instead of re-booting. Both
+   * this writer's `isSession` and the CLI reader's own copy
+   * (`packages/vgai-cli/src/editor-sessions.ts`) validate only the fields
+   * above and tolerate any extra key, so this addition is backward compatible
+   * with entries written by an older build.
+   */
+  kind?: string;
 }
 
 const REGISTRY_DIR = join(homedir(), '.vgai');

package/src/EditorContext.tsx

@@ -1,8 +1,26 @@
-import { createContext, type ReactNode, Suspense, useContext, useEffect, useRef } from 'react';
+import {
+  type ReactNode,
+  Suspense,
+  useContext,
+  useEffect,
+  useRef,
+  useSyncExternalStore,
+} from 'react';
 import { connectCommandListener } from './command-listener';
 import { EditorStore } from './editor-store';
+import { setHarnessChatEditorStore } from './harness-chat-editor-context';
+import { EditorSession } from './history/editor-session';
+import type { HistoryCommandSnapshot, HistoryCommands } from './history/history-commands';
+import type { HistoryService, HistorySnapshot } from './history/history-service';
+import { getProjectFileHistory } from './history/project-file-history';
+import { getDataHistoryBackend } from './history/project-root-history-backends';
+import { createHmrStableReactContext } from './hmr-stable-react-context';
 import { initProject } from './initial-scene';
 import { type InteractiveEditScope, InteractiveEditScopeContext } from './interactive-edit-scope';
+import { getCurrentProject } from './project-manager';
+import { startProjectOperationDiscovery } from './project-operations';
+import { startProjectStoryDiscovery } from './project-story-discovery';
+import { startProjectToolDiscovery } from './project-tool-discovery';
 
 export interface EditorStats {
   fps: number;
@@ -17,14 +35,26 @@ interface EditorContextValue {
   store: EditorStore;
   stats: EditorStats;
   initPromise: Promise<void>;
+  session: EditorSession;
 }
 
-const EditorContext = createContext<EditorContextValue | null>(null);
+const EditorContext = createHmrStableReactContext<EditorContextValue | null>(
+  import.meta.hot?.data,
+  'EditorContext',
+  null,
+);
 
 export function EditorProvider({ children }: { children: ReactNode }) {
   const storeRef = useRef<EditorStore | null>(null);
   if (!storeRef.current) storeRef.current = new EditorStore();
 
+  const sessionRef = useRef<EditorSession | null>(null);
+  if (!sessionRef.current) {
+    const project = getCurrentProject();
+    sessionRef.current = new EditorSession(project?.rootPath ?? 'unknown-project');
+  }
+  storeRef.current.attachHistory(sessionRef.current.history);
+
   const statsRef = useRef<EditorStats | null>(null);
   if (!statsRef.current) {
     statsRef.current = {
@@ -57,9 +87,56 @@ export function EditorProvider({ children }: { children: ReactNode }) {
     return connectCommandListener(storeRef.current!);
   }, []);
 
+  // W0 (docs/EDITOR-WORKSPACE-SHELL-TODO.md §7.2/§9): project-tool discovery
+  // is EDITOR-INIT lifecycle, not a bottom-dock side effect — it runs (and
+  // keeps re-running on project change / tool-file add/unlink) whether or
+  // not the Dockview workspace is mounted. WorkspaceDock only consumes the
+  // discovered registrations.
+  useEffect(() => startProjectToolDiscovery(), []);
+
+  useEffect(() => startProjectOperationDiscovery(), []);
+
+  // CSF stories may exist without a currently mounted React root. Discover
+  // them at editor init so hierarchy/Inspector story affordances and restored
+  // story documents are complete before any story document is opened.
+  useEffect(() => startProjectStoryDiscovery(), []);
+
+  useEffect(() => {
+    setHarnessChatEditorStore(storeRef.current);
+    return () => setHarnessChatEditorStore(null);
+  }, []);
+
+  useEffect(() => () => sessionRef.current?.dispose(), []);
+
+  useEffect(() => {
+    const target = globalThis as typeof globalThis & {
+      __vgaiHistoryWriteData?: (path: string, content: string) => Promise<void>;
+    };
+    const writer = async (path: string, content: string): Promise<void> => {
+      await getProjectFileHistory(
+        sessionRef.current!.history,
+        getDataHistoryBackend(),
+        'project-data',
+      ).write(path, content, {
+        label: `Edit ${path.split('/').pop() ?? 'Data'}`,
+        kind: 'data',
+        contentType: 'application/json',
+      });
+    };
+    target.__vgaiHistoryWriteData = writer;
+    return () => {
+      if (target.__vgaiHistoryWriteData === writer) delete target.__vgaiHistoryWriteData;
+    };
+  }, []);
+
   return (
     <EditorContext.Provider
-      value={{ store: storeRef.current, stats: statsRef.current, initPromise: initRef.current }}
+      value={{
+        store: storeRef.current,
+        stats: statsRef.current,
+        initPromise: initRef.current,
+        session: sessionRef.current,
+      }}
     >
       <InteractiveEditScopeContext.Provider value={editScopeRef.current}>
         <Suspense>{children}</Suspense>
@@ -85,3 +162,30 @@ export function useEditorInit(): Promise<void> {
   if (!ctx) throw new Error('useEditorInit must be used within <EditorProvider>');
   return ctx.initPromise;
 }
+
+export function useHistoryService(): HistoryService {
+  const ctx = useContext(EditorContext);
+  if (!ctx) throw new Error('useHistoryService must be used within <EditorProvider>');
+  return ctx.session.history;
+}
+
+/** History-aware panels may still be rendered in isolated component tests. */
+export function useOptionalHistoryService(): HistoryService | null {
+  return useContext(EditorContext)?.session.history ?? null;
+}
+
+export function useHistoryCommands(): HistoryCommands {
+  const ctx = useContext(EditorContext);
+  if (!ctx) throw new Error('useHistoryCommands must be used within <EditorProvider>');
+  return ctx.session.historyCommands;
+}
+
+export function useHistoryCommandSnapshot(): HistoryCommandSnapshot {
+  const history = useHistoryCommands();
+  return useSyncExternalStore(history.subscribe, history.getSnapshot, history.getSnapshot);
+}
+
+export function useHistorySnapshot(): HistorySnapshot {
+  const history = useHistoryService();
+  return useSyncExternalStore(history.subscribe, history.getSnapshot, history.getSnapshot);
+}

package/src/action-registry.ts

@@ -1,12 +1,18 @@
-import { timelineRedo, timelineUndo } from './authoring/undo-timeline';
+import { PROJECT_ASSET_COMMANDS } from './asset-workflow/project-asset-commands';
+import { openBuildProfilesDocument } from './components/build-documents';
+import { openDebuggerPanel } from './components/debugger-panel-state';
+import { getEditorMode } from './editor-mode';
 import type { EditorStore } from './editor-store';
+import type { HistoryCommandSnapshot, HistoryCommands } from './history/history-commands';
+import { openUndoHistory } from './workspace-aux-commands';
+import { showWorkspaceNavigator, toggleWorkspaceFocus } from './workspace-dock-controller';
 
 export interface EditorAction {
   id: string;
   label: string;
   category: 'action' | 'entity' | 'asset';
   shortcut?: string;
-  execute: () => void;
+  execute: () => void | Promise<void>;
 }
 
 const RECENT_KEY = 'editor:recent-actions';
@@ -28,28 +34,34 @@ export function pushRecentAction(id: string): void {
 }
 
 /** Build the static list of editor command actions. */
-export function buildStaticActions(store: EditorStore): EditorAction[] {
+export function buildStaticActions(
+  store: EditorStore,
+  history: HistoryCommands,
+  historySnapshot?: HistoryCommandSnapshot,
+): EditorAction[] {
   const isMac = navigator.platform.includes('Mac');
   const mod = isMac ? '\u2318' : 'Ctrl+';
 
   return [
     {
       id: 'editor.undo',
-      label: 'Undo',
+      label: historySnapshot?.undoLabel ? `Undo ${historySnapshot.undoLabel}` : 'Undo',
       category: 'action',
       shortcut: `${mod}Z`,
-      // T3.2 slice 2: through the editor-global timeline, NOT `store.undo()`
-      // directly \u2014 same reasoning as the Ctrl+Z hotkey (docs/
-      // PERSISTENCE-PROVIDER-DESIGN.md \u00A73): whichever adapter (first-party/
-      // ingest/UI) recorded the most recent op, not always the first-party store.
-      execute: () => timelineUndo(),
+      // H2: shell actions use the project-scoped command service. Its temporary
+      // compatibility bridge preserves chronology with producers not yet migrated.
+      execute: async () => {
+        await history.undo();
+      },
     },
     {
       id: 'editor.redo',
-      label: 'Redo',
+      label: historySnapshot?.redoLabel ? `Redo ${historySnapshot.redoLabel}` : 'Redo',
       category: 'action',
       shortcut: `${mod}\u21E7Z`,
-      execute: () => timelineRedo(),
+      execute: async () => {
+        await history.redo();
+      },
     },
     {
       id: 'editor.copy',
@@ -236,21 +248,107 @@ export function buildStaticActions(store: EditorStore): EditorAction[] {
       },
     },
     {
-      id: 'build.web',
-      label: 'Build for Web (itch.io)',
+      id: 'view.focusMode',
+      label: 'Toggle Focus Mode',
       category: 'action',
+      shortcut: `${mod}⇧F`,
       execute: () => {
-        window.dispatchEvent(new CustomEvent('editor:show-build-tab'));
+        toggleWorkspaceFocus();
       },
     },
     {
-      id: 'build.steam',
-      label: 'Build for Desktop (Steam)',
+      id: 'view.undoHistory',
+      label: 'Undo History',
       category: 'action',
       execute: () => {
-        window.dispatchEvent(new CustomEvent('editor:show-build-tab'));
+        // Undo History is an on-demand panel, not a permanent tab. Dockview
+        // defaults it beside Inspector but preserves a user's later move.
+        // §8 naming: 'Undo History', not 'History'.
+        openUndoHistory();
       },
     },
+    {
+      id: 'view.profiler',
+      label: 'Open Profiler',
+      category: 'action',
+      execute: () => openDebuggerPanel('profiler'),
+    },
+    {
+      id: 'view.state-watch',
+      label: 'Open State Watch',
+      category: 'action',
+      execute: () => openDebuggerPanel('state'),
+    },
+    {
+      id: 'view.network-debugger',
+      label: 'Open Network Diagnostics',
+      category: 'action',
+      execute: () => openDebuggerPanel('network'),
+    },
+    {
+      id: 'view.machine-debugger',
+      label: 'Open State Machines',
+      category: 'action',
+      execute: () => openDebuggerPanel('machines'),
+    },
+    {
+      id: 'view.debug-commands',
+      label: 'Open Debug Commands',
+      category: 'action',
+      execute: () => openDebuggerPanel('commands'),
+    },
+    ...Object.values(PROJECT_ASSET_COMMANDS)
+      .filter((command) => command.id !== PROJECT_ASSET_COMMANDS.open.id)
+      .map((command) => ({
+        id: command.id,
+        label: `${command.id
+          .replace('project-asset.', '')
+          .split('-')
+          .map((part) => part[0]?.toUpperCase() + part.slice(1))
+          .join(' ')} Project Asset`,
+        category: 'asset' as const,
+        ...(command.shortcut ? { shortcut: command.shortcut.replace('Mod', mod) } : {}),
+        execute: () => {
+          window.dispatchEvent(
+            new CustomEvent('editor:project-asset-command', { detail: { id: command.id } }),
+          );
+        },
+      })),
+    // W3 build split (build-documents.tsx): the build actions open the Build
+    // Profiles CENTER document (config + the Build trigger); the log streams
+    // into the Build Output utility. Server mode only — builds spawn npm
+    // scripts server-side (pre-W3 these dispatched an event no tab handled
+    // in browser mode).
+    ...(getEditorMode() === 'server'
+      ? [
+          {
+            // Assets and Library are permanent peer navigators; individual
+            // results open as center asset documents.
+            id: 'view.asset-library',
+            label: 'Asset Library',
+            category: 'action' as const,
+            execute: () => {
+              showWorkspaceNavigator('asset-library');
+            },
+          },
+          {
+            id: 'build.web',
+            label: 'Build for Web (itch.io)',
+            category: 'action' as const,
+            execute: () => {
+              openBuildProfilesDocument(store);
+            },
+          },
+          {
+            id: 'build.steam',
+            label: 'Build for Desktop (Steam)',
+            category: 'action' as const,
+            execute: () => {
+              openBuildProfilesDocument(store);
+            },
+          },
+        ]
+      : []),
   ];
 }