@vgai/editor 0.2.0

package/src/storage/handle-storage.ts

@@ -0,0 +1,150 @@
+/**
+ * Shared `StorageBackend` implementation over a `FileSystemDirectoryHandle`.
+ *
+ * Both browser backends are the same code over a different root handle:
+ *   - `OpfsStorage` — root is `navigator.storage.getDirectory()` (sandboxed, no
+ *     prompt; the zero-friction default for a server-less editor).
+ *   - `FsaStorage`  — root is a handle from `showDirectoryPicker()`, i.e. a REAL
+ *     on-disk folder the user chose (File System Access API).
+ *
+ * The handle API is identical for both, so all path logic lives here; subclasses
+ * only supply the root handle (and, for FSA, a permission gate).
+ *
+ * No OS file-change notifications exist for either, so `watch` derives events
+ * from this backend's own mutations — in a server-less editor the editor is the
+ * sole writer, which is exactly the change signal HMR needs.
+ */
+
+import { dirAndBase, normalize, segments } from './paths';
+import type { DirEntry, Stat, StorageBackend, WatchCallback, WatchEvent } from './types';
+
+export abstract class HandleStorage implements StorageBackend {
+  abstract readonly id: string;
+
+  private readonly watchers = new Set<WatchCallback>();
+
+  /** Resolve the backend's root directory handle (subclass-supplied). */
+  protected abstract rootHandle(): Promise<FileSystemDirectoryHandle>;
+
+  private emit(event: WatchEvent): void {
+    for (const cb of this.watchers) cb(event);
+  }
+
+  /** Walk to a directory handle, optionally creating intermediate dirs. */
+  private async dirHandle(
+    path: string,
+    create: boolean,
+  ): Promise<FileSystemDirectoryHandle | null> {
+    let handle = await this.rootHandle();
+    for (const seg of segments(path)) {
+      try {
+        handle = await handle.getDirectoryHandle(seg, { create });
+      } catch {
+        return null;
+      }
+    }
+    return handle;
+  }
+
+  /** Resolve a file handle from its parent directory + base name. */
+  private async fileHandle(path: string, create: boolean): Promise<FileSystemFileHandle | null> {
+    const [dir, base] = dirAndBase(path);
+    if (!base) return null;
+    const parent = await this.dirHandle(dir, create);
+    if (!parent) return null;
+    try {
+      return await parent.getFileHandle(base, { create });
+    } catch {
+      return null;
+    }
+  }
+
+  async read(path: string): Promise<string> {
+    const bytes = await this.readBytes(path);
+    return new TextDecoder().decode(bytes);
+  }
+
+  async readBytes(path: string): Promise<Uint8Array> {
+    const handle = await this.fileHandle(path, false);
+    if (!handle) throw new Error(`${this.id}.read: no such file '${normalize(path)}'`);
+    const file = await handle.getFile();
+    return new Uint8Array(await file.arrayBuffer());
+  }
+
+  async write(path: string, data: string | Uint8Array): Promise<void> {
+    const existed = await this.exists(path);
+    const handle = await this.fileHandle(path, true);
+    if (!handle) throw new Error(`${this.id}.write: cannot create '${normalize(path)}'`);
+    const writable = await handle.createWritable();
+    // `new Uint8Array(data)` copies into an ArrayBuffer-backed view, satisfying
+    // the DOM BufferSource type (TS 5.9's default generic is ArrayBufferLike).
+    await writable.write(typeof data === 'string' ? data : new Uint8Array(data));
+    await writable.close();
+    this.emit({ type: existed ? 'update' : 'create', path: normalize(path) });
+  }
+
+  async list(dir: string): Promise<DirEntry[]> {
+    const handle = await this.dirHandle(dir, false);
+    if (!handle) throw new Error(`${this.id}.list: no such directory '${normalize(dir)}'`);
+    const base = normalize(dir);
+    const entries: DirEntry[] = [];
+    // FileSystemDirectoryHandle is an async iterable of [name, handle].
+    for await (const [name, child] of handle as AsyncIterable<[string, FileSystemHandle]> &
+      FileSystemDirectoryHandle) {
+      const isDir = child.kind === 'directory';
+      const entry: DirEntry = {
+        name,
+        path: base ? `${base}/${name}` : name,
+        type: isDir ? 'dir' : 'file',
+      };
+      if (!isDir) entry.size = (await (child as FileSystemFileHandle).getFile()).size;
+      entries.push(entry);
+    }
+    // Directories first, then alphabetical — matches the server's /assets route.
+    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);
+    const file = await this.fileHandle(path, false);
+    if (file) {
+      const f = await file.getFile();
+      return { path: norm, type: 'file', size: f.size, mtime: f.lastModified };
+    }
+    const dir = await this.dirHandle(path, false);
+    if (dir) return { path: norm, type: 'dir', size: 0, mtime: 0 };
+    return null;
+  }
+
+  async exists(path: string): Promise<boolean> {
+    return (await this.stat(path)) !== null;
+  }
+
+  async mkdir(path: string): Promise<void> {
+    const existed = await this.exists(path);
+    await this.dirHandle(path, true);
+    if (!existed) this.emit({ type: 'create', path: normalize(path) });
+  }
+
+  async remove(path: string): Promise<void> {
+    const [dir, base] = dirAndBase(path);
+    if (!base) return;
+    const parent = await this.dirHandle(dir, false);
+    if (!parent) return;
+    try {
+      await parent.removeEntry(base, { recursive: true });
+      this.emit({ type: 'remove', path: normalize(path) });
+    } catch {
+      // Already gone — treat remove as idempotent.
+    }
+  }
+
+  watch(callback: WatchCallback): () => void {
+    this.watchers.add(callback);
+    return () => this.watchers.delete(callback);
+  }
+}

