@scenoco-three/editor 0.3.2 → 0.5.0

package/dist/server.js

@@ -1,374 +1,437 @@
-import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { createServer as createNetServer } from 'node:net';
-import { dirname, relative, resolve, sep } from 'node:path';
+import { dirname, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import chokidar from 'chokidar';
+import react from '@vitejs/plugin-react';
 import { createServer } from 'vite';
 import { WebSocketServer } from 'ws';
-import { bundlePrefab, bundleScene, collectedPackageSchemas, compilePrefabXml, compileSceneXml, componentLoadError, detectTagPackages, generateMaterialXsd, generatePrefabXsd, generateXsd, loadComponents, patchSceneXml, scanComponents, } from '@scenoco-three/compiler';
+import { build, findAssets, formatDiagnostic, indexDocument, insertChild, moveElement, removeElement, setAttribute, } 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;
-};
+const appRoot = fileURLToPath(new URL('../app', import.meta.url));
 /**
- * (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.
+ * The editor's own dev server.
+ *
+ * It serves the editor page from this package and lets it import the **project's** generated
+ * modules over `/@fs`, which is the arrangement decided when this was ported: riding the
+ * project's own Vite would put a React app inside the game's build.
+ *
+ * Its jobs are few. Compile the project **with provenance** so the page can map a mesh back to
+ * the element that built it. Serve the model and the document text the inspector needs. Take a
+ * save and splice it into the source. Watch, rebuild, and tell the page.
  */
-async function refreshComponents(roots, cwd, packages) {
-    await loadComponents(roots, cwd, { packages }).catch(() => { });
-    const error = componentLoadError();
-    if (!error)
-        regenerateSchemas(cwd);
-    return error;
+export async function startEditorServer(options = {}) {
+    const root = resolve(options.root ?? process.cwd());
+    let model;
+    /** Compile the project. Provenance is always on here — that is what an editor is. */
+    const compile = (rescan) => {
+        if (rescan)
+            model = undefined;
+        const result = build({
+            root,
+            // No list means the project's own dependencies decide, which is what `build` does with
+            // an absent `modules` — the editor must accept exactly what `vite dev` accepts.
+            ...(options.modules ? { modules: options.modules } : {}),
+            provenance: true,
+            ...(model ? { model } : {}),
+        });
+        model = result.model;
+        if (result.diagnostics.length === 0)
+            return { ok: true };
+        return { ok: false, message: result.diagnostics.map((d) => formatDiagnostic(d)).join('\n') };
+    };
+    const first = compile(true);
+    if (!first.ok)
+        throw new Error(`[scenoco] this project does not compile yet:\n${first.message}`);
+    // The same port as last time whenever it is free: a tab the previous session left behind is
+    // retrying this exact URL every second, and reclaiming the port is what lets it come back
+    // instead of being stranded while a duplicate opens beside it.
+    let chosen = options.port !== undefined ? { port: options.port, reused: false } : await choosePort(root);
+    const serve = (port) => createServer({
+        root: appRoot,
+        configFile: false,
+        plugins: [react(), editorApi(root, () => model, compile)],
+        server: {
+            port,
+            // Listen on every interface, so the editor can be opened from a phone on the same
+            // network — which is the only way to try the touch controls on real fingers. It is a
+            // dev server on a local network, and `fs.allow` below still bounds what it will read.
+            host: true,
+            // Strict, so losing the race for the remembered port is an error we can fall back from
+            // rather than a silent move to port+1 that no stranded tab is watching.
+            strictPort: true,
+            // The page imports the project's generated modules by absolute path, so the project has
+            // to be readable. Nothing outside these two roots is.
+            fs: { allow: [appRoot, root] },
+        },
+        // One `three` across the editor and the project, or `instanceof` quietly fails across two
+        // copies and every raycast hit looks like nothing at all.
+        resolve: { dedupe: ['three'] },
+        optimizeDeps: { include: ['react', 'react-dom/client'] },
+    });
+    let vite = await serve(chosen.port);
+    try {
+        await vite.listen();
+    }
+    catch (error) {
+        // A caller that asked for a specific port meant it; anything else falls back to a fresh one
+        // (and, with it, a fresh tab — there is nothing waiting on a port we never had).
+        if (options.port !== undefined)
+            throw error;
+        await vite.close().catch(() => { });
+        chosen = { port: await freePort(), reused: false };
+        vite = await serve(chosen.port);
+        await vite.listen();
+    }
+    const port = vite.httpServer.address().port;
+    rememberPort(root, port);
+    const bridge = attachBridge(vite, options);
+    watchProject(vite, root, compile, bridge);
+    // Vite works out which interface is actually reachable; guessing from `os.networkInterfaces()`
+    // picks a VPN or a container bridge as often as the Wi-Fi.
+    const networkUrl = vite.resolvedUrls?.network[0]?.replace(/\/$/, '');
+    return {
+        url: `http://localhost:${port}`,
+        ...(networkUrl ? { networkUrl } : {}),
+        port,
+        reusedPort: chosen.reused,
+        bridge,
+        model: () => model,
+        async close() {
+            bridge.push({ push: 'shutdown' });
+            await vite.close();
+        },
+    };
 }
 /**
- * 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).
+ * The port to serve on: last session's if it is free, otherwise a fresh one.
+ *
+ * Sticky by default rather than on request, because the thing it fixes — a restart stacking up a
+ * second tab while the first sits there retrying — happens on every restart.
  */
-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 */
-        }
+async function choosePort(root) {
+    const remembered = readPort(root);
+    return remembered === undefined ? { port: await freePort(), reused: false } : { port: remembered, reused: true };
+}
+function portFile(root) {
+    return join(root, '.scenoco', 'editor-port');
+}
+/** The port the last session bound, if one was recorded. */
+function readPort(root) {
+    try {
+        const n = Number(readFileSync(portFile(root), 'utf8').trim());
+        return Number.isInteger(n) && n > 0 && n < 65536 ? n : undefined;
+    }
+    catch {
+        return undefined; // no file yet, or unreadable — take a fresh port
     }
 }
