@scenoco-three/editor 0.2.0

package/README.md

@@ -0,0 +1,101 @@
+# @scenoco-three/editor
+
+A local **visual editor + headless renderer** for [SceNoCo](https://github.com/) scenes and
+prefabs, with an **MCP server** so a (multimodal) LLM can open a scene, render frames, drive
+gameplay, and read back telemetry — the "eyes and hands" for an agent that authors scenes
+with `@scenoco-three/compiler`. Humans get a browser editor; agents get MCP tools, over **one
+shared live session**.
+
+```bash
+npm i -D @scenoco-three/editor
+```
+
+## CLI
+
+```
+scenoco-editor <scene|prefab> [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 a browser
+```
+
+```bash
+scenoco-editor scenes/level.scene.xml --components src --packages @scenoco-three/box2d
+#   editor:  http://localhost:PORT?file=…   ← opens in your browser
+#   mcp:     http://localhost:PORT/mcp      ← add to your MCP client (transport: http)
+```
+
+It serves the editor app through Vite + `@scenoco-three/vite` (so the open scene compiles
+exactly like production), bridges that browser session to an MCP server over a WebSocket, and
+watches the scene's source dependencies for **live reload** (with an unsaved-changes conflict
+prompt).
+
+## MCP tools
+
+| Tool | Args | Returns |
+| --- | --- | --- |
+| `open_file` | `path` | Opens a `.scene.xml` / `.prefab.xml` in edit mode. |
+| `get_preview` | `camera?`, `lookAt?`, `size?` | A **PNG** of the current view. |
+| `playback` | `state` | `play` / `pause` / `stop` — enter play mode (components, systems, physics) / freeze / return to the authored scene. |
+| `get_telemetry` | `id` | **JSON** of current property values for the node + components at a scene `id`. |
+| `simulate` | `commands: SimStep[]` | Ordered **images + JSON** — the workhorse below. |
+
+### `simulate` — closed-loop driving
+
+One call injects input, steps the sim, and captures — *see a game move, not a static scene*.
+Each command is `{ do, … }`:
+
+```ts
+type SimStep =
+  | { do: 'play' | 'pause' | 'stop' }
+  | { do: 'step'; frames?: number; dt?: number }
+  | { do: 'key'; code: string; action: 'down' | 'up' | 'tap' }
+  | { do: 'mouse'; x?: number; y?: number; dx?: number; dy?: number;
+      button?: 'left' | 'right' | 'middle'; action?: 'move' | 'down' | 'up' | 'click' }
+  | { do: 'gamepad'; index?: number; buttons?: boolean[]; axes?: number[] }
+  | { do: 'preview'; camera?: string; lookAt?: string }
+  | { do: 'telemetry'; id: string };
+```
+
+```jsonc
+// "press Space, advance 90 frames, read the ball, screenshot" — in one tool call
+[ { "do": "play" },
+  { "do": "key", "code": "Space", "action": "tap" },
+  { "do": "step", "frames": 90 },
+  { "do": "telemetry", "id": "ball" },
+  { "do": "preview" } ]
+```
+
+The result is a `multi` payload: each capture's image/JSON in step order.
+
+## Programmatic API
+
+```ts
+import { startEditorServer, startMcpServer } from '@scenoco-three/editor';
+
+const editor = await startEditorServer({ cwd, componentRoots: ['src'], packages: [] });
+const mcp = await startMcpServer(editor.bridge);   // editor.bridge.send(EditorCommand)
+console.log(editor.url, mcp.url);
+// … later
+await mcp.close(); await editor.close();
+```
+
+Also exported: `buildMcpServer`, the WebSocket `protocol` types (`EditorCommand`,
+`EditorResponse`, `EditorResult`, `WS_PATH`, `commandId`).
+
+## Standalone & dependencies
+
+Build-time / Node-side tool — **not** part of the browser runtime; nothing here ships to
+production. It depends on `@scenoco-three/compiler` and `@scenoco-three/vite` (compile +
+serve) and the MCP SDK; `@scenoco-three/core`, `three`, and `vite` are **peers** (the editor
+renders your scene with the same runtime your app uses). You can run it purely for the **human
+browser UI** without ever touching MCP, or wire **only** the MCP server to an agent — the two
+share one live session but neither requires the other.
+
+See the [repository](../../README.md), [ARCHITECTURE.md](../../ARCHITECTURE.md), and the
+[agentic guide](../../agentic/SCENOCO-AGENTIC-GUIDE.md).
+
+## License
+
+[MIT](./LICENSE)

package/app/cameraRig.ts

