@vgai/editor 0.2.0

package/src/playground/main.ts

@@ -0,0 +1,206 @@
+/**
+ * vgai Code Playground — a stranger can WRITE + RUN + SAVE a game entirely in
+ * the browser, with no backend.
+ *
+ *   CodeMirror (TS source)  → src/browser-transpile.ts (esbuild-wasm) → live
+ *   createGameRuntime (the REAL engine) → render. Source autosaves to
+ *   localStorage. Run rebuilds the runtime from the current source.
+ *
+ * This is the hands-on surface behind the tutorials' "Open the editor" links —
+ * what RunHuman testers use to actually build a game while following a lesson.
+ */
+
+import { javascript } from '@codemirror/lang-javascript';
+import { EditorState } from '@codemirror/state';
+import { oneDark } from '@codemirror/theme-one-dark';
+import { keymap } from '@codemirror/view';
+import type { VgaiMountedGame } from '@engine/adapter/vgai-scene-game-adapter';
+import * as gameComponentModule from '@engine/ecs/game-component';
+import { createGameRuntime, type GameSession } from '@engine/runtime/create-runtime';
+import { basicSetup, EditorView } from 'codemirror';
+import * as THREE from 'three';
+
+// Disable auto-close-brackets: beginner testers typing a full component (incl.
+// their own closing braces) would otherwise get DOUBLED braces → a syntax error.
+// What-you-type-is-what-you-get is the right model for a learn-by-coding surface.
+const noAutoCloseBrackets = EditorState.languageData.of(() => [
+  { closeBrackets: { brackets: [] } },
+]);
+
+import { importFromSource, registerRuntimeModules } from '../browser-transpile';
+
+// Let in-browser-transpiled user code share the running engine's singletons
+// (so `extends GameComponent` and `instanceof THREE.*` work across the boundary).
+registerRuntimeModules({
+  three: THREE as unknown as Record<string, unknown>,
+  '@engine/ecs/game-component': gameComponentModule as unknown as Record<string, unknown>,
+});
+
+const STORAGE_KEY = 'vgai-playground-source-v1';
+
+const STARTER = `import { GameComponent } from '@engine/ecs/game-component';
+import * as THREE from 'three';
+
+// A GameComponent is gameplay attached to a Three.js object.
+// init() runs once; update(dt) runs every frame. Edit and press Run!
+export class Spinner extends GameComponent {
+  t = 0;
+
+  update(dt) {
+    this.t += dt;
+    // spin
+    this.object3D.rotation.y += dt * 1.5;
+    this.object3D.rotation.x += dt * 0.6;
+    // bob up and down
+    this.object3D.position.y = Math.sin(this.t * 2) * 0.4;
+    // shift color over time
+    const hue = (this.t * 0.1) % 1;
+    this.object3D.material.color.setHSL(hue, 0.6, 0.55);
+  }
+}
+`;
+
+const codeEl = document.getElementById('code') as HTMLElement;
+const statusEl = document.getElementById('status') as HTMLElement;
+const runBtn = document.getElementById('run') as HTMLButtonElement;
+const resetBtn = document.getElementById('reset') as HTMLButtonElement;
+const canvas = document.getElementById('c') as HTMLCanvasElement;
+
+function setStatus(msg: string, kind: 'ok' | 'err' | '' = ''): void {
+  statusEl.textContent = msg;
+  statusEl.className = kind;
+}
+
+// --- CodeMirror editor ---------------------------------------------------
+const saved = localStorage.getItem(STORAGE_KEY);
+const runKeymap = keymap.of([
+  {
+    key: 'Mod-s',
+    run: () => {
+      void run();
+      return true;
+    },
+    preventDefault: true,
+  },
+  {
+    key: 'Mod-Enter',
+    run: () => {
+      void run();
+      return true;
+    },
+    preventDefault: true,
+  },
+]);
+const view = new EditorView({
+  doc: saved ?? STARTER,
+  parent: codeEl,
+  extensions: [
+    basicSetup,
+    noAutoCloseBrackets,
+    javascript({ typescript: true }),
+    oneDark,
+    runKeymap,
+    EditorView.updateListener.of((u) => {
+      if (u.docChanged) localStorage.setItem(STORAGE_KEY, view.state.doc.toString());
+    }),
+  ],
+});
+
+// --- Runtime -------------------------------------------------------------
+let session: GameSession | null = null;
+let cube: THREE.Mesh | null = null;
+
+function findComponentClass(mod: Record<string, unknown>): (new () => object) | null {
+  const Base = gameComponentModule.GameComponent;
+  // Prefer an exported class whose prototype extends GameComponent.
+  for (const v of Object.values(mod)) {
+    if (typeof v === 'function' && v.prototype instanceof Base) return v as new () => object;
+  }
+  // Fall back to the first exported function (class).
+  for (const v of Object.values(mod)) {
+    if (typeof v === 'function') return v as new () => object;
+  }
+  return null;
+}
+
+async function run(): Promise<void> {
+  const source = view.state.doc.toString();
+  localStorage.setItem(STORAGE_KEY, source);
+  setStatus('transpiling + running…');
+  let mod: Record<string, unknown>;
+  try {
+    mod = await importFromSource(source, 'playground.tsx');
+  } catch (err) {
+    setStatus(`Transpile error:\n${err}`, 'err');
+    return;
+  }
+  const Cls = findComponentClass(mod) as
+    | (new () => InstanceType<typeof gameComponentModule.GameComponent>)
+    | null;
+  if (!Cls) {
+    setStatus(
+      'No exported GameComponent class found. Export a class that `extends GameComponent`.',
+      'err',
+    );
+    return;
+  }
+  const OK = '✓ running — edit the code and press Run (or ⌘/Ctrl+S) to update.';
+  try {
+    if (session && cube) {
+      // Re-run: swap the component on the LIVE runtime — never re-create the
+      // renderer (a 2nd createGameRuntime on the same canvas loses the WebGL
+      // context). detach+attach also handles a renamed class cleanly.
+      const ctx = (session.mounted as VgaiMountedGame).ctx;
+      ctx.components.detach(cube);
+      // No manual initAll() here (T1.11): the ComponentManager now flushes
+      // pending init() automatically at the frame boundary, before the new
+      // instance's first update() — nothing after this depends on init()
+      // having completed synchronously.
+      ctx.components.attach(cube, new Cls());
+      setStatus(OK, 'ok');
+      return;
+    }
+    // First run: build the runtime once.
+    session = await createGameRuntime({
+      canvas,
+      width: canvas.clientWidth,
+      height: canvas.clientHeight,
+      setup: async (ctx) => {
+        ctx.camera.position.set(3, 2.5, 3);
+        ctx.camera.lookAt(0, 0, 0);
+        ctx.scene.background = new THREE.Color('#14161a');
+        ctx.scene.add(new THREE.AmbientLight(0xffffff, 0.75));
+        const dir = new THREE.DirectionalLight(0xffffff, 1.2);
+        dir.position.set(5, 8, 4);
+        ctx.scene.add(dir);
+        const grid = new THREE.GridHelper(10, 10, 0x444444, 0x222222);
+        grid.position.y = -1;
+        ctx.scene.add(grid);
+
+        cube = new THREE.Mesh(
+          new THREE.BoxGeometry(1.4, 1.4, 1.4),
+          new THREE.MeshStandardMaterial({ color: '#888', roughness: 0.4, metalness: 0.1 }),
+        );
+        ctx.scene.add(cube);
+        // No manual initAll() (T1.11) — see the comment in the re-run branch
+        // above; the automatic frame-boundary flush covers this.
+        ctx.components.attach(cube, new Cls());
+        return { dispose() {} };
+      },
+    });
+    setStatus(OK, 'ok');
+  } catch (err) {
+    setStatus(`Runtime error:\n${err}`, 'err');
+  }
+}
+
+runBtn.addEventListener('click', () => void run());
+resetBtn.addEventListener('click', () => {
+  view.dispatch({ changes: { from: 0, to: view.state.doc.length, insert: STARTER } });
+  localStorage.setItem(STORAGE_KEY, STARTER);
+  void run();
+});
+window.addEventListener('resize', () => session?.resize(canvas.clientWidth, canvas.clientHeight));
+
+// Boot: run whatever's in the editor (saved or starter).
+void run();