-function writeIfChanged(path, content) {
+/** Record the port just bound. Best-effort: sticky reuse is a convenience, not a requirement. */
+function rememberPort(root, port) {
     try {
-        if (existsSync(path) && readFileSync(path, 'utf8') === content)
-            return;
+        mkdirSync(dirname(portFile(root)), { recursive: true });
+        writeFileSync(portFile(root), String(port));
     }
     catch {
-        /* unreadable — fall through and overwrite */
+        /* couldn't write .scenoco/ — the next launch just takes a fresh port */
     }
-    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.
+ * The handful of endpoints the page needs beyond its own modules.
+ *
+ * Everything is scoped under `/@scenoco/`, and every path that names a file is checked to be
+ * inside the project — a dev server that will read any absolute path is a dev server that will
+ * read your SSH key.
  */
-export async function startEditorServer(opts = {}) {
-    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,
-        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];
+function editorApi(root, model, compile) {
+    const insideProject = (path) => {
+        const absolute = resolve(root, path);
+        const rel = relative(root, absolute);
+        return rel && !rel.startsWith('..') && !rel.startsWith(sep) ? absolute : null;
+    };
     return {
-        url,
-        ...(networkUrl ? { networkUrl } : {}),
-        bridge,
-        close: async () => {
-            await watcher.close();
-            await server.close();
+        name: 'scenoco:editor-api',
+        configureServer(server) {
+            server.middlewares.use('/@scenoco/documents', (_req, res) => {
+                // Every document in the project, for the file picker.
+                json(res, findAssets(root).map((a) => ({ kind: a.kind, path: a.relativePath, stem: a.stem })));
+            });
+            server.middlewares.use('/@scenoco/model', (_req, res) => {
+                // The inspector's whole schema: field names, types, defaults, doc comments, source
+                // links. Read from the project's TypeScript, so it cannot drift from the code.
+                const { components, systems, tags } = model();
+                json(res, { components, systems, tags });
+            });
+            server.middlewares.use('/@scenoco/document', (req, res) => {
+                const path = new URL(req.url ?? '', 'http://x').searchParams.get('path');
+                const absolute = path ? insideProject(path) : null;
+                if (!absolute || !existsSync(absolute))
+                    return fail(res, 404, 'no such document');
+                const text = readFileSync(absolute, 'utf8');
+                json(res, {
+                    path,
+                    // The generated module the page imports to build the live scene.
+                    module: `/@fs${absolute.replace(/\.xml$/, '.gen.ts')}`,
+                    text,
+                    // The element index, from the **compiler's own parser** — the one whose positions the
+                    // provenance stamps were written with. The page reimplementing this was the one thing
+                    // guaranteed to drift, and it did: a long or multi-line open tag came out at a
+                    // different column, so every node but the short ones failed to match its element.
+                    elements: indexDocument(text).map((e) => ({
+                        tag: e.tag,
+                        line: e.line,
+                        column: e.column,
+                        // The byte range, so the page can lift an element's source text for a copy.
+                        start: e.start,
+                        end: e.end,
+                        attributes: e.attributes,
+                    })),
+                });
+            });
+            server.middlewares.use('/@scenoco/save', (req, res) => {
+                if (req.method !== 'POST')
+                    return fail(res, 405, 'POST only');
+                readBody(req, (body) => {
+                    const { path, edits } = body;
+                    const absolute = path ? insideProject(path) : null;
+                    if (!absolute || !existsSync(absolute))
+                        return fail(res, 404, 'no such document');
+                    const applied = applyEdits(readFileSync(absolute, 'utf8'), edits ?? []);
+                    if (applied.problems.length > 0)
+                        return fail(res, 409, applied.problems.join('\n'));
+                    if (applied.text !== readFileSync(absolute, 'utf8'))
+                        writeFileSync(absolute, applied.text);
+                    // Compiled synchronously so a save that breaks the document says so *here*, with the
+                    // diagnostics, rather than as a blank scene a moment later.
+                    const built = compile(false);
+                    if (!built.ok)
+                        return fail(res, 422, built.message);
+                    // The fresh index comes back with the text: every position after a splice has moved,
+                    // and the page's pending edits address positions.
+                    json(res, {
+                        text: applied.text,
+                        elements: indexDocument(applied.text).map((e) => ({
+                            tag: e.tag,
+                            line: e.line,
+                            column: e.column,
+                            start: e.start,
+                            end: e.end,
+                            attributes: e.attributes,
+                        })),
+                    });
+                });
+            });
         },
     };
 }
 /**
- * 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.
+ * Apply a save.
+ *
+ * One at a time against the running text, because each edit's addresses are computed by the page
+ * from the document it is looking at — so a batch has to be built as a sequence of
+ * already-consistent steps, not as parallel edits into one snapshot.
  */
-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');
-        },
-    };
+export function applyEdits(source, edits) {
+    let text = source;
+    const problems = [];
+    for (const edit of edits) {
+        const result = edit.op === 'setAttribute'
+            ? setAttribute(text, edit.at, edit.name, edit.value)
+            : edit.op === 'removeElement'
+                ? removeElement(text, edit.at)
+                : edit.op === 'insertChild'
+                    ? insertChild(text, edit.at, edit.xml, edit.index)
+                    : moveElement(text, edit.at, edit.parent, edit.index);
+        if (result.problem)
+            problems.push(result.problem);
+        text = result.text;
+    }
+    return { text, problems };
 }
-/** `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,
-            // 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'))
-                    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) }));
-                });
-            });
-            // 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();
-                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: e instanceof Error ? e.message : String(e), componentError: compError?.message }));
-                    }
-                })();
-            });
-        },
+/** Rebuild when the project changes, and tell the page what happened. */
+function watchProject(vite, root, compile, bridge) {
+    // The directory, not a glob. chokidar dropped glob support in v4 — which Vite 8 ships — so
+    // `add('<root>/**/*.xml')` registered a literal path with asterisks in it, matched nothing,
+    // and silently watched nothing at all: editing a document in your own editor changed the file
+    // and the running editor never heard about it. What to care about is decided below anyway.
+    vite.watcher.add(root);
+    let queued;
+    let rescan = false;
+    const changed = (path) => {
+        const isDocument = path.endsWith('.xml');
+        const isSource = path.endsWith('.ts') && !path.endsWith('.gen.ts');
+        if (!isDocument && !isSource)
+            return;
+        if (!path.startsWith(root))
+            return;
+        // Watching the root means seeing installed packages and build output too; neither is
+        // something a person edits, and a rescan of either costs a full recompile.
+        if (path.includes(`${sep}node_modules${sep}`) || path.includes(`${sep}dist${sep}`))
+            return;
+        rescan ||= isSource;
+        clearTimeout(queued);
+        queued = setTimeout(() => {
+            const built = compile(rescan);
+            rescan = false;
+            bridge.push(built.ok
+                ? { push: 'documentChanged', file: relative(root, path) }
+                : { push: 'buildFailed', message: built.message });
+        }, 40);
     };
+    vite.watcher.on('change', changed);
+    vite.watcher.on('add', changed);
+    vite.watcher.on('unlink', changed);
 }
-/** WebSocket bridge: one editor page ↔ the MCP server, with id-correlated replies. */
-function attachBridge(server) {
+/** The WebSocket relay, plus the idle self-halt that keeps a closed tab from leaking a process. */
+function attachBridge(vite, options) {
+    const { bridge, register } = createBridgeCore(options);
     const wss = new WebSocketServer({ noServer: true });
-    let editor;
+    vite.httpServer.on('upgrade', (request, socket, head) => {
+        if (!request.url?.startsWith(WS_PATH))
+            return;
+        // Vite's own HMR upgrades use a different path and fall through to its handler.
+        wss.handleUpgrade(request, socket, head, (ws) => register(ws));
+    });
+    return bridge;
+}
+/**
+ * Command routing, failover and the idle self-halt, with no server attached.
+ *
+ * Separate from `attachBridge` because these are the rules worth pinning down — which tab a
+ * command goes to, what happens to a command when that tab closes, when the process gives up —
+ * and none of them need a port, a browser, or a compiled project to be true.
+ */
+export function createBridgeCore(options = {}) {
+    /** Every live page, in connect order — the last one is the tab in front of the user. */
+    const sockets = new Set();
     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))
+    const waiters = new Set();
+    let idle;
+    const armIdle = (after) => {
+        if (!options.onIdle)
             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);
+        clearTimeout(idle);
+        idle = setTimeout(() => {
+            if (sockets.size === 0)
+                options.onIdle?.();
+        }, after);
+    };
+    armIdle(options.initialGraceMs ?? 30_000);
+    /**
+     * The page a command goes to: the most recently connected one still open.
+     *
+     * Newest rather than oldest because that is the tab the person just opened. Opening a second
+     * editor tab and watching the first one answer every tool call is the whole bug.
+     */
+    const active = () => {
+        let latest;
+        for (const ws of sockets)
+            if (ws.readyState === ws.OPEN)
+                latest = ws;
+        return latest;
+    };
+    const register = (ws) => {
+        sockets.add(ws);
+        clearTimeout(idle);
+        for (const wake of [...waiters])
+            wake(); // a tab attached — release anyone waiting for one
+        ws.on('message', (data) => {
+            const response = JSON.parse(String(data));
+            const waiting = pending.get(response.id);
+            if (!waiting)
+                return;
+            clearTimeout(waiting.timer);
+            pending.delete(response.id);
+            waiting.resolve(response);
+        });
+        ws.on('close', () => {
+            sockets.delete(ws);
+            // Hand anything this tab still owed to another open one, so closing the tab a tool call
+            // happened to be routed to doesn't strand the call for its full timeout.
+            for (const [id, waiting] of pending) {
+                if (waiting.socket !== ws)
+                    continue;
+                const next = active();
+                if (next) {
+                    waiting.socket = next;
+                    next.send(JSON.stringify(waiting.command));
                 }
-                catch {
-                    /* ignore malformed */
+                else {
+                    clearTimeout(waiting.timer);
+                    pending.delete(id);
+                    waiting.reject(new Error('the editor tab closed before answering'));
                 }
-            });
-            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);
+            if (sockets.size === 0)
+                armIdle(options.idleMs ?? 5_000);
+        });
+    };
+    const bridge = {
+        connected: () => active() !== undefined,
+        push(message) {
+            const text = JSON.stringify(message);
+            for (const ws of sockets)
+                ws.send(text);
+        },
+        waitForConnection: (ms) => new Promise((done) => {
+            if (active())
+                return done(true);
+            const wake = () => {
+                waiters.delete(wake);
+                clearTimeout(timer);
+                done(true);
+            };
+            waiters.add(wake);
+            const timer = setTimeout(() => {
+                waiters.delete(wake);
+                done(false);
+            }, ms);
+            timer.unref(); // never hold the process open just to time this out
         }),
-        push: (msg) => {
-            if (editor && editor.readyState === editor.OPEN)
-                editor.send(JSON.stringify(msg));
+        send(command) {
+            const socket = active();
+            if (!socket)
+                return Promise.reject(new Error('no editor page is open'));
+            return new Promise((resolve, reject) => {
+                // A page that never answers must not hang the caller for ever — an agent waiting on a
+                // screenshot has no way to tell "slow" from "gone".
+                const timer = setTimeout(() => {
+                    pending.delete(command.id);
+                    reject(new Error(`the editor did not answer "${command.type}" within 30s`));
+                }, 30_000);
+                pending.set(command.id, { command, socket, timer, resolve, reject });
+                socket.send(JSON.stringify(command));
+            });
         },
     };
+    return { bridge, register };
 }
-/** 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);
-    });
+// --- plumbing --------------------------------------------------------------------------------
+function json(res, data) {
+    res.setHeader('Content-Type', 'application/json');
+    res.end(JSON.stringify(data));
 }
-/**
- * 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;
+function fail(res, code, message) {
+    res.statusCode = code;
+    json(res, { error: message });
+}
+function readBody(req, then) {
+    let raw = '';
+    req.on('data', (chunk) => (raw += chunk));
+    req.on('end', () => {
         try {
-            entries = readdirSync(dir, { withFileTypes: true });
+            then(JSON.parse(raw || '{}'));
         }
         catch {
-            return; // missing/unreadable root — nothing to list
+            then({});
         }
-        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) => {
+    return new Promise((done) => {
         const probe = createNetServer();
-        probe.on('error', rej);
         probe.listen(0, () => {
-            const port = probe.address().port;
-            probe.close(() => res(port));
+            const { port } = probe.address();
+            probe.close(() => done(port));
         });
     });
 }