@scenoco-three/editor 0.2.0

package/dist/cli/index.js

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

package/dist/index.d.ts

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

package/dist/protocol.js

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