@scenoco-three/editor 0.2.0

package/app/session.ts

@@ -0,0 +1,294 @@
+import {
+  AmbientLight, Box3, Color, DirectionalLight, PerspectiveCamera, Sphere, Vector3, type Object3D,
+} from 'three';
+import { Engine, Registry, bundleKind, type Bundle, type Component } from '@scenoco-three/core';
+import type { SceneProvenance } from '@scenoco-three/compiler';
+import type { EditOp, EditorResult, SimStep } from '../src/protocol.js';
+
+export type EditorMode = 'edit' | 'play';
+
+/**
+ * Owns the engine and the edit ⇄ play lifecycle. In **edit** mode the scene shows
+ * its authored pose through an editor-controlled camera (Engine `editor:true`); in
+ * **play** mode a fresh `editor:false` engine runs the real gameplay through the
+ * scene's own camera. The engine is recreated on each switch.
+ */
+export class EditorSession {
+  engine: Engine;
+  mode: EditorMode = 'edit';
+  playing = false;
+  /** The editor camera (edit mode only). */
+  editorCamera?: PerspectiveCamera;
+  /** Fired after the engine/scene changes, so the host rebinds camera + panels. */
+  onChange?: () => void;
+  /** Fired when a watched file changes on disk (the open file or a `src=` dep). */
+  onExternalChange?: (file: string, role: 'open' | 'dep') => void;
+
+  private bundle?: Bundle;
+  /** Source path of the open scene/prefab — the target of `save`. */
+  filePath?: string;
+  /** Editor provenance for the open file (prefab/material origins), for the document. */
+  provenance?: SceneProvenance;
+
+  constructor(private readonly canvas: HTMLCanvasElement) {
+    this.engine = this.makeEngine(true);
+  }
+
+  private makeEngine(editor: boolean): Engine {
+    return new Engine({ canvas: this.canvas, autoStart: false, editor, preserveDrawingBuffer: true });
+  }
+
+  /** Fetch + load a scene/prefab (edit mode). Returns a small summary. */
+  async open(path: string): Promise<{ file: string; kind: 'scene' | 'prefab'; nodes: number }> {
+    const res = await fetch(`/@scenoco/bundle?file=${encodeURIComponent(path)}`);
+    const data = (await res.json()) as { bundle: Bundle; provenance: SceneProvenance } | { error: string };
+    if (!res.ok || !('bundle' in data) || !Array.isArray(data.bundle)) {
+      throw new Error((data as { error?: string }).error ?? 'failed to open file');
+    }
+    this.bundle = data.bundle;
+    this.provenance = data.provenance;
+    this.filePath = path;
+    this.toEdit();
+    return { file: path, kind: bundleKind(this.bundle) === 'prefab' ? 'prefab' : 'scene', nodes: count(this.engine.scene) };
+  }
+
+  /** Write a set of attribute edits back to the source file (surgical diff). */
+  async save(edits: EditOp[]): Promise<{ changed: number; unresolved: number }> {
+    if (!this.filePath) throw new Error('no file open to save');
+    const res = await fetch('/@scenoco/save', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ file: this.filePath, edits }),
+    });
+    const data = (await res.json()) as { changed: number; unresolved: number; error?: string };
+    if (!res.ok) throw new Error(data.error ?? 'save failed');
+    return data;
+  }
+
+  /** Start (or resume) gameplay. */
+  run(): void {
+    if (this.mode === 'play') {
+      this.playing = true; // resume from pause
+      return;
+    }
+    this.swap(false);
+    this.playing = true;
+    this.onChange?.();
+  }
+  pause(): void {
+    this.playing = false;
+  }
+  /** Advance gameplay by a single frame while paused (no-op outside play mode). */
+  step(dt = 1 / 60): void {
+    if (this.mode !== 'play') return;
+    this.engine.tick(dt); // bypass the play+paused gate in tick()
+  }
+  stop(): void {
+    this.toEdit();
+  }
+
+  /** Advance one frame: edit always renders; play advances only while playing. */
+  tick(dt: number): void {
+    this.engine.tick(this.mode === 'play' && !this.playing ? 0 : dt);
+  }
+
+  /** Capture the current view as a PNG data URL (optionally re-framing the editor camera). */
+  preview(opts: { camera?: string; lookAt?: string }): string {
+    if (this.mode === 'edit' && this.editorCamera) {
+      const cam = vec3(opts.camera);
+      const look = vec3(opts.lookAt);
+      if (cam) this.editorCamera.position.copy(cam);
+      if (look) this.editorCamera.lookAt(look);
+    }
+    this.engine.tick(0); // render the current frame
+    return this.canvas.toDataURL('image/png');
+  }
+
+  /** Current property values for the node + its components at `id`, as plain JSON. */
+  telemetry(id: string): unknown {
+    const node = this.engine.findObject(id);
+    if (!node) return { error: `no object with id "${id}"` };
+    const components: Record<string, Record<string, unknown>> = {};
+    for (const c of this.engine.getComponents(node)) {
+      // Surface the component's scene id (if any), alongside its @property values.
+      components[componentName(c) ?? c.constructor.name] = { ...(c.id !== undefined ? { id: c.id } : {}), ...propValues(c) };
+    }
+    return {
+      id,
+      type: node.type,
+      transform: {
+        position: arr(node.position),
+        rotation: degArr(node.rotation),
+        scale: arr(node.scale),
+        visible: node.visible,
+      },
+      components,
+    };
+  }
+
+  /**
+   * Execute a batch of player-simulation steps in order against the live engine —
+   * transport, frame stepping, synthetic key/mouse/gamepad input, and preview/
+   * telemetry captures. Runs synchronously (no real-time loop interleaves), so an
+   * agent can drive the game to a precise condition and sample it there. Injected
+   * input is committed on the next `step`, so the usual order is input → step →
+   * preview/telemetry. Returns the captures in step order.
+   */
+  simulate(steps: SimStep[]): EditorResult[] {
+    const out: EditorResult[] = [];
+    for (const step of steps) {
+      const input = this.engine.input;
+      switch (step.do) {
+        case 'play':
+          this.run();
+          break;
+        case 'pause':
+          this.pause();
+          break;
+        case 'stop':
+          this.stop();
+          break;
+        case 'step': {
+          const frames = Math.max(0, Math.floor(step.frames ?? 1));
+          const dt = step.dt ?? 1 / 60;
+          for (let i = 0; i < frames; i++) this.engine.tick(dt);
+          break;
+        }
+        case 'tap':
+          input.injectKey(step.key, true);
+          input.injectKey(step.key, false);
+          break;
+        case 'keyDown':
+          input.injectKey(step.key, true);
+          break;
+        case 'keyUp':
+          input.injectKey(step.key, false);
+          break;
+        case 'click': {
+          if (step.x !== undefined && step.y !== undefined) input.injectMouseMove(step.x, step.y);
+          const b = step.button === 'right' ? 1 : step.button === 'middle' ? 2 : 0;
+          input.injectMouseButton(b, true);
+          input.injectMouseButton(b, false);
+          break;
+        }
+        case 'move':
+          input.injectMouseMove(step.x ?? 0, step.y ?? 0, step.dx ?? 0, step.dy ?? 0);
+          break;
+        case 'gamepad':
+          input.injectGamepad(step.index ?? 0, { ...(step.buttons ? { buttons: step.buttons } : {}), ...(step.axes ? { axes: step.axes } : {}) });
+          break;
+        case 'preview':
+          out.push({ kind: 'image', dataUrl: this.preview({ ...(step.camera ? { camera: step.camera } : {}), ...(step.lookAt ? { lookAt: step.lookAt } : {}) }) });
+          break;
+        case 'telemetry':
+          out.push({ kind: 'json', data: this.telemetry(step.id) });
+          break;
+      }
+    }
+    return out;
+  }
+
+  // ── internals ────────────────────────────────────────────────────────────────
+
+  private toEdit(): void {
+    this.swap(true);
+    this.mode = 'edit';
+    this.playing = false;
+    this.editorCamera = this.frameCamera();
+    this.onChange?.();
+  }
+
+  private swap(editor: boolean): void {
+    this.engine.dispose();
+    this.engine = this.makeEngine(editor);
+    this.editorCamera = undefined;
+    this.mode = editor ? 'edit' : 'play';
+    this.applyBundle();
+  }
+
+  private applyBundle(): void {
+    if (!this.bundle) return;
+    if (bundleKind(this.bundle) === 'prefab') {
+      this.engine.instantiate(this.bundle);
+      // Editor-only preview lights — flagged so the Hierarchy/picking ignore them.
+      const ambient = new AmbientLight(0xffffff, 0.6);
+      ambient.userData.scenocoEditorOnly = true;
+      this.engine.scene.add(ambient);
+      const key = new DirectionalLight(0xffffff, 2);
+      key.position.set(3, 5, 4);
+      key.userData.scenocoEditorOnly = true;
+      this.engine.scene.add(key);
+      if (!this.engine.scene.background) this.engine.scene.background = new Color(0x15181f);
+    } else {
+      this.engine.loadScene(this.bundle);
+    }
+  }
+
+  /** Editor camera framing the scene from a 3/4 angle. */
+  private frameCamera(): PerspectiveCamera {
+    const cam = new PerspectiveCamera(50, this.canvas.clientWidth / this.canvas.clientHeight || 1, 0.01, 50000);
+    const box = new Box3().setFromObject(this.engine.scene);
+    const center = new Vector3();
+    let radius = 1;
+    if (!box.isEmpty()) {
+      const sphere = box.getBoundingSphere(new Sphere());
+      center.copy(sphere.center);
+      radius = sphere.radius || 1;
+    }
+    cam.position.copy(center).addScaledVector(new Vector3(0.6, 0.45, 1).normalize(), (radius / Math.sin((50 * Math.PI) / 180 / 2)) * 1.2);
+    cam.lookAt(center);
+    this.engine.mainCamera = cam;
+    return cam;
+  }
+}
+
+// ── value helpers (telemetry → JSON) ─────────────────────────────────────────────
+
+function propValues(component: Component): Record<string, unknown> {
+  const meta = registeredMeta(component);
+  const out: Record<string, unknown> = {};
+  if (!meta) return out;
+  for (const [name] of meta.properties) out[name] = jsonValue((component as unknown as Record<string, unknown>)[name]);
+  return out;
+}
+function jsonValue(v: unknown): unknown {
+  if (v == null || typeof v === 'number' || typeof v === 'boolean' || typeof v === 'string') return v ?? null;
+  if (Array.isArray(v)) return v.map(jsonValue);
+  const o = v as { isVector3?: boolean; isVector2?: boolean; isColor?: boolean; isEuler?: boolean; isObject3D?: boolean; x?: number; y?: number; z?: number; name?: string; getHexString?: () => string };
+  if (o.isVector3) return [o.x, o.y, o.z];
+  if (o.isVector2) return [o.x, o.y];
+  if (o.isEuler) return [deg(o.x!), deg(o.y!), deg(o.z!)];
+  if (o.isColor) return `#${o.getHexString!()}`;
+  if (o.isObject3D) return o.name || '(node)';
+  if ('node' in (o as object) && 'engine' in (o as object)) return componentName(v as Component) ?? '(component)';
+  return String(v);
+}
+const arr = (v: { x: number; y: number; z: number }) => [round(v.x), round(v.y), round(v.z)];
+const degArr = (v: { x: number; y: number; z: number }) => [deg(v.x), deg(v.y), deg(v.z)];
+const deg = (rad: number) => round((rad * 180) / Math.PI);
+const round = (n: number) => Math.round(n * 1000) / 1000;
+
+function vec3(s?: string): Vector3 | undefined {
+  if (!s) return undefined;
+  const p = s.split(/[ ,]+/).map(Number).filter((n) => Number.isFinite(n));
+  return p.length === 3 ? new Vector3(p[0], p[1], p[2]) : undefined;
+}
+function count(root: Object3D): number {
+  let n = 0;
+  root.traverse(() => n++);
+  return n;
+}
+function registeredMeta(component: Component) {
+  for (const name of Registry.componentNames()) {
+    const entry = Registry.getComponent(name);
+    if (entry && component instanceof entry.ctor) return entry.meta;
+  }
+  return undefined;
+}
+function componentName(component: Component): string | undefined {
+  for (const name of Registry.componentNames()) {
+    const entry = Registry.getComponent(name);
+    if (entry && component.constructor === entry.ctor) return name;
+  }
+  return undefined;
+}

