@scenoco-three/editor 0.3.1 → 0.4.0

package/app/document.ts

@@ -12,7 +12,7 @@ import {
   type SceneGraph,
 } from '@scenoco-three/core';
 import type { NodeOrigin, SceneProvenance } from '@scenoco-three/compiler';
-import type { EditOp, EditTarget } from '../src/protocol.js';
+import type { EditOp, EditTarget } from '../dist/protocol.js';
 import { UndoStack } from './commands.js';
 
 export type TransformChannel = 'position' | 'rotation' | 'scale';

package/app/main.ts

@@ -217,6 +217,9 @@ let reloading = false;
 let conflictBanner: HTMLElement | undefined;
 
 session.onExternalChange = (_file, role) => void handleExternalChange(role);
+// A gameplay frame that throws surfaces in the same banner; playback is already
+// paused by the session, so the editor stays alive until the code is fixed.
+session.onRuntimeError = (message) => setComponentError(message);
 
 async function handleExternalChange(role: 'open' | 'dep'): Promise<void> {
   if (reloading) return;
@@ -322,11 +325,19 @@ async function openFile(path: string): Promise<void> {
 }
 
 void (async () => {
-  // Register every project component, package tag, and built-in node. Imported
-  // dynamically + caught so a broken component file can't abort page startup: the
-  // WS bridge (hence MCP) and the error banner still come up. While something is
-  // broken the editor can't render scenes, but it stays alive; a full reload on
-  // the next successful HMR update revives it once every error is fixed.
+  // Core tags + tag packages first, as their own import — this is the registry
+  // every core scene decodes against, so it must NOT depend on project components
+  // loading (a broken component previously cascaded into "Background not registered").
+  try {
+    await import('virtual:scenoco-runtime');
+  } catch (e) {
+    console.error('[editor] runtime tags failed to load:', e);
+    setComponentError(e instanceof Error ? e.message : String(e));
+  }
+  // Project components, imported separately + caught so a broken component file
+  // can't abort page startup or wipe the core tags above: the WS bridge (hence
+  // MCP) and the error banner still come up, and core scenes still preview. A full
+  // reload on the next successful HMR update revives components once they're fixed.
   try {
     await import('virtual:scenoco-components');
   } catch (e) {

package/app/session.ts

@@ -1,9 +1,9 @@
 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 { Engine, PrefabRef, 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';
+import type { EditOp, EditorResult, SimStep } from '../dist/protocol.js';
 
 export type EditorMode = 'edit' | 'play';
 
@@ -19,10 +19,19 @@ export class EditorSession {
   playing = false;
   /** The editor camera (edit mode only). */
   editorCamera?: PerspectiveCamera;
+  /** A reused framing camera for play-mode previews of scenes/prefabs that have no camera of their own. */
+  private previewCamera?: 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;
+  /**
+   * Fired when a gameplay frame throws (a component hook / system error). The host
+   * shows it in the same "component code has an error" banner; the session stays
+   * alive (playback paused) so a fix + HMR reload recovers, rather than the RAF
+   * loop dying or the MCP session wedging.
+   */
+  onRuntimeError?: (message: string) => void;
 
   private bundle?: Bundle;
   /** Source path of the open scene/prefab — the target of `save`. */
@@ -86,7 +95,7 @@ export class EditorSession {
   /** 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()
+    this.runTick(dt); // bypass the play+paused gate in tick()
   }
   stop(): void {
     this.toEdit();
@@ -94,18 +103,45 @@ export class EditorSession {
 
   /** 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);
+    this.runTick(this.mode === 'play' && !this.playing ? 0 : dt);
+  }
+
+  /**
+   * Drive the engine one frame, catching any error a component hook / system
+   * throws so a single bad frame can't kill the RAF loop or the MCP session.
+   * On failure it pauses playback (so the failing frame isn't re-run every RAF)
+   * and surfaces the error to the host banner. Returns the error message, if any.
+   */
+  private runTick(dt: number): string | undefined {
+    try {
+      this.engine.tick(dt);
+      return undefined;
+    } catch (e) {
+      this.playing = false;
+      const message = e instanceof Error ? (e.stack ?? e.message) : String(e);
+      this.onRuntimeError?.(message);
+      return message;
+    }
   }
 
   /** 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);
+    if (this.mode === 'edit') {
+      if (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);
+      }
+      // Particles only emit under their play-mode render system — render a short
+      // throwaway play burst so a VFX prefab isn't previewed empty while authoring.
+      if (this.hasParticles()) return this.particlePreview(opts);
+    } else {
+      // Play mode: honor the camera override (P2) and give a camera-less lone prefab
+      // a default framed camera + backdrop, so it isn't a blank white frame.
+      this.framePlayPreview(opts);
     }
-    this.engine.tick(0); // render the current frame
+    this.runTick(0); // render the current frame (guarded — a bad frame won't wedge the session)
     return this.canvas.toDataURL('image/png');
   }
 
@@ -156,7 +192,12 @@ export class EditorSession {
         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);
+          for (let i = 0; i < frames; i++) {
+            // A throwing frame surfaces as a result (not a bare transport error)
+            // and stops the batch, leaving the session alive for the agent to inspect.
+            const error = this.runTick(dt);
+            if (error) { out.push({ kind: 'json', data: { error } }); return out; }
+          }
           break;
         }
         case 'tap':
@@ -212,35 +253,100 @@ export class EditorSession {
   }
 
   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);
-    }
+    if (this.bundle) applyBundleToEngine(this.engine, 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 sphere = box.isEmpty() ? new Sphere(new Vector3(), 1) : box.getBoundingSphere(new Sphere());
-    const center = sphere.center;
-    const 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);
+    frameCameraTo(cam, this.engine.scene);
     this.engine.mainCamera = cam;
     return cam;
   }
+
+  /** Any live `ParticleSystem` component in the scene — VFX that only emits under its play-mode render system. */
+  private hasParticles(): boolean {
+    const ctor = Registry.getComponent('ParticleSystem')?.ctor;
+    return ctor ? this.engine.getComponentsOfType(ctor).length > 0 : false;
+  }
+
+  /**
+   * Frame a preview for the current play scene: honor a `camera`/`lookAt` override
+   * (P2 — worked only in edit mode before), and give a scene with no camera of its
+   * own (a lone prefab) a default framed camera + neutral backdrop so it isn't a
+   * blank white frame. Left untouched when the scene has its own camera and no override.
+   */
+  private framePlayPreview(opts: { camera?: string; lookAt?: string }): void {
+    const camPos = vec3(opts.camera);
+    const lookAt = vec3(opts.lookAt);
+    if (this.engine.mainCamera && !camPos && !lookAt) return; // scene's own camera, no override — leave it
+    const cam = (this.previewCamera ??= new PerspectiveCamera(50, 1, 0.01, 50000));
+    cam.aspect = this.canvas.clientWidth / this.canvas.clientHeight || 1;
+    const center = frameCameraTo(cam, this.engine.scene); // auto-frame, then apply any override
+    if (camPos) cam.position.copy(camPos);
+    if (lookAt) cam.lookAt(lookAt);
+    else if (camPos) cam.lookAt(center);
+    cam.updateProjectionMatrix();
+    this.engine.mainCamera = cam; // not one of the scene's cameras → a render override
+    if (!this.engine.scene.background) this.engine.scene.background = new Color(0x15181f);
+  }
+
+  /**
+   * Render a particle-bearing file in a throwaway play engine advanced a few
+   * frames, so its VFX is actually visible when previewed while authoring (in edit
+   * mode the particle render system never runs, so the effect shows empty). The
+   * edit session's own engine is left untouched; the next frame re-renders it.
+   */
+  private particlePreview(opts: { camera?: string; lookAt?: string }): string {
+    const engine = new Engine({ canvas: this.canvas, autoStart: false, editor: false, preserveDrawingBuffer: true });
+    try {
+      if (this.bundle) applyBundleToEngine(engine, this.bundle);
+      const cam = new PerspectiveCamera(50, this.canvas.clientWidth / this.canvas.clientHeight || 1, 0.01, 50000);
+      const center = frameCameraTo(cam, engine.scene);
+      const camPos = vec3(opts.camera);
+      const lookAt = vec3(opts.lookAt);
+      if (camPos) cam.position.copy(camPos);
+      if (lookAt || camPos) cam.lookAt(lookAt ?? center);
+      cam.updateProjectionMatrix();
+      engine.mainCamera = cam;
+      for (let i = 0; i < PARTICLE_PREVIEW_FRAMES; i++) engine.tick(1 / 60);
+      return this.canvas.toDataURL('image/png');
+    } finally {
+      engine.dispose();
+    }
+  }
+}
+
+/** Frames to advance a particle preview so the effect has visibly emitted. */
+const PARTICLE_PREVIEW_FRAMES = 30;
+
+/** Instantiate a bundle into `engine`: a prefab gets neutral preview lights + backdrop; a scene loads as-is. */
+function applyBundleToEngine(engine: Engine, bundle: Bundle): void {
+  if (bundleKind(bundle) === 'prefab') {
+    engine.instantiate(bundle);
+    // Editor-only preview lights — flagged so the Hierarchy/picking ignore them.
+    const ambient = new AmbientLight(0xffffff, 0.6);
+    ambient.userData.scenocoEditorOnly = true;
+    engine.scene.add(ambient);
+    const key = new DirectionalLight(0xffffff, 2);
+    key.position.set(3, 5, 4);
+    key.userData.scenocoEditorOnly = true;
+    engine.scene.add(key);
+    if (!engine.scene.background) engine.scene.background = new Color(0x15181f);
+  } else {
+    engine.loadScene(bundle);
+  }
+}
+
+/** Position `cam` to frame `scene` from a 3/4 angle; returns the scene center it looks at. */
+function frameCameraTo(cam: PerspectiveCamera, scene: Object3D): Vector3 {
+  const box = new Box3().setFromObject(scene);
+  const sphere = box.isEmpty() ? new Sphere(new Vector3(), 1) : box.getBoundingSphere(new Sphere());
+  const center = sphere.center;
+  const 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);
+  return center;
 }
 
 // ── value helpers (telemetry → JSON) ─────────────────────────────────────────────
@@ -255,13 +361,19 @@ function propValues(component: Component): Record<string, unknown> {
 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);
+  if (v instanceof PrefabRef) return v.describe(); // a `prefab` prop → its label, not "[object Object]"
   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)';
+  // A component reference → its scene #id (what the agent correlates on), falling
+  // back to the class name only when the target has no id.
+  if ('node' in (o as object) && 'engine' in (o as object)) {
+    const c = v as Component;
+    return c.id !== undefined ? `#${c.id}` : (componentName(c) ?? '(component)');
+  }
   return String(v);
 }
 const arr = (v: { x: number; y: number; z: number }) => [round(v.x), round(v.y), round(v.z)];

package/app/vite-env.d.ts

@@ -1,5 +1,7 @@
 /// <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).
+// The editor server's plugin emits two modules: `scenoco-runtime` registers the
+// built-in node tags + tag packages, and `scenoco-components` imports every project
+// component. They're split so a broken component can't wipe the core tag registry.
+declare module 'virtual:scenoco-runtime';
 declare module 'virtual:scenoco-components';

package/app/wsClient.ts

@@ -1,4 +1,4 @@
-import { WS_PATH, type EditorCommand, type EditorPush, type EditorResponse, type EditorResult } from '../src/protocol.js';
+import { WS_PATH, type EditorCommand, type EditorPush, type EditorResponse, type EditorResult } from '../dist/protocol.js';
 import type { EditorSession } from './session.js';
 
 /**

package/dist/server.js

@@ -149,22 +149,60 @@ function createFileWatcher() {
         close: () => w.close(),
     };
 }
-/** `virtual:scenoco-components` → import every project component + package + built-in nodes. */
+/**
+ * Two virtual modules, split so a broken project component can't wipe the core
+ * tag registry (the P1 "Background not registered" cascade):
+ *  - `virtual:scenoco-runtime`    → `@scenoco-three/core/nodes` + tag packages
+ *    (the infrastructure every core scene decodes against; imported first).
+ *  - `virtual:scenoco-components` → only the project's component files (fragile —
+ *    a broken one throws here, isolated from core/package registration).
+ * The components module is invalidated when a component file is added/removed, so
+ * a deleted file never lingers as a stale import (the client-cache half of P1).
+ */
 function allComponentsPlugin(roots, packages, cwd) {
-    const id = 'virtual:scenoco-components';
-    const resolved = '\0' + id;
+    const runtimeId = 'virtual:scenoco-runtime';
+    const componentsId = 'virtual:scenoco-components';
+    const resolvedRuntime = '\0' + runtimeId;
+    const resolvedComponents = '\0' + componentsId;
+    const absRoots = roots.map((r) => resolve(cwd, r));
+    const isComponentFile = (file) => SOURCE_EXT_RE.test(file) && absRoots.some((r) => resolve(file).startsWith(r));
     return {
         name: 'scenoco:all-components',
-        resolveId: (source) => (source === id ? resolved : null),
+        resolveId: (source) => source === runtimeId ? resolvedRuntime : source === componentsId ? resolvedComponents : null,
         load(source) {
-            if (source !== resolved)
-                return null;
-            const files = [...scanComponents(roots, cwd).files.keys()].map((f) => `import ${JSON.stringify(`/@fs${f}`)};`);
-            const pkgs = packages.map((p) => `import ${JSON.stringify(p)};`);
-            return ['import "@scenoco-three/core/nodes";', ...pkgs, ...files].join('\n');
+            if (source === resolvedRuntime) {
+                // Core nodes first (so core tags register even if a package throws next), then packages.
+                return ['import "@scenoco-three/core/nodes";', ...packages.map((p) => `import ${JSON.stringify(p)};`)].join('\n');
+            }
+            if (source === resolvedComponents) {
+                return [...scanComponents(roots, cwd).files.keys()].map((f) => `import ${JSON.stringify(`/@fs${f}`)};`).join('\n') || 'export {};';
+            }
+            return null;
+        },
+        configureServer(server) {
+            // Vite's watcher is rooted at the editor app dir, so it only sees component
+            // files once they're in the module graph (already imported). Watch the project
+            // component roots explicitly, so a brand-NEW file's `add` fires too — not just
+            // edits/deletes of already-imported ones.
+            server.watcher.add(absRoots);
+            // Adding/removing a component file changes the import list — rebuild the
+            // components module (not the runtime one) and reload, so a new file gets
+            // imported and a just-deleted one isn't imported from a stale graph.
+            const invalidate = (file) => {
+                if (!isComponentFile(file))
+                    return;
+                const mod = server.moduleGraph.getModuleById(resolvedComponents);
+                if (mod)
+                    server.moduleGraph.invalidateModule(mod);
+                server.ws.send({ type: 'full-reload' });
+            };
+            server.watcher.on('add', invalidate);
+            server.watcher.on('unlink', invalidate);
         },
     };
 }
+/** Component source extensions the editor imports (mirrors the compiler's scan). */
+const SOURCE_EXT_RE = /\.[cm]?[jt]sx?$/;
 /** `GET /@scenoco/bundle?file=<abs>` → the compiled runtime bundle (JSON). */
 function bundleEndpointPlugin(roots, packages, cwd, watcher) {
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scenoco-three/editor",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Local preview + headless frame render for SceNoCo scenes/prefabs (for multimodal LLMs)",
   "type": "module",
   "license": "MIT",
@@ -32,18 +32,18 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "typecheck": "npm --prefix ../core run build && npm --prefix ../compiler run build && npm --prefix ../vite run build && tsc --noEmit -p tsconfig.json"
+    "build": "tsc -p tsconfig.build.json && chmod +x dist/cli/index.js",
+    "typecheck": "npm --prefix ../core run build && npm --prefix ../compiler run build && npm --prefix ../vite run build && npm run build && tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
-    "@scenoco-three/compiler": "^0.3.0",
-    "@scenoco-three/vite": "^0.3.0",
+    "@scenoco-three/compiler": "^0.4.0",
+    "@scenoco-three/vite": "^0.4.0",
     "chokidar": "^4.0.3",
     "ws": "^8.18.0"
   },
   "peerDependencies": {
-    "@scenoco-three/core": "^0.3.0",
+    "@scenoco-three/core": "^0.4.0",
     "three": ">=0.160",
     "vite": ">=5"
   },