@scenoco-three/editor 0.2.0 → 0.3.0

package/README.md

@@ -13,17 +13,20 @@ npm i -D @scenoco-three/editor
 ## CLI
 
 ```
-scenoco-editor <scene|prefab> [options]
-  --components <dirs>   Comma-separated component dirs (default: "src")
-  --packages <pkgs>     Comma-separated tag packages (e.g. @scenoco-three/box2d)
-  --port <n>            Fixed editor server port (default: a free port)
+scenoco-editor [scene|prefab] [options]     Omit the file to choose from a start-up picker
+  --components <dirs>   Comma-separated component dirs (default: "assets")
+  --packages <pkgs>     Comma-separated tag packages (default: every @scenoco-three/*
+                        dependency in the project's package.json)
+  --port <n>            Fixed MCP port — pin it so your MCP client survives restarts
+                        (the HTTP editor server always takes a free port and prints its URL)
   --no-open             Don't auto-open a browser
 ```
 
 ```bash
-scenoco-editor scenes/level.scene.xml --components src --packages @scenoco-three/box2d
-#   editor:  http://localhost:PORT?file=…   ← opens in your browser
-#   mcp:     http://localhost:PORT/mcp      ← add to your MCP client (transport: http)
+scenoco-editor                                    # zero-config: file picker, auto-detected packages
+scenoco-editor assets/scenes/level.scene.xml --port 55470
+#   editor:  http://localhost:HTTP_PORT?file=…    ← opens in your browser
+#   mcp:     http://localhost:55470/mcp           ← add to your MCP client (transport: http)
 ```
 
 It serves the editor app through Vite + `@scenoco-three/vite` (so the open scene compiles
@@ -44,15 +47,17 @@ prompt).
 ### `simulate` — closed-loop driving
 
 One call injects input, steps the sim, and captures — *see a game move, not a static scene*.
-Each command is `{ do, … }`:
+Each command is a self-contained verb `{ do, … }`:
 
 ```ts
 type SimStep =
   | { do: 'play' | 'pause' | 'stop' }
-  | { do: 'step'; frames?: number; dt?: number }
-  | { do: 'key'; code: string; action: 'down' | 'up' | 'tap' }
-  | { do: 'mouse'; x?: number; y?: number; dx?: number; dy?: number;
-      button?: 'left' | 'right' | 'middle'; action?: 'move' | 'down' | 'up' | 'click' }
+  | { do: 'step'; frames?: number; dt?: number }            // advance `frames` ticks (default 1)
+  | { do: 'tap'; key: string }                               // key press + release
+  | { do: 'keyDown'; key: string }
+  | { do: 'keyUp'; key: string }
+  | { do: 'click'; x?: number; y?: number; button?: 'left' | 'right' | 'middle' }
+  | { do: 'move'; x?: number; y?: number; dx?: number; dy?: number }
   | { do: 'gamepad'; index?: number; buttons?: boolean[]; axes?: number[] }
   | { do: 'preview'; camera?: string; lookAt?: string }
   | { do: 'telemetry'; id: string };
@@ -61,7 +66,7 @@ type SimStep =
 ```jsonc
 // "press Space, advance 90 frames, read the ball, screenshot" — in one tool call
 [ { "do": "play" },
-  { "do": "key", "code": "Space", "action": "tap" },
+  { "do": "tap", "key": "Space" },
   { "do": "step", "frames": 90 },
   { "do": "telemetry", "id": "ball" },
   { "do": "preview" } ]