package/src/project-manager.ts

@@ -0,0 +1,173 @@
+/**
+ * Project manager — manages the active game project.
+ *
+ * The editor receives the project path via a `?project=` URL parameter
+ * or the `__VGAI_PROJECT_PATH__` define injected by the dev server.
+ * Projects can also be switched at runtime via `switchProject()`.
+ */
+
+import { getCurrentServerProject, openProjectOnServer } from './editor-api';
+import { getEditorMode } from './editor-mode';
+import { getStorageBackend, restorePersistedProjectRoot } from './storage';
+import { readProjectManifest, seedIfEmpty } from './storage/seed';
+
+export interface ProjectConfig {
+  name: string;
+  resolution?: { width: number; height: number } | undefined;
+  appId?: string | undefined;
+  /**
+   * The project's default scene path, or `null` when the manifest's first
+   * world declares no scene (e.g. an `entry`-only world — §7.1-12). Always
+   * present when synthesized from a manifest (`readProjectView`, server-side);
+   * a hand-authored legacy `project.json` may still omit the key entirely
+   * (verbatim pass-through — §1C), which `loadInitialScene` treats the same
+   * as `null`. Consumers must NOT default a missing/null value to a guessed
+   * path — that was the bug (initial-scene.ts guessing
+   * 'scenes/default.vscn.json' and silently writing a placeholder scene).
+   */
+  defaultScene?: string | null | undefined;
+}
+
+export interface ActiveProject {
+  /** Absolute path to the project root (as passed via URL param / env). */
+  rootPath: string;
+  /** Parsed project.json contents. */
+  config: ProjectConfig;
+  /**
+   * Set when this project is a BUNDLED EXAMPLE opened in the hosted (browser)
+   * build via `?project=<id>` — the `examples/<id>/` folder name, which is also
+   * the `SETUP_BY_EXAMPLE_ID` dispatch key and the `/examples/<id>/` staging
+   * prefix (docs/EXAMPLES-AS-PROJECTS-DESIGN.md §H). Example projects are
+   * read-only: their scenes load with no save path, so autosave is inert.
+   */
+  exampleId?: string;
+}
+
+let _activeProject: ActiveProject | null = null;
+const _listeners = new Set<() => void>();
+
+function _notify(): void {
+  for (const fn of _listeners) fn();
+}
+
+/** Open a project by its root path. Fetches project.json from the server. */
+export async function openProject(rootPath: string): Promise<ActiveProject> {
+  const res = await fetch('/project.json');
+  if (!res.ok) {
+    throw new Error(`Failed to load project.json: ${res.status} ${res.statusText}`);
+  }
+  const config = (await res.json()) as ProjectConfig;
+  _activeProject = { rootPath, config };
+  _notify();
+  return _activeProject;
+}
+
+/**
+ * Switch to a different project at runtime.
+ * Tells the server to update its project root, then refreshes local state.
+ */
+export async function switchProject(projectPath: string): Promise<ActiveProject> {
+  const result = await openProjectOnServer(projectPath);
+  if (!result.ok || !result.config) {
+    throw new Error(`Failed to open project at ${projectPath}`);
+  }
+  _activeProject = { rootPath: projectPath, config: result.config as ProjectConfig };
+  _notify();
+  return _activeProject;
+}
+
+/** Set the active project directly (e.g. from the project screen). */
+export function setActiveProject(project: ActiveProject): void {
+  _activeProject = project;
+  _notify();
+}
+
+/** Get the currently open project, or null if none. */
+export function getCurrentProject(): ActiveProject | null {
+  return _activeProject;
+}
+
+/** Subscribe to project changes. Returns unsubscribe function. */
+export function onProjectChange(fn: () => void): () => void {
+  _listeners.add(fn);
+  return () => _listeners.delete(fn);
+}
+
+declare const __VGAI_PROJECT_PATH__: string;
+
+/** Read the project path from URL param or Vite define. */
+export function getProjectPathFromURL(): string | null {
+  const params = new URLSearchParams(window.location.search);
+  const fromURL = params.get('project');
+  if (fromURL) return fromURL;
+
+  // Fallback: injected by dev server via define
+  if (typeof __VGAI_PROJECT_PATH__ === 'string' && __VGAI_PROJECT_PATH__) {
+    return __VGAI_PROJECT_PATH__;
+  }
+
+  return null;
+}
+
+/**
+ * Detect and open whatever project the server currently has active.
+ * Used in production where __VGAI_PROJECT_PATH__ isn't available at build time.
+ */
+export async function detectServerProject(): Promise<ActiveProject | null> {
+  const info = await getCurrentServerProject();
+  if (!info) return null;
+  _activeProject = { rootPath: info.path, config: info.config as ProjectConfig };
+  _notify();
+  return _activeProject;
+}
+
+/**
+ * Detect if a project is already specified (via URL param, Vite define, or server).
+ * Returns the project if found, null if the project screen should be shown.
+ */
+export async function detectProject(): Promise<ActiveProject | null> {
+  // Browser-first build: no server. `?project=<exampleId>` opens a bundled
+  // example staged at `/examples/<id>/` (Track H — legacy flat-pool `?scene=`
+  // links are rewritten onto that scheme first); otherwise seed a Starter into
+  // the in-browser VFS and open it directly (skips the server-oriented
+  // project screen).
+  if (getEditorMode() === 'browser') {
+    const { applyLegacyPoolRedirect, openExampleProject } = await import('./hosted-example');
+    applyLegacyPoolRedirect();
+    const exampleId = new URLSearchParams(window.location.search).get('project');
+    if (exampleId) {
+      try {
+        _activeProject = await openExampleProject(exampleId);
+        _notify();
+        return _activeProject;
+      } catch (err) {
+        // Unknown/broken example link — fall through to the seeded Starter so
+        // the editor still opens, but say why loudly.
+        console.error(`[vgai] Failed to open example project "${exampleId}":`, err);
+      }
+    }
+    // Reopen the last-picked on-disk folder (File System Access) when its
+    // permission survived the reload — so disk authoring persists across
+    // reloads instead of dropping back into the OPFS sandbox. A folder that
+    // needs a fresh permission gesture can't be reopened without a user click,
+    // so we bail to the project screen (returns null) where a one-click reopen
+    // is offered; nothing remembered → seed/open the OPFS Starter as before.
+    const restored = await restorePersistedProjectRoot();
+    if (restored?.status === 'prompt') return null;
+    const backend = getStorageBackend();
+    await seedIfEmpty(backend);
+    const config = await readProjectManifest(backend);
+    _activeProject = { rootPath: restored?.status === 'granted' ? 'fsa' : 'browser', config };
+    _notify();
+    return _activeProject;
+  }
+
+  // 1. Check URL param or Vite define
+  const projectPath = getProjectPathFromURL();
+  if (projectPath) {
+    return openProject(projectPath);
+  }
+
+  // 2. Check if the server already has a project active
+  return detectServerProject();
+}

