@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/editor-compatibility.ts

@@ -0,0 +1,200 @@
+import { GAME_MANIFEST_VERSION } from '../../engine/src/manifest/schema';
+
+export interface EditorServerCompatibility {
+  apiVersion: 1;
+  engineVersion: string | null;
+  manifestVersion: number;
+  startedAt: string;
+  source:
+    | { state: 'current' }
+    | { state: 'restart-required'; changedPath: string; changedAt: string };
+}
+
+export type StartupRecovery =
+  | {
+      kind: 'retry-editor';
+      title: 'Editor server unavailable';
+      guidance: string;
+      command: 'vgai edit .';
+    }
+  | {
+      kind: 'restart-editor';
+      title: 'Restart this editor';
+      guidance: string;
+      command: 'vgai close . && vgai edit .';
+    }
+  | {
+      kind: 'upgrade-project';
+      title: 'Upgrade this project';
+      guidance: string;
+      command: 'vgai upgrade .';
+    }
+  | {
+      kind: 'use-compatible-editor';
+      title: 'Use a compatible editor';
+      guidance: string;
+    };
+
+export class ProjectCompatibilityError extends Error {
+  readonly recovery: StartupRecovery;
+
+  constructor(message: string, recovery: StartupRecovery) {
+    super(message);
+    this.name = 'ProjectCompatibilityError';
+    this.recovery = recovery;
+  }
+}
+
+export function editorServerUnavailableError(detail?: string): ProjectCompatibilityError {
+  return new ProjectCompatibilityError(
+    `Could not reach the local editor server${detail ? `: ${detail}` : '.'}`,
+    {
+      kind: 'retry-editor',
+      title: 'Editor server unavailable',
+      guidance: 'Make sure the local editor is running, then retry this operation.',
+      command: 'vgai edit .',
+    },
+  );
+}
+
+export function isStartupRecovery(value: unknown): value is StartupRecovery {
+  if (!value || typeof value !== 'object') return false;
+  const candidate = value as Record<string, unknown>;
+  if (typeof candidate['title'] !== 'string' || typeof candidate['guidance'] !== 'string') {
+    return false;
+  }
+  switch (candidate['kind']) {
+    case 'retry-editor':
+      return candidate['command'] === 'vgai edit .';
+    case 'restart-editor':
+      return candidate['command'] === 'vgai close . && vgai edit .';
+    case 'upgrade-project':
+      return candidate['command'] === 'vgai upgrade .';
+    case 'use-compatible-editor':
+      return candidate['command'] === undefined;
+    default:
+      return false;
+  }
+}
+
+interface ProjectIdentity {
+  manifestVersion?: unknown;
+  engine?: { version?: unknown } | undefined;
+}
+
+const EXACT_SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
+function compareSemver(a: string, b: string): -1 | 0 | 1 | null {
+  const aMatch = EXACT_SEMVER.exec(a);
+  const bMatch = EXACT_SEMVER.exec(b);
+  if (!aMatch || !bMatch) return null;
+  for (let index = 1; index <= 3; index++) {
+    const aPart = Number(aMatch[index]);
+    const bPart = Number(bMatch[index]);
+    if (aPart < bPart) return -1;
+    if (aPart > bPart) return 1;
+  }
+  return 0;
+}
+
+export function missingCompatibilityError(): ProjectCompatibilityError {
+  return new ProjectCompatibilityError(
+    'The editor page is newer than its local server. The running server does not expose the compatibility handshake this page expects.',
+    {
+      kind: 'restart-editor',
+      title: 'Restart this editor',
+      guidance: 'From the project folder, restart the local editor and then reopen this page.',
+      command: 'vgai close . && vgai edit .',
+    },
+  );
+}
+
+/** Verify that the browser bundle and its long-running local server still agree. */
+export function assertEditorCompatibility(identity: EditorServerCompatibility): void {
+  if (identity.source.state === 'restart-required') {
+    throw new ProjectCompatibilityError(
+      `The local editor server is stale. ${identity.source.changedPath} changed after this server started at ${identity.startedAt}.`,
+      {
+        kind: 'restart-editor',
+        title: 'Restart this editor',
+        guidance:
+          'The browser has newer source than the running Node process. From the project folder, restart the editor before retrying.',
+        command: 'vgai close . && vgai edit .',
+      },
+    );
+  }
+
+  if (identity.manifestVersion !== GAME_MANIFEST_VERSION) {
+    throw new ProjectCompatibilityError(
+      `The editor page supports project format v${GAME_MANIFEST_VERSION}, but its local server supports v${identity.manifestVersion}.`,
+      {
+        kind: 'restart-editor',
+        title: 'Restart this editor',
+        guidance: 'The browser and server are from different editor builds. Restart them together.',
+        command: 'vgai close . && vgai edit .',
+      },
+    );
+  }
+}
+
+/** Verify the lightweight identity fields before full Zod manifest parsing. */
+export function assertProjectCompatibility(
+  project: ProjectIdentity,
+  editor: EditorServerCompatibility,
+): void {
+  if (
+    typeof project.manifestVersion === 'number' &&
+    project.manifestVersion !== GAME_MANIFEST_VERSION
+  ) {
+    if (project.manifestVersion < GAME_MANIFEST_VERSION) {
+      throw new ProjectCompatibilityError(
+        `This project uses manifest format v${project.manifestVersion}; this editor requires v${GAME_MANIFEST_VERSION}.`,
+        {
+          kind: 'upgrade-project',
+          title: 'Upgrade this project',
+          guidance:
+            'Run the upgrade from the project folder. VGAI reports changes before updating scaffold-managed files.',
+          command: 'vgai upgrade .',
+        },
+      );
+    }
+    throw new ProjectCompatibilityError(
+      `This project uses manifest format v${project.manifestVersion}, which is newer than this editor's v${GAME_MANIFEST_VERSION} format.`,
+      {
+        kind: 'use-compatible-editor',
+        title: 'Use a compatible editor',
+        guidance: 'Open this project with the newer VGAI checkout or installation that created it.',
+      },
+    );
+  }
+
+  const projectEngine = project.engine?.version;
+  const editorEngine = editor.engineVersion;
+  if (typeof projectEngine !== 'string' || !editorEngine || projectEngine === editorEngine) return;
+
+  const comparison = compareSemver(projectEngine, editorEngine);
+  if (comparison === -1) {
+    throw new ProjectCompatibilityError(
+      `This project is pinned to @vgai/engine ${projectEngine}, but this editor is running ${editorEngine}.`,
+      {
+        kind: 'upgrade-project',
+        title: 'Upgrade this project',
+        guidance:
+          'Run the upgrade from the project folder to review template changes and re-pin the engine.',
+        command: 'vgai upgrade .',
+      },
+    );
+  }
+
+  throw new ProjectCompatibilityError(
+    `This project is pinned to @vgai/engine ${projectEngine}, but this editor is running ${editorEngine}.`,
+    {
+      kind: 'use-compatible-editor',
+      title: 'Use a compatible editor',
+      guidance:
+        comparison === 1
+          ? 'This project targets a newer engine. Open it from the matching newer VGAI checkout or installation.'
+          : 'The engine identities differ. Open the project with the exact VGAI version it is pinned to.',
+    },
+  );
+}

