@componentor/fs 2.0.12 → 3.0.1

package/README.md

@@ -1,13 +1,15 @@
 # @componentor/fs
 
-**Battle-tested OPFS-based Node.js `fs` polyfill with sync and async APIs**
+**High-performance OPFS-based Node.js `fs` polyfill for the browser**
 
-A high-performance browser filesystem with native OPFS backend and synchronous API support.
+A virtual filesystem powered by a custom binary format (VFS), SharedArrayBuffer + Atomics for true synchronous APIs, multi-tab coordination via Web Locks, and bidirectional OPFS mirroring.
 
 ```typescript
-import { fs } from '@componentor/fs';
+import { VFSFileSystem } from '@componentor/fs';
 
-// Sync API (requires crossOriginIsolated)
+const fs = new VFSFileSystem();
+
+// Sync API (requires crossOriginIsolated — blocks until ready on first call)
 fs.writeFileSync('/hello.txt', 'Hello World!');
 const data = fs.readFileSync('/hello.txt', 'utf8');
 
@@ -18,13 +20,15 @@ const content = await fs.promises.readFile('/async.txt', 'utf8');
 
 ## Features
 
-- **Node.js Compatible** - Drop-in replacement for `fs` module
-- **Sync API** - `readFileSync`, `writeFileSync`, etc. (requires COOP/COEP)
-- **Async API** - `promises.readFile`, `promises.writeFile`, etc.
-- **Cross-tab Safe** - Uses `navigator.locks` for multi-tab coordination
-- **isomorphic-git Ready** - Full compatibility with git operations
-- **Zero Config** - Works out of the box, no worker files needed
-- **TypeScript First** - Complete type definitions included
+- **True Sync API** — `readFileSync`, `writeFileSync`, etc. via SharedArrayBuffer + Atomics
+- **Async API** — `promises.readFile`, `promises.writeFile` — works without COOP/COEP
+- **VFS Binary Format** — All data in a single `.vfs.bin` file for maximum throughput
+- **OPFS Sync** — Bidirectional mirror to real OPFS files (enabled by default)
+- **Multi-tab Safe** — Leader/follower architecture with automatic failover via `navigator.locks`
+- **FileSystemObserver** — External OPFS changes synced back to VFS automatically (Chrome 129+)
+- **isomorphic-git Ready** — Full compatibility with git operations
+- **Zero Config** — Workers inlined at build time, no external worker files needed
+- **TypeScript First** — Complete type definitions included
 
 ## Installation
 
@@ -35,72 +39,83 @@ npm install @componentor/fs
 ## Quick Start
 
 ```typescript
-import { fs, path } from '@componentor/fs';
-
-// Create a directory
-await fs.promises.mkdir('/projects/my-app', { recursive: true });
-
-// Write a file
-await fs.promises.writeFile('/projects/my-app/index.js', 'console.log("Hello!");');
+import { VFSFileSystem } from '@componentor/fs';
 
-// Read a file
-const code = await fs.promises.readFile('/projects/my-app/index.js', 'utf8');
-console.log(code); // 'console.log("Hello!");'
+const fs = new VFSFileSystem({ root: '/my-app' });
 
-// List directory contents
-const files = await fs.promises.readdir('/projects/my-app');
-console.log(files); // ['index.js']
+// Option 1: Sync API (blocks on first call until VFS is ready)
+fs.mkdirSync('/my-app/src', { recursive: true });
+fs.writeFileSync('/my-app/src/index.js', 'console.log("Hello!");');
+const code = fs.readFileSync('/my-app/src/index.js', 'utf8');
 
-// Get file stats
-const stats = await fs.promises.stat('/projects/my-app/index.js');
-console.log(stats.size); // 23
-
-// Use path utilities
-console.log(path.join('/projects', 'my-app', 'src')); // '/projects/my-app/src'
-console.log(path.dirname('/projects/my-app/index.js')); // '/projects/my-app'
-console.log(path.basename('/projects/my-app/index.js')); // 'index.js'
+// Option 2: Async init (non-blocking)
+await fs.init(); // wait for VFS to be ready
+const files = await fs.promises.readdir('/my-app/src');
+const stats = await fs.promises.stat('/my-app/src/index.js');
 ```
 
-## Performance Tiers
+### Convenience Helpers
 
-@componentor/fs operates in two performance tiers based on browser capabilities:
+```typescript
+import { createFS, getDefaultFS, init } from '@componentor/fs';
 
-### Tier 1: Sync (Fastest)
+// Create with config
+const fs = createFS({ root: '/repo', debug: true });
 