package/src/scene-diff.ts

@@ -0,0 +1,112 @@
+/**
+ * Scene diff — computes minimal operations to transform one SceneFile into another.
+ *
+ * Compares entities by ID. Produces add/remove/update/move operations that can be
+ * applied incrementally to the editor store without a full scene rebuild.
+ *
+ * The inverse of this — `applyDiff` — lives in the engine
+ * (`@engine/scene/scene-apply`), not here, so that `packages/vgai-cli`
+ * (`vgai apply-diff`, T4.5) can reach it without a new cli→editor dependency
+ * edge; see that module's jsdoc for the full rationale. `DiffOp`/`SceneDiff`
+ * are accordingly DEFINED in the engine (`@engine/scene/scene-diff-types`)
+ * and just re-exported here so this stays the only file that COMPUTES a
+ * diff, and no existing import of these two type names (elsewhere in the
+ * editor) needs to change.
+ */
+
+import type { DiffOp, SceneDiff } from '@engine/scene/scene-diff-types';
+import type { SceneEntity, SceneFile } from '@engine/scene/scene-types';
+
+export type { DiffOp, SceneDiff };
+
+interface FlatEntry {
+  entity: SceneEntity;
+  parentId: string | null;
+  index: number;
+}
+
+/** Flatten an entity tree into a map of id → { entity (without children), parentId, index }. */
+function flattenEntities(entities: SceneEntity[], parentId: string | null): Map<string, FlatEntry> {
+  const map = new Map<string, FlatEntry>();
+  for (let i = 0; i < entities.length; i++) {
+    const e = entities[i]!;
+    if (!e.id) continue;
+    // Store entity without children for comparison
+    const { children: _, ...rest } = e;
+    map.set(e.id, { entity: rest as SceneEntity, parentId, index: i });
+    if (e.children) {
+      for (const [k, v] of flattenEntities(e.children, e.id)) {
+        map.set(k, v);
+      }
+    }
+  }
+  return map;
+}
+
+/** Deep equality check via JSON serialization (sufficient for scene entity data). */
+function deepEqual(a: unknown, b: unknown): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+/** Compare entity fields (excluding children and id) to detect property changes. */
+function entityFieldsChanged(a: SceneEntity, b: SceneEntity): boolean {
+  // Compare all fields except id and children
+  const { id: _aId, children: _aC, ...aRest } = a;
+  const { id: _bId, children: _bC, ...bRest } = b;
+  return !deepEqual(aRest, bRest);
+}
+
+export function diffScene(oldDoc: SceneFile, newDoc: SceneFile): SceneDiff {
+  const ops: DiffOp[] = [];
+
+  const oldMap = flattenEntities(oldDoc.entities, null);
+  const newMap = flattenEntities(newDoc.entities, null);
+
+  // Removed entities (in old but not in new) — process deepest first to avoid parent issues
+  const removedIds: string[] = [];
+  for (const id of oldMap.keys()) {
+    if (!newMap.has(id)) removedIds.push(id);
+  }
+  // Reverse so children are removed before parents
+  removedIds.reverse();
+  for (const id of removedIds) {
+    ops.push({ type: 'remove', id });
+  }
+
+  // Added entities (in new but not in old) — process shallowest first
+  for (const [id, entry] of newMap) {
+    if (!oldMap.has(id)) {
+      ops.push({ type: 'add', entity: entry.entity, parentId: entry.parentId, index: entry.index });
+    }
+  }
+
+  // Updated and moved entities (in both)
+  for (const [id, newEntry] of newMap) {
+    const oldEntry = oldMap.get(id);
+    if (!oldEntry) continue;
+
+    // Check for property changes
+    if (entityFieldsChanged(oldEntry.entity, newEntry.entity)) {
+      ops.push({ type: 'update', id, entity: newEntry.entity });
+    }
+
+    // Check for reparent/reorder
+    if (oldEntry.parentId !== newEntry.parentId || oldEntry.index !== newEntry.index) {
+      ops.push({ type: 'move', id, parentId: newEntry.parentId, index: newEntry.index });
+    }
+  }
+
+  // Environment
+  const environmentChanged = !deepEqual(oldDoc.environment, newDoc.environment);
+
+  // Metadata
+  const metaChanged = oldDoc.name !== newDoc.name;
+
+  return {
+    ops,
+    environmentChanged,
+    newEnvironment: environmentChanged ? newDoc.environment : undefined,
+    metaChanged,
+    newName: metaChanged ? newDoc.name : undefined,
+  };
+}