package/src/storage/handle-store.ts

@@ -0,0 +1,116 @@
+/**
+ * Persist the picked project-root directory handle across reloads.
+ *
+ * The File System Access API hands back a `FileSystemDirectoryHandle` that is
+ * structured-cloneable, so it round-trips through IndexedDB verbatim. Persisting
+ * it is what lets the browser-first editor REOPEN the same on-disk folder after
+ * a reload instead of silently dropping back into the OPFS sandbox — the
+ * difference between a toy and a real local-authoring editor.
+ *
+ * Permission is a separate axis from persistence: the handle survives a reload,
+ * but the browser may still require a fresh user gesture (`requestPermission`)
+ * to re-grant read/write. Callers `queryHandlePermission()` (never prompts) on
+ * boot and, when it comes back `'prompt'`, surface a one-click reopen affordance
+ * that calls `requestHandlePermission()` from inside a click handler.
+ *
+ * All IndexedDB calls degrade to no-ops / `null` where `indexedDB` is absent
+ * (SSR, the Node test env, privacy modes) so importing this module is always
+ * safe.
+ */
+
+const DB_NAME = 'vgai-editor';
+const STORE = 'handles';
+/** Single well-known key — the editor tracks one active project root at a time. */
+const KEY = 'project-root';
+
+/** Subset of the FSA permission API (not in older TS DOM lib versions). */
+interface PermissionedHandle {
+  queryPermission?(d: { mode: 'read' | 'readwrite' }): Promise<PermissionState>;
+  requestPermission?(d: { mode: 'read' | 'readwrite' }): Promise<PermissionState>;
+}
+
+function hasIdb(): boolean {
+  return typeof indexedDB !== 'undefined';
+}
+
+function openDb(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const req = indexedDB.open(DB_NAME, 1);
+    req.onupgradeneeded = () => {
+      if (!req.result.objectStoreNames.contains(STORE)) req.result.createObjectStore(STORE);
+    };
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+  });
+}
+
+/** Remember the picked directory handle (no-op where IndexedDB is unavailable). */
+export async function saveProjectHandle(handle: FileSystemDirectoryHandle): Promise<void> {
+  if (!hasIdb()) return;
+  const db = await openDb();
+  try {
+    await new Promise<void>((resolve, reject) => {
+      const tx = db.transaction(STORE, 'readwrite');
+      tx.objectStore(STORE).put(handle, KEY);
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error);
+    });
+  } finally {
+    db.close();
+  }
+}
+
+/** Load the remembered directory handle, or `null` if none / no IndexedDB. */
+export async function loadProjectHandle(): Promise<FileSystemDirectoryHandle | null> {
+  if (!hasIdb()) return null;
+  const db = await openDb();
+  try {
+    return await new Promise<FileSystemDirectoryHandle | null>((resolve, reject) => {
+      const tx = db.transaction(STORE, 'readonly');
+      const req = tx.objectStore(STORE).get(KEY);
+      req.onsuccess = () => resolve((req.result as FileSystemDirectoryHandle | undefined) ?? null);
+      req.onerror = () => reject(req.error);
+    });
+  } finally {
+    db.close();
+  }
+}
+
+/** Forget the remembered handle (e.g. after permission is permanently denied). */
+export async function clearProjectHandle(): Promise<void> {
+  if (!hasIdb()) return;
+  const db = await openDb();
+  try {
+    await new Promise<void>((resolve, reject) => {
+      const tx = db.transaction(STORE, 'readwrite');
+      tx.objectStore(STORE).delete(KEY);
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error);
+    });
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Query the current read/write permission for a handle WITHOUT prompting.
+ * A handle with no permission API (e.g. OPFS) is treated as already granted.
+ */
+export async function queryHandlePermission(
+  handle: FileSystemDirectoryHandle,
+): Promise<PermissionState> {
+  const h = handle as FileSystemDirectoryHandle & PermissionedHandle;
+  if (!h.queryPermission) return 'granted';
+  return h.queryPermission({ mode: 'readwrite' });
+}
+
+/**
+ * Request read/write permission for a handle — MUST be called from within a
+ * user gesture (it may prompt). Resolves `true` once permission is granted.
+ */
+export async function requestHandlePermission(handle: FileSystemDirectoryHandle): Promise<boolean> {
+  const h = handle as FileSystemDirectoryHandle & PermissionedHandle;
+  if (!h.requestPermission) return true;
+  if ((await queryHandlePermission(handle)) === 'granted') return true;
+  return (await h.requestPermission({ mode: 'readwrite' })) === 'granted';
+}

package/src/storage/http-storage.ts

@@ -0,0 +1,137 @@
+/**
+ * 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}] }
+ *   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 { 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;
+}
+
+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 }
+        : { path: normalize(path), content: bytesToBase64(data), encoding: 'base64' as const };
+    const res = await fetch(`${BASE}/save-file`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) throw new Error(`HttpStorage.write '${normalize(path)}': HTTP ${res.status}`);
+  }
+
+  async list(dir: string): Promise<DirEntry[]> {
+    const res = await fetch(`${BASE}/assets?${new URLSearchParams({ dir: normalize(dir) })}`);
+    if (!res.ok) throw new Error(`HttpStorage.list '${normalize(dir)}': HTTP ${res.status}`);
+    const { entries } = (await res.json()) as { entries: ServerAssetEntry[] };
+    return entries.map((e) => {
+      const out: DirEntry = {
+        name: e.name,
+        path: normalize(dir ? `${dir}/${e.name}` : e.name),
+        type: e.type === 'directory' ? 'dir' : 'file',
+      };
+      if (e.type === 'file') out.size = e.size;
+      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: 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 }),
+    });
+    if (!res.ok) throw new Error(`HttpStorage.remove '${normalize(path)}': HTTP ${res.status}`);
+  }
+
+  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();
+    };
+  }
+}
+
+/** Encode bytes as base64 for the save-file route's `encoding: 'base64'` mode. */
+function bytesToBase64(bytes: Uint8Array): string {
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]!);
+  return btoa(binary);
+}

