@volter/editor-core 0.5.57

package/src/storage/http-storage.ts

@@ -0,0 +1,174 @@
+/**
+ * Server-backed `StorageBackend` for the local (Node) editor.
+ *
+ * A thin adapter over the editor server's existing routes — it changes nothing
+ * about how the local editor talks to disk, it just presents that surface behind
+ * the shared interface. The backend is rooted at the project's `public/` folder,
+ * matching the server's `/__editor/assets` (list) and `/__editor/save-file`
+ * (write) routes; reads come from Vite's `/@fs/` static serving.
+ *
+ * Route mapping (paths are relative to `public/`):
+ *   list     → GET  /__editor/assets?dir            → { entries: [{name,type,size,mtime}] }
+ *   write    → POST /__editor/save-file             ({path, content, encoding?})
+ *   read     → GET  /@fs/{projectRoot}/public/{path}
+ *   watch    → EventSource /__editor/events         (chokidar-backed)
+ *
+ * The CLI control channel, native dialogs, `export`, online asset library, and
+ * project/editor-state persistence are NOT file operations and live outside this
+ * interface (see types.ts and editor-api.ts).
+ */
+
+import { bytesToBase64 } from '../bytes-codec';
+import { assertEditorServerAnswered, editorServerJson } from '../editor-server-response';
+import { sourceMutationAttribution } from '../editor-session-attribution';
+import { handleProjectMutationFailure } from '../source-conflict';
+import { dirAndBase, normalize } from './paths';
+import type { DirEntry, Stat, StorageBackend, WatchCallback, WatchEvent } from './types';
+
+const BASE = '/__editor';
+
+interface ServerAssetEntry {
+  name: string;
+  type: 'file' | 'directory';
+  size: number;
+  mtime: number;
+}
+
+export class HttpStorage implements StorageBackend {
+  readonly id = 'http';
+
+  /** Absolute project root on the server (used for /@fs reads). */
+  constructor(private readonly projectRoot: string) {}
+
+  async read(path: string): Promise<string> {
+    const res = await fetch(`/@fs/${this.projectRoot}/public/${normalize(path)}`);
+    if (!res.ok) throw new Error(`HttpStorage.read '${normalize(path)}': HTTP ${res.status}`);
+    return res.text();
+  }
+
+  async readBytes(path: string): Promise<Uint8Array> {
+    const res = await fetch(`/@fs/${this.projectRoot}/public/${normalize(path)}`);
+    if (!res.ok) throw new Error(`HttpStorage.readBytes '${normalize(path)}': HTTP ${res.status}`);
+    return new Uint8Array(await res.arrayBuffer());
+  }
+
+  async write(path: string, data: string | Uint8Array): Promise<void> {
+    const body =
+      typeof data === 'string'
+        ? { path: normalize(path), content: data, ...sourceMutationAttribution() }
+        : {
+            path: normalize(path),
+            content: bytesToBase64(data),
+            encoding: 'base64' as const,
+            ...sourceMutationAttribution(),
+          };
+    const res = await fetch(`${BASE}/save-file`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    // This is the AUTOSAVE path. `!res.ok` alone let a page fallback report
+    // every save as written, so the editor kept showing saved work that no
+    // server had ever received.
+    assertEditorServerAnswered(res, `Write ${normalize(path)} failed`);
+    if (!res.ok) {
+      await handleProjectMutationFailure(res, {
+        label: `Write ${normalize(path)}`,
+        attempted: {
+          [`public/${normalize(path)}`]:
+            typeof data === 'string' ? data : `[${data.byteLength} binary bytes]`,
+        },
+        reapply: () => this.write(path, data),
+      });
+    }
+  }
+
+  async writeIfAbsent(path: string, data: string | Uint8Array): Promise<boolean> {
+    // Browser adaptation never uses HttpStorage: the Node endpoint owns its
+    // true `wx` write. Keep the interface honest for generic callers.
+    if (await this.exists(path)) return false;
+    await this.write(path, data);
+    return true;
+  }
+
+  async list(dir: string): Promise<DirEntry[]> {
+    const res = await fetch(`${BASE}/assets?${new URLSearchParams({ dir: normalize(dir) })}`);
+    const { entries } = await editorServerJson<{ entries: ServerAssetEntry[] }>(
+      res,
+      `HttpStorage.list '${normalize(dir)}' failed`,
+    );
+    return entries.map((e) => {
+      const out: DirEntry = {
+        name: e.name,
+        path: normalize(dir ? `${dir}/${e.name}` : e.name),
+        type: e.type === 'directory' ? 'dir' : 'file',
+        mtime: e.mtime,
+      };
+      if (e.type === 'file') out.size = e.size;
+      out.mtime = e.mtime;
+      return out;
+    });
+  }
+
+  async stat(path: string): Promise<Stat | null> {
+    // The server exposes listings, not a per-path stat. Derive from the parent
+    // listing — sufficient for the editor's needs (existence + type + size).
+    const [dir, base] = dirAndBase(path);
+    if (!base) return { path: '', type: 'dir', size: 0, mtime: 0 };
+    let entries: DirEntry[];
+    try {
+      entries = await this.list(dir);
+    } catch {
+      return null;
+    }
+    const hit = entries.find((e) => e.name === base);
+    return hit
+      ? { path: hit.path, type: hit.type, size: hit.size ?? 0, mtime: hit.mtime ?? 0 }
+      : null;
+  }
+
+  async exists(path: string): Promise<boolean> {
+    return (await this.stat(path)) !== null;
+  }
+
+  async mkdir(path: string): Promise<void> {
+    // The server has no empty-dir route; directories materialize when their
+    // first file is written (save-file creates parents). No-op here.
+    void path;
+  }
+
+  async remove(path: string): Promise<void> {
+    const res = await fetch(`${BASE}/save-file`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ path: normalize(path), delete: true, ...sourceMutationAttribution() }),
+    });
+    assertEditorServerAnswered(res, `Delete ${normalize(path)} failed`);
+    if (!res.ok) {
+      await handleProjectMutationFailure(res, {
+        label: `Delete ${normalize(path)}`,
+        attempted: { [`public/${normalize(path)}`]: null },
+        reapply: () => this.remove(path),
+      });
+    }
+  }
+
+  watch(callback: WatchCallback): () => void {
+    const source = new EventSource(`${BASE}/events`);
+    const handler = (ev: MessageEvent) => {
+      try {
+        const data = JSON.parse(ev.data) as { type?: string; file?: string; path?: string };
+        const path = data.path ?? data.file;
+        if (!path) return;
+        callback({ type: (data.type as WatchEvent['type']) ?? 'update', path: normalize(path) });
+      } catch {
+        // Ignore non-JSON keepalive frames.
+      }
+    };
+    source.addEventListener('message', handler);
+    return () => {
+      source.removeEventListener('message', handler);
+      source.close();
+    };
+  }
+}