@@ -74,8 +79,8 @@ The result is a `multi` payload: each capture's image/JSON in step order.
 ```ts
 import { startEditorServer, startMcpServer } from '@scenoco-three/editor';
 
-const editor = await startEditorServer({ cwd, componentRoots: ['src'], packages: [] });
-const mcp = await startMcpServer(editor.bridge);   // editor.bridge.send(EditorCommand)
+const editor = await startEditorServer({ cwd });   // defaults: assets/ roots, packages from package.json
+const mcp = await startMcpServer(editor.bridge, { port: 55470 });   // editor.bridge.send(EditorCommand)
 console.log(editor.url, mcp.url);
 // … later
 await mcp.close(); await editor.close();

package/app/filePicker.ts

@@ -0,0 +1,64 @@
+/** A scene/prefab the picker can open (mirrors the server's `/@scenoco/files`). */
+interface PickableFile {
+  file: string;
+  kind: 'scene' | 'prefab';
+}
+
+/**
+ * The start-up open dialog: shown when the editor is opened with no `?file=`.
+ * Lists the scenes/prefabs the server found under the project's assets/ folder
+ * and resolves with the one the user picks. It's a modal overlay — the viewport
+ * behind it is empty until a file is chosen.
+ */
+export async function showFilePicker(onPick: (file: string) => void): Promise<void> {
+  const overlay = document.createElement('div');
+  overlay.className = 'sc-picker';
+  const panel = document.createElement('div');
+  panel.className = 'sc-picker-panel';
+  overlay.append(panel);
+
+  const title = document.createElement('div');
+  title.className = 'sc-picker-title';
+  title.textContent = 'Open a scene';
+  panel.append(title);
+
+  const list = document.createElement('div');
+  list.className = 'sc-picker-list';
+  list.textContent = 'Scanning assets…';
+  panel.append(list);
+  document.body.append(overlay);
+
+  let files: PickableFile[] = [];
+  try {
+    const res = await fetch('/@scenoco/files');
+    files = ((await res.json()) as { files: PickableFile[] }).files ?? [];
+  } catch {
+    /* handled by the empty branch below */
+  }
+
+  list.textContent = '';
+  if (files.length === 0) {
+    const empty = document.createElement('div');
+    empty.className = 'sc-picker-empty';
+    empty.textContent = 'No .scene.xml or .prefab.xml files found under assets/.';
+    list.append(empty);
+    return;
+  }
+
+  for (const f of files) {
+    const row = document.createElement('button');
+    row.className = 'sc-picker-row';
+    const name = document.createElement('span');
+    name.className = 'sc-picker-name';
+    name.textContent = f.file;
+    const kind = document.createElement('span');
+    kind.className = 'sc-picker-kind';
+    kind.textContent = f.kind;
+    row.append(name, kind);
+    row.onclick = () => {
+      overlay.remove();
+      onPick(f.file);
+    };
+    list.append(row);
+  }
+}

package/app/index.html

@@ -93,6 +93,33 @@
         color: #ffd9d9; padding: 5px 10px; cursor: pointer; font: 12px ui-monospace, monospace; }
       #sc-conflict button:first-of-type { background: var(--accent); color: #0e1219; border-color: var(--accent); }
       #sc-conflict button:hover { filter: brightness(1.1); }
+      /* component-load error banner: last-good is live, this says what's broken */
+      #sc-error { position: fixed; top: 62px; left: 50%; transform: translateX(-50%); z-index: 7;
+        display: flex; align-items: flex-start; gap: 10px; max-width: min(680px, 92vw);
+        padding: 9px 13px; border-radius: 10px; background: rgba(44, 22, 14, 0.97);
+        border: 1px solid #7a4326; color: #ffdcc2; font: 12px/1.45 ui-monospace, monospace;
+        backdrop-filter: blur(6px); box-shadow: 0 10px 34px rgba(0, 0, 0, 0.5); }
+      #sc-error > span { white-space: pre-wrap; overflow: auto; max-height: 34vh; }
+      #sc-error button { flex: 0 0 auto; border: 1px solid #7a4326; border-radius: 7px; background: transparent;
+        color: #ffdcc2; padding: 5px 10px; cursor: pointer; font: 12px ui-monospace, monospace; }
+      #sc-error button:hover { filter: brightness(1.15); }
+      /* start-up file picker: shown when the editor opens with no ?file= */
+      .sc-picker { position: fixed; inset: 0; z-index: 8; display: flex; align-items: center;
+        justify-content: center; background: rgba(10, 12, 18, 0.72); backdrop-filter: blur(4px); }
+      .sc-picker-panel { width: min(440px, 88vw); max-height: 76vh; display: flex; flex-direction: column;
+        background: var(--panel); border: 1px solid var(--line); border-radius: 14px; overflow: hidden;
+        font: 13px/1.5 ui-monospace, monospace; box-shadow: 0 18px 60px rgba(0, 0, 0, 0.5); }
+      .sc-picker-title { padding: 14px 18px; font-weight: 700; color: #9fe7ff; letter-spacing: 0.06em;
+        text-transform: uppercase; font-size: 12px; border-bottom: 1px solid var(--line); }
+      .sc-picker-list { overflow: auto; padding: 6px; }
+      .sc-picker-row { width: 100%; display: flex; align-items: center; justify-content: space-between;
+        gap: 10px; padding: 9px 12px; border: 0; border-radius: 8px; background: transparent; color: #e7f0fb;
+        font: 13px ui-monospace, monospace; text-align: left; cursor: pointer; }
+      .sc-picker-row:hover { background: rgba(74, 240, 224, 0.12); color: #eafdff; }
+      .sc-picker-name { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+      .sc-picker-kind { flex: 0 0 auto; color: #6f93b8; font-size: 11px; text-transform: uppercase;
+        letter-spacing: 0.04em; border: 1px solid var(--line); border-radius: 5px; padding: 1px 6px; }
+      .sc-picker-empty { padding: 22px 18px; color: #8fa6c4; text-align: center; }
     </style>
   </head>
   <body>

package/app/main.ts

@@ -1,7 +1,4 @@
 import { Box3, BoxHelper, Raycaster, Vector2, Vector3, type Object3D } from 'three';
-// Register every project component, package tag, and built-in node up front, so
-// any scene/prefab the agent opens has its tags available.
-import 'virtual:scenoco-components';
 import { EditorSession } from './session.js';
 import { connectEditor } from './wsClient.js';
 import { CameraRig } from './cameraRig.js';
@@ -11,6 +8,7 @@ import { buildPanels, type Panels } from './panels.js';
 import { SceneDocument } from './document.js';
 import { Gizmo, type GizmoMode } from './gizmo.js';
 import { buildToolbar, type Toolbar } from './toolbar.js';
+import { showFilePicker } from './filePicker.js';
 
 const canvas = document.getElementById('app') as HTMLCanvasElement;
 // Right mouse drag is the fly-camera look control — suppress the native
@@ -32,6 +30,9 @@ let saving = false;
 // engine swaps (open / run / stop). Play mode runs the scene's own camera with
 // no editor rig, document, or gizmo.
 function rebind(): void {
+  // A file is loaded (from the URL, a user pick, or an MCP `open`) — the start-up
+  // picker, if still up, has served its purpose.
+  if (session.filePath) document.querySelector('.sc-picker')?.remove();
   selection = undefined; // the old engine (and its scene helpers) is disposed
   rig = undefined;
   desktop = undefined;
@@ -234,10 +235,12 @@ async function reloadScene(preserveEdits: boolean): Promise<void> {
   reloading = true;
   const pending = preserveEdits ? (doc?.netEdits() ?? []) : [];
   try {
-    await session.open(path); // re-fetch + swap → rebind() builds a fresh document
+    const summary = await session.open(path); // re-fetch + swap → rebind() builds a fresh document
     if (pending.length) doc?.applyEdits(pending);
+    setComponentError(summary.componentError); // clears when a fix takes effect
   } catch (e) {
     console.error('[editor] reload failed:', e);
+    setComponentError(e instanceof Error ? e.message : String(e));
   } finally {
     reloading = false;
     dismissConflict();
@@ -259,6 +262,28 @@ function dismissConflict(): void {
   conflictBanner?.remove();
   conflictBanner = undefined;
 }
+
+// A persistent error banner for a broken component set. The editor page stays
+// alive (MCP too) but can't render until the code compiles again; this says why
+// and reloads automatically on fix. Passing `undefined` clears it.
+let errorBanner: HTMLElement | undefined;
+function setComponentError(message: string | undefined): void {
+  if (!message) {
+    errorBanner?.remove();
+    errorBanner = undefined;
+    return;
+  }
+  const text = `Component code has an error — the editor will reload once it's fixed:\n${message}`;
+  if (errorBanner) {
+    (errorBanner.firstChild as HTMLElement).textContent = text;
+    return;
+  }
+  const bar = document.createElement('div');
+  bar.id = 'sc-error';
+  bar.append(textSpan(text), bannerButton('Dismiss', () => setComponentError(undefined)));
+  document.body.append(bar);
+  errorBanner = bar;
+}
 function textSpan(text: string): HTMLElement {
   const s = document.createElement('span');
   s.textContent = text;
@@ -282,17 +307,38 @@ function frame(now: number): void {
   requestAnimationFrame(frame);
 }
 
+/** Open a file and reflect it in the URL, so reloads and the wi-fi link resume it. */
+async function openFile(path: string): Promise<void> {
+  try {
+    const summary = await session.open(path);
+    const url = new URL(location.href);
+    url.searchParams.set('file', path);
+    history.replaceState(null, '', url);
+    setComponentError(summary.componentError);
+  } catch (e) {
+    console.error('[editor] open failed:', e);
+    setComponentError(e instanceof Error ? e.message : String(e));
+  }
+}
+
 void (async () => {
+  // Register every project component, package tag, and built-in node. Imported
+  // dynamically + caught so a broken component file can't abort page startup: the
+  // WS bridge (hence MCP) and the error banner still come up. While something is
+  // broken the editor can't render scenes, but it stays alive; a full reload on
+  // the next successful HMR update revives it once every error is fixed.
+  try {
+    await import('virtual:scenoco-components');
+  } catch (e) {
+    console.error('[editor] components failed to load:', e);
+    setComponentError(e instanceof Error ? e.message : String(e));
+    if (import.meta.hot) import.meta.hot.on('vite:afterUpdate', () => location.reload());
+  }
   rebind(); // builds the (empty) panels
   connectEditor(session);
   const initial = new URLSearchParams(location.search).get('file');
-  if (initial) {
-    try {
-      await session.open(initial);
-    } catch (e) {
-      console.error('[editor] open failed:', e);
-    }
-  }
+  if (initial) await openFile(initial);
+  else void showFilePicker(openFile); // no ?file= → let the user pick from assets/
   requestAnimationFrame(frame);
 })();
 

package/app/session.ts

@@ -39,17 +39,22 @@ export class EditorSession {
   }
 
   /** Fetch + load a scene/prefab (edit mode). Returns a small summary. */
-  async open(path: string): Promise<{ file: string; kind: 'scene' | 'prefab'; nodes: number }> {
+  async open(path: string): Promise<{ file: string; kind: 'scene' | 'prefab'; nodes: number; componentError?: string }> {
     const res = await fetch(`/@scenoco/bundle?file=${encodeURIComponent(path)}`);
-    const data = (await res.json()) as { bundle: Bundle; provenance: SceneProvenance } | { error: string };
+    const data = (await res.json()) as
+      | { bundle: Bundle; provenance: SceneProvenance; componentError?: string }
+      | { error: string; componentError?: string };
     if (!res.ok || !('bundle' in data) || !Array.isArray(data.bundle)) {
-      throw new Error((data as { error?: string }).error ?? 'failed to open file');
+      const message = (data as { error?: string }).error ?? 'failed to open file';
+      const componentError = (data as { componentError?: string }).componentError;
+      throw new Error(componentError ? `${message}\n\n${componentError}` : message);
     }
     this.bundle = data.bundle;
     this.provenance = data.provenance;
     this.filePath = path;
     this.toEdit();
-    return { file: path, kind: bundleKind(this.bundle) === 'prefab' ? 'prefab' : 'scene', nodes: count(this.engine.scene) };
+    const summary = { file: path, kind: bundleKind(this.bundle) === 'prefab' ? ('prefab' as const) : ('scene' as const), nodes: count(this.engine.scene) };
+    return data.componentError ? { ...summary, componentError: data.componentError } : summary;
   }
 
   /** Write a set of attribute edits back to the source file (surgical diff). */
@@ -228,13 +233,9 @@ export class EditorSession {
   private frameCamera(): PerspectiveCamera {
     const cam = new PerspectiveCamera(50, this.canvas.clientWidth / this.canvas.clientHeight || 1, 0.01, 50000);
     const box = new Box3().setFromObject(this.engine.scene);
-    const center = new Vector3();
-    let radius = 1;
-    if (!box.isEmpty()) {
-      const sphere = box.getBoundingSphere(new Sphere());
-      center.copy(sphere.center);
-      radius = sphere.radius || 1;
-    }
+    const sphere = box.isEmpty() ? new Sphere(new Vector3(), 1) : box.getBoundingSphere(new Sphere());
+    const center = sphere.center;
+    const radius = sphere.radius || 1;
     cam.position.copy(center).addScaledVector(new Vector3(0.6, 0.45, 1).normalize(), (radius / Math.sin((50 * Math.PI) / 180 / 2)) * 1.2);
     cam.lookAt(center);
     this.engine.mainCamera = cam;

package/app/wsClient.ts

@@ -10,6 +10,8 @@ export function connectEditor(session: EditorSession): void {
   const proto = location.protocol === 'https:' ? 'wss' : 'ws';
   const url = `${proto}://${location.host}${WS_PATH}`;
 
+  let stopped = false; // set on a shutdown push — don't reconnect to a dead server
+
   const open = (): void => {
     const ws = new WebSocket(url);
     ws.onmessage = async (ev) => {
@@ -19,9 +21,14 @@ export function connectEditor(session: EditorSession): void {
       } catch {
         return;
       }
-      // Unsolicited server push (a watched file changed) — not an id-correlated command.
+      // Unsolicited server pushes — not id-correlated commands.
       if ('push' in msg) {
-        session.onExternalChange?.(msg.file, msg.role);
+        if (msg.push === 'shutdown') {
+          stopped = true;
+          closeEditorTab();
+        } else {
+          session.onExternalChange?.(msg.file, msg.role);
+        }
         return;
       }
       const cmd = msg;
@@ -33,12 +40,31 @@ export function connectEditor(session: EditorSession): void {
       }
       ws.send(JSON.stringify(response));
     };
-    ws.onclose = () => setTimeout(open, 1000);
+    ws.onclose = () => {
+      if (!stopped) setTimeout(open, 1000);
+    };
     ws.onerror = () => ws.close();
   };
   open();
 }
 
+/**
+ * The dev server stopped: close this tab. `window.close()` only succeeds for a
+ * tab the script itself opened (or one Chrome deems closable) — if the browser
+ * blocks it, fall back to a "server stopped" placeholder so the stale page is
+ * obvious and inert rather than silently retrying a dead connection.
+ */
+function closeEditorTab(): void {
+  window.close();
+  setTimeout(() => {
+    document.title = 'Editor stopped';
+    document.body.innerHTML =
+      '<div style="position:fixed;inset:0;display:flex;align-items:center;justify-content:center;' +
+      'font:500 15px system-ui,sans-serif;color:#9aa4b2;background:#0a0e16">' +
+      'Editor server stopped — you can close this tab.</div>';
+  }, 150);
+}
+
 /**
  * Execute one relayed command against the session. Exported so the command
  * dispatch (not just the WS plumbing) can be driven directly in tests.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scenoco-three/editor",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Local preview + headless frame render for SceNoCo scenes/prefabs (for multimodal LLMs)",
   "type": "module",
   "license": "MIT",
@@ -37,13 +37,13 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
-    "@scenoco-three/compiler": "^0.2.0",
-    "@scenoco-three/vite": "^0.2.0",
+    "@scenoco-three/compiler": "^0.3.0",
+    "@scenoco-three/vite": "^0.3.0",
     "chokidar": "^4.0.3",
     "ws": "^8.18.0"
   },
   "peerDependencies": {
-    "@scenoco-three/core": "^0.2.0",
+    "@scenoco-three/core": "^0.3.0",
     "three": ">=0.160",
     "vite": ">=5"
   },

package/dist/args.d.ts

@@ -1,8 +0,0 @@
-/** Split a comma-separated list, trimming blanks. */
-export declare function parseList(v: string | undefined): string[] | undefined;
-/** Flags that take a value; other `--flags` are booleans (`''`), the rest positionals. */
-export declare const VALUE_FLAGS: Record<string, string>;
-export declare function parseArgs(args: string[]): {
-    positionals: string[];
-    options: Record<string, string>;
-};

package/dist/args.js

@@ -1,28 +0,0 @@
-// Pure CLI-arg helpers (no vite imports), so they're unit-testable.
-/** Split a comma-separated list, trimming blanks. */
-export function parseList(v) {
-    return v ? v.split(',').map((s) => s.trim()).filter(Boolean) : undefined;
-}
-/** Flags that take a value; other `--flags` are booleans (`''`), the rest positionals. */
-export const VALUE_FLAGS = {
-    '--components': 'components',
-    '--packages': 'packages',
-    '--port': 'port',
-};
-export function parseArgs(args) {
-    const positionals = [];
-    const options = {};
-    for (let i = 0; i < args.length; i++) {
-        const arg = args[i];
-        if (arg in VALUE_FLAGS) {
-            options[VALUE_FLAGS[arg]] = args[++i] ?? '';
-        }
-        else if (arg.startsWith('--')) {
-            options[arg.slice(2)] = ''; // boolean flag, e.g. --no-open
-        }
-        else {
-            positionals.push(arg);
-        }
-    }
-    return { positionals, options };
-}

package/dist/cli/index.d.ts

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-export {};

package/dist/cli/index.js

@@ -1,74 +0,0 @@
-#!/usr/bin/env node
-import { spawn } from 'node:child_process';
-import { resolve } from 'node:path';
-import { parseArgs, parseList } from '../args.js';
-import { startEditorServer } from '../server.js';
-import { startMcpServer } from '../mcp.js';
-const USAGE = `scenoco-editor — open a scene/prefab and drive it from an MCP client
-
-Usage:
-  scenoco-editor <scene|prefab> [options]
-
-Options:
-  --components <dirs>  Comma-separated component dirs (default: "src")
-  --packages <pkgs>    Comma-separated tag packages (e.g. @scenoco-three/box2d)
-  --port <n>           Fixed editor server port (default: a free port)
-  --no-open            Don't auto-open the editor in a browser
-
-Starts a local editor (opened in your browser) and an MCP server. Point an MCP
-client at the printed endpoint; its tools — open_file, get_preview, run, pause,
-stop, get_telemetry — drive the live editor.`;
-async function main(argv) {
-    const { positionals, options } = parseArgs(argv);
-    const file = positionals[0];
-    if (file === undefined || file === '-h' || file === '--help') {
-        console.log(USAGE);
-        return file === undefined ? 1 : 0;
-    }
-    // npm/npx rewrites process.cwd() to the nearest enclosing package.json when
-    // run from inside a workspace package without its own node_modules/.bin
-    // (e.g. `npx scenoco-editor` from examples/breakout/scenes). INIT_CWD still
-    // holds the shell's actual directory.
-    const cwd = process.env.INIT_CWD || process.cwd();
-    const editor = await startEditorServer({
-        cwd,
-        componentRoots: parseList(options.components) ?? ['src'],
-        packages: parseList(options.packages) ?? [],
-        ...(options.port ? { port: Number(options.port) } : {}),
-    });
-    const mcp = await startMcpServer(editor.bridge);
-    const appUrl = `${editor.url}?file=${encodeURIComponent(resolve(cwd, file))}`;
-    console.log(`\n  editor:  ${appUrl}`);
-    if (editor.networkUrl)
-        console.log(`  wi-fi:   ${editor.networkUrl}?file=${encodeURIComponent(resolve(cwd, file))}`);
-    console.log(`  mcp:     ${mcp.url}   ← add this to your MCP client (transport: http)`);
-    console.log(`\n  press Ctrl+C to stop\n`);
-    if (!('no-open' in options))
-        openBrowser(appUrl);
-    const shutdown = async () => {
-        // Connected browsers keep WS/HMR/keep-alive sockets open, so `close()` can
-        // stall waiting for them to drain — cap it so Ctrl+C always exits promptly.
-        const deadline = new Promise((r) => setTimeout(r, 1500).unref());
-        await Promise.race([Promise.all([mcp.close().catch(() => { }), editor.close().catch(() => { })]), deadline]);
-        process.exit(0);
-    };
-    process.on('SIGINT', () => void shutdown());
-    process.on('SIGTERM', () => void shutdown());
-    await new Promise(() => { }); // keep alive
-    return 0;
-}
-/** Open a URL in the default browser (best-effort, per platform). */
-function openBrowser(url) {
-    const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
-    const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
-    try {
-        spawn(cmd, args, { stdio: 'ignore', detached: true }).unref();
-    }
-    catch {
-        /* non-fatal: the URL is printed */
-    }
-}
-process.exitCode = await main(process.argv.slice(2)).catch((e) => {
-    console.error(e instanceof Error ? e.message : String(e));
-    return 1;
-});

package/dist/index.d.ts

@@ -1,3 +0,0 @@
-export { startEditorServer, type ServerOptions, type EditorServer, type EditorBridge } from './server.js';
-export { startMcpServer, buildMcpServer, type McpHandle } from './mcp.js';
-export { WS_PATH, commandId, type EditorCommand, type EditorResponse, type EditorResult, } from './protocol.js';

package/dist/index.js

@@ -1,6 +0,0 @@
-// `@scenoco-three/editor` — programmatic API behind the `scenoco-editor` CLI.
-// Serves the editor app, bridges it to an MCP server over a WebSocket, and exposes
-// MCP tools (open_file / get_preview / run / pause / stop / get_telemetry).
-export { startEditorServer } from './server.js';
-export { startMcpServer, buildMcpServer } from './mcp.js';
-export { WS_PATH, commandId, } from './protocol.js';

package/dist/mcp.d.ts

@@ -1,16 +0,0 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { EditorBridge } from './server.js';
-export interface McpHandle {
-    /** The MCP endpoint URL to add to an MCP client. */
-    url: string;
-    close(): Promise<void>;
-}
-/**
- * Start a stateless MCP server (Streamable HTTP) whose tools relay to the live
- * editor over `bridge`. A fresh `McpServer` + transport is built per request.
- */
-export declare function startMcpServer(bridge: EditorBridge, opts?: {
-    port?: number;
-}): Promise<McpHandle>;
-/** Build an McpServer whose tools relay to the editor. */
-export declare function buildMcpServer(bridge: EditorBridge): McpServer;

package/dist/mcp.js

@@ -1,150 +0,0 @@
-import { createServer as createHttpServer } from 'node:http';
-import { createServer as createNetServer } from 'node:net';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { z } from 'zod';
-import { commandId } from './protocol.js';
-/**
- * Start a stateless MCP server (Streamable HTTP) whose tools relay to the live
- * editor over `bridge`. A fresh `McpServer` + transport is built per request.
- */
-export async function startMcpServer(bridge, opts = {}) {
-    const port = opts.port ?? (await freePort());
-    const http = createHttpServer((req, res) => void handle(req, res, bridge));
-    await new Promise((resolve) => http.listen(port, resolve));
-    return {
-        url: `http://localhost:${port}/mcp`,
-        close: () => new Promise((resolve) => http.close(() => resolve())),
-    };
-}
-/** Build an McpServer whose tools relay to the editor. */
-export function buildMcpServer(bridge) {
-    const server = new McpServer({ name: 'scenoco-editor', version: '0.1.0' });
-    const relay = (cmd) => relayToEditor(bridge, cmd);
-    server.registerTool('open_file', { description: 'Open a scene (.scene.xml) or prefab (.prefab.xml) in the editor (edit mode).', inputSchema: { path: z.string() } }, ({ path }) => relay({ id: commandId(), type: 'open', path }));
-    server.registerTool('get_preview', {
-        description: 'Capture the current editor view as a PNG. Optionally frame a specific camera.',
-        inputSchema: {
-            camera: z.string().optional().describe('Camera position "x y z"'),
-            lookAt: z.string().optional().describe('Look-at point "x y z"'),
-        },
-    }, ({ camera, lookAt }) => relay({ id: commandId(), type: 'preview', ...(camera ? { camera } : {}), ...(lookAt ? { lookAt } : {}) }));
-    server.registerTool('playback', {
-        description: 'Control gameplay: play (run components/systems/physics), pause, or stop (back to edit mode).',
-        inputSchema: { state: z.enum(['play', 'pause', 'stop']) },
-    }, ({ state }) => relay({ id: commandId(), type: state === 'play' ? 'run' : state }));
-    server.registerTool('get_telemetry', { description: 'Current property values (JSON) for the node/components at a scene id.', inputSchema: { id: z.string() } }, ({ id }) => relay({ id: commandId(), type: 'telemetry', targetId: id }));
-    // A simulation command — one entry in the `simulate` batch. Loose (all fields
-    // optional) so the agent composes any step; only `do` is required.
-    const simStep = z.object({
-        do: z.enum(['play', 'pause', 'stop', 'step', 'tap', 'keyDown', 'keyUp', 'click', 'move', 'gamepad', 'preview', 'telemetry']),
-        key: z.string().optional().describe("tap/keyDown/keyUp: key name, e.g. 'Space', 'W', 'LeftArrow'"),
-        frames: z.number().int().optional(),
-        dt: z.number().optional(),
-        x: z.number().optional(),
-        y: z.number().optional(),
-        dx: z.number().optional(),
-        dy: z.number().optional(),
-        button: z.enum(['left', 'right', 'middle']).optional(),
-        index: z.number().int().optional(),
-        buttons: z.array(z.boolean()).optional(),
-        axes: z.array(z.number()).optional(),
-        camera: z.string().optional(),
-        lookAt: z.string().optional(),
-        id: z.string().optional(),
-    });
-    server.registerTool('simulate', {
-        description: 'Drive gameplay: an ordered batch of steps; returns previews (images) and telemetry (JSON) in order. ' +
-            'Each step is one self-contained verb: { do: "play"|"pause"|"stop" | "step"(frames) | "tap"(key) | ' +
-            '"keyDown"(key) | "keyUp"(key) | "click"(x,y,button) | "move"(x,y,dx,dy) | "preview"(camera,lookAt) | "telemetry"(id) }. ' +
-            'Example: [{do:"play"},{do:"tap",key:"Space"},{do:"step",frames:90},{do:"preview"}].',
-        inputSchema: { commands: z.array(simStep) },
-    }, ({ commands }) => relay({ id: commandId(), type: 'simulate', steps: commands }));
-    return server;
-}
-/** Send a command to the editor and map its reply to MCP tool content. */
-async function relayToEditor(bridge, cmd) {
-    let response;
-    try {
-        response = await bridge.send(cmd);
-    }
-    catch (e) {
-        return { isError: true, content: [{ type: 'text', text: e instanceof Error ? e.message : String(e) }] };
-    }
-    if (!response.ok)
-        return { isError: true, content: [{ type: 'text', text: response.error }] };
-    return toContent(response.result);
-}
-function toContent(result) {
-    switch (result.kind) {
-        case 'image': {
-            const base64 = result.dataUrl.replace(/^data:image\/png;base64,/, '');
-            return { content: [{ type: 'image', data: base64, mimeType: 'image/png' }] };
-        }
-        case 'json':
-            return { content: [{ type: 'text', text: JSON.stringify(result.data, null, 2) }] };
-        case 'multi': {
-            // Flatten each capture's blocks, preserving step order.
-            const content = result.results.flatMap((r) => toContent(r).content);
-            return { content: content.length > 0 ? content : [{ type: 'text', text: 'ok' }] };
-        }
-        case 'ok':
-        default:
-            return { content: [{ type: 'text', text: result.info ?? 'ok' }] };
-    }
-}
-async function handle(req, res, bridge) {
-    res.setHeader('Access-Control-Allow-Origin', '*');
-    res.setHeader('Access-Control-Allow-Headers', 'content-type, mcp-session-id, mcp-protocol-version');
-    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
-    if (req.method === 'OPTIONS') {
-        res.statusCode = 204;
-        res.end();
-        return;
-    }
-    if ((req.url ?? '').split('?')[0] !== '/mcp') {
-        res.statusCode = 404;
-        res.end('not found');
-        return;
-    }
-    if (req.method !== 'POST') {
-        res.statusCode = 405;
-        res.setHeader('Allow', 'POST');
-        res.end(JSON.stringify({ error: 'this MCP endpoint is stateless — use POST' }));
-        return;
-    }
-    const body = await readJson(req);
-    // Stateless: a fresh server + transport per request.
-    const server = buildMcpServer(bridge);
-    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
-    res.on('close', () => {
-        void transport.close();
-        void server.close();
-    });
-    await server.connect(transport);
-    await transport.handleRequest(req, res, body);
-}
-function readJson(req) {
-    return new Promise((resolve) => {
-        let data = '';
-        req.on('data', (c) => (data += c));
-        req.on('end', () => {
-            try {
-                resolve(data ? JSON.parse(data) : undefined);
-            }
-            catch {
-                resolve(undefined);
-            }
-        });
-    });
-}
-function freePort() {
-    return new Promise((res, rej) => {
-        const probe = createNetServer();
-        probe.on('error', rej);
-        probe.listen(0, () => {
-            const port = probe.address().port;
-            probe.close(() => res(port));
-        });
-    });
-}

package/dist/protocol.d.ts

@@ -1,157 +0,0 @@
-/** WebSocket path the editor connects to on the dev server. */
-export declare const WS_PATH = "/scenoco-ws";
-/** A command sent MCP-server → editor (id-correlated with its response). */
-export type EditorCommand = {
-    id: string;
-    type: 'open';
-    path: string;
-} | {
-    id: string;
-    type: 'preview';
-    camera?: string;
-    lookAt?: string;
-    size?: string;
-} | {
-    id: string;
-    type: 'run';
-} | {
-    id: string;
-    type: 'pause';
-} | {
-    id: string;
-    type: 'stop';
-} | {
-    id: string;
-    type: 'telemetry';
-    targetId: string;
-} | {
-    id: string;
-    type: 'simulate';
-    steps: SimStep[];
-};
-/**
- * One step in a `simulate` batch — transport, frame stepping, synthetic input, or
- * a capture. Executed in order against the live engine, so an agent can drive the
- * game to a precise condition and sample preview/telemetry there.
- */
-export type SimStep = {
-    do: 'play' | 'pause' | 'stop';
-}
-/** Advance the simulation by `frames` ticks (default 1) of `dt` seconds (default 1/60). */
- | {
-    do: 'step';
-    frames?: number;
-    dt?: number;
-}
-/** Keyboard — `key` is a Unity KeyCode name (e.g. 'Space', 'W'). Each action is its own verb. */
- | {
-    do: 'tap';
-    key: string;
-} | {
-    do: 'keyDown';
-    key: string;
-} | {
-    do: 'keyUp';
-    key: string;
-}
-/** Mouse — `x,y` canvas-relative px (top-left). `click` = down+up; button defaults to left. */
- | {
-    do: 'click';
-    x?: number;
-    y?: number;
-    button?: 'left' | 'right' | 'middle';
-} | {
-    do: 'move';
-    x?: number;
-    y?: number;
-    dx?: number;
-    dy?: number;
-}
-/** Gamepad: synthetic pad `index` (default 0) with pressed `buttons` + `axes`. */
- | {
-    do: 'gamepad';
-    index?: number;
-    buttons?: boolean[];
-    axes?: number[];
-} | {
-    do: 'preview';
-    camera?: string;
-    lookAt?: string;
-} | {
-    do: 'telemetry';
-    id: string;
-};
-/** The editor's reply, keyed by the command id. */
-export type EditorResponse = {
-    id: string;
-    ok: true;
-    result: EditorResult;
-} | {
-    id: string;
-    ok: false;
-    error: string;
-};
-/**
- * An unsolicited server→editor notification (not id-correlated). Sent when a
- * watched file changes on disk: the open scene/prefab (`role: 'open'`) or one of
- * its `src=` dependencies — a prefab/material (`role: 'dep'`).
- */
-export interface EditorPush {
-    push: 'fileChanged';
-    /** Absolute path of the changed file. */
-    file: string;
-    role: 'open' | 'dep';
-}
-/** Result payloads, discriminated by `kind`. */
-export type EditorResult = {
-    kind: 'ok';
-    info?: string;
-} | {
-    kind: 'image';
-    dataUrl: string;
-} | {
-    kind: 'json';
-    data: unknown;
-} | {
-    kind: 'multi';
-    results: EditorResult[];
-};
-/** Random correlation id for a command. */
-export declare function commandId(): string;
-/**
- * Which compiled element an edit targets. Resolved server-side via the source
- * map (compiled index → source element), so it survives prefab expansion where
- * structural paths don't. `id`s are carried for readability/debugging.
- */
-export type EditTarget = {
-    kind: 'node';
-    nodeIndex: number;
-    id?: string;
-} | {
-    kind: 'component';
-    componentIndex: number;
-    nodeIndex: number;
-    nodeId?: string;
-    /** Component tag + its ordinal among same-typed components on the node. */
-    type: string;
-    ordinal: number;
-} | {
-    kind: 'attachment';
-    nodeIndex: number;
-    /** Owning node id; absent for the scene-root, which `root` then marks. */
-    nodeId?: string;
-    root?: boolean;
-    /** Attachment tag + its ordinal among same-tag attachments on the node. */
-    tag: string;
-    ordinal: number;
-};
-/**
- * One attribute change in compiled form (numbers/arrays/strings/bools). The
- * server serializes `value` to an attribute string using the registry codecs,
- * or removes the attribute when it equals the registry default (minimal diff).
- */
-export interface EditOp {
-    target: EditTarget;
-    attr: string;
-    value: number | boolean | string | number[];
-}

package/dist/protocol.js

@@ -1,9 +0,0 @@
-// Shared command/response protocol for the WebSocket bridge between the MCP
-// server (Node) and the editor app (browser). Pure types + a tiny correlation
-// helper, so both ends agree and the relay logic is unit-testable.
-/** WebSocket path the editor connects to on the dev server. */
-export const WS_PATH = '/scenoco-ws';
-/** Random correlation id for a command. */
-export function commandId() {
-    return Math.random().toString(36).slice(2, 10);
-}

package/dist/server.d.ts

@@ -1,44 +0,0 @@
-import { type EditorCommand, type EditorPush, type EditorResponse } from './protocol.js';
-export interface ServerOptions {
-    /** Directories scanned for `@component`/`@node` tags (default `['src']`). */
-    componentRoots?: string[];
-    /** Tag packages to register (e.g. `['@scenoco-three/box2d']`). */
-    packages?: string[];
-    /** Fixed port (default: a free OS port). */
-    port?: number;
-    /** Base directory `componentRoots` are resolved against (default: `process.cwd()`). */
-    cwd?: string;
-}
-/** Relays MCP tool commands to the connected editor page and awaits its reply. */
-export interface EditorBridge {
-    connected(): boolean;
-    send(cmd: EditorCommand): Promise<EditorResponse>;
-    /** Send an unsolicited notification to the editor page (e.g. a file change). */
-    push(msg: EditorPush): void;
-}
-/** Watches the open file + its `src=` deps and pushes change notifications. */
-export interface FileWatcher {
-    /** (Re)arm the watch set after a successful compile of `openFile` with `deps`. */
-    arm(openFile: string, openContents: string, deps: {
-        path: string;
-        contents: string;
-    }[]): void;
-    /** Record content the editor itself just wrote, so its own save isn't seen as external. */
-    note(file: string, contents: string): void;
-    setPush(push: (msg: EditorPush) => void): void;
-    close(): Promise<void>;
-}
-export interface EditorServer {
-    /** Local URL the editor app is served at. */
-    url: string;
-    /** LAN URL (open on another device on the same network). */
-    networkUrl?: string;
-    bridge: EditorBridge;
-    close(): Promise<void>;
-}
-/**
- * Start the editor's Vite dev server: serves the app, registers all project
- * components/packages, compiles any scene/prefab on demand, and bridges the page
- * to the MCP server over a WebSocket.
- */
-export declare function startEditorServer(opts?: ServerOptions): Promise<EditorServer>;

package/dist/server.js

@@ -1,264 +0,0 @@
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { createServer as createNetServer } from 'node:net';
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import chokidar from 'chokidar';
-import { createServer } from 'vite';
-import { WebSocketServer } from 'ws';
-import { bundlePrefab, bundleScene, compilePrefabXml, compileSceneXml, loadComponents, patchSceneXml, scanComponents, } from '@scenoco-three/compiler';
-import { WS_PATH } from './protocol.js';
-const appDir = fileURLToPath(new URL('../app', import.meta.url));
-/** Loads `src=` resources from disk, relative to the referencing file. */
-const fsResolver = (request, referrer) => {
-    const path = resolve(referrer ? dirname(referrer) : '.', request);
-    return existsSync(path) ? { path, contents: readFileSync(path, 'utf8') } : null;
-};
-/**
- * Start the editor's Vite dev server: serves the app, registers all project
- * components/packages, compiles any scene/prefab on demand, and bridges the page
- * to the MCP server over a WebSocket.
- */
-export async function startEditorServer(opts = {}) {
-    const componentRoots = opts.componentRoots ?? ['src'];
-    const packages = opts.packages ?? [];
-    const port = opts.port ?? (await freePort());
-    const cwd = opts.cwd ?? process.cwd();
-    const watcher = createFileWatcher();
-    const server = await createServer({
-        configFile: false,
-        root: appDir,
-        logLevel: 'warn',
-        server: { host: true, port, strictPort: true, fs: { strict: false } },
-        plugins: [allComponentsPlugin(componentRoots, packages, cwd), bundleEndpointPlugin(componentRoots, packages, cwd, watcher)],
-    });
-    await server.listen();
-    const bridge = attachBridge(server);
-    watcher.setPush((msg) => bridge.push(msg));
-    const url = server.resolvedUrls?.local[0] ?? `http://localhost:${port}/`;
-    const networkUrl = server.resolvedUrls?.network[0];
-    return {
-        url,
-        ...(networkUrl ? { networkUrl } : {}),
-        bridge,
-        close: async () => {
-            await watcher.close();
-            await server.close();
-        },
-    };
-}
-/**
- * A push-based file watcher: tracks the open file plus its `src=` dependencies,
- * and notifies the editor when one changes on disk. Changes whose content matches
- * what we last compiled/wrote are ignored — so the editor's own save (and no-op
- * touches) don't masquerade as external edits.
- */
-function createFileWatcher() {
-    const w = chokidar.watch([], { ignoreInitial: true, awaitWriteFinish: true });
-    const content = new Map(); // abs path → last-known content
-    let openFile = '';
-    let push = () => { };
-    const onChange = (changed) => {
-        const abs = resolve(changed);
-        if (!content.has(abs))
-            return; // not in our set
-        let text;
-        try {
-            text = readFileSync(abs, 'utf8');
-        }
-        catch {
-            return; // deleted mid-event; ignore
-        }
-        if (text === content.get(abs))
-            return; // our own write or a no-op touch
-        content.set(abs, text);
-        push({ push: 'fileChanged', file: abs, role: abs === openFile ? 'open' : 'dep' });
-    };
-    w.on('change', onChange);
-    w.on('add', onChange);
-    return {
-        arm(file, openContents, deps) {
-            const abs = resolve(file);
-            const next = new Map([[abs, openContents]]);
-            for (const d of deps)
-                next.set(resolve(d.path), d.contents);
-            for (const old of content.keys())
-                if (!next.has(old))
-                    w.unwatch(old);
-            for (const p of next.keys())
-                if (!content.has(p))
-                    w.add(p);
-            content.clear();
-            for (const [k, v] of next)
-                content.set(k, v);
-            openFile = abs;
-        },
-        note(file, contents) {
-            content.set(resolve(file), contents);
-        },
-        setPush(fn) {
-            push = fn;
-        },
-        close: () => w.close(),
-    };
-}
-/** `virtual:scenoco-components` → import every project component + package + built-in nodes. */
-function allComponentsPlugin(roots, packages, cwd) {
-    const id = 'virtual:scenoco-components';
-    const resolved = '\0' + id;
-    return {
-        name: 'scenoco:all-components',
-        resolveId: (source) => (source === id ? resolved : null),
-        load(source) {
-            if (source !== resolved)
-                return null;
-            const files = [...scanComponents(roots, cwd).files.keys()].map((f) => `import ${JSON.stringify(`/@fs${f}`)};`);
-            const pkgs = packages.map((p) => `import ${JSON.stringify(p)};`);
-            return ['import "@scenoco-three/core/nodes";', ...pkgs, ...files].join('\n');
-        },
-    };
-}
-/** `GET /@scenoco/bundle?file=<abs>` → the compiled runtime bundle (JSON). */
-function bundleEndpointPlugin(roots, packages, cwd, watcher) {
-    return {
-        name: 'scenoco:bundle-endpoint',
-        async configureServer(server) {
-            // Register components in this Node process so compilation/validation works.
-            await loadComponents(roots, cwd, { packages }).catch(() => { });
-            // POST /@scenoco/save — surgical, attribute-level write-back to the source.
-            server.middlewares.use((req, res, next) => {
-                if (req.method !== 'POST' || !req.url || !req.url.startsWith('/@scenoco/save'))
-                    return next();
-                void readJsonBody(req)
-                    .then((body) => {
-                    const { file, edits } = (body ?? {});
-                    if (!file || !Array.isArray(edits))
-                        throw new Error('expected { file, edits }');
-                    const abs = resolve(cwd, file);
-                    const { text, changed, unresolved } = patchSceneXml(readFileSync(abs, 'utf8'), edits);
-                    if (changed > 0)
-                        writeFileSync(abs, text);
-                    watcher.note(abs, text); // our own write — don't report it back as an external change
-                    res.setHeader('Content-Type', 'application/json');
-                    res.end(JSON.stringify({ ok: true, changed, unresolved: unresolved.length }));
-                })
-                    .catch((e) => {
-                    res.statusCode = 400;
-                    res.setHeader('Content-Type', 'application/json');
-                    res.end(JSON.stringify({ error: e instanceof Error ? e.message : String(e) }));
-                });
-            });
-            server.middlewares.use((req, res, next) => {
-                if (!req.url || !req.url.startsWith('/@scenoco/bundle'))
-                    return next();
-                try {
-                    const file = new URL(req.url, 'http://x').searchParams.get('file');
-                    if (!file)
-                        throw new Error('missing ?file=');
-                    const abs = resolve(cwd, file);
-                    const xml = readFileSync(abs, 'utf8');
-                    const isPrefab = abs.endsWith('.prefab.xml');
-                    // Track which src= files the compile touches, so we can watch them too.
-                    const deps = [];
-                    const trackingResolver = (request, referrer) => {
-                        const r = fsResolver(request, referrer);
-                        if (r)
-                            deps.push({ path: r.path, contents: r.contents });
-                        return r;
-                    };
-                    const result = isPrefab
-                        ? compilePrefabXml(xml, { path: abs, resolve: trackingResolver })
-                        : compileSceneXml(xml, { path: abs, resolve: trackingResolver });
-                    if (!result.ok) {
-                        res.statusCode = 400;
-                        res.setHeader('Content-Type', 'application/json');
-                        res.end(JSON.stringify({ error: 'compile failed', diagnostics: result.diagnostics }));
-                        return;
-                    }
-                    watcher.arm(abs, xml, deps); // watch this file + its src deps for changes
-                    const bundle = isPrefab ? bundlePrefab(result.scene) : bundleScene(result.scene);
-                    res.setHeader('Content-Type', 'application/json');
-                    res.end(JSON.stringify({ bundle, provenance: result.provenance }));
-                }
-                catch (e) {
-                    res.statusCode = 400;
-                    res.setHeader('Content-Type', 'application/json');
-                    res.end(JSON.stringify({ error: e instanceof Error ? e.message : String(e) }));
-                }
-            });
-        },
-    };
-}
-/** WebSocket bridge: one editor page ↔ the MCP server, with id-correlated replies. */
-function attachBridge(server) {
-    const wss = new WebSocketServer({ noServer: true });
-    let editor;
-    const pending = new Map();
-    server.httpServer?.on('upgrade', (req, socket, head) => {
-        // Only our path; Vite's HMR upgrades (vite-hmr subprotocol) fall through to it.
-        if (!req.url || !req.url.startsWith(WS_PATH))
-            return;
-        wss.handleUpgrade(req, socket, head, (ws) => {
-            editor = ws;
-            ws.on('message', (data) => {
-                try {
-                    const r = JSON.parse(String(data));
-                    pending.get(r.id)?.(r);
-                    pending.delete(r.id);
-                }
-                catch {
-                    /* ignore malformed */
-                }
-            });
-            ws.on('close', () => {
-                if (editor === ws)
-                    editor = undefined;
-            });
-        });
-    });
-    return {
-        connected: () => !!editor && editor.readyState === editor.OPEN,
-        send: (cmd) => new Promise((res, rej) => {
-            if (!editor || editor.readyState !== editor.OPEN) {
-                rej(new Error('no editor connected — open the editor page in a browser first'));
-                return;
-            }
-            pending.set(cmd.id, res);
-            editor.send(JSON.stringify(cmd));
-            setTimeout(() => {
-                if (pending.delete(cmd.id))
-                    rej(new Error('editor did not respond in time'));
-            }, 15000);
-        }),
-        push: (msg) => {
-            if (editor && editor.readyState === editor.OPEN)
-                editor.send(JSON.stringify(msg));
-        },
-    };
-}
-/** Read a request's JSON body (for the save endpoint). */
-function readJsonBody(req) {
-    return new Promise((resolve, reject) => {
-        let data = '';
-        req.on('data', (c) => (data += c));
-        req.on('end', () => {
-            try {
-                resolve(data ? JSON.parse(data) : undefined);
-            }
-            catch (e) {
-                reject(e instanceof Error ? e : new Error(String(e)));
-            }
-        });
-        req.on('error', reject);
-    });
-}
-/** Ask the OS for a free TCP port (avoids Vite's 5173-default collisions). */
-function freePort() {
-    return new Promise((res, rej) => {
-        const probe = createNetServer();
-        probe.on('error', rej);
-        probe.listen(0, () => {
-            const port = probe.address().port;
-            probe.close(() => res(port));
-        });
-    });
-}