@scenoco-three/editor 0.3.2 → 0.5.0

package/dist/protocol.d.ts

@@ -1,6 +1,40 @@
-/** WebSocket path the editor connects to on the dev server. */
+/**
+ * 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";
-/** A command sent MCP-server → editor (id-correlated with its response). */
+/**
+ * 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';
@@ -8,9 +42,9 @@ export type EditorCommand = {
 } | {
     id: string;
     type: 'preview';
-    camera?: string;
+    camera: string;
     lookAt?: string;
-    size?: string;
+    frame: PreviewFrame;
 } | {
     id: string;
     type: 'run';
@@ -28,24 +62,30 @@ export type EditorCommand = {
     id: string;
     type: 'simulate';
     steps: SimStep[];
+    frame: PreviewFrame;
 };
 /**
- * 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.
+ * 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 the simulation by `frames` ticks (default 1) of `dt` seconds (default 1/60). */
+/** Advance 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. */
+/**
+ * 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: 'tap';
+    do: 'press';
     key: string;
 } | {
     do: 'keyDown';
@@ -54,7 +94,7 @@ export type SimStep = {
     do: 'keyUp';
     key: string;
 }
-/** Mouse — `x,y` canvas-relative px (top-left). `click` = down+up; button defaults to left. */
+/** Mouse. `x,y` are canvas-relative pixels from the top left; `click` is down plus up. */
  | {
     do: 'click';
     x?: number;
@@ -67,21 +107,22 @@ export type SimStep = {
     dx?: number;
     dy?: number;
 }
-/** Gamepad: synthetic pad `index` (default 0) with pressed `buttons` + `axes`. */
+/**
+ * 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: 'gamepad';
-    index?: number;
-    buttons?: boolean[];
-    axes?: number[];
-} | {
     do: 'preview';
-    camera?: string;
+    camera: string;
     lookAt?: string;
-} | {
+}
+/** Sample state at an `id` the document declares — a node and its components. */
+ | {
     do: 'telemetry';
     id: string;
 };
-/** The editor's reply, keyed by the command id. */
+/** The page's reply, keyed by the command id. */
 export type EditorResponse = {
     id: string;
     ok: true;
@@ -92,17 +133,20 @@ export type EditorResponse = {
     error: string;
 };
 /**
- * An unsolicited server→editor notification (not id-correlated).
+ * An unsolicited Node → page notification.
  *
- * - `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.
+ * - `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: 'fileChanged';
+    push: 'documentChanged';
     file: string;
-    role: 'open' | 'dep';
+} | {
+    push: 'buildFailed';
+    message: string;
 } | {
     push: 'shutdown';
 };
@@ -116,46 +160,11 @@ export type EditorResult = {
 } | {
     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;
-/**
- * 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

@@ -1,7 +1,20 @@
-// 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. */
+/**
+ * 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() {

package/dist/server.d.ts

@@ -1,57 +1,124 @@
+import { type ElementAt, type ProjectModel } from '@scenoco-three/compiler';
 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). */
+    /** 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;
-    /** Base directory `componentRoots` are resolved against (default: `process.cwd()`). */
-    cwd?: string;
+    /**
+     * 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 MCP tool commands to the connected editor page and awaits its reply. */
+/** Relays a command 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>;
+    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 {
-    /** Local URL the editor app is served at. */
     url: string;
-    /** LAN URL (open on another device on the same network). */
+    /**
+     * 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>;
 }
 /**
- * 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 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 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';
+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;
 }
 /**
- * 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.
+ * 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 listSceneFiles(roots: string[], cwd: string): SceneFile[];
+export declare function createBridgeCore(options?: BridgeOptions): {
+    bridge: EditorBridge;
+    register: (ws: BridgeSocket) => void;
+};