@vgai/editor 0.2.0

package/src/storage/opfs-storage.ts

@@ -0,0 +1,25 @@
+/**
+ * Browser `StorageBackend` over the Origin Private File System (OPFS).
+ *
+ * OPFS is a sandboxed, origin-scoped filesystem available in all modern browsers
+ * via `navigator.storage.getDirectory()`. It needs no server and no permission
+ * prompt — the zero-friction default for a self-contained, server-less editor.
+ * To edit a user's REAL on-disk folder instead, use `FsaStorage` (same logic,
+ * different root handle).
+ *
+ * All behavior lives in `HandleStorage`; this subclass only supplies the OPFS
+ * root handle.
+ */
+
+import { HandleStorage } from './handle-storage';
+
+export class OpfsStorage extends HandleStorage {
+  readonly id = 'opfs';
+
+  private rootPromise: Promise<FileSystemDirectoryHandle> | null = null;
+
+  protected rootHandle(): Promise<FileSystemDirectoryHandle> {
+    if (!this.rootPromise) this.rootPromise = navigator.storage.getDirectory();
+    return this.rootPromise;
+  }
+}

package/src/storage/paths.ts

@@ -0,0 +1,26 @@
+/**
+ * Path helpers for storage backends. Paths are POSIX-style, root-relative,
+ * '/'-separated, with no leading/trailing slashes.
+ */
+
+/** Split a path into non-empty segments, collapsing `.` and redundant slashes. */
+export function segments(path: string): string[] {
+  return path.split('/').filter((s) => s.length > 0 && s !== '.');
+}
+
+/** Normalize to a canonical root-relative path (`''` for the root). */
+export function normalize(path: string): string {
+  return segments(path).join('/');
+}
+
+/** Split into `[parentDir, baseName]`. Root entries have `parent === ''`. */
+export function dirAndBase(path: string): [string, string] {
+  const segs = segments(path);
+  const base = segs.pop() ?? '';
+  return [segs.join('/'), base];
+}
+
+/** Join path parts into a normalized path. */
+export function join(...parts: string[]): string {
+  return normalize(parts.join('/'));
+}

package/src/storage/seed.ts