package/src/storage/index.ts

@@ -0,0 +1,75 @@
+/**
+ * Storage backend selection — the `public/`-rooted file interface the editor's
+ * asset surfaces read and write through.
+ *
+ * ONE TIER, two implementations, and the second is a decorator:
+ *   - `HttpStorage`      — the session's own `/__editor/*` routes.
+ *   - `HostFilesStorage` — the same view, written through `EditorHost.files`
+ *                          so a write is the WORKBENCH's own (U5).
+ * `MemStorage` is the design system's fixture backend and nothing else.
+ *
+ * Upstream code depends only on `StorageBackend` from `./types` and obtains
+ * an instance via `getStorageBackend()`.
+ */
+
+import { getProjectDefinePath } from '../editor-mode';
+import { filesProviderInstalled } from '../files/file-provider';
+import { HostFilesStorage } from './host-files-storage';
+import { HttpStorage } from './http-storage';
+import type { StorageBackend } from './types';
+
+export { HttpStorage } from './http-storage';
+export { MemStorage } from './mem-storage';
+export type { DirEntry, HostCapabilities, Stat, StorageBackend, WatchEvent } from './types';
+
+let _backend: StorageBackend | null = null;
+/** The tier's own backend, kept beside the active one so the frame decorator
+ *  never becomes its own delegate — see {@link tierStorageBackend}. */
+let _tier: StorageBackend | null = null;
+
+/**
+ * THE TIER'S OWN backend — never the frame decorator, and the only thing the
+ * file door's host fill is allowed to stand on.
+ *
+ * Without this the fill would recurse: `projectFiles.read` falls back to
+ * `getStorageBackend()`, which under the frame is `HostFilesStorage`, whose
+ * `read` is `projectFiles.read`. One function, so the cycle cannot be written
+ * by accident.
+ */
+export function tierStorageBackend(): StorageBackend {
+  if (_backend && !(_backend instanceof HostFilesStorage)) return _backend;
+  if (!_tier) _tier = new HttpStorage(getProjectDefinePath());
+  return _tier;
+}
+
+/**
+ * The active storage backend: the session's own, wrapped by the frame's file
+ * door once its provider has landed.
+ *
+ * UNDER THE CODE-OSS FRAME the file system is the WORKBENCH'S, not the
+ * session's (U5; ARCHITECTURE-CORE §The core is Code-OSS, "the storage
+ * backends → file system providers"). `HostFilesStorage` is the `public/`
+ * view onto `EditorHost.files`, so an asset write is the workbench's own write
+ * on the URI it already holds — the same property that closed U4's redo open
+ * for source files. Everything the file door does not carry (remove, mkdir,
+ * stat, list, watch) stays this tier's, which is why the decorator keeps it
+ * rather than replacing it.
+ *
+ * Read at FIRST USE rather than at module load: the bridge takes ownership
+ * before the editor mounts, but the provider arrives with the contribution's
+ * own services, after — see `files/file-provider.ts`.
+ */
+export function getStorageBackend(): StorageBackend {
+  if (_backend) return _backend;
+  const tier = tierStorageBackend();
+  _backend = filesProviderInstalled() ? new HostFilesStorage(tier) : tier;
+  return _backend;
+}
+
+/** Override the active backend (the design system's fixture). */
+export function setStorageBackend(backend: StorageBackend): void {
+  _backend = backend;
+  // An explicitly installed backend REPLACES the tier, so the file door's host
+  // fill stands on it too rather than on a stale one it would otherwise hold.
+  if (!(backend instanceof HostFilesStorage)) _tier = backend;
+}