package/app/toolbar.ts

@@ -0,0 +1,131 @@
+import type { GizmoMode } from './gizmo.js';
+
+export interface ToolbarHandlers {
+  // transport
+  play(): void;
+  pause(): void;
+  step(): void;
+  stop(): void;
+  // gizmo + edit
+  getMode(): GizmoMode;
+  setMode(mode: GizmoMode): void;
+  undo(): void;
+  redo(): void;
+  save(): void;
+  /** Current state, polled on each `refresh`. */
+  state(): {
+    mode: 'edit' | 'play';
+    playing: boolean;
+    canUndo: boolean;
+    canRedo: boolean;
+    dirty: boolean;
+    saving: boolean;
+    enabled: boolean;
+  };
+}
+
+export interface Toolbar {
+  /** Re-read handler state into the button styles (transport, active mode, enabled, dirty dot). */
+  refresh(): void;
+}
+
+// Material-style 24×24 icon paths (filled, `currentColor`).
+const ICON = {
+  play: 'M8 5v14l11-7z',
+  pause: 'M6 5h4v14H6zm8 0h4v14h-4z',
+  step: 'M6 18l8.5-6L6 6v12zM16 6v12h2V6h-2z',
+  stop: 'M6 6h12v12H6z',
+  move: 'M10 9h4V6h3l-5-5-5 5h3v3zm-1 1H6V7l-5 5 5 5v-3h3v-4zm14 2l-5-5v3h-3v4h3v3l5-5zm-9 3h-4v3H8l4 4 4-4h-3v-3z',
+  rotate:
+    'M15.55 5.55L11 1v3.07C7.06 4.56 4 7.92 4 12s3.05 7.44 7 7.93v-2.02c-2.84-.48-5-2.94-5-5.91s2.16-5.43 5-5.91V10l4.55-4.45zM19.93 11c-.17-1.39-.72-2.73-1.62-3.89l-1.42 1.42c.54.75.88 1.6 1.02 2.47h2.02zM13 17.9v2.02c1.39-.17 2.74-.71 3.9-1.61l-1.44-1.44c-.75.54-1.59.89-2.46 1.03zm3.89-2.42l1.42 1.41c.9-1.16 1.45-2.5 1.62-3.89h-2.02c-.14.87-.48 1.72-1.02 2.48z',
+  scale:
+    'M15 3l2.3 2.3-2.89 2.87 1.42 1.42L18.7 6.7 21 9V3h-6zM3 9l2.3-2.3 2.87 2.89 1.42-1.42L6.7 5.3 9 3H3v6zm6 12l-2.3-2.3 2.89-2.87-1.42-1.42L5.3 17.3 3 15v6h6zm12-6l-2.3 2.3-2.87-2.89-1.42 1.42 2.89 2.87L15 21h6v-6z',
+  undo: 'M12.5 8c-2.65 0-5.05.99-6.9 2.6L2 7v9h9l-3.62-3.62c1.39-1.16 3.16-1.88 5.12-1.88 3.54 0 6.55 2.31 7.6 5.5l2.37-.78C21.08 11.03 17.15 8 12.5 8z',
+  redo: 'M18.4 10.6C16.55 8.99 14.15 8 11.5 8c-4.65 0-8.58 3.03-9.96 7.22L3.9 16c1.05-3.19 4.05-5.5 7.6-5.5 1.95 0 3.73.72 5.12 1.88L13 16h9V7l-3.6 3.6z',
+  save: 'M17 3H5c-1.11 0-2 .9-2 2v14c0 1.1.89 2 2 2h14c1.1 0 2-.9 2-2V7l-4-4zm-5 16c-1.66 0-3-1.34-3-3s1.34-3 3-3 3 1.34 3 3-1.34 3-3 3zm3-10H5V5h10v4z',
+} as const;
+
+/**
+ * Two floating, touch-reachable toolbars: a **play** panel (play/pause/step/stop)
+ * and a **movement** panel (gizmo mode, undo/redo, save). The movement panel is
+ * hidden in play mode — there's no editing while the sim runs. All actions defer
+ * to `handlers`, which read the live session/document/gizmo.
+ */
+export function buildToolbar(handlers: ToolbarHandlers): Toolbar {
+  const bars = el('div', 'sc-toolbars');
+  const playBar = el('div', 'sc-toolbar');
+  const editBar = el('div', 'sc-toolbar');
+
+  const play = btn('Play', ICON.play, () => handlers.play());
+  const pause = btn('Pause', ICON.pause, () => handlers.pause());
+  const step = btn('Step one frame', ICON.step, () => handlers.step());
+  const stop = btn('Stop', ICON.stop, () => handlers.stop());
+  playBar.append(play, pause, step, stop);
+
+  const move = modeBtn('translate', 'Move', ICON.move);
+  const rotate = modeBtn('rotate', 'Rotate', ICON.rotate);
+  const scale = modeBtn('scale', 'Scale', ICON.scale);
+  const undo = btn('Undo', ICON.undo, () => handlers.undo());
+  const redo = btn('Redo', ICON.redo, () => handlers.redo());
+  const save = btn('Save', ICON.save, () => handlers.save());
+  save.classList.add('sc-save');
+  editBar.append(move, rotate, scale, sep(), undo, redo, sep(), save);
+
+  bars.append(playBar, editBar);
+  document.body.append(bars);
+
+  function modeBtn(mode: GizmoMode, title: string, path: string): HTMLButtonElement {
+    return btn(title, path, () => handlers.setMode(mode), mode);
+  }
+
+  function refresh(): void {
+    const s = handlers.state();
+    const editing = s.mode === 'edit';
+    const paused = s.mode === 'play' && !s.playing;
+
+    // Transport.
+    play.disabled = s.playing; // edit → start; paused → resume; playing → disabled
+    play.classList.toggle('active', s.playing);
+    pause.disabled = !s.playing;
+    step.disabled = !paused;
+    stop.disabled = editing;
+
+    // Movement panel: editing only happens in edit mode — hide it during play.
+    editBar.style.display = editing ? '' : 'none';
+
+    const mode = handlers.getMode();
+    for (const b of [move, rotate, scale]) {
+      b.classList.toggle('active', b.dataset.mode === mode);
+      b.disabled = !s.enabled;
+    }
+    undo.disabled = !s.canUndo;
+    redo.disabled = !s.canRedo;
+    save.disabled = !s.dirty || s.saving;
+    save.classList.toggle('dirty', s.dirty);
+    save.classList.toggle('saving', s.saving);
+  }
+
+  refresh();
+  return { refresh };
+}
+
+// ── DOM helpers ──────────────────────────────────────────────────────────────────
+
+function el(tag: string, className: string): HTMLElement {
+  const node = document.createElement(tag);
+  node.className = className;
+  return node;
+}
+function btn(title: string, iconPath: string, onClick: () => void, mode?: GizmoMode): HTMLButtonElement {
+  const b = document.createElement('button');
+  b.className = 'sc-tbtn';
+  b.title = title;
+  b.setAttribute('aria-label', title);
+  b.innerHTML = `<svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="${iconPath}"/></svg>`;
+  if (mode) b.dataset.mode = mode;
+  b.onclick = onClick;
+  return b;
+}
+function sep(): HTMLElement {
+  return el('div', 'sc-tsep');
+}

