@scenoco-three/editor 0.5.4 → 0.7.0

package/dist/mcp.d.ts

@@ -1,32 +0,0 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { EditorBridge } from './server.js';
-/**
- * The MCP surface: **eyes, not hands.**
- *
- * Open a document, render it, drive it, read what happened. There is no tool here that writes to
- * the user's source, and that is a decision rather than an omission. An agent already has file
- * tools, and the editor's watcher rebuilds whatever it writes — so an edit tool would have been
- * a second write path into someone's project that never passed through their editor, their diff
- * or their undo. An agent holding one can reshape a scene while believing it is only looking at
- * it.
- *
- * v1 shipped `patch`, `structural` and `save` tools alongside these. They are deleted.
- *
- * The one thing worth insisting on: `simulate` exists because a screenshot of frame zero says
- * almost nothing about whether a game works. Drive it to the interesting moment, *then* look.
- */
-export declare function createMcpServer(bridge: EditorBridge, editorUrl: () => string): McpServer;
-/**
- * Serve the MCP over HTTP on a fixed port.
- *
- * Fixed on purpose: an MCP client is configured once with a URL, and a port that moved on every
- * restart would need reconfiguring every time.
- *
- * **One transport per session**, created when a client initializes and kept until it goes away.
- * A single shared transport looked simpler and allowed exactly one client ever: the first
- * `initialize` claimed it, and every later one — a reconnect, a second client, a restarted
- * agent — got a bare `400`, which reads like a crashed server rather than a design limit.
- */
-export declare function startMcpHttp(makeServer: () => McpServer, port: number): Promise<{
-    close(): Promise<void>;
-}>;

package/dist/mcp.js