package/src/storage/mem-storage.ts

@@ -0,0 +1,149 @@
+/**
+ * Pure in-memory `StorageBackend` — a virtual filesystem backed by a `Map`.
+ *
+ * Nothing touches disk; files live as bytes in JS and vanish on reload. The
+ * most "virtual" of the backends, and the simplest — the design system's
+ * fixture (`design-system-stories/fixtures/editor-runtime.tsx`) is what uses
+ * it: a story needs a project-shaped backend and must write nothing.
+ *
+ * Implements the same interface as every other backend, so it is a drop-in via
+ * `setStorageBackend(new MemStorage())`.
+ */
+
+import { dirAndBase, normalize } from './paths';
+import type { DirEntry, Stat, StorageBackend, WatchCallback, WatchEvent } from './types';
+
+type Node = { type: 'file'; data: Uint8Array; mtime: number } | { type: 'dir'; mtime: number };
+
+export class MemStorage implements StorageBackend {
+  readonly id = 'mem';
+
+  /** Normalized path → node. The root (`''`) is implicit. */
+  private readonly nodes = new Map<string, Node>();
+  private readonly watchers = new Set<WatchCallback>();
+
+  /** Optionally seed the VFS from a `{ path: contents }` map. */
+  constructor(seed?: Record<string, string | Uint8Array>) {
+    if (seed) for (const [path, data] of Object.entries(seed)) this.writeSync(path, data);
+  }
+
+  private emit(event: WatchEvent): void {
+    for (const cb of this.watchers) cb(event);
+  }
+
+  /** Ensure every ancestor directory of `path` exists. */
+  private ensureParents(path: string): void {
+    const parts = normalize(path).split('/');
+    parts.pop();
+    let cur = '';
+    for (const part of parts) {
+      cur = cur ? `${cur}/${part}` : part;
+      if (this.nodes.get(cur)?.type !== 'dir') this.nodes.set(cur, { type: 'dir', mtime: now() });
+    }
+  }
+
+  private writeSync(path: string, data: string | Uint8Array): boolean {
+    const norm = normalize(path);
+    this.ensureParents(norm);
+    const existed = this.nodes.get(norm)?.type === 'file';
+    const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : new Uint8Array(data);
+    this.nodes.set(norm, { type: 'file', data: bytes, mtime: now() });
+    return existed;
+  }
+
+  async read(path: string): Promise<string> {
+    return new TextDecoder().decode(await this.readBytes(path));
+  }
+
+  async readBytes(path: string): Promise<Uint8Array> {
+    const node = this.nodes.get(normalize(path));
+    if (node?.type !== 'file')
+      throw new Error(`MemStorage.read: no such file '${normalize(path)}'`);
+    // Reads own their bytes, just like File/HTTP backends. Asset serving
+    // transfers this buffer to a worker; sharing the stored buffer would
+    // detach the file itself and break every subsequent read.
+    return node.data.slice();
+  }
+
+  async write(path: string, data: string | Uint8Array): Promise<void> {
+    const existed = this.writeSync(path, data);
+    this.emit({ type: existed ? 'update' : 'create', path: normalize(path) });
+  }
+
+  async writeIfAbsent(path: string, data: string | Uint8Array): Promise<boolean> {
+    if (await this.exists(path)) return false;
+    this.writeSync(path, data);
+    this.emit({ type: 'create', path: normalize(path) });
+    return true;
+  }
+
+  async list(dir: string): Promise<DirEntry[]> {
+    const dn = normalize(dir);
+    if (dn !== '' && this.nodes.get(dn)?.type !== 'dir') {
+      throw new Error(`MemStorage.list: no such directory '${dn}'`);
+    }
+    const entries: DirEntry[] = [];
+    for (const [path, node] of this.nodes) {
+      const [parent, base] = dirAndBase(path);
+      if (parent !== dn || !base) continue;
+      const entry: DirEntry = {
+        name: base,
+        path,
+        type: node.type === 'dir' ? 'dir' : 'file',
+        mtime: node.mtime,
+      };
+      if (node.type === 'file') entry.size = node.data.length;
+      entry.mtime = node.mtime;
+      entries.push(entry);
+    }
+    entries.sort((a, b) => {
+      if (a.type !== b.type) return a.type === 'dir' ? -1 : 1;
+      return a.name.localeCompare(b.name);
+    });
+    return entries;
+  }
+
+  async stat(path: string): Promise<Stat | null> {
+    const norm = normalize(path);
+    if (norm === '') return { path: '', type: 'dir', size: 0, mtime: 0 };
+    const node = this.nodes.get(norm);
+    if (!node) return null;
+    return node.type === 'file'
+      ? { path: norm, type: 'file', size: node.data.length, mtime: node.mtime }
+      : { path: norm, type: 'dir', size: 0, mtime: node.mtime };
+  }
+
+  async exists(path: string): Promise<boolean> {
+    return (await this.stat(path)) !== null;
+  }
+
+  async mkdir(path: string): Promise<void> {
+    const norm = normalize(path);
+    if (!norm || this.nodes.get(norm)?.type === 'dir') return;
+    this.ensureParents(norm);
+    this.nodes.set(norm, { type: 'dir', mtime: now() });
+    this.emit({ type: 'create', path: norm });
+  }
+
+  async remove(path: string): Promise<void> {
+    const norm = normalize(path);
+    if (!norm) return;
+    let removed = false;
+    for (const key of [...this.nodes.keys()]) {
+      if (key === norm || key.startsWith(`${norm}/`)) {
+        this.nodes.delete(key);
+        removed = true;
+      }
+    }
+    if (removed) this.emit({ type: 'remove', path: norm });
+  }
+
+  watch(callback: WatchCallback): () => void {
+    this.watchers.add(callback);
+    return () => this.watchers.delete(callback);
+  }
+}
+
+function now(): number {
+  return Date.now();
+}

