@scenoco-three/editor 0.4.0 → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SceNoCo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,10 +1,10 @@
 # @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**.
+A local **visual editor** 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 and agents share the **same live browser tab**: the MCP
+tools drive it over a WebSocket bridge, there's no separate headless render path.
 
 ```bash
 npm i -D @scenoco-three/editor
@@ -19,7 +19,6 @@ scenoco-editor [scene|prefab] [options]     Omit the file to choose from a start
                         dependency in the project's package.json)
   --port <n>            Fixed MCP port — pin it so your MCP client survives restarts
                         (the HTTP editor server always takes a free port and prints its URL)
-  --no-open             Don't auto-open a browser
 ```
 
 ```bash
@@ -39,10 +38,16 @@ prompt).
 | 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. |
+| `screenshot` | `camera`, `lookAt?`, `width`, `height`, `fit`, `ui` | A **PNG** of the current view, at exactly the size and camera fit you state, with or without the HUD. |
 | `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. |
+| `inspect` | `id` | **JSON** of current property values at a scene `id` — a **node** (its transform + every component on it) or a **component** (its authored field values + its host node's transform). Nodes and components share one id namespace. |
+
+Values read back in the same vocabulary the scene XML is written in: vectors are
+named by axis (`{"x": 0, "y": 1.5, "z": 0}`), eulers are **degrees**, colours are
+`"#rrggbb"`, and a reference is `"#id"`. Points you pass *in* (`camera`, `lookAt`)
+take the DSL's own vector grammar — `"y: 6; z: 12"`, an omitted axis being 0, with
+the positional `"0 6 12"` still accepted.
+| `simulate` | `commands: SimStep[]` + the same `width`/`height`/`fit`/`ui` | Ordered **images + JSON** — the workhorse below. The capture format is stated once for the batch, not per shot. |
 
 ### `simulate` — closed-loop driving
 
@@ -53,23 +58,24 @@ Each command is a self-contained verb `{ do, … }`:
 type SimStep =
   | { do: 'play' | 'pause' | 'stop' }
   | { do: 'step'; frames?: number; dt?: number }            // advance `frames` ticks (default 1)
-  | { do: 'tap'; key: string }                               // key press + release
+  | { do: 'press'; key: string }                              // key press + release
   | { do: 'keyDown'; key: string }
   | { do: 'keyUp'; key: string }
   | { do: 'click'; x?: number; y?: number; button?: 'left' | 'right' | 'middle' }
   | { do: 'move'; x?: number; y?: number; dx?: number; dy?: number }
   | { do: 'gamepad'; index?: number; buttons?: boolean[]; axes?: number[] }
-  | { do: 'preview'; camera?: string; lookAt?: string }
+  | { do: 'preview'; camera: string; lookAt?: string }       // size/fit/ui come from the call
   | { do: 'telemetry'; id: string };
 ```
 
 ```jsonc
 // "press Space, advance 90 frames, read the ball, screenshot" — in one tool call
-[ { "do": "play" },
-  { "do": "tap", "key": "Space" },
-  { "do": "step", "frames": 90 },
-  { "do": "telemetry", "id": "ball" },
-  { "do": "preview" } ]
+{ "width": 960, "height": 540, "fit": "contain", "ui": true,
+  "commands": [ { "do": "play" },
+                { "do": "press", "key": "Space" },
+                { "do": "step", "frames": 90 },
+                { "do": "telemetry", "id": "ball" },
+                { "do": "preview", "camera": "fit" } ] }
 ```
 
 The result is a `multi` payload: each capture's image/JSON in step order.
@@ -99,7 +105,7 @@ browser UI** without ever touching MCP, or wire **only** the MCP server to an ag
 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).
+[measurements](../../bench/README.md).
 
 ## License
 

package/app/cameraRig.ts

@@ -12,46 +12,107 @@ export class CameraRig {
   /**
    * 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.
+   * fast when far. Set by `frameOn`; dolly shrinks/grows it.
    */
   focusDistance: number;
 
   private readonly q = new Quaternion();
   private readonly v = new Vector3();
 
-  constructor(
-    readonly camera: PerspectiveCamera,
-    target: Vector3,
-  ) {
+  /** Where a focus glide is taking the camera, while one is running. */
+  private glideTo: Vector3 | null = null;
+
+  readonly camera: PerspectiveCamera;
+
+  constructor(camera: PerspectiveCamera, target: Vector3) {
+    this.camera = camera;
     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));
+  /**
+   * Frame a point: keep looking exactly the way you are, and move until it is centred
+   * `distance` away.
+   *
+   * This is Unity's F, and the angle is the whole of it. Turning to face the selection instead
+   * throws away the view the person spent their time arranging — they lined the scene up from
+   * one side, pressed F to get closer to a node, and now they are looking at it from wherever
+   * the pivot maths decided. Keeping the orientation means F only ever answers "put that in
+   * front of me", which is the question it was asked.
+   *
+   * The camera glides rather than teleports: a cut leaves you working out where you ended up,
+   * and the motion is what tells you the scene did not change — only your seat.
+   */
+  frameOn(point: Vector3, distance: number): void {
+    this.focusDistance = Math.max(0.1, distance);
+    // Straight back along the current view direction — `-Z` in camera space, which is where the
+    // camera already looks, so nothing about the orientation moves.
+    this.glideTo = point.clone().addScaledVector(this.forward(this.v), -this.focusDistance);
+    this.speed = Math.max(1, this.focusDistance * 0.5); // fly speed scales with how far out we sit
+  }
+
+  /** The unit vector the camera currently looks along. */
+  private forward(into: Vector3): Vector3 {
+    return into.set(0, 0, -1).applyQuaternion(this.q.setFromEuler(this.euler));
   }
 
   /** Add yaw/pitch in radians (pitch clamped to avoid flipping). */
   rotate(dYaw: number, dPitch: number): void {
+    this.glideTo = null; // the person is driving now
     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. */
+  /**
+   * Translate: `right` and `forward` in camera-local space, `up` along **world** up.
+   *
+   * Local up is the tempting reading and the wrong one. With the camera pitched down at the
+   * scene — which is where an editor camera spends its life — a local "up" also carries you
+   * backwards, so Q and E slide the view around instead of raising and lowering it. Unity's scene
+   * camera uses world up for the same reason.
+   */
   move(right: number, up: number, forward: number): void {
-    this.v.set(right, up, -forward).applyQuaternion(this.q.setFromEuler(this.euler));
+    this.glideTo = null; // any input cancels a focus glide — the camera has one owner at a time
+    this.v.set(right, 0, -forward).applyQuaternion(this.q.setFromEuler(this.euler));
+    this.v.y += up;
     this.camera.position.add(this.v);
   }
 
-  /** Apply the orientation to the camera. Call once per frame, after input. */
-  sync(): void {
+  /**
+   * Apply the orientation, and advance a focus glide. Call once per frame, after input.
+   *
+   * Frame-rate independent easing: the *fraction of the remaining distance* covered per second
+   * is fixed, so the same glide takes the same time at 60Hz and at 144Hz. `1 - k ** dt` is the
+   * exponential form of that — the naive `lerp(a, b, 0.1)` per frame is twice as fast on a
+   * 120Hz display, which is how a smooth camera on one machine becomes a snap on another.
+   */
+  sync(dt = 0): void {
     this.camera.quaternion.setFromEuler(this.euler);
+    if (!this.glideTo) return;
+    const remaining = this.v.subVectors(this.glideTo, this.camera.position);
+    // Close enough that another frame of easing would be invisible: land exactly and stop, so
+    // the camera is never left a hair off with a live tween attached to it.
+    if (remaining.lengthSq() < 1e-8) {
+      this.camera.position.copy(this.glideTo);
+      this.glideTo = null;
+      return;
+    }
+    this.camera.position.addScaledVector(remaining, 1 - GLIDE_LEFT_PER_SECOND ** dt);
   }
 }
 
+/**
+ * The fraction of the distance to the focus target still left after one second.
+ *
+ * Measured rather than guessed: at 1e-6 the camera is 94% of the way there in 0.2s and 98.5% in
+ * 0.3s, so the move reads as quick and decisive and is visually over in about a third of a
+ * second. Ten times gentler (1e-5) drifts long enough to feel laggy on a phone; ten times
+ * sharper is indistinguishable from a cut.
+ */
+const GLIDE_LEFT_PER_SECOND = 1e-6;
+
 function clamp(v: number, lo: number, hi: number): number {
   return Math.max(lo, Math.min(hi, v));
 }

package/app/commands.ts

@@ -21,7 +21,11 @@ export class UndoStack {
   private readonly undoables: Command[] = [];
   private readonly redoables: Command[] = [];
 
-  constructor(private readonly onChange?: () => void) {}
+  private readonly onChange: (() => void) | undefined;
+
+  constructor(onChange?: () => void) {
+    this.onChange = onChange;
+  }
 
   /** Apply a command and record it, merging into the previous one if keys match. */
   run(cmd: Command): void {

package/app/desktopControls.ts

@@ -1,4 +1,4 @@
-import type { InputManager } from '@scenoco-three/core';
+import { Input, KeyCode, MouseButton } from '@scenoco-three/core';
 import type { CameraRig } from './cameraRig.js';
 
 /**
@@ -8,10 +8,13 @@ import type { CameraRig } from './cameraRig.js';
 export class DesktopControls {
   private readonly look = 0.0025; // radians per pixel
 
-  constructor(
-    private readonly rig: CameraRig,
-    private readonly input: InputManager,
-  ) {}
+  private readonly rig: CameraRig;
+  /** v2's input is one singleton attached to the canvas, not a per-engine manager. */
+  private readonly input = Input;
+
+  constructor(rig: CameraRig) {
+    this.rig = rig;
+  }
 
   /** Advance one frame (call after `engine.tick`). */
   update(dt: number): void {
@@ -20,17 +23,17 @@ export class DesktopControls {
     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)) {
+    if (input.getMouseButton(MouseButton.Right)) {
       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'));
+    const right = axis(input.getKey(KeyCode.D), input.getKey(KeyCode.A));
+    const up = axis(input.getKey(KeyCode.E), input.getKey(KeyCode.Q));
+    const forward = axis(input.getKey(KeyCode.W), input.getKey(KeyCode.S));
     if (right || up || forward) {
       const len = Math.hypot(right, up, forward);
-      const step = (rig.speed * (input.getKey('LeftShift') ? 4 : 1) * dt) / len;
+      const step = (rig.speed * (input.getKey(KeyCode.LeftShift) ? 4 : 1) * dt) / len;
       rig.move(right * step, up * step, forward * step);
     }
   }