@scenoco-three/editor 0.2.0 → 0.3.1

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/dist/cli/index.js

@@ -7,45 +7,70 @@ 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]
+  scenoco-editor [scene|prefab] [--port <n>] [--no-open]
+
+With no file, the editor opens a picker listing the scenes/prefabs in the
+project's assets/ folder. Components are scanned from that assets/ folder and tag
+packages are read from its package.json — no --components/--packages needed.
 
 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
+  --port <n>   Fixed MCP server port — set this so the endpoint an MCP client
+               connects to is stable across restarts (the editor's own HTTP
+               server always takes a free port; it doesn't need to be fixed)
+  --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.`;
+Starts a local editor and an MCP server. The editor opens in your default
+browser; when you stop the server (Ctrl+C) it tells the page to close its own
+tab, so no stale tab is left behind. 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') {
+    if (file === '-h' || file === '--help') {
         console.log(USAGE);
-        return file === undefined ? 1 : 0;
+        return 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();
+    // Components default to assets/ and tag packages to the project's package.json
+    // deps (see startEditorServer); --components/--packages remain as optional
+    // overrides for non-standard layouts.
+    // The editor's HTTP server can float on any free port — the browser is pointed
+    // at whatever it gets. `--port` fixes the MCP endpoint instead, so an MCP
+    // client's configured URL stays valid across editor restarts.
     const editor = await startEditorServer({
         cwd,
-        componentRoots: parseList(options.components) ?? ['src'],
-        packages: parseList(options.packages) ?? [],
+        ...(parseList(options.components) ? { componentRoots: parseList(options.components) } : {}),
+        ...(parseList(options.packages) ? { packages: parseList(options.packages) } : {}),
+    });
+    const mcp = await startMcpServer(editor.bridge, {
         ...(options.port ? { port: Number(options.port) } : {}),
     });
-    const mcp = await startMcpServer(editor.bridge);
-    const appUrl = `${editor.url}?file=${encodeURIComponent(resolve(cwd, file))}`;
+    // With no file, open bare — the editor page shows a picker of the assets/ scenes.
+    const query = file ? `?file=${encodeURIComponent(resolve(cwd, file))}` : '';
+    const appUrl = `${editor.url}${query}`;
     console.log(`\n  editor:  ${appUrl}`);
     if (editor.networkUrl)
-        console.log(`  wi-fi:   ${editor.networkUrl}?file=${encodeURIComponent(resolve(cwd, file))}`);
+        console.log(`  wi-fi:   ${editor.networkUrl}${query}`);
     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);
+    let closing = false;
     const shutdown = async () => {
+        if (closing)
+            return;
+        closing = true;
+        // Tell the editor page to close its own tab, then give the notification a
+        // moment to reach the browser before we tear the socket down. Works in any
+        // browser/OS (the tab was opened with the platform's default `open`), though
+        // window.close() is best-effort — see the app's wsClient for the fallback.
+        editor.bridge.push({ push: 'shutdown' });
+        await new Promise((r) => setTimeout(r, 250).unref());
         // 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());

package/dist/protocol.d.ts

@@ -92,16 +92,20 @@ export type EditorResponse = {
     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'`).
+ * An unsolicited server→editor notification (not id-correlated).
+ *
+ * - `fileChanged`: a watched file changed on disk — the open scene/prefab
+ *   (`role: 'open'`) or one of its `src=` deps, a prefab/material (`role: 'dep'`).
+ * - `shutdown`: the dev server is stopping; the editor page closes itself so no
+ *   stale tab is left behind.
  */
