@vgai/editor 0.2.0

package/src/browser-transpile.ts

@@ -0,0 +1,246 @@
+/**
+ * In-browser TypeScript transpile + module resolution.
+ *
+ * This is the client-side replacement for Vite's on-the-fly transpile of
+ * project scripts. It lets the editor hot-reload edited component source
+ * **without any server round-trip** — no Node, no Vite dev server, no file
+ * write. The flow is:
+ *
+ *   TS source string
+ *     → esbuild-wasm transform (TS/TSX → ESM JS, in a Web Worker)
+ *     → rewrite bare imports (`three`, `@engine/...`) to blob-URL shims that
+ *       re-export the **live, already-running** singletons
+ *     → Blob → URL.createObjectURL → dynamic import()
+ *
+ * Sharing singletons is the load-bearing detail: a hot-swapped component must
+ * extend the SAME `GameComponent` class and use the SAME `THREE` instance as
+ * the running runtime, or `instanceof` checks and prototype chains break. We
+ * therefore never pull `three`/engine code from a CDN — we re-export the
+ * modules the editor already imported, via `registerRuntimeModules()`.
+ *
+ * Idiomatic: esbuild-wasm is the same engine Vite uses, just run client-side;
+ * we call its documented API directly (no wrapper abstraction).
+ */
+
+import * as esbuild from 'esbuild-wasm';
+// Vite serves the wasm binary as a static asset URL — fully local, no CDN.
+import esbuildWasmUrl from 'esbuild-wasm/esbuild.wasm?url';
+import { GAME_GLOBALS_PRELUDE } from './gated-globals';
+
+/** Live runtime modules, keyed by the bare specifier used to import them. */
+type ModuleNamespace = Record<string, unknown>;
+const runtimeModules = new Map<string, ModuleNamespace>();
+
+/** Per-specifier shim blob URLs, memoized (the live module identity is stable). */
+const shimUrlCache = new Map<string, string>();
+
+let initPromise: Promise<void> | null = null;
+
+/**
+ * Initialize esbuild-wasm exactly once. Safe to call repeatedly — concurrent
+ * callers share the same promise.
+ */
+export function initBrowserTranspile(): Promise<void> {
+  if (!initPromise) {
+    initPromise = esbuild.initialize({ wasmURL: esbuildWasmUrl }).catch((err) => {
+      // Allow a retry on failure rather than caching a rejected promise.
+      initPromise = null;
+      throw err;
+    });
+  }
+  return initPromise;
+}
+
+/**
+ * Register the live runtime module namespaces that transpiled user code is
+ * allowed to import. Call once at editor/runtime init with the modules the
+ * host already imported statically (so identities are shared).
+ *
+ *   registerRuntimeModules({
+ *     three: THREE,
+ *     '@engine/ecs/game-component': gameComponentModule,
+ *   });
+ */
+export function registerRuntimeModules(modules: Record<string, ModuleNamespace>): void {
+  for (const [spec, ns] of Object.entries(modules)) {
+    runtimeModules.set(spec, ns);
+    shimUrlCache.delete(spec); // invalidate any stale shim
+  }
+  // Exposed on globalThis so shim modules (which run in their own module scope)
+  // can reach the live namespaces by specifier.
+  (globalThis as Record<string, unknown>)['__vgaiModules'] = Object.fromEntries(runtimeModules);
+}
+
+const IDENT_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+// Reserved words can't be `export const <name>` binding identifiers. Some real
+// modules expose them as convenience named exports (e.g. zod exports `catch`,
+// `enum`, `function`, `void`) — re-exporting those verbatim would make the shim
+// itself a SyntaxError ("Unexpected token 'catch'"). They're never imported by
+// those names, so we skip them.
+const RESERVED_WORDS = new Set([
+  'break',
+  'case',
+  'catch',
+  'class',
+  'const',
+  'continue',
+  'debugger',
+  'default',
+  'delete',
+  'do',
+  'else',
+  'enum',
+  'export',
+  'extends',
+  'false',
+  'finally',
+  'for',
+  'function',
+  'if',
+  'import',
+  'in',
+  'instanceof',
+  'new',
+  'null',
+  'return',
+  'super',
+  'switch',
+  'this',
+  'throw',
+  'true',
+  'try',
+  'typeof',
+  'var',
+  'void',
+  'while',
+  'with',
+  'yield',
+  'let',
+  'static',
+  'await',
+  'implements',
+  'interface',
+  'package',
+  'private',
+  'protected',
+  'public',
+]);
+
+/** Build (or reuse) a blob-URL ESM module that re-exports a live namespace. */
+function shimUrlFor(spec: string): string {
+  const cached = shimUrlCache.get(spec);
+  if (cached) return cached;
+
+  const ns = runtimeModules.get(spec);
+  if (!ns) {
+    throw new Error(
+      `Cannot resolve import '${spec}' in browser HMR — not a registered runtime module. ` +
+        `Register it via registerRuntimeModules({ '${spec}': <module> }).`,
+    );
+  }
+
+  const lines = [`const __m = globalThis.__vgaiModules[${JSON.stringify(spec)}];`];
+  for (const key of Object.keys(ns)) {
+    if (key === 'default' || !IDENT_RE.test(key) || RESERVED_WORDS.has(key)) continue;
+    lines.push(`export const ${key} = __m[${JSON.stringify(key)}];`);
+  }
+  if ('default' in ns) lines.push(`export default __m[${JSON.stringify('default')}];`);
+
+  const url = URL.createObjectURL(new Blob([lines.join('\n')], { type: 'text/javascript' }));
+  shimUrlCache.set(spec, url);
+  return url;
+}
+
+// Matches `from '...'` / `from "..."` and bare `import '...'`, but NOT dynamic
+// `import('...')` (a `(` follows `import`, not a quote) — those stay untouched.
+const IMPORT_RE = /(\bfrom\s*|\bimport\s+)(['"])([^'"]+)\2/g;
+
+/** True for specifiers that are already directly importable in the browser. */
+function isResolvable(spec: string): boolean {
+  return (
+    spec.startsWith('.') ||
+    spec.startsWith('/') ||
+    spec.startsWith('blob:') ||
+    spec.startsWith('http:') ||
+    spec.startsWith('https:')
+  );
+}
+
+/** Rewrite bare imports in transpiled JS to blob-URL shims over live modules. */
+function rewriteImports(code: string): string {
+  return code.replace(IMPORT_RE, (match, lead: string, quote: string, spec: string) => {
+    if (isResolvable(spec)) return match;
+    return `${lead}${quote}${shimUrlFor(spec)}${quote}`;
+  });
+}
+
+/**
+ * Transpile TS/TSX source to an importable ESM module URL (blob:). Bare imports
+ * are rewritten to live-singleton shims.
+ *
+ * Low-level primitive: it does NOT apply the game-globals shadow. Project /
+ * game code must go through {@link importFromSource} (which wraps this) so its
+ * `window`/`document` input listeners stay focus-gated; only shadow-exempt
+ * editor-internal source should call this directly.
+ */
+export async function transpileToModuleUrl(
+  source: string,
+  filename = 'in-browser-edit.tsx',
+): Promise<string> {
+  await initBrowserTranspile();
+  const { code } = await esbuild.transform(source, {
+    loader: filename.endsWith('.tsx') ? 'tsx' : 'ts',
+    format: 'esm',
+    target: 'es2022',
+    sourcefile: filename,
+    // Match the editor's tsconfig: decorators + classic field semantics.
+    tsconfigRaw: {
+      compilerOptions: { experimentalDecorators: true, useDefineForClassFields: false },
+    },
+  });
+  const rewritten = rewriteImports(code);
+  return URL.createObjectURL(new Blob([rewritten], { type: 'text/javascript' }));
+}
+
+/**
+ * Prepend the game-globals lexical shadow to project source — the browser-side
+ * analogue of the dev server's `vgai-game-globals` Vite plugin
+ * (`server/dev.ts` + `shouldShadowGameGlobals`). The server shadows per-module
+ * because Vite transforms EVERY module indiscriminately and must be told which
+ * ones are game code; the browser has no such firehose — {@link importFromSource}
+ * is the single client-transpile chokepoint and only ever receives project
+ * code, so "scoping" here is by construction (route project code through this
+ * seam; never through the raw {@link transpileToModuleUrl}). Applying the shadow
+ * to EVERY module that reaches this seam is what keeps game `window`/`document`
+ * input focus-gated on the whole browser path — the bundled project scripts
+ * (`browser-project-scripts.ts`) AND every single-file hot-swap alike, not just
+ * hot-swaps. Kept as its own named, exported function so that invariant is
+ * unit-testable and can't be silently dropped (`browser-globals-shadow.test.ts`).
+ */
+export function applyGameGlobalsShadow(source: string): string {
+  return GAME_GLOBALS_PRELUDE + source;
+}
+
+/**
+ * Transpile TS/TSX source in-browser and dynamically import it, returning the
+ * module namespace. The blob URL is revoked once the import settles.
+ *
+ * This is the ONLY path project code should take: it applies the game-globals
+ * shadow ({@link applyGameGlobalsShadow}) so a component's `window`/`document`
+ * resolve to the editor's gated proxies (input stays focus-gated on the HMR
+ * path too). The raw {@link transpileToModuleUrl} deliberately does NOT shadow —
+ * it is the low-level primitive; feeding project code to it directly would leak
+ * ungated input listeners.
+ */
+export async function importFromSource(
+  source: string,
+  filename = 'in-browser-edit.tsx',
+): Promise<Record<string, unknown>> {
+  const url = await transpileToModuleUrl(applyGameGlobalsShadow(source), filename);
+  try {
+    return (await import(/* @vite-ignore */ url)) as Record<string, unknown>;
+  } finally {
+    URL.revokeObjectURL(url);
+  }
+}

package/src/browser-watch-reload.ts

@@ -0,0 +1,100 @@
+/**
+ * Browser-mode live-reload (Phase A2).
+ *
+ * A server-backed editor learns about file changes two ways: chokidar → SSE
+ * (`scene-changed`, consumed by `connectSceneEvents`) and the Vite dev server's
+ * `vgai:script-update` HMR event (consumed in `play-mode.ts`). A server-less
+ * browser editor has neither. What it DOES have is `StorageBackend.watch()`:
+ * because the browser backend (OPFS / File System Access) is the sole writer,
+ * its self-derived write events ARE the change signal — exactly what HMR needs.
+ *
+ * This module is the browser counterpart of those two consumers. `asset-events`
+ * and `play-mode` keep the server (SSE / `import.meta.hot`) paths and route
+ * through here only when `getEditorMode() === 'browser'`.
+ *
+ * A `WatchEvent` carries only `{ type, path }` — no bytes — so each helper reads
+ * the file back from the backend before dispatching:
+ *   - Scene changes: today this is the editor's own autosave echo, suppressed
+ *     downstream by the store's `_lastSavedContent` guard (a self-write reads
+ *     back byte-identical). It becomes a genuine external-change signal once A4
+ *     adds File System Access out-of-band change detection — this wiring needs
+ *     no further change for that.
+ *   - Component sources: fires whenever anything writes a project `.ts`/`.tsx`
+ *     through the backend (a future code panel, an agent apply-diff, the dev
+ *     `storage-hmr-demo`), driving the same in-browser hot-swap the server's
+ *     `vgai:script-update` handler performs.
+ */
+
+import type { StorageBackend, WatchEvent } from './storage';
+import { getStorageBackend } from './storage';
+
+/** A scene document the editor can reload (`.vscn.json`). */
+export function isSceneFile(path: string): boolean {
+  return path.endsWith('.vscn.json');
+}
+
+/**
+ * A project source file that hot-swaps in place (a GameComponent module).
+ *
+ * `.ts`/`.tsx` only, excluding the entry (`main.ts`) and component registry
+ * (`registry.ts`) — editing those needs a warm restart (server mode) or a
+ * client-side re-bundle (browser mode, not yet available), never a live
+ * prototype swap. Mirrors the server `vgai:script-update` handler's split.
+ */
+export function isHotSwapScriptFile(path: string): boolean {
+  if (!path.endsWith('.ts') && !path.endsWith('.tsx')) return false;
+  const base = path.slice(path.lastIndexOf('/') + 1);
+  return base !== 'main.ts' && base !== 'registry.ts';
+}
+
+/** create/update carry new content; remove does not (nothing to reload). */
+function isWriteEvent(ev: WatchEvent): boolean {
+  return ev.type === 'create' || ev.type === 'update';
+}
+
+/**
+ * Subscribe to backend writes matching `match`, read the new content, and hand
+ * it to `deliver`. Returns an unsubscribe function. Reads that fail (a file
+ * removed between the event and the read) are ignored.
+ */
+function watchFileWrites(
+  backend: StorageBackend,
+  match: (path: string) => boolean,
+  deliver: (path: string, content: string) => void,
+): () => void {
+  return backend.watch((ev) => {
+    if (!isWriteEvent(ev) || !match(ev.path)) return;
+    void backend
+      .read(ev.path)
+      .then((content) => deliver(ev.path, content))
+      .catch(() => {
+        /* file vanished between the write event and the read — ignore */
+      });
+  });
+}
+
+/**
+ * Browser analogue of `connectSceneEvents`: fire `onChange` with the reloaded
+ * `.vscn.json` content whenever the active scene file is written through the
+ * backend. Returns an unsubscribe function.
+ */
+export function watchSceneChanges(
+  onChange: (event: { path: string; content: string }) => void,
+  backend: StorageBackend = getStorageBackend(),
+): () => void {
+  return watchFileWrites(backend, isSceneFile, (path, content) => onChange({ path, content }));
+}
+
+/**
+ * Browser analogue of the `vgai:script-update` HMR handler: fire `onChange` with
+ * a hot-swappable component source whenever one is written through the backend.
+ * Returns an unsubscribe function.
+ */
+export function watchScriptChanges(
+  onChange: (event: { path: string; source: string }) => void,
+  backend: StorageBackend = getStorageBackend(),
+): () => void {
+  return watchFileWrites(backend, isHotSwapScriptFile, (path, source) =>
+    onChange({ path, source }),
+  );
+}

package/src/command-listener.ts

@@ -0,0 +1,326 @@
+/**
+ * Command listener — receives commands from the editor server via SSE
+ * and dispatches them to the EditorStore and play-mode functions.
+ *
+ * The server broadcasts `editor-command` events sent by the SDK/CLI.
+ * This module translates them into store method calls.
+ */
+
+import { parseSceneFile, SceneParseError } from '@engine/scene/parse';
+import { connectEvents, reportCommandResult, reportEditorState } from './editor-api';
+import { editorConsole } from './editor-console';
+import { getEditorMode } from './editor-mode';
+import type { AssetKind, EditorStore, HelperVisibility } from './editor-store';
+import {
+  enterPlayMode,
+  exitPlayMode,
+  pausePlayMode,
+  resumePlayMode,
+  stepPlayMode,
+} from './play-mode';
+
+export interface EditorCommand {
+  type: string;
+  _requestId?: string;
+  [key: string]: unknown;
+}
+
+export interface CommandResult {
+  ok: boolean;
+  error?: string;
+  /** Optional payload for commands that answer with data (e.g. `capture-viewport`'s base64 PNG). */
+  data?: Record<string, unknown>;
+}
+
+/** Live viewport camera pose — undefined when nothing has bound a camera yet
+ *  (see `EditorStore.cameraPose`'s doc comment). */
+function collectCamera(store: EditorStore):
+  | {
+      position: { x: number; y: number; z: number };
+      target: { x: number; y: number; z: number };
+      fov: number;
+    }
+  | undefined {
+  const pose = store.cameraPose;
+  if (!pose) return undefined;
+  return {
+    position: { x: pose.position.x, y: pose.position.y, z: pose.position.z },
+    target: { x: pose.target.x, y: pose.target.y, z: pose.target.z },
+    fov: pose.fov,
+  };
+}
+
+export function collectState(store: EditorStore): Record<string, unknown> {
+  return {
+    playState: store.playState,
+    selectedEntityId: store.selectedEntityId,
+    selectedEntityIds: [...store.selectedEntityIds],
+    activeViewportTab: store.activeViewportTab,
+    activeTabKey: store.activeTabKey,
+    showGrid: store.showGrid,
+    showHelpers: store.showHelpers,
+    showStats: store.showStats,
+    shadingMode: store.shadingMode,
+    helperVisibility: { ...store.helperVisibility },
+    transformMode: store.transformMode,
+    transformSpace: store.transformSpace,
+    snapEnabled: store.snapEnabled,
+    entityCount: store.allEntities().length,
+    savePath: store.savePath,
+    // Camera facet (B3-followup): real pose when a viewport is bound, absent
+    // otherwise — never a fabricated value (see EditorStore.cameraPose).
+    camera: collectCamera(store),
+    // Hierarchy facet (B3-followup): the real entity tree, flattened to
+    // id/name/childIds rows (same shape editor.hierarchy.inspect declares).
+    // `hierarchyRows()` lives on EditorStore (inside the SceneEntity
+    // allowlist — see authoring-inversion-guard.test.ts) so this file never
+    // needs to import SceneEntity itself.
+    entities: store.hierarchyRows(),
+  };
+}
+
+/** Validate the current scene document against the Zod schema. */
+function validateCurrentScene(store: EditorStore): CommandResult {
+  const doc = store.getDocument();
+  try {
+    parseSceneFile(doc);
+    return { ok: true };
+  } catch (err) {
+    if (err instanceof SceneParseError) {
+      return { ok: false, error: err.message };
+    }
+    return { ok: false, error: `Scene validation failed: ${err}` };
+  }
+}
+
+/**
+ * Exported (alongside `collectState` above) so unit tests can dispatch
+ * commands directly against a headless `EditorStore`, with no SSE/server
+ * round-trip — see `packages/editor/test/command-listener.test.ts`, notably
+ * the false-ack regression test: an unrecognized command must return
+ * `{ok:false}`, never fall through to a fabricated `{ok:true}`.
+ */
+export async function handleCommand(
+  store: EditorStore,
+  cmd: EditorCommand,
+): Promise<CommandResult> {
+  switch (cmd['type']) {
+    // Play control
+    case 'play': {
+      // Validate before play — enterPlayMode() also validates, but we need
+      // the error message to flow back to the SDK/CLI.
+      const validation = validateCurrentScene(store);
+      if (!validation.ok) {
+        return validation;
+      }
+      try {
+        await enterPlayMode();
+      } catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+      }
+      break;
+    }
+    case 'stop':
+      exitPlayMode();
+      break;
+    case 'pause':
+      pausePlayMode();
+      break;
+    case 'resume':
+      resumePlayMode();
+      break;
+    case 'step':
+      stepPlayMode();
+      break;
+
+    // Selection
+    case 'select':
+      store.select((cmd['id'] as string | null) ?? null);
+      break;
+    case 'select-multiple':
+      store.selectMultiple(cmd['ids'] as string[]);
+      break;
+    case 'select-all':
+      store.selectAll();
+      break;
+
+    // Viewport
+    case 'focus-entity':
+      store.focusOnEntity(cmd['id'] as string);
+      break;
+    case 'focus-selection':
+      store.focusOnSelection();
+      break;
+    case 'view-preset':
+      store.setViewPreset(cmd['preset'] as 'top' | 'front' | 'right' | 'perspective');
+      break;
+    case 'set-camera': {
+      const position = cmd['position'] as { x: number; y: number; z: number } | undefined;
+      const target = cmd['target'] as { x: number; y: number; z: number } | undefined;
+      const fov = cmd['fov'] as number | undefined;
+      if (
+        !position ||
+        !target ||
+        typeof position.x !== 'number' ||
+        typeof position.y !== 'number' ||
+        typeof position.z !== 'number' ||
+        typeof target.x !== 'number' ||
+        typeof target.y !== 'number' ||
+        typeof target.z !== 'number'
+      ) {
+        return { ok: false, error: 'set-camera requires numeric {x,y,z} position and target.' };
+      }
+      store.setCameraPose(position, target, fov);
+      break;
+    }
+
+    // Panels
+    case 'viewport-tab':
+      store.setActiveViewportTab(cmd['tab'] as 'scene' | 'game');
+      break;
+    case 'active-tab':
+      store.setActiveTab(cmd['key'] as string);
+      break;
+    case 'open-asset-tab':
+      store.openAssetTab(cmd['path'] as string, cmd['kind'] as AssetKind);
+      break;
+    case 'close-asset-tab':
+      store.closeAssetTab(cmd['key'] as string);
+      break;
+    case 'toggle-command-palette':
+      store.toggleCommandPalette();
+      break;
+    case 'toggle-console':
+      window.dispatchEvent(new CustomEvent('editor:toggle-console'));
+      break;
+    case 'show-build':
+      window.dispatchEvent(new CustomEvent('editor:show-build-tab'));
+      break;
+    case 'capture-viewport': {
+      // Fresh, unthrottled on-demand capture (see EditorStore.captureViewportImage's
+      // doc comment) — distinct from the periodic autosave thumbnail the
+      // project-thumbnail snapshot path serves. `size` is optional; defaults
+      // to the store's standard thumbnail size.
+      const size = cmd['size'] as number | undefined;
+      const dataUrl = store.captureViewportImage(size);
+      if (!dataUrl) {
+        return {
+          ok: false,
+          error: 'Viewport is not bound yet (no renderer/scene/camera) — cannot capture.',
+        };
+      }
+      const comma = dataUrl.indexOf(',');
+      const base64 = comma >= 0 ? dataUrl.slice(comma + 1) : dataUrl;
+      return { ok: true, data: { base64, mimeType: 'image/png' } };
+    }
+
+    // Scene loading
+    case 'open-scene': {
+      const scenePath = cmd['path'] as string;
+      const url = scenePath.startsWith('/') ? scenePath : `/${scenePath}`;
+      const res = await fetch(url);
+      if (!res.ok) {
+        return { ok: false, error: `Failed to fetch scene: ${res.status} ${res.statusText}` };
+      }
+      try {
+        const doc = parseSceneFile(await res.json());
+        const savePath = scenePath.replace(/^\//, '');
+        store.loadDocument(doc, savePath);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        editorConsole.error(`Failed to open scene: ${msg}`, 'scene');
+        return { ok: false, error: msg };
+      }
+      break;
+    }
+
+    // Display — set semantics (only toggle when value differs)
+    case 'set-grid':
+      if (store.showGrid !== (cmd['enabled'] as boolean)) store.toggleGrid();
+      break;
+    case 'set-helpers':
+      if (store.showHelpers !== (cmd['enabled'] as boolean)) store.toggleHelpers();
+      break;
+    case 'set-stats':
+      if (store.showStats !== (cmd['enabled'] as boolean)) store.toggleStats();
+      break;
+    case 'set-shading-mode':
+      store.setShadingMode(cmd['mode'] as 'solid' | 'wireframe' | 'unlit');
+      break;
+    case 'set-helper-type': {
+      const helperType = cmd['helperType'] as keyof HelperVisibility;
+      if (store.helperVisibility[helperType] !== (cmd['enabled'] as boolean)) {
+        store.toggleHelperType(helperType);
+      }
+      break;
+    }
+
+    // Transform tools — set semantics
+    case 'set-transform-mode':
+      store.setTransformMode(cmd['mode'] as 'translate' | 'rotate' | 'scale');
+      break;
+    case 'set-transform-space':
+      store.setTransformSpace(cmd['space'] as 'world' | 'local');
+      break;
+    case 'set-snap':
+      if (store.snapEnabled !== (cmd['enabled'] as boolean)) store.toggleSnap();
+      break;
+
+    default:
+      // Every unrecognized command type used to fall through to `return { ok:
+      // true }` below — a silent, false ack: the browser did NOTHING, but the
+      // SDK/CLI caller was told it succeeded. Every "honest gap" op in
+      // packages/vgai-sdk/src/editor/*-operations.ts (camera.get,
+      // hierarchy.inspect pre-wiring, story.open) exists specifically to avoid
+      // ever sending a command that would land here. Reporting a structured
+      // failure — never a fabricated success — is the fix, and it must hold for
+      // ANY unrecognized `type`, not just the ones known about today.
+      return { ok: false, error: `Unknown editor command: ${String(cmd['type'])}` };
+  }
+
+  return { ok: true };
+}
+
+/**
+ * Connect the command listener to the editor server's SSE stream.
+ * Dispatches incoming commands to the store and play-mode functions.
+ * Reports state after each command and on initial connect.
+ */
+export function connectCommandListener(store: EditorStore): () => void {
+  // Browser mode (Phase A2): the `vgai` CLI control channel is server-only (it
+  // is an SSE command stream + state POSTs to `/__editor/*`, which do not exist
+  // without a Node server). Skip it — otherwise the EventSource retry-loops
+  // against a 404 and every `reportEditorState` POSTs into the void.
+  if (getEditorMode() === 'browser') {
+    void store;
+    return () => {};
+  }
+  const source = connectEvents();
+
+  // Report initial state
+  reportEditorState(collectState(store));
+
+  source.addEventListener('editor-command', (e: MessageEvent) => {
+    try {
+      const cmd = JSON.parse(e.data as string) as EditorCommand;
+      const requestId = cmd._requestId;
+      handleCommand(store, cmd).then((result) => {
+        // Report command result back to server (so SDK/CLI gets the response)
+        if (requestId) {
+          reportCommandResult(requestId, result.ok, result.error, result.data);
+        }
+        // Report updated state after command execution
+        reportEditorState(collectState(store));
+      });
+    } catch {
+      /* ignore malformed events */
+    }
+  });
+
+  // When the server switches projects, reload to pick up the new project's files
+  source.addEventListener('project-changed', () => {
+    window.location.reload();
+  });
+
+  return () => source.close();
+}