-**Requirements:** `crossOriginIsolated` context (COOP/COEP headers)
+// Lazy singleton (created on first access)
+const defaultFs = getDefaultFS();
 
-Uses `SharedArrayBuffer` + `Atomics` for zero-copy data transfer between main thread and worker. Enables **synchronous** filesystem operations.
+// Async init helper
+await init(); // initializes the default singleton
+```
+
+## Configuration
 
 ```typescript
-// Tier 1 unlocks sync APIs
-fs.writeFileSync('/file.txt', 'data');
-const data = fs.readFileSync('/file.txt', 'utf8');
-fs.mkdirSync('/dir', { recursive: true });
-fs.existsSync('/file.txt'); // true
+const fs = new VFSFileSystem({
+  root: '/',              // OPFS root directory (default: '/')
+  opfsSync: true,         // Mirror VFS to real OPFS files (default: true)
+  opfsSyncRoot: undefined, // Custom OPFS root for mirroring (default: same as root)
+  uid: 0,                 // User ID for file ownership (default: 0)
+  gid: 0,                 // Group ID for file ownership (default: 0)
+  umask: 0o022,           // File creation mask (default: 0o022)
+  strictPermissions: false, // Enforce Unix permissions (default: false)
+  sabSize: 4194304,       // SharedArrayBuffer size in bytes (default: 4MB)
+  debug: false,           // Enable debug logging (default: false)
+});
 ```
 
-### Tier 2: Async (Always Available)
+### OPFS Sync
+
+When `opfsSync` is enabled (the default), VFS mutations are mirrored to real OPFS files in the background:
+
+- **VFS → OPFS**: Every write, delete, mkdir, rename is replicated to real OPFS files after the sync operation completes (zero performance impact on the hot path)
+- **OPFS → VFS**: A `FileSystemObserver` watches for external changes and syncs them back (Chrome 129+)
 
-Works in any browser context without special headers. Uses Web Worker with `postMessage` for async operations.
+This allows external tools (browser DevTools, OPFS extensions) to see and modify files while VFS handles all the fast read/write operations internally.
 
 ```typescript
-// Tier 2 - promises API always works
-await fs.promises.writeFile('/file.txt', 'data');
-const data = await fs.promises.readFile('/file.txt', 'utf8');
-await fs.promises.mkdir('/dir', { recursive: true });
-await fs.promises.exists('/file.txt'); // true
+// OPFS sync enabled (default)
+const fs = new VFSFileSystem({ opfsSync: true });
+fs.writeFileSync('/file.txt', 'data');
+// → /file.txt also appears in OPFS (visible in DevTools > Application > Storage)
+
+// Disable for maximum performance (no OPFS mirroring)
+const fastFs = new VFSFileSystem({ opfsSync: false });
 ```
 
-## COOP/COEP Headers (Required for Tier 1)
+## COOP/COEP Headers
 
-To enable Tier 1 (sync) performance, your server must send these headers:
+To enable the sync API, your page must be `crossOriginIsolated`. Add these headers:
 
 ```
 Cross-Origin-Opener-Policy: same-origin
 Cross-Origin-Embedder-Policy: require-corp
 ```
 
-### Vite Configuration
+Without these headers, only the async (`promises`) API is available.
+
+### Vite
 
 ```typescript
 // vite.config.ts