package/src/storage/index.ts

@@ -0,0 +1,147 @@
+/**
+ * Storage backend selection.
+ *
+ * One backend-agnostic file interface, three implementations:
+ *   - `HttpStorage`  — the local (Node server) editor; wraps `/__editor/*`.
+ *   - `OpfsStorage`  — server-less browser editor; sandboxed OPFS.
+ *   - `FsaStorage`   — server-less browser editor over a REAL on-disk folder
+ *                      (File System Access API; Chromium).
+ *
+ * Upstream editor/engine code should depend only on `StorageBackend` from
+ * `./types` and obtain an instance via `getStorageBackend()` — never branch on
+ * the environment itself.
+ */
+
+import { FsaStorage } from './fsa-storage';
+import {
+  clearProjectHandle,
+  loadProjectHandle,
+  queryHandlePermission,
+  requestHandlePermission,
+  saveProjectHandle,
+} from './handle-store';
+import { HttpStorage } from './http-storage';
+import { OpfsStorage } from './opfs-storage';
+import type { HostCapabilities, StorageBackend } from './types';
+
+export { FsaStorage } from './fsa-storage';
+export { HttpStorage } from './http-storage';
+export { MemStorage } from './mem-storage';
+export { OpfsStorage } from './opfs-storage';
+export type { DirEntry, HostCapabilities, Stat, StorageBackend, WatchEvent } from './types';
+
+import { getEditorMode, getProjectDefinePath } from '../editor-mode';
+
+let _backend: StorageBackend | null = null;
+
+/**
+ * Get the active storage backend, defaulted by build mode:
+ *   - server-first → `HttpStorage` (edits the on-disk project via the server)
+ *   - browser-first → `OpfsStorage` (in-browser OPFS VFS, no server)
+ * Call `setStorageBackend()` to override (e.g. a File System Access root the
+ * user picked, or a test double).
+ */
+export function getStorageBackend(): StorageBackend {
+  if (_backend) return _backend;
+  _backend =
+    getEditorMode() === 'server' ? new HttpStorage(getProjectDefinePath()) : new OpfsStorage();
+  return _backend;
+}
+
+/** Override the active backend (FSA-picked root, tests, etc.). */
+export function setStorageBackend(backend: StorageBackend): void {
+  _backend = backend;
+}
+
+/** Subset of the File System Access API used for picking a project root. */
+interface DirectoryPickerWindow {
+  showDirectoryPicker?(opts?: { mode?: 'read' | 'readwrite' }): Promise<FileSystemDirectoryHandle>;
+}
+
+/**
+ * Host capabilities for the current environment — the non-file operations that
+ * do not belong on `StorageBackend` (native dialogs, reveal-in-OS).
+ *
+ * `pickProjectRoot` is present only where the File System Access API exists
+ * (Chromium): it prompts for a real on-disk folder, makes an `FsaStorage` rooted
+ * there the active backend, and returns it. `reveal` is omitted in the browser.
+ */
+export function getHostCapabilities(): HostCapabilities {
+  const picker = (window as unknown as DirectoryPickerWindow).showDirectoryPicker;
+  if (!picker) return {};
+  return {
+    async pickProjectRoot(): Promise<StorageBackend | null> {
+      try {
+        const handle = await picker.call(window, { mode: 'readwrite' });
+        const backend = new FsaStorage(handle);
+        setStorageBackend(backend);
+        // Remember the folder so a reload reopens it instead of falling back to
+        // the OPFS sandbox (see restorePersistedProjectRoot). Never blocks the
+        // pick: a storage failure here only forfeits the reopen-on-reload nicety.
+        await saveProjectHandle(handle).catch((err) =>
+          console.warn('[vgai] could not persist project folder handle:', err),
+        );
+        return backend;
+      } catch {
+        // User cancelled the picker.
+        return null;
+      }
+    },
+  };
+}
+
+/** A remembered on-disk project folder and whether it is usable right now. */
+export interface PersistedProjectRoot {
+  /** The folder's display name (its base name). */
+  name: string;
+  /**
+   * `'granted'` — permission survived the reload; this call already installed
+   * an `FsaStorage` over it as the active backend. `'prompt'` — the folder is
+   * remembered but needs a fresh user gesture to re-grant read/write, so it is
+   * NOT installed; call `reopenPersistedProjectRoot()` from a click handler.
+   */
+  status: 'granted' | 'prompt';
+}
+
+/**
+ * On boot (browser mode), try to silently reopen the last-picked on-disk folder.
+ *
+ * The File System Access spec forbids prompting outside a user gesture, so this
+ * only *queries* permission: when it is still `'granted'`, it installs an
+ * `FsaStorage` over the remembered handle as the active backend and reports
+ * `'granted'`; when it is `'prompt'`, it reports `'prompt'` without installing
+ * (the caller shows a reopen affordance); a permanently-`'denied'` handle is
+ * forgotten. Returns `null` when nothing is remembered.
+ */
+export async function restorePersistedProjectRoot(): Promise<PersistedProjectRoot | null> {
+  const handle = await loadProjectHandle();
+  if (!handle) return null;
+  const status = await queryHandlePermission(handle);
+  if (status === 'denied') {
+    await clearProjectHandle();
+    return null;
+  }
+  if (status === 'granted') setStorageBackend(new FsaStorage(handle));
+  return { name: handle.name, status };
+}
+
+/**
+ * Re-grant permission to the remembered on-disk folder and install it as the
+ * active backend. MUST be called from within a user gesture — it may prompt.
+ * Resolves to the installed backend, or `null` if nothing is remembered or the
+ * user denied the prompt.
+ */
+export async function reopenPersistedProjectRoot(): Promise<StorageBackend | null> {
+  const handle = await loadProjectHandle();
+  if (!handle) return null;
+  if (!(await requestHandlePermission(handle))) return null;
+  const backend = new FsaStorage(handle);
+  setStorageBackend(backend);
+  return backend;
+}
+
+/** Display name of the remembered on-disk folder, or `null` if none. */
+export async function peekPersistedProjectRootName(): Promise<string | null> {
+  const handle = await loadProjectHandle();
+  return handle?.name ?? null;
+}

package/src/storage/mem-storage.ts

@@ -0,0 +1,135 @@
+/**
+ * Pure in-memory `StorageBackend` — a virtual filesystem backed by a `Map`.
+ *
+ * Nothing touches disk or OPFS; files live as bytes in JS and vanish on reload.
+ * The most "virtual" of the backends, and the simplest. Useful for:
+ *   - tests (deterministic, instant, no OPFS cleanup),
+ *   - ephemeral "try it" playgrounds (open, hack, close — nothing persisted),
+ *   - seeding (load a bundled template into memory, then optionally flush to an
+ *     `FsaStorage`/`OpfsStorage` to persist).
+ *
+ * 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)}'`);
+    return node.data;
+  }
+
+  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 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' };
+      if (node.type === 'file') entry.size = node.data.length;
+      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();
+}