package/src/storage/path-lock.ts

@@ -0,0 +1,44 @@
+/**
+ * The one cross-realm mutual exclusion a browser storage backend has:
+ * `navigator.locks`, keyed by backend id + path.
+ *
+ * Two callers matter and they MUST agree on the name, which is why this is a
+ * shared function rather than a string built at each site — and why the name is
+ * derived from the NORMALIZED path here rather than from whatever each caller
+ * happens to hold. Sharing the function is not enough on its own: one caller
+ * passes an already-normalized path and the other passes a module constant, so
+ * agreement used to rest on that constant being spelled in normalized form.
+ * Respell it as `/.vgai/assets.json` and the two names diverge, both locks are
+ * "held", and mutual exclusion is silently gone with nothing failing. Deriving
+ * the name from `normalize()` makes the agreement structural.
+ *
+ * Callers:
+ *   - the asset ledger's `.lock` compare-and-delete
+ *     (`../asset-workflow/asset-ledger-backend.ts`) — several steps that must
+ *     not interleave with each other OR with the create above.
+ *
+ * Scope, stated exactly: Web Locks span every same-origin realm — the two
+ * tabs on one project that motivate the ledger lock in the first place — and
+ * nothing else. A writer that is not same-origin JS (a Node process
+ * reaching the same files, i.e. `HttpStorage` racing the CLI) is not serialized
+ * by this, and cannot be from the browser side.
+ *
+ * Absent in a non-secure context and in Node (tests): callers then get the bare
+ * operation, which is the same exclusivity the platform itself offers.
+ */
+import { normalize } from './paths';
+
+export function withPathLock<T>(
+  backendId: string,
+  path: string,
+  operation: () => Promise<T>,
+): Promise<T> {
+  const locks = globalThis.navigator?.locks;
+  if (!locks) return operation();
+  // `LockManager.request`'s DOM typing infers its result from the callback's
+  // literal return type (`(lock) => T`), so an async callback types as
+  // `Promise<Promise<T>>`. The platform awaits the returned promise before
+  // releasing the lock — that flattening is the documented behavior, not an
+  // assumption — so the settled value really is `T`.
+  return locks.request(`vgai:${backendId}:${normalize(path)}`, operation) as Promise<T>;
+}

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/types.ts

@@ -0,0 +1,116 @@
+/**
+ * Backend-agnostic file interface for the editor.
+ *
+ * The editor and engine read/write project files through one `StorageBackend`
+ * and never learn which implementation is behind it — the session's own
+ * `/__editor/*` routes, the frame's file door over them, or the design
+ * system's in-memory fixture.
+ *
+ * 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;
+  /** Last-modified time, epoch ms (omitted if the backend cannot report it). */
+  mtime?: 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>;
+  /**
+   * Create a new file without replacing an existing one. Returns false when
+   * the path already exists. Browser handle APIs have no OS-level O_EXCL;
+   * HandleStorage serializes same-origin writers and rechecks at handle
+   * acquisition, while an external process may still win the final race.
+   */
+  writeIfAbsent(path: string, data: string | Uint8Array): Promise<boolean>;
+
+  /** 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.
+ */
+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>;
+}