package/app/touchControls.ts

@@ -0,0 +1,104 @@
+import { Vector2 } from 'three';
+import type { CameraRig } from './cameraRig.js';
+
+/**
+ * Touch navigation for mobile 3D editing (HypeHype-style):
+ *   • one finger drag  → pan the camera up/down/left/right (like Q/E/A/D)
+ *   • two finger drag  → rotate (look) with the two-finger movement
+ *   • two finger pinch → dolly forward / back
+ *
+ * Event-driven (touchmove drives the rig directly); coexists with the desktop
+ * controls because both only ever call `rig` verbs.
+ */
+export class TouchControls {
+  private readonly points = new Map<number, Vector2>();
+  private prevPinch = 0;
+  // Per-pixel factors, multiplied by the focus distance (Unity-like): drag/dolly
+  // feel the same on screen at any zoom — fine up close, fast when far away.
+  private readonly pan = 0.0016;
+  private readonly dolly = 0.005;
+  private readonly look = 0.005; // radians per pixel
+  private detach: Array<() => void> = [];
+
+  constructor(
+    private readonly rig: CameraRig,
+    canvas: HTMLElement,
+    /** When true, a gizmo handle owns the gesture — leave the camera alone. */
+    private readonly isBlocked: () => boolean = () => false,
+  ) {
+    const on = (type: string, fn: (e: TouchEvent) => void) => {
+      const h = fn as EventListener;
+      canvas.addEventListener(type, h, { passive: false });
+      this.detach.push(() => canvas.removeEventListener(type, h));
+    };
+    on('touchstart', this.onStart);
+    on('touchmove', this.onMove);
+    on('touchend', this.onEnd);
+    on('touchcancel', this.onEnd);
+  }
+
+  private onStart = (e: TouchEvent): void => {
+    e.preventDefault();
+    for (const t of Array.from(e.changedTouches)) this.points.set(t.identifier, new Vector2(t.clientX, t.clientY));
+    this.prevPinch = this.pinchDistance();
+  };
+
+  private onMove = (e: TouchEvent): void => {
+    // A single finger dragging a gizmo handle also emits touch events — yield it.
+    if (this.points.size === 1 && this.isBlocked()) return;
+    e.preventDefault();
+    const k = this.rig.focusDistance;
+    if (this.points.size === 1) {
+      // One finger → drag the scene: the camera moves *opposite* the finger so the
+      // grabbed point follows it. Scaled by focus distance.
+      for (const t of Array.from(e.touches)) {
+        const prev = this.points.get(t.identifier);
+        if (!prev) continue;
+        this.rig.move(-(t.clientX - prev.x) * this.pan * k, (t.clientY - prev.y) * this.pan * k, 0);
+        prev.set(t.clientX, t.clientY);
+      }
+    } else if (this.points.size >= 2) {
+      // Two fingers → rotate by the average movement, dolly by the pinch change.
+      let dx = 0;
+      let dy = 0;
+      let n = 0;
+      for (const t of Array.from(e.touches)) {
+        const prev = this.points.get(t.identifier);
+        if (!prev) continue;
+        dx += t.clientX - prev.x;
+        dy += t.clientY - prev.y;
+        prev.set(t.clientX, t.clientY);
+        n++;
+      }
+      if (n > 0) this.rig.rotate((-dx / n) * this.look, (-dy / n) * this.look);
+
+      const pinch = this.pinchDistance();
+      if (this.prevPinch > 0) {
+        const forward = (pinch - this.prevPinch) * this.dolly * k;
+        this.rig.move(0, 0, forward);
+        this.rig.focusDistance = Math.max(0.1, this.rig.focusDistance - forward); // dollied closer → finer
+      }
+      this.prevPinch = pinch;
+    }
+  };
+
+  private onEnd = (e: TouchEvent): void => {
+    for (const t of Array.from(e.changedTouches)) this.points.delete(t.identifier);
+    this.prevPinch = this.pinchDistance();
+  };
+
+  private pinchDistance(): number {
+    const pts = [...this.points.values()];
+    return pts.length >= 2 ? pts[0]!.distanceTo(pts[1]!) : 0;
+  }
+
+  dispose(): void {
+    for (const off of this.detach) off();
+    this.detach = [];
+  }
+}
+
+/** True on a touch-capable device. */
+export function isTouchDevice(): boolean {
+  return typeof window !== 'undefined' && ('ontouchstart' in window || (navigator.maxTouchPoints ?? 0) > 0);
+}