@@ -0,0 +1,106 @@
+/**
+ * First-run seeding for the browser-first build.
+ *
+ * On a fresh OPFS (or any empty backend) the editor would otherwise have no
+ * project. `seedIfEmpty` writes a MINIMAL Starter — one asset-free scene, a
+ * default input map, and a project manifest — so the browser editor opens to a
+ * usable scene with no server and no download. Asset-heavy examples (models,
+ * textures, audio) are intentionally NOT seeded; they load on demand and would
+ * require routing the engine's asset pipeline through the backend.
+ */
+
+import { parseSceneFile } from '@engine/scene/parse';
+import type { StorageBackend } from './types';
+
+export const STARTER_SCENE_PATH = 'scenes/default.vscn.json';
+const STARTER_INPUTMAP_PATH = 'inputmaps/default.inputmap.json';
+const PROJECT_MANIFEST_PATH = 'project.json';
+
+/** Minimal, asset-free scene: a camera, a light, a ground plane, and a box. */
+const STARTER_SCENE = {
+  version: 1,
+  name: 'Starter',
+  entities: [
+    {
+      name: 'Camera',
+      camera: { type: 'perspective' },
+      transform: { position: [4, 3, 5], rotation: [-0.18, 0.36, 0.07, 0.91] },
+    },
+    {
+      name: 'Sun',
+      light: { type: 'directional', intensity: 2 },
+      transform: { position: [5, 8, 4] },
+    },
+    {
+      name: 'Ambient',
+      light: { type: 'hemisphere', color: '#ffffff', groundColor: '#444444', intensity: 0.5 },
+    },
+    {
+      name: 'Ground',
+      mesh: { type: 'plane' },
+      material: { type: 'standard', color: '#3a3f47' },
+      // -90° about X (lay the plane flat); -sqrt(1/2) / sqrt(1/2) quaternion.
+      transform: { rotation: [-Math.SQRT1_2, 0, 0, Math.SQRT1_2], scale: [20, 20, 20] },
+    },
+    {
+      name: 'Box',
+      mesh: { type: 'box' },
+      material: { type: 'standard', color: '#579eff' },
+      transform: { position: [0, 0.5, 0] },
+    },
+  ],
+};
+
+/** Minimal WASD + jump input map. */
+const STARTER_INPUTMAP = {
+  version: 1,
+  actions: {
+    move_forward: { bindings: [{ type: 'key', code: 'KeyW' }] },
+    move_backward: { bindings: [{ type: 'key', code: 'KeyS' }] },
+    move_left: { bindings: [{ type: 'key', code: 'KeyA' }] },
+    move_right: { bindings: [{ type: 'key', code: 'KeyD' }] },
+    jump: { bindings: [{ type: 'key', code: 'Space' }] },
+  },
+};
+
+const PROJECT_MANIFEST = {
+  name: 'Browser Project',
+  defaultScene: STARTER_SCENE_PATH,
+};
+
+/**
+ * Seed the Starter project into `backend` if it has not been seeded yet.
+ * Idempotent — returns immediately once a VALID default scene exists.
+ *
+ * Self-healing: if a default scene already exists but no longer parses against
+ * the engine schema (e.g. an earlier build seeded an invalid scene), it is
+ * re-seeded. This repairs browsers whose OPFS holds a stale/broken Starter —
+ * `exists()` alone would skip them forever and the editor would fall back to a
+ * bare scene on every visit.
+ */
+export async function seedIfEmpty(backend: StorageBackend): Promise<void> {
+  if (await backend.exists(STARTER_SCENE_PATH)) {
+    // Validate the existing scene; only re-seed the scene file if it's broken.
+    try {
+      parseSceneFile(JSON.parse(await backend.read(STARTER_SCENE_PATH)));
+      return; // valid — leave the user's scene (possibly edited) untouched
+    } catch {
+      await backend.write(STARTER_SCENE_PATH, JSON.stringify(STARTER_SCENE, null, 2));
+      return;
+    }
+  }
+  await backend.write(STARTER_SCENE_PATH, JSON.stringify(STARTER_SCENE, null, 2));
+  await backend.write(STARTER_INPUTMAP_PATH, JSON.stringify(STARTER_INPUTMAP, null, 2));
+  await backend.write(PROJECT_MANIFEST_PATH, JSON.stringify(PROJECT_MANIFEST, null, 2));
+}
+
+/** Read the project manifest from a backend, or a default if absent. */
+export async function readProjectManifest(
+  backend: StorageBackend,
+): Promise<{ name: string; defaultScene: string }> {
+  try {
+    return JSON.parse(await backend.read(PROJECT_MANIFEST_PATH));
+  } catch {
+    return { ...PROJECT_MANIFEST };
+  }
+}

package/src/storage/types.ts