-export interface EditorPush {
+export type EditorPush = {
     push: 'fileChanged';
-    /** Absolute path of the changed file. */
     file: string;
     role: 'open' | 'dep';
-}
+} | {
+    push: 'shutdown';
+};
 /** Result payloads, discriminated by `kind`. */
 export type EditorResult = {
     kind: 'ok';

package/dist/server.d.ts

@@ -1,8 +1,8 @@
 import { type EditorCommand, type EditorPush, type EditorResponse } from './protocol.js';
 export interface ServerOptions {
-    /** Directories scanned for `@component`/`@node` tags (default `['src']`). */
+    /** Directories scanned for `@component`/`@node` tags (default `['assets']`). */
     componentRoots?: string[];
-    /** Tag packages to register (e.g. `['@scenoco-three/box2d']`). */
+    /** Tag packages to register (default: the `@scenoco-three/*` deps in package.json). */
     packages?: string[];
     /** Fixed port (default: a free OS port). */
     port?: number;
@@ -42,3 +42,16 @@ export interface EditorServer {
  * to the MCP server over a WebSocket.
  */
 export declare function startEditorServer(opts?: ServerOptions): Promise<EditorServer>;
+/** A scene/prefab source the picker can open, addressed relative to `cwd`. */
+export interface SceneFile {
+    /** Path relative to `cwd` — what the editor passes to `?file=` / `open()`. */
+    file: string;
+    /** Whether it's a scene or a prefab, for the picker's label. */
+    kind: 'scene' | 'prefab';
+}
+/**
+ * Every `*.scene.xml` / `*.prefab.xml` under the asset `roots` (default assets/),
+ * relative to `cwd`. Isolated to the roots — the walk never escapes them, and
+ * build/cache dirs are skipped. Sorted for a stable picker order.
+ */
+export declare function listSceneFiles(roots: string[], cwd: string): SceneFile[];

package/dist/server.js

@@ -1,11 +1,11 @@
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { createServer as createNetServer } from 'node:net';
-import { dirname, resolve } from 'node:path';
+import { dirname, relative, resolve, sep } 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 { bundlePrefab, bundleScene, collectedPackageSchemas, compilePrefabXml, compileSceneXml, componentLoadError, detectTagPackages, generateMaterialXsd, generatePrefabXsd, generateXsd, 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. */
@@ -13,16 +13,64 @@ const fsResolver = (request, referrer) => {
     const path = resolve(referrer ? dirname(referrer) : '.', request);
     return existsSync(path) ? { path, contents: readFileSync(path, 'utf8') } : null;
 };
+/**
+ * (Re)register the project's components (change-aware — a no-op when nothing
+ * changed) and, while the registry is healthy, keep the project's `schema/` XSDs
+ * in sync. A corrupted component file no longer wipes the registry: the last-good
+ * set stays live and the failure is returned for the editor/MCP to surface.
+ */
+async function refreshComponents(roots, cwd, packages) {
+    await loadComponents(roots, cwd, { packages }).catch(() => { });
+    const error = componentLoadError();
+    if (!error)
+        regenerateSchemas(cwd);
+    return error;
+}
+/**
+ * Rewrite `schema/{scene,prefab,material}.xsd` plus each tag package's XSD from the
+ * live registry, so an IDE linked to them tracks component edits without a manual
+ * `scenoco export`. Opt-in: only maintains an *existing* `schema/` dir; writes only
+ * files whose content changed (no git churn, no watcher feedback loop).
+ */
+function regenerateSchemas(cwd) {
+    const dir = resolve(cwd, 'schema');
+    if (!existsSync(dir))
+        return;
+    writeIfChanged(resolve(dir, 'scene.xsd'), generateXsd());
+    writeIfChanged(resolve(dir, 'prefab.xsd'), generatePrefabXsd());
+    writeIfChanged(resolve(dir, 'material.xsd'), generateMaterialXsd());
+    for (const schema of collectedPackageSchemas()) {
+        try {
+            writeIfChanged(resolve(dir, schema.filename), readFileSync(schema.path, 'utf8'));
+        }
+        catch {
+            /* a package XSD went missing — skip it */
+        }
+    }
+}
+function writeIfChanged(path, content) {
+    try {
+        if (existsSync(path) && readFileSync(path, 'utf8') === content)
+            return;
+    }
+    catch {
+        /* unreadable — fall through and overwrite */
+    }
+    writeFileSync(path, content);
+}
 /**
  * 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();
+    // Convention over configuration: scan `assets/` for components and register the
+    // `@scenoco-three/*` tag packages listed in the project's package.json, so the
+    // editor needs no `--components`/`--packages`.
+    const componentRoots = opts.componentRoots ?? ['assets'];
+    const packages = opts.packages ?? detectTagPackages(cwd);
+    const port = opts.port ?? (await freePort());
     const watcher = createFileWatcher();
     const server = await createServer({
         configFile: false,
@@ -122,8 +170,9 @@ 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(() => { });
+            // Register components in this Node process so compilation/validation works,
+            // and publish the project's XSDs (if it has a schema/ dir).
+            await refreshComponents(roots, cwd, packages);
             // 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'))
@@ -147,43 +196,72 @@ function bundleEndpointPlugin(roots, packages, cwd, watcher) {
                     res.end(JSON.stringify({ error: e instanceof Error ? e.message : String(e) }));
                 });
             });
+            // GET /@scenoco/files — the scenes/prefabs under the project's asset roots,
+            // for the start-up file picker (used when the editor is opened with no ?file=).
+            // Isolated to `roots` (default assets/): nothing outside them is listed.
+            server.middlewares.use((req, res, next) => {
+                if (!req.url || !req.url.startsWith('/@scenoco/files'))
+                    return next();
+                res.setHeader('Content-Type', 'application/json');
+                res.end(JSON.stringify({ files: listSceneFiles(roots, cwd) }));
+            });
             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) {
+                void (async () => {
+                    // Pick up any component edits (and re-sync schema/) before compiling, with
+                    // last-good fallback — a broken component is reported, not fatal.
+                    const compError = await refreshComponents(roots, cwd, packages);
+                    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');
+                            // A component load failure is the likely root cause of an "unknown tag"
+                            // compile error — pass it along so the editor can explain it.
+                            res.end(JSON.stringify({ error: 'compile failed', diagnostics: result.diagnostics, componentError: compError?.message }));
+                            return;
+                        }
+                        // A scene's sibling `*.ui.html` (its DOM UI overlay) is embedded in the
+                        // bundle and watched as a dep, so editing it live-refreshes the overlay
+                        // — visible statically even in edit mode (engine.overlay).
+                        if (!isPrefab) {
+                            const uiFile = abs.replace(/\.(scene\.)?xml$/, '.ui.html');
+                            if (existsSync(uiFile)) {
+                                const uiHtml = readFileSync(uiFile, 'utf8');
+                                result.scene.ui = uiHtml;
+                                deps.push({ path: uiFile, contents: uiHtml });
+                            }
+                        }
+                        watcher.arm(abs, xml, deps); // watch this file + its src/ui deps for changes
+                        const bundle = isPrefab ? bundlePrefab(result.scene) : bundleScene(result.scene);
+                        res.setHeader('Content-Type', 'application/json');
+                        // `componentError` is present when the scene still compiled (stale last-good
+                        // registry) but a component file is currently broken — a warning, not fatal.
+                        res.end(JSON.stringify({ bundle, provenance: result.provenance, componentError: compError?.message }));
+                    }
+                    catch (e) {
                         res.statusCode = 400;
                         res.setHeader('Content-Type', 'application/json');
-                        res.end(JSON.stringify({ error: 'compile failed', diagnostics: result.diagnostics }));
-                        return;
+                        res.end(JSON.stringify({ error: e instanceof Error ? e.message : String(e), componentError: compError?.message }));
                     }
-                    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) }));
-                }
+                })();
             });
         },
     };
@@ -251,6 +329,38 @@ function readJsonBody(req) {
         req.on('error', reject);
     });
 }
+/**
+ * Every `*.scene.xml` / `*.prefab.xml` under the asset `roots` (default assets/),
+ * relative to `cwd`. Isolated to the roots — the walk never escapes them, and
+ * build/cache dirs are skipped. Sorted for a stable picker order.
+ */
+export function listSceneFiles(roots, cwd) {
+    const found = new Map(); // keyed by file, dedupes overlapping roots
+    const skip = new Set(['node_modules', 'dist', '.scenoco', '.git']);
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return; // missing/unreadable root — nothing to list
+        }
+        for (const e of entries) {
+            const abs = resolve(dir, e.name);
+            if (e.isDirectory()) {
+                if (!e.name.startsWith('.') && !skip.has(e.name))
+                    walk(abs);
+            }
+            else if (e.name.endsWith('.scene.xml') || e.name.endsWith('.prefab.xml')) {
+                const file = relative(cwd, abs).split(sep).join('/');
+                found.set(file, { file, kind: e.name.endsWith('.prefab.xml') ? 'prefab' : 'scene' });
+            }
+        }
+    };
+    for (const root of roots)
+        walk(resolve(cwd, root));
+    return [...found.values()].sort((a, b) => a.file.localeCompare(b.file));
+}
 /** Ask the OS for a free TCP port (avoids Vite's 5173-default collisions). */
 function freePort() {
     return new Promise((res, rej) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scenoco-three/editor",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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"
   },