@@ -114,7 +129,7 @@ export default defineConfig({
 });
 ```
 
-### Express/Node.js
+### Express
 
 ```javascript
 app.use((req, res, next) => {
@@ -127,7 +142,6 @@ app.use((req, res, next) => {
 ### Vercel
 
 ```json
-// vercel.json
 {
   "headers": [
     {
@@ -141,41 +155,37 @@ app.use((req, res, next) => {
 }
 ```
 
-### Check if Tier 1 is Available
+### Runtime Check
 
 ```typescript
 if (crossOriginIsolated) {
-  console.log('Tier 1 (sync) available!');
+  // Sync + async APIs available
   fs.writeFileSync('/fast.txt', 'blazing fast');
 } else {
-  console.log('Tier 2 (async) only');
+  // Async API only
   await fs.promises.writeFile('/fast.txt', 'still fast');
 }
 ```
 
 ## Benchmarks
 
-Tested against LightningFS (IndexedDB-based filesystem) in Chrome with Tier 1 enabled:
+Tested against LightningFS (IndexedDB-based) in Chrome with `crossOriginIsolated` enabled:
 
-| Operation | @componentor/fs | LightningFS | Winner |
-|-----------|-----------------|-------------|--------|
-| Write 100 x 1KB | 131ms (763 ops/s) | 317ms (316 ops/s) | **OPFS 2.4x** |
-| Write 100 x 4KB | 145ms (690 ops/s) | 49ms (2061 ops/s) | LightningFS |
-| Read 100 x 1KB | 11ms (9170 ops/s) | 17ms (5824 ops/s) | **OPFS 1.6x** |
-| Read 100 x 4KB | 10ms (10493 ops/s) | 16ms (6431 ops/s) | **OPFS 1.6x** |
-| Large 10 x 1MB | 19ms (538 ops/s) | 11ms (910 ops/s) | LightningFS |
-| Batch Write 500 | 416ms (1202 ops/s) | 125ms (4014 ops/s) | LightningFS |
-| Batch Read 500 | 311ms (1608 ops/s) | 74ms (6736 ops/s) | LightningFS |
-| **Git Clone** | 427ms | 1325ms | **OPFS 3.1x** |
-| Git Status 10x | 53ms | 39ms | LightningFS |
+| Operation | LightningFS | VFS Sync | VFS Promises | Winner |
+|-----------|------------|----------|-------------|--------|
+| Write 100 x 1KB | 46ms | **12ms** | 23ms | **VFS 4x** |
+| Write 100 x 4KB | 36ms | **13ms** | 22ms | **VFS 2.8x** |
+| Read 100 x 1KB | 19ms | **2ms** | 14ms | **VFS 9x** |
+| Read 100 x 4KB | 62ms | **2ms** | 13ms | **VFS 28x** |
+| Large 10 x 1MB | 11ms | **10ms** | 17ms | **VFS 1.1x** |
+| Batch Write 500 x 256B | 138ms | **50ms** | 75ms | **VFS 2.8x** |
+| Batch Read 500 x 256B | 73ms | **7ms** | 91ms | **VFS 10x** |
 
 **Key takeaways:**
-- **Git clone is 2-3x faster** - the most important real-world operation
-- **Reads are 1.6x faster** - OPFS excels at read operations
-- **Small writes (1KB) are 2.4x faster** - great for config files and metadata
-- LightningFS wins on batch operations and larger sequential writes
-
-*Results from Chrome 120+ with crossOriginIsolated enabled. Performance varies by browser and hardware.*
+- **Reads are 9-28x faster** — VFS binary format eliminates IndexedDB overhead
+- **Writes are 2.8-4x faster** — Single binary file vs individual OPFS/IDB entries
+- **Batch operations are 2.8-10x faster** — VFS excels at many small operations
+- VFS Sync is the fastest path (SharedArrayBuffer + Atomics, zero async overhead)
 
 Run benchmarks yourself:
 
@@ -185,114 +195,149 @@ npm run benchmark:open
 
 ## API Reference
 
-### Sync API (Tier 1 Only)
+### Sync API (requires crossOriginIsolated)
 
 ```typescript
 // Read/Write
-fs.readFileSync(path: string, options?: { encoding?: string }): Uint8Array | string
-fs.writeFileSync(path: string, data: Uint8Array | string, options?: { flush?: boolean }): void
-fs.appendFileSync(path: string, data: Uint8Array | string): void
+fs.readFileSync(path, options?): Uint8Array | string
+fs.writeFileSync(path, data, options?): void
+fs.appendFileSync(path, data): void
 
 // Directories
-fs.mkdirSync(path: string, options?: { recursive?: boolean }): void
-fs.rmdirSync(path: string, options?: { recursive?: boolean }): void
-fs.readdirSync(path: string): string[]
+fs.mkdirSync(path, options?): void
+fs.rmdirSync(path, options?): void
+fs.rmSync(path, options?): void
+fs.readdirSync(path, options?): string[] | Dirent[]
 
 // File Operations
-fs.unlinkSync(path: string): void
-fs.renameSync(oldPath: string, newPath: string): void
-fs.copyFileSync(src: string, dest: string): void
-fs.truncateSync(path: string, len?: number): void
+fs.unlinkSync(path): void
+fs.renameSync(oldPath, newPath): void
+fs.copyFileSync(src, dest, mode?): void
+fs.truncateSync(path, len?): void
+fs.symlinkSync(target, path): void
+fs.readlinkSync(path): string
+fs.linkSync(existingPath, newPath): void
 
 // Info
-fs.statSync(path: string): Stats
-fs.existsSync(path: string): boolean
-fs.accessSync(path: string, mode?: number): void
+fs.statSync(path): Stats
+fs.lstatSync(path): Stats
+fs.existsSync(path): boolean
+fs.accessSync(path, mode?): void
+fs.realpathSync(path): string
+
+// Metadata
+fs.chmodSync(path, mode): void
+fs.chownSync(path, uid, gid): void
+fs.utimesSync(path, atime, mtime): void
+
+// File Descriptors
+fs.openSync(path, flags?, mode?): number
+fs.closeSync(fd): void
+fs.readSync(fd, buffer, offset?, length?, position?): number
+fs.writeSync(fd, buffer, offset?, length?, position?): number
+fs.fstatSync(fd): Stats
+fs.ftruncateSync(fd, len?): void
+fs.fdatasyncSync(fd): void
+
+// Temp / Flush
+fs.mkdtempSync(prefix): string
+fs.flushSync(): void
 ```
 
-### Async API (Always Available)
+### Async API (always available)
 
 ```typescript
 // Read/Write
-fs.promises.readFile(path: string, options?: ReadOptions): Promise<Uint8Array | string>
-fs.promises.writeFile(path: string, data: Uint8Array | string, options?: WriteOptions): Promise<void>
-fs.promises.appendFile(path: string, data: Uint8Array | string): Promise<void>
+fs.promises.readFile(path, options?): Promise<Uint8Array | string>
+fs.promises.writeFile(path, data, options?): Promise<void>
+fs.promises.appendFile(path, data): Promise<void>
 
 // Directories
-fs.promises.mkdir(path: string, options?: { recursive?: boolean }): Promise<void>
-fs.promises.rmdir(path: string, options?: { recursive?: boolean }): Promise<void>
-fs.promises.readdir(path: string, options?: { withFileTypes?: boolean }): Promise<string[] | Dirent[]>
+fs.promises.mkdir(path, options?): Promise<void>
+fs.promises.rmdir(path, options?): Promise<void>
+fs.promises.rm(path, options?): Promise<void>
+fs.promises.readdir(path, options?): Promise<string[] | Dirent[]>
 
 // File Operations
-fs.promises.unlink(path: string): Promise<void>
-fs.promises.rename(oldPath: string, newPath: string): Promise<void>
-fs.promises.copyFile(src: string, dest: string): Promise<void>
-fs.promises.truncate(path: string, len?: number): Promise<void>
-fs.promises.rm(path: string, options?: { recursive?: boolean, force?: boolean }): Promise<void>
+fs.promises.unlink(path): Promise<void>
+fs.promises.rename(oldPath, newPath): Promise<void>
+fs.promises.copyFile(src, dest, mode?): Promise<void>
+fs.promises.truncate(path, len?): Promise<void>
+fs.promises.symlink(target, path): Promise<void>
+fs.promises.readlink(path): Promise<string>
+fs.promises.link(existingPath, newPath): Promise<void>
 
 // Info
-fs.promises.stat(path: string): Promise<Stats>
-fs.promises.lstat(path: string): Promise<Stats>
-fs.promises.exists(path: string): Promise<boolean>
-fs.promises.access(path: string, mode?: number): Promise<void>
-fs.promises.realpath(path: string): Promise<string>
+fs.promises.stat(path): Promise<Stats>
+fs.promises.lstat(path): Promise<Stats>
+fs.promises.exists(path): Promise<boolean>
+fs.promises.access(path, mode?): Promise<void>
+fs.promises.realpath(path): Promise<string>
+
+// Metadata
+fs.promises.chmod(path, mode): Promise<void>
+fs.promises.chown(path, uid, gid): Promise<void>
+fs.promises.utimes(path, atime, mtime): Promise<void>
 
 // Advanced
-fs.promises.open(path: string, flags?: string, mode?: number): Promise<FileHandle>
-fs.promises.opendir(path: string): Promise<Dir>
-fs.promises.mkdtemp(prefix: string): Promise<string>
-fs.promises.symlink(target: string, path: string): Promise<void>
-fs.promises.readlink(path: string): Promise<string>
-fs.promises.link(existingPath: string, newPath: string): Promise<void>
-
-// Cache Management
-fs.promises.flush(): Promise<void>   // Flush pending writes
-fs.promises.purge(): Promise<void>   // Clear all caches
+fs.promises.open(path, flags?, mode?): Promise<FileHandle>
+fs.promises.opendir(path): Promise<Dir>
+fs.promises.mkdtemp(prefix): Promise<string>
+
+// Flush
+fs.promises.flush(): Promise<void>
 ```
 
 ### Streams API
 
 ```typescript
-// Create a readable stream (Web Streams API)
-fs.createReadStream(path: string, options?: {
-  start?: number,       // Byte offset to start reading
-  end?: number,         // Byte offset to stop reading
-  highWaterMark?: number // Chunk size (default: 64KB)
-}): ReadableStream<Uint8Array>
-
-// Create a writable stream (Web Streams API)
-fs.createWriteStream(path: string, options?: {
-  start?: number,       // Byte offset to start writing
-  flush?: boolean       // Flush on close (default: true)
-}): WritableStream<Uint8Array>
-
-// Example: Stream a file
-const stream = fs.createReadStream('/large-file.bin');
+// Readable stream (Web Streams API)
+const stream = fs.createReadStream('/large-file.bin', {
+  start: 0,           // byte offset to start
+  end: 1024,          // byte offset to stop
+  highWaterMark: 64 * 1024, // chunk size (default: 64KB)
+});
 for await (const chunk of stream) {
   console.log('Read chunk:', chunk.length, 'bytes');
 }
 
-// Example: Write with streams
+// Writable stream
 const writable = fs.createWriteStream('/output.bin');
 const writer = writable.getWriter();
 await writer.write(new Uint8Array([1, 2, 3]));
 await writer.close();
 ```
 
+### Watch API
+
+```typescript
+// Watch for changes
+const watcher = fs.watch('/dir', { recursive: true }, (eventType, filename) => {
+  console.log(eventType, filename); // 'change' 'file.txt'
+});
+watcher.close();
+
+// Watch specific file with polling
+fs.watchFile('/file.txt', { interval: 1000 }, (curr, prev) => {
+  console.log('File changed:', curr.mtimeMs !== prev.mtimeMs);
+});
+fs.unwatchFile('/file.txt');
+```
+
 ### Path Utilities
 
 ```typescript
 import { path } from '@componentor/fs';
 
-path.join('/foo', 'bar', 'baz')     // '/foo/bar/baz'
-path.resolve('foo', 'bar')          // '/foo/bar'
-path.dirname('/foo/bar/baz.txt')    // '/foo/bar'
-path.basename('/foo/bar/baz.txt')   // 'baz.txt'
-path.extname('/foo/bar/baz.txt')    // '.txt'
-path.normalize('/foo//bar/../baz')  // '/foo/baz'
-path.isAbsolute('/foo')             // true
+path.join('/foo', 'bar', 'baz')       // '/foo/bar/baz'
+path.resolve('foo', 'bar')            // '/foo/bar'
+path.dirname('/foo/bar/baz.txt')      // '/foo/bar'
+path.basename('/foo/bar/baz.txt')     // 'baz.txt'
+path.extname('/foo/bar/baz.txt')      // '.txt'
+path.normalize('/foo//bar/../baz')    // '/foo/baz'
+path.isAbsolute('/foo')               // true
 path.relative('/foo/bar', '/foo/baz') // '../baz'
-path.parse('/foo/bar/baz.txt')      // { root, dir, base, ext, name }
+path.parse('/foo/bar/baz.txt')        // { root, dir, base, ext, name }
 path.format({ dir: '/foo', name: 'bar', ext: '.txt' }) // '/foo/bar.txt'
 ```
 
@@ -319,13 +364,13 @@ constants.O_APPEND   // 1024
 
 ## isomorphic-git Integration
 
-@componentor/fs works seamlessly with isomorphic-git:
-
 ```typescript
-import { fs } from '@componentor/fs';
+import { VFSFileSystem } from '@componentor/fs';
 import git from 'isomorphic-git';
 import http from 'isomorphic-git/http/web';
 
+const fs = new VFSFileSystem({ root: '/repo' });
+
 // Clone a repository
 await git.clone({
   fs,
@@ -351,93 +396,52 @@ await git.commit({
 ## Architecture
 
 ```
-┌─────────────────────────────────────────────────────────────┐
-│                      Main Thread                            │
-│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
-│  │   Sync API  │  │  Async API  │  │    Path Utilities   │  │
-│  │ readFileSync│  │  promises.  │  │ join, dirname, etc. │  │
-│  │writeFileSync│  │  readFile   │  └─────────────────────┘  │
-│  └──────┬──────┘  └──────┬──────┘                           │
-│         │                │                                  │
-│         │ Atomics.wait   │ postMessage                      │
-│         │ (Tier 1)       │ (Tier 2)                         │
-└─────────┼────────────────┼──────────────────────────────────┘
-          │                │
-          ▼                ▼
-┌─────────────────────────────────────────────────────────────┐
-│                      Web Worker                             │
-│  ┌────────────────────────────────────────────────────────┐ │
-│  │                   OPFS Kernel                          │ │
-│  │  ┌──────────────┐  ┌──────────────┐  ┌─────────────┐   │ │
-│  │  │ Sync Handle  │  │  Directory   │  │  navigator  │   │ │
-│  │  │    Cache     │  │    Cache     │  │    .locks   │   │ │
-│  │  │  (100 max)   │  │              │  │ (cross-tab) │   │ │
-│  │  └──────────────┘  └──────────────┘  └─────────────┘   │ │
-│  └────────────────────────────────────────────────────────┘ │
-│                            │                                │
-└────────────────────────────┼────────────────────────────────┘
+┌──────────────────────────────────────────────────────────────────┐
+│                         Main Thread                              │
+│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────────┐  │
+│  │   Sync API   │  │  Async API   │  │    Path / Constants    │  │
+│  │ readFileSync │  │  promises.   │  │ join, dirname, etc.    │  │
+│  │writeFileSync │  │  readFile    │  └────────────────────────┘  │
+│  └──────┬───────┘  └──────┬───────┘                              │
+│         │                 │                                      │
+│   SAB + Atomics     postMessage                                  │
+└─────────┼─────────────────┼──────────────────────────────────────┘
+          │                 │
+          ▼                 ▼
+┌──────────────────────────────────────────────────────────────────┐
+│               sync-relay Worker (Leader)                         │
+│  ┌────────────────────────────────────────────────────────────┐  │
+│  │                     VFS Engine                             │  │
+│  │  ┌──────────────────┐  ┌─────────────┐  ┌──────────────┐  │  │
+│  │  │  VFS Binary File  │  │  Inode/Path │  │  Block Data  │  │  │
+│  │  │  (.vfs.bin OPFS)  │  │    Table    │  │   Region     │  │  │
+│  │  └──────────────────┘  └─────────────┘  └──────────────┘  │  │
+│  └────────────────────────────────────────────────────────────┘  │
+│                            │                                     │
+│                    notifyOPFSSync()                               │
+│                     (fire & forget)                               │
+└────────────────────────────┼─────────────────────────────────────┘
                              │
                              ▼
-┌─────────────────────────────────────────────────────────────┐
-│                         OPFS                                │
-│            Origin Private File System                       │
-│              (Browser Storage API)                          │
-└─────────────────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────────────┐
+│                    opfs-sync Worker                               │
+│  ┌────────────────────┐  ┌────────────────────────────────────┐  │
+│  │  VFS → OPFS Mirror │  │  FileSystemObserver (OPFS → VFS)  │  │
+│  │  (queue + echo     │  │  External changes detected and    │  │
+│  │   suppression)     │  │  synced back to VFS engine        │  │
+│  └────────────────────┘  └────────────────────────────────────┘  │
+└──────────────────────────────────────────────────────────────────┘
+
+Multi-tab (via Service Worker + navigator.locks):
+  Tab 1 (Leader) ←→ Service Worker ←→ Tab 2 (Follower)
+  Tab 1 holds VFS engine, Tab 2 forwards requests via MessagePort
+  If Tab 1 dies, Tab 2 auto-promotes to leader
 ```
 
-## Feature Comparison
-
-### API Compatibility
-
-| Feature | Node.js fs | @componentor/fs v2 | @componentor/fs v1 | LightningFS |
-|---------|------------|--------------------|--------------------|-------------|
-| `readFile` | ✅ | ✅ | ✅ | ✅ |
-| `writeFile` | ✅ | ✅ | ✅ | ✅ |
-| `readFileSync` | ✅ | ✅ Tier 1 | ❌ | ❌ |
-| `writeFileSync` | ✅ | ✅ Tier 1 | ❌ | ❌ |
-| `mkdir` / `mkdirSync` | ✅ | ✅ | ✅ | ✅ |
-| `readdir` / `readdirSync` | ✅ | ✅ | ✅ | ✅ |
-| `stat` / `statSync` | ✅ | ✅ | ✅ | ✅ |
-| `unlink` / `unlinkSync` | ✅ | ✅ | ✅ | ✅ |
-| `rename` / `renameSync` | ✅ | ✅ | ✅ | ✅ |
-| `rm` (recursive) | ✅ | ✅ | ✅ | ❌ |
-| `copyFile` | ✅ | ✅ | ✅ | ❌ |
-| `symlink` / `readlink` | ✅ | ✅ | ✅ | ✅ |
-| `watch` / `watchFile` | ✅ | ✅ | ❌ | ❌ |
-| `open` / `FileHandle` | ✅ | ✅ | ❌ | ❌ |
-| `opendir` / `Dir` | ✅ | ✅ | ❌ | ❌ |
-| `mkdtemp` | ✅ | ✅ | ❌ | ❌ |
-| Streams | ✅ | ✅ | ❌ | ❌ |
-
-### Performance Tiers
-
-| Capability | Tier 1 Sync | Tier 1 Promises | Tier 2 | Legacy v1 | LightningFS |
-|------------|-------------|-----------------|--------|-----------|-------------|
-| **Sync API** | ✅ | ❌ | ❌ | ❌ | ❌ |
-| **Async API** | ✅ | ✅ | ✅ | ✅ | ✅ |
-| **Requires COOP/COEP** | ✅ | ✅ | ❌ | ❌ | ❌ |
-| **SharedArrayBuffer** | ✅ | ✅ | ❌ | ❌ | ❌ |
-| **Handle Caching** | ✅ | ✅ | ❌ | ❌ | N/A |
-| **Zero-copy Transfer** | ✅ | ❌ | ❌ | ❌ | ❌ |
-| **Cross-tab Safety** | ✅ | ✅ | ✅ | ✅ | ❌ |
-| **Storage Backend** | OPFS | OPFS | OPFS | OPFS | IndexedDB |
-
-### Architecture Comparison
-
-| Aspect | @componentor/fs v2 | @componentor/fs v1 | LightningFS |
-|--------|--------------------|--------------------|-------------|
-| **Storage** | OPFS (native FS) | OPFS | IndexedDB |
-| **Worker** | Dedicated kernel | Shared worker | None |
-| **Sync Method** | Atomics.wait | N/A | N/A |
-| **Handle Strategy** | Cached (100 max) | Per-operation | N/A |
-| **Locking** | navigator.locks | navigator.locks | None |
-| **Bundle Size** | ~16KB | ~12KB | ~25KB |
-| **TypeScript** | Full | Full | Partial |
-
 ## Browser Support
 
-| Browser | Tier 1 (Sync) | Tier 2 (Async) |
-|---------|---------------|----------------|
+| Browser | Sync API | Async API |
+|---------|----------|-----------|
 | Chrome 102+ | Yes | Yes |
 | Edge 102+ | Yes | Yes |
 | Firefox 111+ | Yes* | Yes |
@@ -445,103 +449,71 @@ await git.commit({
 | Opera 88+ | Yes | Yes |
 
 \* Firefox requires `dom.workers.modules.enabled` flag
-\** Safari doesn't support `createSyncAccessHandle` in workers
+\** Safari doesn't support `SharedArrayBuffer` in the required context
 
 ## Troubleshooting
 
 ### "SharedArrayBuffer is not defined"
 
-Your page is not crossOriginIsolated. Add COOP/COEP headers:
+Your page is not `crossOriginIsolated`. Add COOP/COEP headers (see above). The async API still works without them.
 
-```
-Cross-Origin-Opener-Policy: same-origin
-Cross-Origin-Embedder-Policy: require-corp
-```
+### "Sync API requires crossOriginIsolated"
+
+Same issue — sync methods (`readFileSync`, etc.) need `SharedArrayBuffer`. Use `fs.promises.*` as a fallback.
 
 ### "Atomics.wait cannot be called in this context"
 
-`Atomics.wait` can only be called from a Worker. The library handles this automatically - use the async API on the main thread.
+`Atomics.wait` only works in Workers. The library handles this internally — if you see this error, you're likely calling sync methods from the main thread without proper COOP/COEP headers.
 
-### "NotAllowedError: Access handle is already open"
+### Files not visible in OPFS DevTools
 
-Another tab or operation has the file open. The library uses `navigator.locks` to prevent this, but if you're using multiple filesystem instances, ensure they coordinate.
+Make sure `opfsSync` is enabled (it's `true` by default). Files are mirrored to OPFS in the background after each VFS operation. Check DevTools > Application > Storage > OPFS.
 
-### Slow Performance
+### External OPFS changes not detected
 
-1. Check if Tier 1 is enabled: `console.log(crossOriginIsolated)`
-2. Use batch operations when possible
-3. Disable flush for bulk writes: `{ flush: false }`
-4. Call `fs.promises.flush()` after bulk operations
+`FileSystemObserver` requires Chrome 129+. The VFS instance must be running (observer is set up during init). Changes to files outside the configured `root` directory won't be detected.
 
 ## Changelog
 
-### v2.0.11 (2026)
-
-**Document streams API:**
-- Update readme about available streams API
-
-### v2.0.7 (2025)
-
-**High-Performance Handle Caching with `readwrite-unsafe`:**
-- Uses `readwrite-unsafe` mode (Chrome 121+) - no exclusive locks
-- Zero per-operation overhead: cache lookup is a single Map.get()
-- Browser extensions can access files while handles are cached
-- LRU eviction when cache exceeds 100 handles
-- Falls back to 100ms debounced release on older browsers (handles block)
-
-### v2.0.2 (2025)
-
-**Improvements:**
-- Sync access handles now auto-release after idle timeout
-- Allows external tools (like OPFS Chrome extension) to access files when idle
-- Maintains full performance during active operations
-
-### v2.0.1 (2025)
+### v3.0.1 (2026)
 
 **Bug Fixes:**
-- Fixed mtime not updating correctly when files are modified
-- `stat()` now always returns accurate `lastModified` from OPFS instead of approximation
-- Ensures git status and other mtime-dependent operations work correctly
+- Fix empty files (e.g. `.gitkeep`) not being mirrored to OPFS — both the sync-relay (skipped sending empty data) and opfs-sync worker (skipped writing 0-byte files) now handle empty files correctly
 
-### v2.0.0 (2025)
+**Benchmark:**
+- Add memfs (in-memory) to the benchmark suite for comparison
 
-**Major rewrite with sync API support and performance tiers.**
+### v3.0.0 (2026)
 
-**New Features:**
-- Synchronous API (`readFileSync`, `writeFileSync`, etc.) via Atomics
-- Performance tiers (Tier 1 Sync, Tier 1 Promises, Tier 2)
-- Dedicated worker kernel with handle caching (100 max)
-- `watch()` and `watchFile()` for file change notifications
-- `FileHandle` API (`fs.promises.open()`)
-- `Dir` API (`fs.promises.opendir()`)
-- `mkdtemp()` for temporary directories
-- `flush()` and `purge()` for cache management
-- Full `Dirent` support with `withFileTypes` option
+**Complete architecture rewrite — VFS binary format with SharedArrayBuffer.**
+
+**New Architecture:**
+- VFS binary format — all data stored in a single `.vfs.bin` file (Superblock → Inode Table → Path Table → Bitmap → Data Region)
+- SharedArrayBuffer + Atomics for true zero-overhead synchronous operations
+- Multi-tab leader/follower architecture with automatic failover via `navigator.locks` + Service Worker
+- Bidirectional OPFS sync — VFS mutations mirrored to real OPFS files, external changes synced back via `FileSystemObserver`
+- Workers inlined as blob URLs at build time (zero config, no external worker files)
+- Echo suppression for OPFS sync (prevents infinite sync loops)
 
 **Performance:**
-- 2-3x faster git clone vs LightningFS
-- 1.6x faster reads
-- Handle caching eliminates repeated open/close overhead
-- Zero-copy data transfer with SharedArrayBuffer (Tier 1)
+- 9-28x faster reads vs LightningFS
+- 2.8-4x faster writes vs LightningFS
+- 2.8-10x faster batch operations vs LightningFS
+- Fire-and-forget OPFS sync — zero impact on hot path
 
 **Breaking Changes:**
-- Requires `crossOriginIsolated` for Tier 1 (sync) features
-- New architecture - not backwards compatible with v1 internals
-- Minimum browser versions increased
+- New API: `new VFSFileSystem(config)` instead of default `fs` singleton
+- `createFS(config)` and `getDefaultFS()` helpers available
+- Requires `crossOriginIsolated` for sync API (async API works everywhere)
+- Complete internal rewrite — not backwards compatible with v2 internals
 
-### v1.2.8 (2024)
+### v2.0.0 (2025)
 
-- Final release of v1 branch
-- OPFS-based async filesystem
-- Basic isomorphic-git compatibility
-- Cross-tab locking with `navigator.locks`
+Major rewrite with sync API support via OPFS sync access handles and performance tiers.
 
 ### v1.0.0 (2024)
 
-- Initial release
-- Async-only OPFS filesystem
-- Node.js `fs.promises` compatible API
-- Basic directory and file operations
+Initial release — async-only OPFS filesystem with `fs.promises` API.
 
 ## Contributing
 
@@ -549,9 +521,9 @@ Another tab or operation has the file open. The library uses `navigator.locks` t
 git clone https://github.com/componentor/fs
 cd fs
 npm install
-npm run dev      # Watch mode
-npm test         # Run tests
-npm run benchmark:open  # Run benchmarks
+npm run build       # Build the library
+npm test            # Run unit tests (77 tests)
+npm run benchmark:open  # Run benchmarks in browser
 ```
 
 ## License