package/src/scene-serializer.ts

@@ -0,0 +1,144 @@
+/**
+ * Scene serializer — extracts a SceneFile from the live Three.js scene graph.
+ *
+ * Each entity object in the scene carries its SceneEntity descriptor in
+ * `userData['entity']`. The serializer walks the graph, reads those descriptors,
+ * overwrites transforms with the live object transforms, and reconstructs
+ * the tree from parent-child relationships.
+ *
+ * Used by: save, undo push, play-mode snapshot.
+ */
+
+import type { SceneEntity, SceneEnvironment, SceneFile } from '@engine/scene/scene-types';
+import type { UIRoot } from '@engine/scene/schema';
+import { getUserData } from '@engine/scene/user-data';
+import type * as THREE from 'three';
+
+export interface SceneMetadata {
+  version: number;
+  name: string;
+  environment?: SceneEnvironment;
+  /** Scene-graph UI (the `ui` field) — preserved through load/serialize (A1/C9). */
+  ui?: UIRoot[];
+}
+
+type Transform = NonNullable<SceneEntity['transform']>;
+
+const EPS = 1e-6;
+
+/**
+ * True if a transform is the identity (position 0, rotation identity quat,
+ * scale 1) — i.e. the default applied by the entity factory. Such transforms
+ * are omitted from serialized output to avoid spurious diff churn (ED9).
+ */
+export function isDefaultTransform(t: Transform | undefined): boolean {
+  if (!t) return true;
+  const p = t.position ?? [0, 0, 0];
+  const r = t.rotation ?? [0, 0, 0, 1];
+  const s = t.scale ?? [1, 1, 1];
+  return (
+    Math.abs(p[0]) < EPS &&
+    Math.abs(p[1]) < EPS &&
+    Math.abs(p[2]) < EPS &&
+    Math.abs(r[0]) < EPS &&
+    Math.abs(r[1]) < EPS &&
+    Math.abs(r[2]) < EPS &&
+    Math.abs(r[3] - 1) < EPS &&
+    Math.abs(s[0] - 1) < EPS &&
+    Math.abs(s[1] - 1) < EPS &&
+    Math.abs(s[2] - 1) < EPS
+  );
+}
+
+/**
+ * Serialize the live Three.js scene into a SceneFile.
+ *
+ * Walks `scene.children` recursively, collecting `userData['entity']` from
+ * each entity object and overwriting its transform with the live values.
+ */
+export function serializeScene(scene: THREE.Scene, meta: SceneMetadata): SceneFile {
+  const entities = serializeChildren(scene);
+
+  const doc: SceneFile = {
+    version: meta.version,
+    name: meta.name,
+    entities,
+  };
+
+  if (meta.environment) {
+    doc.environment = meta.environment;
+  }
+  if (meta.ui && meta.ui.length > 0) {
+    doc.ui = meta.ui;
+  }
+
+  return doc;
+}
+
+/** Recursively collect entity descriptors from an object's children. */
+function serializeChildren(parent: THREE.Object3D): SceneEntity[] {
+  const result: SceneEntity[] = [];
+
+  for (const child of parent.children) {
+    // Only process objects that are entities (have entityId), not helpers
+    if (getUserData(child, 'entityId') === undefined) continue;
+    if (getUserData(child, 'editorHelper')) continue;
+
+    const stored = getUserData(child, 'entity') as SceneEntity | undefined;
+    if (!stored) continue;
+
+    // Deep clone the stored descriptor so we don't mutate it
+    const entity: SceneEntity = JSON.parse(JSON.stringify(stored)) as SceneEntity;
+
+    // Overwrite transform from live Three.js values. Omit a default/identity
+    // transform to avoid spurious diff churn (ED9).
+    if (!entity.boneAttachment) {
+      const transform: Transform = {
+        position: [child.position.x, child.position.y, child.position.z],
+        rotation: [child.quaternion.x, child.quaternion.y, child.quaternion.z, child.quaternion.w],
+        scale: [child.scale.x, child.scale.y, child.scale.z],
+      };
+      if (isDefaultTransform(transform)) {
+        delete entity.transform;
+      } else {
+        entity.transform = transform;
+      }
+    }
+
+    // Recurse into children (filter out helpers, only entity children)
+    const childEntities = serializeChildren(child);
+    if (childEntities.length > 0) {
+      entity.children = childEntities;
+    } else {
+      delete entity.children;
+    }
+
+    result.push(entity);
+  }
+
+  return result;
+}
+
+/**
+ * Strip empty/default values from a serialized SceneFile for clean output.
+ * Matches the cleanup logic in the old `EditorStore.getDocument()`.
+ */
+export function cleanDocument(doc: SceneFile): SceneFile {
+  const cleaned = JSON.parse(JSON.stringify(doc)) as SceneFile;
+  walkEntities(cleaned.entities, (e) => {
+    // Strip empty children arrays
+    if (e.children && e.children.length === 0) delete e.children;
+    // Strip zero pivots
+    if (e.pivot && e.pivot[0] === 0 && e.pivot[1] === 0 && e.pivot[2] === 0) delete e.pivot;
+    // Strip default/identity transforms (ED9)
+    if (e.transform && isDefaultTransform(e.transform)) delete e.transform;
+  });
+  return cleaned;
+}
+
+function walkEntities(entities: SceneEntity[], fn: (e: SceneEntity) => void): void {
+  for (const e of entities) {
+    fn(e);
+    if (e.children) walkEntities(e.children, fn);
+  }
+}