@scenoco-three/editor 0.5.4 → 0.7.0

package/README.md

@@ -1,112 +1,37 @@
 # @scenoco-three/editor
 
-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.
+A visual editor for SceNoCo scenes that is never part of the project. Part of
+[SceNoCo](https://github.com/RomaRogov/scenoco-three).
 
 ```bash
-npm i -D @scenoco-three/editor
+npm run dev                  # the game's own dev server, as always
+npx scenoco-editor           # the editor's interface, on http://localhost:5185
 ```
 
-## CLI
-
-```
-scenoco-editor [scene|prefab] [options]     Omit the file to choose from a start-up picker
-  --components <dirs>   Comma-separated component dirs (default: "assets")
-  --packages <pkgs>     Comma-separated tag packages (default: every @scenoco-three/*
-                        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)
-```
-
-```bash
-scenoco-editor                                    # zero-config: file picker, auto-detected packages
-scenoco-editor assets/scenes/level.scene.xml --port 55470
-#   editor:  http://localhost:HTTP_PORT?file=…    ← opens in your browser
-#   mcp:     http://localhost:55470/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. |
-| `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. |
-| `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
-
-One call injects input, steps the sim, and captures — *see a game move, not a static scene*.
-Each command is a self-contained verb `{ do, … }`:
-
-```ts
-type SimStep =
-  | { do: 'play' | 'pause' | 'stop' }
-  | { do: 'step'; frames?: number; dt?: number }            // advance `frames` ticks (default 1)
-  | { 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 }       // 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
-{ "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.
-
-## Programmatic API
-
-```ts
-import { startEditorServer, startMcpServer } from '@scenoco-three/editor';
-
-const editor = await startEditorServer({ cwd });   // defaults: assets/ roots, packages from package.json
-const mcp = await startMcpServer(editor.bridge, { port: 55470 });   // 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
-[measurements](../../bench/README.md).
-
-## License
-
-[MIT](./LICENSE)
+Then open the game with `?edit` — `http://localhost:5173/?edit` — or any scene or prefab function
+with `?edit&scene=/src/scenes/levels.tsx%23Level2`.
+
+- **The game builds the scene.** In development, `play()` sees `?edit`, builds the scene with the
+  game's own code on the game's own server, and holds it still: no behaviour wakes. Then it loads
+  this package's interface from its URL (`?edit=<url>` to load it from elsewhere).
+- **What you see is live.** A tree of the scene, an inspector — transform, the element's own
+  attributes, the geometry's and material's, every behaviour's fields — and a move / rotate / scale
+  gizmo, with Global or Local handles. A change is applied to the live object the way the scene sets it.
+- **Made for a finger as much as a mouse.** On a phone held upright the node list and the inspector
+  are bottom sheets, one at a time; turned sideways, or on a screen, they are side columns that can
+  both be open. Drag the letter beside a number to scrub it: the scene follows the drag, and the
+  file is written once, when it ends.
+- **What you change is written back, and nothing else is.** The project's `scenoco()` Vite plugin
+  writes one attribute into the `.tsx` file the element came from, splicing its text; comments,
+  layout and every other attribute stay byte for byte. A value it cannot see through — a
+  `material={paint.wall}`, a ref — is shown, not edited. Rotations show in degrees and are written
+  in radians; numbers are rounded to four decimals.
+
+- **Undo puts the text back.** ⌘Z / Ctrl+Z and ⇧⌘Z / Ctrl+Y restore an attribute exactly as it
+  was written — `-Math.PI / 2` too — and survive the reload that removing an attribute needs.
+- **A file changed behind its back is refused.** Every write names the element it means as the
+  editor last read it; if the file was edited elsewhere since, nothing is written and the editor
+  says to reload.
+
+What it does not do yet: add or remove elements, or show what behaviours spawn at runtime
+(nothing runs while editing — `BrickField`'s bricks are not there).

package/bin/serve.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+/**
+ * `scenoco-editor [--port 5185]` — serves the editor's interface for a game's page to load.
+ *
+ * Start the game's own dev server as usual, run this beside it, and open the game with `?edit`:
+ * the page builds the scene, holds it still, and imports the interface from here. Nothing about
+ * the editor is installed in the project.
+ */
+import { createReadStream, existsSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { fileURLToPath } from 'node:url';
+
+const argv = process.argv.slice(2);
+if (argv.includes('-h') || argv.includes('--help')) {
+  console.log('scenoco-editor [--port <n>]\n\nServes the editor for a game page opened with ?edit (port 5185 by default).');
+  process.exit(0);
+}
+const port = Number(argv[argv.indexOf('--port') + 1] || 0) || 5185;
+const file = fileURLToPath(new URL('../dist/editor.js', import.meta.url));
+if (!existsSync(file)) {
+  console.error('scenoco-editor: this package has no dist/editor.js — run `npm run build` in packages/editor');
+  process.exit(1);
+}
+
+createServer((req, res) => {
+  // The game's page is on another port, so the module needs CORS to load at all.
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  if (new URL(req.url ?? '/', 'http://x').pathname !== '/editor.js') {
+    res.statusCode = 404;
+    return res.end('Open your game with ?edit — it loads /editor.js from here.');
+  }
+  res.setHeader('Content-Type', 'text/javascript');
+  res.setHeader('Cache-Control', 'no-store');
+  createReadStream(file).pipe(res);
+}).listen(port, () => {
+  console.log(`scenoco-editor: serving on http://localhost:${port}/editor.js — open your game with ?edit`);
+});