@@ -1,191 +0,0 @@
-import { randomUUID } from 'node:crypto';
-import { createServer as createHttpServer } from 'node:http';
-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';
-/**
- * The MCP surface: **eyes, not hands.**
- *
- * Open a document, render it, drive it, read what happened. There is no tool here that writes to
- * the user's source, and that is a decision rather than an omission. An agent already has file
- * tools, and the editor's watcher rebuilds whatever it writes — so an edit tool would have been
- * a second write path into someone's project that never passed through their editor, their diff
- * or their undo. An agent holding one can reshape a scene while believing it is only looking at
- * it.
- *
- * v1 shipped `patch`, `structural` and `save` tools alongside these. They are deleted.
- *
- * The one thing worth insisting on: `simulate` exists because a screenshot of frame zero says
- * almost nothing about whether a game works. Drive it to the interesting moment, *then* look.
- */
-export function createMcpServer(bridge, editorUrl) {
-    const mcp = new McpServer({ name: 'scenoco-editor', version: '2.0.0' });
-    /** Every tool needs a live page; saying so plainly beats a timeout. */
-    const send = async (command) => {
-        if (!bridge.connected()) {
-            throw new Error(`no editor page is open — visit ${editorUrl()} first, then retry`);
-        }
-        const response = await bridge.send(command);
-        if (!response.ok)
-            throw new Error(response.error);
-        return response.result;
-    };
-    const frameSchema = {
-        width: z.number().int().positive().describe('Captured image width in pixels'),
-        height: z.number().int().positive().describe('Captured image height in pixels'),
-        ui: z
-            .boolean()
-            .describe('Include the screen-space UI layer, framing the shot through the camera that hosts it'),
-    };
-    const POINT = '"y: 6; z: 12" — the document\'s own vector grammar; an omitted axis is 0';
-    mcp.registerTool('open', {
-        description: 'Open a scene or prefab document in the editor page.',
-        inputSchema: { path: z.string().describe('Project-relative path, e.g. assets/scenes/main.scene.xml') },
-    }, async ({ path }) => text(await send({ id: commandId(), type: 'open', path })));
-    mcp.registerTool('screenshot', {
-        description: 'Render one PNG of the open scene from a given viewpoint. Does not move the editor camera.',
-        inputSchema: {
-            camera: z.string().describe(`Where to look from: ${POINT}, or "fit" to frame the whole scene`),
-            lookAt: z.string().optional().describe(`What to look at: ${POINT}. Defaults to the origin`),
-            ...frameSchema,
-        },
-    }, async ({ camera, lookAt, width, height, ui }) => image(await send({
-        id: commandId(),
-        type: 'preview',
-        camera,
-        ...(lookAt ? { lookAt } : {}),
-        frame: { width, height, ui },
-    })));
-    mcp.registerTool('telemetry', {
-        description: 'Read the live state at an id the document declares — transform, visibility, and each component’s public values.',
-        inputSchema: { id: z.string().describe('An id= from the open document') },
-    }, async ({ id }) => text(await send({ id: commandId(), type: 'telemetry', targetId: id })));
-    for (const [name, type] of [
-        ['play', 'run'],
-        ['pause', 'pause'],
-        ['stop', 'stop'],
-    ]) {
-        mcp.registerTool(name, { description: `${name[0].toUpperCase()}${name.slice(1)} the open scene.`, inputSchema: {} }, async () => text(await send({ id: commandId(), type })));
-    }
-    mcp.registerTool('simulate', {
-        description: 'Run a batch of steps against the live scene and collect what each produced. This is how ' +
-            'to find out whether a game works: drive it to the moment that matters, then capture. ' +
-            'Steps run in order.',
-        inputSchema: {
-            steps: z
-                .array(z.record(z.string(), z.unknown()))
-                .describe('Ordered steps. {"do":"play"} · {"do":"step","frames":30,"dt":0.0167} · ' +
-                '{"do":"press","key":"Space"} (a KeyCode member name) · {"do":"keyDown"/"keyUp","key":…} · ' +
-                '{"do":"click","x":100,"y":80} · {"do":"move","x":…,"y":…} · ' +
-                `{"do":"preview","camera":${JSON.stringify(POINT)}} · {"do":"telemetry","id":"ball"}`),
-            ...frameSchema,
-        },
-    }, async ({ steps, width, height, ui }) => {
-        const result = await send({
-            id: commandId(),
-            type: 'simulate',
-            steps: steps,
-            frame: { width, height, ui },
-        });
-        if (result.kind !== 'multi')
-            return text(result);
-        // Images and readings interleaved in the order they were captured, so a caller can line a
-        // frame up with the numbers that went with it.
-        return {
-            content: result.results.map((one) => one.kind === 'image'
-                ? { type: 'image', data: one.dataUrl.split(',')[1] ?? '', mimeType: 'image/png' }
-                : { type: 'text', text: JSON.stringify(one.kind === 'json' ? one.data : one, null, 2) }),
-        };
-    });
-    return mcp;
-}
-function text(result) {
-    const body = result.kind === 'json'
-        ? JSON.stringify(result.data, null, 2)
-        : result.kind === 'ok'
-            ? (result.info ?? 'ok')
-            : JSON.stringify(result);
-    return { content: [{ type: 'text', text: body }] };
-}
-function image(result) {
-    if (result.kind !== 'image')
-        throw new Error('the editor did not return an image');
-    return {
-        content: [{ type: 'image', data: result.dataUrl.split(',')[1] ?? '', mimeType: 'image/png' }],
-    };
-}
-/**
- * Serve the MCP over HTTP on a fixed port.
- *
- * Fixed on purpose: an MCP client is configured once with a URL, and a port that moved on every
- * restart would need reconfiguring every time.
- *
- * **One transport per session**, created when a client initializes and kept until it goes away.
- * A single shared transport looked simpler and allowed exactly one client ever: the first
- * `initialize` claimed it, and every later one — a reconnect, a second client, a restarted
- * agent — got a bare `400`, which reads like a crashed server rather than a design limit.
- */
-export async function startMcpHttp(makeServer, port) {
-    const sessions = new Map();
-    const http = createHttpServer((req, res) => {
-        void handle(req, res).catch((error) => {
-            res.statusCode = 500;
-            res.end(String(error instanceof Error ? error.message : error));
-        });
-    });
-    async function handle(req, res) {
-        const id = req.headers['mcp-session-id'];
-        const existing = typeof id === 'string' ? sessions.get(id) : undefined;
-        if (existing)
-            return existing.handleRequest(req, res, await body(req));
-        const parsed = await body(req);
-        if (!isInitialize(parsed)) {
-            res.statusCode = 400;
-            res.setHeader('Content-Type', 'application/json');
-            res.end(JSON.stringify({
-                jsonrpc: '2.0',
-                id: null,
-                error: { code: -32000, message: 'unknown session — send `initialize` first' },
-            }));
-            return;
-        }
-        const transport = new StreamableHTTPServerTransport({
-            sessionIdGenerator: () => randomUUID(),
-            onsessioninitialized: (session) => {
-                sessions.set(session, transport);
-            },
-        });
-        transport.onclose = () => {
-            if (transport.sessionId)
-                sessions.delete(transport.sessionId);
-        };
-        await makeServer().connect(transport);
-        return transport.handleRequest(req, res, parsed);
-    }
-    await new Promise((done) => http.listen(port, done));
-    return {
-        close: async () => {
-            for (const transport of sessions.values())
-                await transport.close().catch(() => { });
-            sessions.clear();
-            await new Promise((done) => http.close(() => done()));
-        },
-    };
-}
-function isInitialize(parsed) {
-    return typeof parsed === 'object' && parsed !== null && parsed.method === 'initialize';
-}
-/** The request body, read once — the transport is handed the parsed value rather than the stream. */
-async function body(req) {
-    const chunks = [];
-    for await (const chunk of req)
-        chunks.push(chunk);
-    const raw = Buffer.concat(chunks).toString('utf8');
-    try {
-        return raw ? JSON.parse(raw) : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}

package/dist/protocol.d.ts

@@ -1,170 +0,0 @@
-/**
- * The contract between the Node side and the editor page.
- *
- * Pure types plus one correlation helper, so both ends agree and the relay is testable on its
- * own. Nothing here reaches the compiler: the browser holds no compiler in v2 either.
- *
- * ### What is deliberately absent
- *
- * v1 carried an editing half — `EditTarget`, `EditOp`, `StructuralOp`, and `CompiledScene`
- * fragments travelling over the wire so a remote caller could reshape a document. All of it is
- * gone. An agent has file tools and the watcher rebuilds either way, so a second write path into
- * the user's source bought nothing and cost the guarantee that every change to their scene went
- * through their editor, their diff and their undo.
- *
- * What remains is observation: open, render, drive, sample.
- */
-/** WebSocket path the editor page connects to. */
-export declare const WS_PATH = "/scenoco-ws";
-/**
- * How a capture is rendered — everything except *where the camera is*.
- *
- * Framing belongs to the individual shot and changes between them; this is the output format,
- * and it is the same for every capture in one command. So it sits on the command rather than on
- * each step: one simulation renders one way throughout, and two shots of the same run stay
- * comparable because nothing but the camera moved between them.
- */
-export interface PreviewFrame {
-    width: number;
-    height: number;
-    /**
-     * Include the screen-space UI layer — a `<Canvas>` HUD and anything else parented to a camera.
-     * The shot is then framed *through* that camera, which is what puts the HUD where the player
-     * sees it rather than floating in world space in front of a camera nobody is looking through.
-     */
-    ui: boolean;
-}
-/** A command sent Node → editor page, correlated with its reply by `id`. */
-export type EditorCommand = {
-    id: string;
-    type: 'open';
-    path: string;
-} | {
-    id: string;
-    type: 'preview';
-    camera: string;
-    lookAt?: string;
-    frame: PreviewFrame;
-} | {
-    id: string;
-    type: 'run';
-} | {
-    id: string;
-    type: 'pause';
-} | {
-    id: string;
-    type: 'stop';
-} | {
-    id: string;
-    type: 'telemetry';
-    targetId: string;
-} | {
-    id: string;
-    type: 'simulate';
-    steps: SimStep[];
-    frame: PreviewFrame;
-};
-/**
- * One step in a `simulate` batch — transport, frame stepping, synthetic input, or a capture.
- *
- * Run in order against the live engine, so a caller can drive the game to a precise condition
- * and sample it there. This is the whole reason the editor is worth having for an agent: a
- * screenshot of frame zero says almost nothing about whether a game works.
- */
-export type SimStep = {
-    do: 'play' | 'pause' | 'stop';
-}
-/** Advance by `frames` ticks (default 1) of `dt` seconds (default 1/60). */
- | {
-    do: 'step';
-    frames?: number;
-    dt?: number;
-}
-/**
- * Keyboard. `key` is a `KeyCode` member name — `Space`, `W`, `LeftArrow`; an unknown one fails
- * the batch with the valid list rather than doing nothing. Each action is its own verb.
- */
- | {
-    do: 'press';
-    key: string;
-} | {
-    do: 'keyDown';
-    key: string;
-} | {
-    do: 'keyUp';
-    key: string;
-}
-/** Mouse. `x,y` are canvas-relative pixels from the top left; `click` is down plus up. */
- | {
-    do: 'click';
-    x?: number;
-    y?: number;
-    button?: 'left' | 'right' | 'middle';
-} | {
-    do: 'move';
-    x?: number;
-    y?: number;
-    dx?: number;
-    dy?: number;
-}
-/**
- * Capture a PNG. `camera` is a position in the document's own vector grammar
- * (`"y: 6; z: 12"`), or `"fit"` to frame the whole scene. Size and UI come from the batch's
- * `frame` — see {@link PreviewFrame} for why they are not repeated per step.
- */
- | {
-    do: 'preview';
-    camera: string;
-    lookAt?: string;
-}
-/** Sample state at an `id` the document declares — a node and its components. */
- | {
-    do: 'telemetry';
-    id: string;
-};
-/** The page's reply, keyed by the command id. */
-export type EditorResponse = {
-    id: string;
-    ok: true;
-    result: EditorResult;
-} | {
-    id: string;
-    ok: false;
-    error: string;
-};
-/**
- * An unsolicited Node → page notification.
- *
- * - `documentChanged` — the open document, or something it references, changed on disk. The page
- *   reloads the scene.
- * - `buildFailed` — a document no longer compiles. The page shows the diagnostics rather than
- *   reloading into a broken scene.
- * - `shutdown` — the server is stopping, so the page closes itself instead of being left stale.
- */
-export type EditorPush = {
-    push: 'documentChanged';
-    file: string;
-} | {
-    push: 'buildFailed';
-    message: string;
-} | {
-    push: 'shutdown';
-};
-/** Result payloads, discriminated by `kind`. */
-export type EditorResult = {
-    kind: 'ok';
-    info?: string;
-} | {
-    kind: 'image';
-    dataUrl: string;
-} | {
-    kind: 'json';
-    data: unknown;
-}
-/** `simulate` — one entry per capturing step, in order. */
- | {
-    kind: 'multi';
-    results: EditorResult[];
-};
-/** Random correlation id for a command. */
-export declare function commandId(): string;

package/dist/protocol.js

@@ -1,22 +0,0 @@
-/**
- * The contract between the Node side and the editor page.
- *
- * Pure types plus one correlation helper, so both ends agree and the relay is testable on its
- * own. Nothing here reaches the compiler: the browser holds no compiler in v2 either.
- *
- * ### What is deliberately absent
- *
- * v1 carried an editing half — `EditTarget`, `EditOp`, `StructuralOp`, and `CompiledScene`
- * fragments travelling over the wire so a remote caller could reshape a document. All of it is
- * gone. An agent has file tools and the watcher rebuilds either way, so a second write path into
- * the user's source bought nothing and cost the guarantee that every change to their scene went
- * through their editor, their diff and their undo.
- *
- * What remains is observation: open, render, drive, sample.
- */
-/** WebSocket path the editor page connects to. */
-export const WS_PATH = '/scenoco-ws';
-/** Random correlation id for a command. */
-export function commandId() {
-    return Math.random().toString(36).slice(2, 10);
-}

package/dist/server.d.ts

@@ -1,124 +0,0 @@
-import { type ElementAt, type ProjectModel } from '@scenoco-three/compiler';
-import { type EditorCommand, type EditorPush, type EditorResponse } from './protocol.js';
-export interface ServerOptions {
-    /** Project root — the directory holding `tsconfig.json` and `assets/`. Defaults to cwd. */
-    root?: string;
-    /** Packages whose tags the documents may use, beyond `three`. */
-    modules?: readonly string[];
-    /** Fixed port. Defaults to a free one the OS picks. */
-    port?: number;
-    /**
-     * Called when no editor page has been connected for a while — none ever connected within
-     * `initialGraceMs`, or the last one disconnected and none came back within `idleMs`.
-     *
-     * Opt-in, so an embedder or a test stays long-lived. The CLI wires it to a graceful shutdown,
-     * which is what keeps a closed tab from leaving an editor process running for the rest of the
-     * day.
-     */
-    onIdle?: () => void;
-    idleMs?: number;
-    initialGraceMs?: number;
-}
-/** Relays a command to the connected editor page and awaits its reply. */
-export interface EditorBridge {
-    connected(): boolean;
-    send(command: EditorCommand): Promise<EditorResponse>;
-    push(message: EditorPush): void;
-    /**
-     * Resolve as soon as an editor page is connected, or `false` after `ms`.
-     *
-     * The CLI waits on this after reclaiming the previous session's port: a tab stranded by an
-     * ungraceful exit is still retrying its socket every second, so giving it a moment to come
-     * back is the difference between reusing the tab and stacking up a new one.
-     */
-    waitForConnection(ms: number): Promise<boolean>;
-}
-export interface EditorServer {
-    url: string;
-    /**
-     * The same editor, reachable from another device on the network — a phone, for testing touch.
-     *
-     * Absent when the host has no LAN interface to offer.
-     */
-    networkUrl?: string;
-    port: number;
-    /**
-     * True when this server bound the **previous** session's port rather than a fresh one, so any
-     * tab left over from that session is about to reattach on its own retry loop.
-     */
-    reusedPort: boolean;
-    bridge: EditorBridge;
-    /** What the project's TypeScript declares — the inspector's schema. */
-    model(): ProjectModel;
-    close(): Promise<void>;
-}
-/**
- * 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.
- */
-export declare function startEditorServer(options?: ServerOptions): Promise<EditorServer>;
-/** One change to a document, addressed the way provenance addresses everything. */
-export type Edit = {
-    op: 'setAttribute';
-    at: ElementAt;
-    name: string;
-    value: string | null;
-} | {
-    op: 'removeElement';
-    at: ElementAt;
-} | {
-    op: 'insertChild';
-    at: ElementAt;
-    xml: string;
-    index?: number;
-} | {
-    op: 'moveElement';
-    at: ElementAt;
-    parent: ElementAt;
-    index?: number;
-};
-/**
- * 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.
- */
-export declare function applyEdits(source: string, edits: readonly Edit[]): {
-    text: string;
-    problems: string[];
-};
-/**
- * The half of an editor socket this file uses — `ws`'s `WebSocket`, and anything a test can fake.
- */
-export interface BridgeSocket {
-    readonly readyState: number;
-    readonly OPEN: number;
-    send(data: string): void;
-    on(event: 'message', listener: (data: unknown) => void): void;
-    on(event: 'close', listener: () => void): void;
-}
-/** How the bridge decides the process has nothing left to serve. */
-export interface BridgeOptions {
-    onIdle?: () => void;
-    idleMs?: number;
-    initialGraceMs?: number;
-}
-/**
- * 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 declare function createBridgeCore(options?: BridgeOptions): {
-    bridge: EditorBridge;
-    register: (ws: BridgeSocket) => void;
-};