package/app/vite-env.d.ts

@@ -0,0 +1,5 @@
+/// <reference types="vite/client" />
+
+// The editor server's plugin emits a module that imports every project component,
+// package, and built-in node tag (so any opened scene/prefab has its tags ready).
+declare module 'virtual:scenoco-components';

package/app/wsClient.ts

@@ -0,0 +1,66 @@
+import { WS_PATH, type EditorCommand, type EditorPush, type EditorResponse, type EditorResult } from '../src/protocol.js';
+import type { EditorSession } from './session.js';
+
+/**
+ * Connect the editor page to the dev server's WebSocket bridge and execute the
+ * commands the MCP server relays, replying with the result (id-correlated).
+ * Auto-reconnects (e.g. across a dev-server restart).
+ */
+export function connectEditor(session: EditorSession): void {
+  const proto = location.protocol === 'https:' ? 'wss' : 'ws';
+  const url = `${proto}://${location.host}${WS_PATH}`;
+
+  const open = (): void => {
+    const ws = new WebSocket(url);
+    ws.onmessage = async (ev) => {
+      let msg: EditorCommand | EditorPush;
+      try {
+        msg = JSON.parse(ev.data as string) as EditorCommand | EditorPush;
+      } catch {
+        return;
+      }
+      // Unsolicited server push (a watched file changed) — not an id-correlated command.
+      if ('push' in msg) {
+        session.onExternalChange?.(msg.file, msg.role);
+        return;
+      }
+      const cmd = msg;
+      let response: EditorResponse;
+      try {
+        response = { id: cmd.id, ok: true, result: await runCommand(session, cmd) };
+      } catch (e) {
+        response = { id: cmd.id, ok: false, error: e instanceof Error ? e.message : String(e) };
+      }
+      ws.send(JSON.stringify(response));
+    };
+    ws.onclose = () => setTimeout(open, 1000);
+    ws.onerror = () => ws.close();
+  };
+  open();
+}
+
+/**
+ * Execute one relayed command against the session. Exported so the command
+ * dispatch (not just the WS plumbing) can be driven directly in tests.
+ */
+export async function runCommand(session: EditorSession, cmd: EditorCommand): Promise<EditorResult> {
+  switch (cmd.type) {
+    case 'open':
+      return { kind: 'json', data: await session.open(cmd.path) };
+    case 'preview':
+      return { kind: 'image', dataUrl: session.preview({ camera: cmd.camera, lookAt: cmd.lookAt }) };
+    case 'run':
+      session.run();
+      return { kind: 'ok', info: 'playing' };
+    case 'pause':
+      session.pause();
+      return { kind: 'ok', info: 'paused' };
+    case 'stop':
+      session.stop();
+      return { kind: 'ok', info: 'edit mode' };
+    case 'telemetry':
+      return { kind: 'json', data: session.telemetry(cmd.targetId) };
+    case 'simulate':
+      return { kind: 'multi', results: session.simulate(cmd.steps) };
+  }
+}