@@ -0,0 +1,110 @@
+/**
+ * Backend-agnostic file interface for the editor.
+ *
+ * The editor and engine read/write project files through one `StorageBackend`
+ * and never learn whether the bytes live on a local filesystem (Node server) or
+ * in the browser (OPFS / File System Access). Swapping the backend is what turns
+ * the editor server-less: the same code paths (scene load/save, asset listing,
+ * in-browser HMR script reads) run unchanged against either implementation.
+ *
+ * Scope — this interface deliberately covers ONLY what reduces to file
+ * operations. Three editor concerns do not, and are handled elsewhere:
+ *   - native folder dialogs / "reveal in OS file manager" → `HostCapabilities`
+ *   - the `vgai` CLI control channel (SSE + command RPC) → server-only, dropped
+ *     in a pure-browser editor
+ *   - `export` / packaging (spawns a build) → a client-side bundler in-browser
+ *
+ * `watch` is part of the interface but its semantics are backend-specific: a
+ * server backend reports real filesystem events (chokidar); a browser backend
+ * has no OS file-change notifications, so it derives events from its OWN writes
+ * (in a server-less editor the editor is the only writer — which is exactly the
+ * signal HMR needs).
+ *
+ * Paths are POSIX-style, project-root-relative, '/'-separated, no leading slash
+ * (e.g. `src/scripts/components/spin.ts`).
+ */
+
+export type NodeType = 'file' | 'dir';
+
+export interface Stat {
+  /** Normalized, root-relative path. */
+  path: string;
+  type: NodeType;
+  /** Byte length for files; 0 for directories. */
+  size: number;
+  /** Last-modified time, epoch ms (0 if the backend cannot report it). */
+  mtime: number;
+}
+
+export interface DirEntry {
+  /** Base name (no slashes). */
+  name: string;
+  /** Normalized, root-relative path. */
+  path: string;
+  type: NodeType;
+  /** Byte length for files (omitted for directories). */
+  size?: number;
+}
+
+export type WatchEventType = 'create' | 'update' | 'remove';
+
+export interface WatchEvent {
+  type: WatchEventType;
+  /** Normalized, root-relative path of the affected node. */
+  path: string;
+}
+
+export type WatchCallback = (event: WatchEvent) => void;
+
+/**
+ * The one file interface every storage backend implements. All methods take and
+ * return normalized, root-relative POSIX paths.
+ */
+export interface StorageBackend {
+  /** Stable identifier for the active backend (for diagnostics/feature flags). */
+  readonly id: string;
+
+  /** Read a UTF-8 text file. Rejects if the path is missing or is a directory. */
+  read(path: string): Promise<string>;
+  /** Read raw bytes. Rejects if the path is missing or is a directory. */
+  readBytes(path: string): Promise<Uint8Array>;
+
+  /** Write a file, creating parent directories as needed. Emits a watch event. */
+  write(path: string, data: string | Uint8Array): Promise<void>;
+
+  /** Shallow directory listing. Rejects if the path is missing or is a file. */
+  list(dir: string): Promise<DirEntry[]>;
+
+  /** Stat a node, or resolve to `null` if it does not exist. */
+  stat(path: string): Promise<Stat | null>;
+
+  /** Convenience existence check. */
+  exists(path: string): Promise<boolean>;
+
+  /** Recursively create a directory (no-op if it already exists). */
+  mkdir(path: string): Promise<void>;
+
+  /** Recursively remove a file or directory (no-op if missing). Emits an event. */
+  remove(path: string): Promise<void>;
+
+  /** Subscribe to change events. Returns an unsubscribe function. */
+  watch(callback: WatchCallback): () => void;
+}
+
+/**
+ * Non-file host capabilities, kept separate from `StorageBackend` because they
+ * do not reduce to path operations. A backend may implement none of these — a
+ * pure-browser host typically omits `reveal`, and exposes `pickProjectRoot`
+ * only where the File System Access API is available.
+ */
+export interface HostCapabilities {
+  /**
+   * Prompt the user to choose a project root and return a backend rooted there.
+   * Browser: `showDirectoryPicker()` (Chromium). Resolves to `null` if the user
+   * cancels. Absent entirely where unsupported.
+   */
+  pickProjectRoot?(): Promise<StorageBackend | null>;
+
+  /** Reveal a path in the OS file manager. Absent in the browser. */
+  reveal?(path: string): Promise<void>;
+}

package/src/tool-loader.ts