package/src/editor-console.ts

@@ -123,8 +123,17 @@ export const editorConsole = new EditorConsole();
 // anticipates: direct read access to console entries without DOM-scraping
 // `ConsolePanel` (which has no per-entry testids). Same ad-hoc `window.__vgai*`
 // convention as every other dev-only hook in `test-window.ts`.
-(window as unknown as { __vgaiEditorConsole?: EditorConsole })['__vgaiEditorConsole'] =
-  editorConsole;
+//
+// Guarded on `window`: this module is now imported by `ingest-authoring-adapter.ts`
+// (to report a failed history journal loudly), which is exercised by node-env
+// vitest suites where `window` does not exist. A bare module-scope reference
+// throws `ReferenceError: window is not defined` at COLLECTION time — before any
+// test body runs — so the guard belongs here at the source rather than as a
+// `vi.mock` repeated in every importing test file.
+if (typeof window !== 'undefined') {
+  (window as unknown as { __vgaiEditorConsole?: EditorConsole })['__vgaiEditorConsole'] =
+    editorConsole;
+}
 
 /**
  * Listen for `console-bridge` postMessage events from game iframes (or self)
@@ -146,22 +155,31 @@ const ENGINE_LEVEL_MAP: Record<string, ConsoleLevel> = {
   fatal: 'error',
 };
 
-window.addEventListener('message', (e: MessageEvent) => {
-  // Structured engine-log messages (from engine logger)
-  if (e.data?.type === 'engine-log') {
-    const level = ENGINE_LEVEL_MAP[e.data.level];
-    if (!level) return;
-    editorConsole.logStructured(level, e.data.message, 'engine', e.data.subsystem, e.data.metadata);
-    return;
-  }
+// Same `window` guard as the test hook above — see the comment there.
+if (typeof window !== 'undefined') {
+  window.addEventListener('message', (e: MessageEvent) => {
+    // Structured engine-log messages (from engine logger)
+    if (e.data?.type === 'engine-log') {
+      const level = ENGINE_LEVEL_MAP[e.data.level];
+      if (!level) return;
+      editorConsole.logStructured(
+        level,
+        e.data.message,
+        'engine',
+        e.data.subsystem,
+        e.data.metadata,
+      );
+      return;
+    }
 
-  // Plain console-bridge messages (from game code)
-  if (e.data?.type === 'console-bridge') {
-    const level = BRIDGE_LEVEL_MAP[e.data.level];
-    if (!level) return;
-    editorConsole[level === 'info' ? 'log' : level](e.data.message, 'engine');
-  }
-});
+    // Plain console-bridge messages (from game code)
+    if (e.data?.type === 'console-bridge') {
+      const level = BRIDGE_LEVEL_MAP[e.data.level];
+      if (!level) return;
+      editorConsole[level === 'info' ? 'log' : level](e.data.message, 'engine');
+    }
+  });
+}
 
 /**
  * Connect to the editor SSE endpoint and pipe `server-log` events

package/src/editor-hotkeys.ts

@@ -3,7 +3,6 @@ import {
   getActiveAuthoring,
   hasAuthoringOverride,
 } from './authoring/active-adapter';
-import { timelineRedo, timelineUndo } from './authoring/undo-timeline';
 import { resetWorldPan } from './authoring/world-pan-state';
 import {
   boxEditForId,
@@ -13,7 +12,12 @@ import {
 } from './components/world-overlay-gestures';
 import type { EditorStore } from './editor-store';
 import type { EditorViewport } from './editor-viewport';
+import type { HistoryCommands } from './history/history-commands';
 import { installHotkeys, registerHotkeys, setActiveScope } from './hotkeys';
+import { toggleWorkspaceFocus } from './workspace-dock-controller';
+import { saveActiveWorkspaceDocument } from './workspace-document-registry';
+
+const AUTHORING_SELECTION_SCOPES = ['viewport', 'hierarchy'] as const;
 
 /**
  * D4 (spec27 §6 D4, §8 "Keyboard / undo / pan-zoom" row) — RECONCILED by the
@@ -62,6 +66,17 @@ import { installHotkeys, registerHotkeys, setActiveScope } from './hotkeys';
 // capability-gate behavior (structure/boxEdit absent -> no-op) directly
 // against them, without needing a full `EditorViewport`/canvas fixture.
 
+/** Copy is shared with the browser. Claim Cmd/Ctrl+C only when the current
+ * selection is copyable by the scene clipboard and the user is not selecting
+ * DOM text. Returning false lets the native copy event continue untouched. */
+export function shouldHandleEditorCopy(store: EditorStore): boolean {
+  const selection = window.getSelection();
+  const hasTextSelection = Boolean(
+    selection && !selection.isCollapsed && selection.toString().length > 0,
+  );
+  return store.selectedEntities.length > 0 && !hasTextSelection;
+}
+
 /**
  * D4 (spec27 §6 D4 "Ctrl+D duplicate, Del/Backspace delete — route through
  * adapter.structure.* (capability-gated)"): the pre-D4 `'d'`/`'delete'`/
@@ -213,46 +228,47 @@ export function registerEditorHotkeys(
   store: EditorStore,
   viewport: EditorViewport,
   canvas: HTMLCanvasElement,
+  history: HistoryCommands,
 ): () => void {
   const unregister = registerHotkeys([
     // --- Global (fire regardless of active panel) ---
-    // Undo/redo (T3.2 slice 2): dispatch through the editor-global undo TIMELINE,
-    // NOT `hasAuthoringOverride() ? adapter : store` — the timeline pops whichever
-    // adapter (first-party store / ingest / UI) recorded the MOST RECENT op,
-    // globally, regardless of which one is currently active (docs/
-    // PERSISTENCE-PROVIDER-DESIGN.md §3). Ctrl+Y mirrors Ctrl+Shift+Z (Windows
-    // convention) — see `undo-timeline.ts`.
+    // H2: one project-scoped async command queue owns shell undo/redo. Ctrl+Y
+    // mirrors Ctrl+Shift+Z (Windows convention).
     {
       key: 'z',
       mod: true,
       shift: true,
       scope: 'global',
-      action: () => timelineRedo(),
+      action: () => void history.redo(),
     },
     {
       key: 'y',
       mod: true,
       scope: 'global',
-      action: () => timelineRedo(),
+      action: () => void history.redo(),
     },
     {
       key: 'z',
       mod: true,
       scope: 'global',
-      action: () => timelineUndo(),
+      action: () => void history.undo(),
     },
     {
       key: 'c',
       mod: true,
-      scope: 'global',
-      action: () => {
-        if (store.selectedEntityIds.size > 0) store.copyEntities();
-      },
+      scope: AUTHORING_SELECTION_SCOPES,
+      // Native text copy wins whenever the user has selected text in a log,
+      // source preview, path label, or other non-input surface. Previously
+      // this binding matched first and called preventDefault() even when no
+      // entity was selected, which made Copy appear to fail at random across
+      // Dockview panels.
+      when: () => shouldHandleEditorCopy(store),
+      action: () => store.copyEntities(),
     },
     {
       key: 'x',
       mod: true,
-      scope: 'global',
+      scope: AUTHORING_SELECTION_SCOPES,
       action: () => {
         if (store.selectedEntityIds.size > 0) store.cutEntities();
       },
@@ -260,7 +276,7 @@ export function registerEditorHotkeys(
     {
       key: 'v',
       mod: true,
-      scope: 'global',
+      scope: AUTHORING_SELECTION_SCOPES,
       action: () => {
         if (store.hasClipboard) store.pasteEntities();
       },
@@ -268,7 +284,7 @@ export function registerEditorHotkeys(
     {
       key: 'd',
       mod: true,
-      scope: 'global',
+      scope: AUTHORING_SELECTION_SCOPES,
       action: () => duplicateSelection(store),
     },
     // D4 — wrap/unwrap (override-only, capability-gated — see
@@ -277,34 +293,44 @@ export function registerEditorHotkeys(
       key: 'g',
       mod: true,
       alt: true,
-      scope: 'global',
+      scope: AUTHORING_SELECTION_SCOPES,
       action: () => wrapSelection(store),
     },
     {
       key: 'g',
       mod: true,
       shift: true,
-      scope: 'global',
+      scope: AUTHORING_SELECTION_SCOPES,
       action: () => unwrapSelection(store),
     },
     // D4 — arrow-nudge (↑↓←→, Shift=×10 — see `nudgeSelection`'s doc comment).
-    { key: 'arrowup', scope: 'global', action: () => nudgeSelection(store, 0, -1) },
-    { key: 'arrowup', shift: true, scope: 'global', action: () => nudgeSelection(store, 0, -10) },
-    { key: 'arrowdown', scope: 'global', action: () => nudgeSelection(store, 0, 1) },
-    { key: 'arrowdown', shift: true, scope: 'global', action: () => nudgeSelection(store, 0, 10) },
-    { key: 'arrowleft', scope: 'global', action: () => nudgeSelection(store, -1, 0) },
-    { key: 'arrowleft', shift: true, scope: 'global', action: () => nudgeSelection(store, -10, 0) },
-    { key: 'arrowright', scope: 'global', action: () => nudgeSelection(store, 1, 0) },
+    { key: 'arrowup', scope: 'viewport', action: () => nudgeSelection(store, 0, -1) },
+    { key: 'arrowup', shift: true, scope: 'viewport', action: () => nudgeSelection(store, 0, -10) },
+    { key: 'arrowdown', scope: 'viewport', action: () => nudgeSelection(store, 0, 1) },
+    {
+      key: 'arrowdown',
+      shift: true,
+      scope: 'viewport',
+      action: () => nudgeSelection(store, 0, 10),
+    },
+    { key: 'arrowleft', scope: 'viewport', action: () => nudgeSelection(store, -1, 0) },
+    {
+      key: 'arrowleft',
+      shift: true,
+      scope: 'viewport',
+      action: () => nudgeSelection(store, -10, 0),
+    },
+    { key: 'arrowright', scope: 'viewport', action: () => nudgeSelection(store, 1, 0) },
     {
       key: 'arrowright',
       shift: true,
-      scope: 'global',
+      scope: 'viewport',
       action: () => nudgeSelection(store, 10, 0),
     },
     {
       key: 'a',
       mod: true,
-      scope: 'global',
+      scope: AUTHORING_SELECTION_SCOPES,
       action: () => {
         if (hasAuthoringOverride()) {
           const a = getActiveAuthoring(store);
@@ -312,27 +338,39 @@ export function registerEditorHotkeys(
         } else store.selectAll();
       },
     },
-    { key: 's', mod: true, scope: 'global', action: () => void store.saveNow() },
+    {
+      key: 's',
+      mod: true,
+      scope: 'global',
+      allowInEditable: true,
+      action: () => {
+        void saveActiveWorkspaceDocument().then((handled) => {
+          // Scene/Game and legacy documents have no document-local editor.
+          // Preserve the established scene save path for those surfaces.
+          if (handled === null) void store.saveNow();
+        });
+      },
+    },
     // D4 (spec27 §8 "space-pan" row) — Ctrl+0, the conventional "reset
     // zoom/pan to 100%" shortcut (browsers/design tools alike), resets the
     // DOM/react overlay's shared pan translate (`world-pan-state.ts`) back to
     // `(0, 0)`. A no-op when already at rest or when the active surface has
     // no pan-capable world (there is nothing for it to affect either way —
     // `resetWorldPan()` itself no-ops at `(0,0)`).
-    { key: '0', mod: true, scope: 'global', action: () => resetWorldPan() },
+    { key: '0', mod: true, scope: 'viewport', action: () => resetWorldPan() },
     {
       key: 'delete',
-      scope: 'global',
+      scope: AUTHORING_SELECTION_SCOPES,
       action: () => void deleteSelection(store),
     },
     {
       key: 'backspace',
-      scope: 'global',
+      scope: AUTHORING_SELECTION_SCOPES,
       action: () => void deleteSelection(store),
     },
     {
       key: 'escape',
-      scope: 'global',
+      scope: AUTHORING_SELECTION_SCOPES,
       // While playing, Escape is owned by play-mode (stop on Escape) — don't also
       // clear the editor selection out from under the running game.
       action: () => {
@@ -350,6 +388,20 @@ export function registerEditorHotkeys(
       scope: 'global',
       action: () => window.dispatchEvent(new CustomEvent('editor:toggle-console')),
     },
+    // W5 (§6.2 focus/maximize mode) — Ctrl/Cmd+Shift+F. SHORTCUT DECISION,
+    // recorded: the benchmarks are Unity's Shift+Space (maximize view under
+    // cursor) and VS Code zen's Ctrl+K Z chord — but this registry is
+    // single-fire and chord-less, and Space already participates in the
+    // overlay's space-pan HOLD gesture (`WorldSelectionOverlay`), so both
+    // benchmarks' literal keys would collide. mod+shift+F ("Focus") is free
+    // in this registry and unclaimed by Chromium on an app page.
+    {
+      key: 'f',
+      mod: true,
+      shift: true,
+      scope: 'global',
+      action: () => toggleWorkspaceFocus(),
+    },
 
     // --- Viewport-scoped (only when viewport/canvas is active) ---
     {