package/dist/args.d.ts

@@ -0,0 +1,8 @@
+/** Split a comma-separated list, trimming blanks. */
+export declare function parseList(v: string | undefined): string[] | undefined;
+/** Flags that take a value; other `--flags` are booleans (`''`), the rest positionals. */
+export declare const VALUE_FLAGS: Record<string, string>;
+export declare function parseArgs(args: string[]): {
+    positionals: string[];
+    options: Record<string, string>;
+};

package/dist/args.js

@@ -0,0 +1,28 @@
+// Pure CLI-arg helpers (no vite imports), so they're unit-testable.
+/** Split a comma-separated list, trimming blanks. */
+export function parseList(v) {
+    return v ? v.split(',').map((s) => s.trim()).filter(Boolean) : undefined;
+}
+/** Flags that take a value; other `--flags` are booleans (`''`), the rest positionals. */
+export const VALUE_FLAGS = {
+    '--components': 'components',
+    '--packages': 'packages',
+    '--port': 'port',
+};
+export function parseArgs(args) {
+    const positionals = [];
+    const options = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg in VALUE_FLAGS) {
+            options[VALUE_FLAGS[arg]] = args[++i] ?? '';
+        }
+        else if (arg.startsWith('--')) {
+            options[arg.slice(2)] = ''; // boolean flag, e.g. --no-open
+        }
+        else {
+            positionals.push(arg);
+        }
+    }
+    return { positionals, options };
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};