@@ -0,0 +1,291 @@
+/**
+ * Project-tool loader — W4/W3 of `docs/DATA-TOOLS-DESIGN.md` (§3.1 contract,
+ * §3.5 discovery). The tool sibling of `script-loader.ts`: project
+ * `src/tools/*.tool.tsx` modules are dynamically imported via Vite's `/@fs/`
+ * path (the same loader pattern, cache-busted with `?t=` on every refresh so
+ * a re-discover always gets fresh code).
+ *
+ * The registry here is LIVE project state derived from the folder scan
+ * (`GET /__editor/tool-files`, editor-server.ts) — never a cached manifest
+ * (§3.5 rule 2). Dock tools (`placement: 'dock'`) are consumed by
+ * `BottomPanel` through the tiny subscribe/get store below
+ * (`useSyncExternalStore`-shaped, mirroring `editorConsole`'s contract).
+ * Inspector tools (`placement: 'inspector'`, W3) are threaded into the
+ * PERMANENT section seam instead: each one becomes an
+ * `inspector-section-registry` registration (the same contract the
+ * first-party adapters use), wrapped in `InspectorToolSection`'s
+ * editor-styled chrome + error boundary. The registry's own change
+ * notification re-renders the inspector shell when tools (re)load.
+ *
+ * HMR: `dev.ts`'s `vgai-script-hmr` plugin already broadcasts
+ * `vgai:script-update` for every project `.tsx` change (the same event
+ * `play-mode.ts` reloads scripts from). The module-level listener at the
+ * bottom re-runs the whole discover+import pass whenever the changed file
+ * lives under `src/tools/` — Vite has already invalidated the changed
+ * module(s) in its graph by then, so the cache-busted re-import picks up
+ * edits to a tool AND to any helper module it imports, no editor reload.
+ *
+ * Failure physics (§6.5 "errors teach", §3's "never crashes the editor"):
+ * a tool file that fails to import, or that lacks the `tool`/default-component
+ * export pair, gets ONE console teaching error naming the file and citing the
+ * template example, and is skipped — every other tool still loads. A throwing
+ * inspector `match` is caught per call (logged once per load) and treated as
+ * "no match". Render-time crashes are the error boundary's job
+ * (`ToolHost.tsx` / `InspectorToolSection.tsx`), not ours.
+ */
+
+import type { AuthoringAdapter, EditorNode } from '@engine/adapter';
+import type { InspectorToolProps, ToolConfig } from '@engine/tools/define-tool';
+import { type ComponentType, createElement } from 'react';
+import { InspectorToolSection } from './components/InspectorToolSection';
+import { registerInspectorSections } from './inspector-section-registry';
+import { getCurrentProject } from './project-manager';
+
+/** Fields shared by every successfully loaded project tool. */
+interface LoadedToolBase {
+  /** `ToolConfig.id` — the mount's `data-testid` suffix. */
+  id: string;
+  /** `ToolConfig.title` — the tab label / section header (after ⚙, §3.5). */
+  title: string;
+  /** Project-relative source file, e.g. `src/tools/example.tool.tsx`. */
+  file: string;
+  /** Bumped on every (re)load — keys the host so an HMR reload remounts the
+   *  component fresh and clears any tripped error boundary. */
+  version: number;
+}
+
+/** One successfully loaded dock tool, ready for `BottomPanel` to render. */
+export interface DockTool extends LoadedToolBase {
+  placement: 'dock';
+  /** The module's default export — plain React, rendered inside `ToolHost`. */
+  Component: ComponentType;
+}
+
+/** One successfully loaded inspector tool (W3), ready to register. */
+export interface InspectorTool extends LoadedToolBase {
+  placement: 'inspector';
+  /** The module's default export, rendered inside `InspectorToolSection`. */
+  Component: ComponentType<InspectorToolProps>;
+  /** The tool's own selection predicate (§3.1 — registry contract). */
+  match: (node: EditorNode | null, adapter: AuthoringAdapter) => boolean;
+}
+
+export type ProjectTool = DockTool | InspectorTool;
+
+const TEMPLATE_EXAMPLE = 'the template worked example: src/tools/example.tool.tsx';
+
+/**
+ * Validate a dynamically imported tool module against the §3.1 contract:
+ * `export const tool = defineTool(…)` plus a default-exported React
+ * component (and, for `placement: 'inspector'`, a callable `match`). Pure
+ * and export-tested; returns either the loaded tool or the teaching error to
+ * print — the caller owns the console (`refreshProjectTools`) so tests don't
+ * have to spy on it.
+ */
+export function extractProjectTool(
+  mod: unknown,
+  file: string,
+  version: number,
+): { tool: ProjectTool } | { error: string } {
+  const record = (mod ?? {}) as Record<string, unknown>;
+  const config = record['tool'] as ToolConfig | undefined;
+  if (
+    config === null ||
+    typeof config !== 'object' ||
+    typeof config.id !== 'string' ||
+    typeof config.title !== 'string'
+  ) {
+    return {
+      error:
+        `[tools] ${file} does not export \`tool\` — every project tool exports ` +
+        `\`export const tool = defineTool({ id, title, placement: 'dock' | 'inspector' })\` ` +
+        `(docs/DATA-TOOLS-DESIGN.md §3.1; see ${TEMPLATE_EXAMPLE}). Skipped.`,
+    };
+  }
+  if (config.placement !== 'dock' && config.placement !== 'inspector') {
+    return {
+      error:
+        `[tools] ${file} has placement ${JSON.stringify((config as { placement?: unknown }).placement)} — ` +
+        `the placements are 'dock' and 'inspector' (docs/DATA-TOOLS-DESIGN.md §3.2). Skipped.`,
+    };
+  }
+  const Component = record['default'];
+  if (typeof Component !== 'function') {
+    return {
+      error:
+        `[tools] ${file} has no default-exported React component — export default a plain ` +
+        `function component next to \`tool\` (docs/DATA-TOOLS-DESIGN.md §3.1; see ` +
+        `${TEMPLATE_EXAMPLE}). Skipped.`,
+    };
+  }
+  const base = { id: config.id, title: config.title, file, version };
+  if (config.placement === 'inspector') {
+    // Re-checked here (defineTool already validates) because a hand-rolled
+    // `tool` object can bypass defineTool entirely.
+    if (typeof config.match !== 'function') {
+      return {
+        error:
+          `[tools] ${file} has placement 'inspector' but no \`match\` function — pass ` +
+          `match: (node) => boolean in defineTool (docs/DATA-TOOLS-DESIGN.md §3.1; see ` +
+          `${TEMPLATE_EXAMPLE}). Skipped.`,
+      };
+    }
+    return {
+      tool: {
+        ...base,
+        placement: 'inspector',
+        Component: Component as ComponentType<InspectorToolProps>,
+        match: config.match,
+      },
+    };
+  }
+  return { tool: { ...base, placement: 'dock', Component: Component as ComponentType } };
+}
+
+// --- The live registry (subscribe/get store, `useSyncExternalStore`-shaped) ---
+
+let _dockTools: DockTool[] = [];
+const _listeners = new Set<() => void>();
+
+/** Current dock tools (stable reference between refreshes). */
+export function getDockTools(): DockTool[] {
+  return _dockTools;
+}
+
+/** Subscribe to dock-tool registry changes. Returns an unsubscribe function. */
+export function subscribeDockTools(fn: () => void): () => void {
+  _listeners.add(fn);
+  return () => _listeners.delete(fn);
+}
+
+// Inspector tools live in the SECTION registry, not a parallel store: each
+// loaded tool holds one `registerInspectorSections` registration, replaced
+// wholesale on every refresh (fresh Section identity per load = remount =
+// tripped error boundaries clear on HMR, same physics as the dock's
+// version-keyed `ToolHost`).
+let _unregisterInspectorTools: Array<() => void> = [];
+
+function registrationForInspectorTool(tool: InspectorTool): () => void {
+  // A project `match` that throws must not take the inspector shell down —
+  // it runs inside `Inspector.tsx`'s render. Teach once per load, then
+  // treat as "no match" (the §6.5 failure physics, at match granularity).
+  let warned = false;
+  return registerInspectorSections({
+    match: (node, adapter) => {
+      try {
+        return tool.match(node, adapter);
+      } catch (err) {
+        if (!warned) {
+          warned = true;
+          teachingError(
+            `[tools] ${tool.file}'s match() threw — treating it as "no match" until the file ` +
+              `is fixed and saved (docs/DATA-TOOLS-DESIGN.md §3.1).\n${String(err)}`,
+          );
+        }
+        return false;
+      }
+    },
+    Section: ({ adapter, nodeId }) =>
+      createElement(InspectorToolSection, {
+        id: tool.id,
+        title: tool.title,
+        file: tool.file,
+        Component: tool.Component,
+        adapter,
+        nodeId,
+      }),
+  });
+}
+
+function publishInspectorTools(tools: InspectorTool[]): void {
+  for (const unregister of _unregisterInspectorTools) unregister();
+  _unregisterInspectorTools = tools.map(registrationForInspectorTool);
+}
+
+/**
+ * Re-run the whole discovery pass: scan (`/__editor/tool-files`) → import
+ * each module fresh (`/@fs/` + `?t=` cache-bust) → validate → publish (dock
+ * store + inspector-section registrations). Cheap by design (a project has
+ * a handful of tools), so it doubles as the v1 HMR path — see the module
+ * doc comment. Never throws: per-file failures are console teaching errors
+ * and the file is skipped.
+ */
+export async function refreshProjectTools(): Promise<void> {
+  const project = getCurrentProject();
+  if (!project) {
+    publishDockTools([]);
+    publishInspectorTools([]);
+    return;
+  }
+
+  let paths: string[];
+  try {
+    const res = await fetch('/__editor/tool-files');
+    if (!res.ok) return; // no dev server route (e.g. browser mode) — keep whatever we had
+    const { files } = (await res.json()) as { files: Array<{ path: string }> };
+    paths = files.map((f) => f.path);
+  } catch {
+    return; // server unreachable — keep whatever we had
+  }
+
+  const version = Date.now();
+  const nextDock: DockTool[] = [];
+  const nextInspector: InspectorTool[] = [];
+  const seen = new Set<string>();
+  for (const file of paths) {
+    let mod: unknown;
+    try {
+      // Same `/@fs/` dynamic-import path as script-loader.ts — the module
+      // arrives through Vite (transpiled, aliases resolved), and the `?t=`
+      // bust guarantees a fresh evaluation on every refresh.
+      mod = await import(/* @vite-ignore */ `/@fs/${project.rootPath}/${file}?t=${version}`);
+    } catch (err) {
+      // Import-time failure: a syntax error, or defineTool itself throwing
+      // its teaching error — surface it verbatim, name the file, keep the
+      // editor alive.
+      teachingError(
+        `[tools] failed to load ${file} — fix the error below or delete the file ` +
+          `(see ${TEMPLATE_EXAMPLE}). Skipped.\n${String(err)}`,
+      );
+      continue;
+    }
+    const result = extractProjectTool(mod, file, version);
+    if ('error' in result) {
+      teachingError(result.error);
+      continue;
+    }
+    if (seen.has(result.tool.id)) {
+      teachingError(
+        `[tools] ${file} reuses tool id "${result.tool.id}" — ids must be unique per project ` +
+          `(they key the dock tabs and inspector sections). Skipped.`,
+      );
+      continue;
+    }
+    seen.add(result.tool.id);
+    if (result.tool.placement === 'inspector') nextInspector.push(result.tool);
+    else nextDock.push(result.tool);
+  }
+  publishDockTools(nextDock);
+  publishInspectorTools(nextInspector);
+}
+
+function publishDockTools(next: DockTool[]): void {
+  _dockTools = next;
+  for (const fn of _listeners) fn();
+}
+
+function teachingError(message: string): void {
+  // biome-ignore lint/suspicious/noConsole: deliberate, greppable — a broken project tool must be loud in the editor console without crashing the editor (§6.5 "errors teach"; mirrors data-asset.ts's hotSwap rejection)
+  console.error(message);
+}
+
+// --- HMR: re-discover on any src/tools/ change (see module doc comment) ---
+if (import.meta.hot) {
+  import.meta.hot.on('vgai:script-update', (data: { file: string }) => {
+    // `data.file` is absolute and forward-slash normalized (dev.ts). Any
+    // change under src/tools/ — the tool itself OR a helper it imports —
+    // triggers a full cheap refresh; Vite already invalidated the module.
+    if (!data.file.includes('/src/tools/')) return;
+    void refreshProjectTools();
+  });
+}