@@ -0,0 +1,57 @@
+import { Euler, Quaternion, Vector3, type PerspectiveCamera } from 'three';
+
+/**
+ * Owns the editor camera's orientation (yaw/pitch, roll-free) and exposes simple
+ * verbs that both the desktop (mouse/keyboard) and touch input adapters call, so
+ * the two never fight over the camera transform. Call `sync()` once per frame.
+ */
+export class CameraRig {
+  readonly euler = new Euler(0, 0, 0, 'YXZ');
+  /** Base movement speed (world units/sec), tuned by the wheel / scene size. */
+  speed: number;
+  /**
+   * Distance to the focus point (Unity scene-camera pivot). Touch pan/dolly scale
+   * by this, so motion stays consistent on screen at any zoom — fine near objects,
+   * fast when far. Set via `focusOn`; dolly shrinks/grows it.
+   */
+  focusDistance: number;
+
+  private readonly q = new Quaternion();
+  private readonly v = new Vector3();
+
+  constructor(
+    readonly camera: PerspectiveCamera,
+    target: Vector3,
+  ) {
+    camera.lookAt(target);
+    this.euler.setFromQuaternion(camera.quaternion);
+    this.speed = Math.max(1, camera.position.distanceTo(target) * 0.5);
+    this.focusDistance = Math.max(0.1, camera.position.distanceTo(target));
+  }
+
+  /** Re-pivot on a world point (e.g. the selected node) and reset the focus distance. */
+  focusOn(point: Vector3): void {
+    this.focusDistance = Math.max(0.1, this.camera.position.distanceTo(point));
+  }
+
+  /** Add yaw/pitch in radians (pitch clamped to avoid flipping). */
+  rotate(dYaw: number, dPitch: number): void {
+    this.euler.y += dYaw;
+    this.euler.x = clamp(this.euler.x + dPitch, -Math.PI / 2 + 0.01, Math.PI / 2 - 0.01);
+  }
+
+  /** Translate in camera-local space: +x right, +y up, +z forward. */
+  move(right: number, up: number, forward: number): void {
+    this.v.set(right, up, -forward).applyQuaternion(this.q.setFromEuler(this.euler));
+    this.camera.position.add(this.v);
+  }
+
+  /** Apply the orientation to the camera. Call once per frame, after input. */
+  sync(): void {
+    this.camera.quaternion.setFromEuler(this.euler);
+  }
+}
+
+function clamp(v: number, lo: number, hi: number): number {
+  return Math.max(lo, Math.min(hi, v));
+}

package/app/commands.ts

@@ -0,0 +1,74 @@
+/**
+ * The stateful edit primitive. Every mutation in the editor is a `Command` so it
+ * can be undone and (because each one also mutates the compiled scene) saved as a
+ * diff. Commands are deliberately tiny — `apply` redoes, `invert` undoes.
+ */
+export interface Command {
+  /** Human label (undo menu / debugging). */
+  readonly label: string;
+  apply(): void;
+  invert(): void;
+  /**
+   * Edits sharing a key, applied back-to-back, collapse into a single undo step.
+   * A gizmo drag or a numeric scrub emits one command per frame; undo should
+   * rewind the whole gesture, not each intermediate value.
+   */
+  readonly coalesceKey?: string;
+}
+
+/** Undo/redo history with same-key coalescing. `onChange` fires after every mutation. */
+export class UndoStack {
+  private readonly undoables: Command[] = [];
+  private readonly redoables: Command[] = [];
+
+  constructor(private readonly onChange?: () => void) {}
+
+  /** Apply a command and record it, merging into the previous one if keys match. */
+  run(cmd: Command): void {
+    cmd.apply();
+    const prev = this.undoables[this.undoables.length - 1];
+    if (cmd.coalesceKey !== undefined && prev?.coalesceKey === cmd.coalesceKey) {
+      // Adopt the latest `apply` (current value) but keep the earliest `invert`
+      // (the pre-gesture state), so one undo rewinds the entire gesture.
+      this.undoables[this.undoables.length - 1] = {
+        label: prev.label,
+        coalesceKey: prev.coalesceKey,
+        apply: cmd.apply,
+        invert: prev.invert,
+      };
+    } else {
+      this.undoables.push(cmd);
+    }
+    this.redoables.length = 0;
+    this.onChange?.();
+  }
+
+  undo(): void {
+    const cmd = this.undoables.pop();
+    if (!cmd) return;
+    cmd.invert();
+    this.redoables.push(cmd);
+    this.onChange?.();
+  }
+
+  redo(): void {
+    const cmd = this.redoables.pop();
+    if (!cmd) return;
+    cmd.apply();
+    this.undoables.push(cmd);
+    this.onChange?.();
+  }
+
+  get canUndo(): boolean {
+    return this.undoables.length > 0;
+  }
+  get canRedo(): boolean {
+    return this.redoables.length > 0;
+  }
+
+  clear(): void {
+    this.undoables.length = 0;
+    this.redoables.length = 0;
+    this.onChange?.();
+  }
+}

package/app/desktopControls.ts

@@ -0,0 +1,44 @@
+import type { InputManager } from '@scenoco-three/core';
+import type { CameraRig } from './cameraRig.js';
+
+/**
+ * Desktop fly navigation via `engine.input` (Unity scene-view style):
+ *   • hold RIGHT mouse to look · WASD move · Q/E down/up · Shift faster · wheel speed.
+ */
+export class DesktopControls {
+  private readonly look = 0.0025; // radians per pixel
+
+  constructor(
+    private readonly rig: CameraRig,
+    private readonly input: InputManager,
+  ) {}
+
+  /** Advance one frame (call after `engine.tick`). */
+  update(dt: number): void {
+    const { input, rig } = this;
+
+    const wheel = input.mouseScrollDelta.y;
+    if (wheel !== 0) rig.speed = clamp(rig.speed * (wheel < 0 ? 1.1 : 1 / 1.1), 0.05, 1000);
+
+    if (input.getMouseButton(1)) {
+      const d = input.mouseDelta;
+      rig.rotate(-d.x * this.look, -d.y * this.look);
+    }
+
+    const right = axis(input.getKey('D'), input.getKey('A'));
+    const up = axis(input.getKey('E'), input.getKey('Q'));
+    const forward = axis(input.getKey('W'), input.getKey('S'));
+    if (right || up || forward) {
+      const len = Math.hypot(right, up, forward);
+      const step = (rig.speed * (input.getKey('LeftShift') ? 4 : 1) * dt) / len;
+      rig.move(right * step, up * step, forward * step);
+    }
+  }
+}
+
+function axis(pos: boolean, neg: boolean): number {
+  return (pos ? 1 : 0) - (neg ? 1 : 0);
+}
+function clamp(v: number, lo: number, hi: number): number {
+  return Math.max(lo, Math.min(hi, v));
+}