@scenoco-three/editor 0.3.0 → 0.3.2

package/app/document.ts

@@ -12,7 +12,7 @@ import {
   type SceneGraph,
 } from '@scenoco-three/core';
 import type { NodeOrigin, SceneProvenance } from '@scenoco-three/compiler';
-import type { EditOp, EditTarget } from '../src/protocol.js';
+import type { EditOp, EditTarget } from '../dist/protocol.js';
 import { UndoStack } from './commands.js';
 
 export type TransformChannel = 'position' | 'rotation' | 'scale';

package/app/session.ts

@@ -3,7 +3,7 @@ import {
 } from 'three';
 import { Engine, Registry, bundleKind, type Bundle, type Component } from '@scenoco-three/core';
 import type { SceneProvenance } from '@scenoco-three/compiler';
-import type { EditOp, EditorResult, SimStep } from '../src/protocol.js';
+import type { EditOp, EditorResult, SimStep } from '../dist/protocol.js';
 
 export type EditorMode = 'edit' | 'play';
 

package/app/wsClient.ts

@@ -1,4 +1,4 @@
-import { WS_PATH, type EditorCommand, type EditorPush, type EditorResponse, type EditorResult } from '../src/protocol.js';
+import { WS_PATH, type EditorCommand, type EditorPush, type EditorResponse, type EditorResult } from '../dist/protocol.js';
 import type { EditorSession } from './session.js';
 
 /**

package/dist/args.d.ts

@@ -0,0 +1,8 @@
+/** 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

@@ -0,0 +1,28 @@
+// 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

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

package/dist/cli/index.js

@@ -0,0 +1,99 @@
+#!/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] [--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:
+  --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 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 === '-h' || file === '--help') {
+        console.log(USAGE);
+        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,
+        ...(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) } : {}),
+    });
+    // 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}${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());
+        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

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,6 @@
+// `@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

@@ -0,0 +1,16 @@
+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

@@ -0,0 +1,150 @@
+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

@@ -0,0 +1,161 @@
+/** 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).
+ *
+ * - `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 type EditorPush = {
+    push: 'fileChanged';
+    file: string;
+    role: 'open' | 'dep';
+} | {
+    push: 'shutdown';
+};
+/** 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

@@ -0,0 +1,9 @@
+// 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

@@ -0,0 +1,57 @@
+import { type EditorCommand, type EditorPush, type EditorResponse } from './protocol.js';
+export interface ServerOptions {
+    /** Directories scanned for `@component`/`@node` tags (default `['assets']`). */
+    componentRoots?: string[];
+    /** Tag packages to register (default: the `@scenoco-three/*` deps in package.json). */
+    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>;
+/** 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

@@ -0,0 +1,374 @@
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createServer as createNetServer } from 'node:net';
+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, 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. */
+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 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];
+    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,
+            // 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 }));
+                    }
+                })();
+            });
+        },
+    };
+}
+/** 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);
+    });
+}
+/**
+ * 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) => {
+        const probe = createNetServer();
+        probe.on('error', rej);
+        probe.listen(0, () => {
+            const port = probe.address().port;
+            probe.close(() => res(port));
+        });
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scenoco-three/editor",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Local preview + headless frame render for SceNoCo scenes/prefabs (for multimodal LLMs)",
   "type": "module",
   "license": "MIT",
@@ -33,7 +33,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "typecheck": "npm --prefix ../core run build && npm --prefix ../compiler run build && npm --prefix ../vite run build && tsc --noEmit -p tsconfig.json"
+    "typecheck": "npm --prefix ../core run build && npm --prefix ../compiler run build && npm --prefix ../vite run build && npm run build && tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",