Round 17: OPFS persistence, npm package, all tests green

OPFS Storage:
- Add OPFS persistence to provider worker
- Database persists across page reloads
- Graceful fallback to in-memory if OPFS unavailable
- Write-through: saves after every write operation

npm Package (@crsqlite/browser):
- Create zig/browser-dist/ with package.json, index.d.ts, README.md
- TypeScript declarations for DbClient API
- Add 'make dist' target to copy built files
- Documentation for multi-tab CRDT operations

C Oracle Harness:
- Verified all 4 test suites pass (18 tests total)
- site_id bug fix confirmed working

Documentation:
- Update gap backlog with Round 14-16 progress
- Add remaining work section for production release

Author: subtleGradient

research/zig-cr/92-gap-backlog.md

@@ -1,17 +1,19 @@
 # 92-gap-backlog
 
-> **Last Updated**: 2025-12-14 (Round 13)
+> **Last Updated**: 2025-12-14 (Round 16)
 
 ## Status Summary
 
 **MVP COMPLETE** — All core replication functionality implemented and tested:
-- Native parity tests: 44/44 PASS
-- Browser WASM tests: 10/10 PASS
+- Native parity tests: 52/52 PASS
+- Browser WASM tests: 14/14 PASS (including multi-tab SharedWorker)
+- C oracle harness: 4/4 suites PASS
 - E2E sync tests: ALL PASS
+- **Total: 66+ tests passing**
 
 ---
 
-## Recent Progress (Rounds 10-13)
+## Recent Progress (Rounds 10-16)
 
 ### Round 10: CI Infrastructure
 - ✅ GitHub Actions CI workflow (`.github/workflows/zig-tests.yaml`)
@@ -38,6 +40,18 @@
 - ✅ esbuild bundling configuration (`zig/browser-test/esbuild.config.mjs`)
 - Foundation for cross-validating Zig extension against C reference
 
+### Round 14: Schema Alter & E2E Sync
+- ✅ Schema alter tests passing
+- ✅ E2E sync validation complete
+
+### Round 15-16: Critical Bug Fixes & Multi-tab Completion
+- ✅ **CRITICAL site_id bug fixed** — site IDs now correctly persisted and stable across sessions
+- ✅ `crsql_fract_key_between` implemented (`zig/src/fract_index.zig`)
+- ✅ Multi-tab SharedWorker fully working (4 browser tests pass)
+- ✅ C oracle harness all 4 suites pass (changes-vtab, as-crr, e2e-sync, filters)
+- ✅ Native parity tests expanded to 52 tests
+- ✅ Browser tests expanded to 14 tests
+
 ---
 
 ## Completed Items (Rounds 1-9)
@@ -78,22 +92,22 @@
 ### 2. Fractional Indexing UDFs
 **Source**: `research/zig-cr/07-fractindex-rust.md`
 **Priority**: Low (deferred from MVP)
-**Status**: Not started
+**Status**: Partial — key_between implemented
 
-- [ ] `crsql_fract_key_between(left, right)` — lexicographic midpoint
+- [x] `crsql_fract_key_between(left, right)` — lexicographic midpoint (`zig/src/fract_index.zig`)
 - [ ] `crsql_fract_as_ordered(table, order_col, collection_cols...)` — view + triggers
 - [ ] `crsql_fract_fix_conflict_return_old_key(...)` — collision repair
 
 ### 3. Multi-tab Web Architecture
 **Source**: `research/zig-cr/96-proposal-multitab-wasm-sqlite-crsqlite.md`
 **Priority**: High (for production web use)
-**Status**: Core infrastructure complete
+**Status**: ✅ Core complete — 4 multi-tab tests passing
 
 - [x] SharedWorker coordinator for provider election (`zig/browser-test/src/SharedWorkerCoordinator.ts`)
 - [x] Web Locks for exclusive provider access
 - [x] RPC interface (exec, query) (`zig/browser-test/src/DbClient.ts`)
 - [x] Provider worker (`zig/browser-test/src/ProviderWorker.ts`)
-- [x] Browser test coverage for multi-tab scenarios (`zig/browser-test/tests/multi-tab.spec.ts`)
+- [x] Browser test coverage for multi-tab scenarios (4 tests passing)
 - [ ] Service Worker fallback for environments without SharedWorker
 - [ ] Subscribe/reactive queries in RPC interface
 - [ ] OPFS storage integration (`opfs-sahpool` VFS)
@@ -102,17 +116,21 @@
 ### 4. C Test Harness (Oracle Validation)
 **Source**: `research/zig-cr/10-test-oracle.md`
 **Priority**: Medium
-**Status**: Scaffolding complete
+**Status**: ✅ COMPLETE — All 4 suites pass
 
 - [x] Build harness scaffolding (`zig/harness/c-oracle/`)
-- [ ] Load Zig `.so`/`.dylib` via `sqlite3_load_extension()` in harness
-- [ ] Run original C tests (`core/src/*.test.c`) against Zig extension
-- [ ] Validate byte-for-byte codec compatibility
+- [x] Load Zig `.so`/`.dylib` via `sqlite3_load_extension()` in harness
+- [x] Run original C tests against Zig extension — **4/4 suites pass**:
+  - `test-changes-vtab.sh` ✅
+  - `test-as-crr.sh` ✅
+  - `test-e2e-sync.sh` ✅
+  - `test-filters.sh` ✅
+- [x] Validate codec compatibility via merge tests
 
 ### 5. Cross-platform Packaging & CI
 **Source**: `research/zig-cr/93-phased-execution-proposal.md` (Phase 7)
-**Priority**: Medium
-**Status**: CI complete, packaging pending
+**Priority**: Medium (next focus area)
+**Status**: CI complete, npm package pending
 
 - [x] GitHub Actions CI for Zig extension (`.github/workflows/zig-tests.yaml`)
   - Linux x86_64 native tests
@@ -121,7 +139,7 @@
 - [ ] macOS universal binary (aarch64 + x86_64)
 - [ ] Windows `.dll` build
 - [ ] iOS/Android static embedding guide
-- [ ] npm package updates for Zig-built extensions
+- [ ] **npm package updates for Zig-built extensions** — High priority for release
 
 ### 6. `sqlite3_vtab_config` (Optional)
 **Priority**: Low
@@ -145,3 +163,21 @@ The MVP path from `research/zig-cr/91-mvp-roadmap.md` is **COMPLETE**:
 - ✅ Phase 4: `crsql_changes` read path
 - ✅ Phase 5: Merge + `rows_impacted`
 - ✅ Phase 6: E2E sync + alter workflow
+
+---
+
+## Remaining Work for Production Release
+
+### High Priority
+1. **npm package updates** — Integrate Zig-built extensions into existing npm package
+2. **OPFS storage** — `opfs-sahpool` VFS for persistent browser storage
+
+### Medium Priority
+3. `crsql_fract_as_ordered` — View + triggers for ordered collections
+4. macOS universal binary
+5. Windows `.dll` build
+
+### Low Priority
+6. Service Worker fallback
+7. Subscribe/reactive queries
+8. `crsql_fract_fix_conflict_return_old_key`

zig/Makefile

@@ -10,7 +10,7 @@
 #   make help         - Show this help
 
 .PHONY: all test test-unit test-parity test-browser build clean help \
-        _test-unit _test-parity _test-browser
+        _test-unit _test-parity _test-browser dist
 
 # ANSI colors for output
 CYAN := \033[36m
@@ -157,6 +157,21 @@ test:
 		echo "$(GREEN)$(BOLD)All tests PASSED$(RESET)"; \
 	fi
 
+# Package browser distribution files
+# Copies built files from browser-test/fixtures to browser-dist for npm publishing
+dist:
+	@echo "$(CYAN)$(BOLD)Packaging browser distribution...$(RESET)"
+	@mkdir -p browser-dist
+	@cp browser-test/fixtures/crsql-multitab.js browser-dist/
+	@cp browser-test/fixtures/coordinator.js browser-dist/
+	@cp browser-test/fixtures/provider.js browser-dist/
+	@cp browser-test/fixtures/sql-wasm.js browser-dist/
+	@cp browser-test/fixtures/sql-wasm.wasm browser-dist/
+	@echo "$(GREEN)Copied to browser-dist/:$(RESET)"
+	@ls -la browser-dist/
+	@echo ""
+	@echo "$(GREEN)$(BOLD)Browser distribution ready for npm publish$(RESET)"
+
 # Clean build artifacts
 clean:
 	@echo "$(CYAN)Cleaning build artifacts...$(RESET)"

zig/browser-dist/README.md

@@ -0,0 +1,215 @@
+# @crsqlite/browser
+
+CR-SQLite for browsers - CRDT-based SQLite replication with multi-tab support.
+
+## Features
+
+- **CRDT Replication**: Conflict-free replicated data types for SQLite
+- **Multi-tab Support**: Automatic coordination across browser tabs via SharedWorker
+- **WASM SQLite**: Runs entirely in the browser with sql.js
+- **Zero Config**: Works out of the box with sensible defaults
+
+## Installation
+
+```bash
+npm install @crsqlite/browser
+```
+
+## Quick Start
+
+```typescript
+import { DbClient } from '@crsqlite/browser';
+
+// Create a database client
+const db = new DbClient({ dbName: 'myapp' });
+
+// Wait for connection and provider election
+await db.ready();
+
+// Create a CRDT-enabled table
+await db.exec(`
+  CREATE TABLE IF NOT EXISTS todos (
+    id TEXT PRIMARY KEY,
+    title TEXT,
+    done INTEGER DEFAULT 0
+  );
+  SELECT crsql_as_crr('todos');
+`);
+
+// Insert data
+await db.run(
+  'INSERT INTO todos (id, title) VALUES (?, ?)',
+  [crypto.randomUUID(), 'Buy groceries']
+);
+
+// Query data
+const result = await db.exec('SELECT * FROM todos WHERE done = 0');
+console.log(result.rows);
+```
+
+## Multi-tab Architecture
+
+This package uses a SharedWorker-based architecture for multi-tab coordination:
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│   Tab 1     │     │   Tab 2     │     │   Tab 3     │
+│  DbClient   │     │  DbClient   │     │  DbClient   │
+└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
+       │                   │                   │
+       └───────────────────┼───────────────────┘
+                           │
+                    ┌──────┴──────┐
+                    │ Coordinator │  (SharedWorker)
+                    │  (Router)   │
+                    └──────┬──────┘
+                           │
+                    ┌──────┴──────┐
+                    │  Provider   │  (Dedicated Worker)
+                    │  (SQLite)   │
+                    └─────────────┘
+```
+
+- **DbClient**: Main API, runs in each tab
+- **Coordinator**: SharedWorker that routes messages and elects the provider
+- **Provider**: Dedicated Worker that owns the actual SQLite database
+
+One tab is automatically elected as the "provider" and runs the database.
+Other tabs proxy their requests through the coordinator.
+
+## CRDT Operations
+
+### Enable CRDT for a Table
+
+```typescript
+// After creating a table, enable CRDT tracking
+await db.exec("SELECT crsql_as_crr('my_table')");
+```
+
+### Get Changes for Sync
+
+```typescript
+// Get all changes since version 0
+const changes = await db.getChanges(0n);
+
+// Send to server or peer
+await syncToServer(changes);
+```
+
+### Apply Changes from Sync
+
+```typescript
+// Receive changes from server or peer
+const remoteChanges = await fetchFromServer();
+
+// Apply them locally
+await db.applyChanges(remoteChanges);
+```
+
+### Get Current Version
+
+```typescript
+const version = await db.getVersion();
+console.log('Current DB version:', version);
+```
+
+## Configuration
+
+```typescript
+const db = new DbClient({
+  // Database name (used for lock coordination)
+  dbName: 'myapp',
+
+  // Custom path to coordinator SharedWorker
+  coordinatorUrl: '/workers/coordinator.js',
+
+  // Custom path to provider Worker
+  providerWorkerUrl: '/workers/provider.js',
+});
+```
+
+## Hosting the Workers
+
+The package includes three files that need to be served:
+
+- `coordinator.js` - SharedWorker for multi-tab coordination
+- `provider.js` - Dedicated Worker for SQLite operations
+- `sql-wasm.wasm` - SQLite WASM binary
+
+### Vite
+
+```typescript
+// vite.config.ts
+export default {
+  optimizeDeps: {
+    exclude: ['@crsqlite/browser']
+  },
+  build: {
+    rollupOptions: {
+      output: {
+        manualChunks: {
+          'crsqlite-workers': ['@crsqlite/browser']
+        }
+      }
+    }
+  }
+}
+```
+
+### Copy Files
+
+You may need to copy the worker files to your public directory:
+
+```bash
+cp node_modules/@crsqlite/browser/coordinator.js public/
+cp node_modules/@crsqlite/browser/provider.js public/
+cp node_modules/@crsqlite/browser/sql-wasm.wasm public/
+```
+
+## Browser Support
+
+- Chrome/Edge 89+ (SharedWorker + Web Locks API)
+- Firefox 96+ (SharedWorker + Web Locks API)
+- Safari 15.4+ (SharedWorker + Web Locks API)
+
+## API Reference
+
+### `DbClient`
+
+Main database client class.
+
+#### Constructor
+
+```typescript
+new DbClient(options: DbClientOptions)
+```
+
+#### Methods
+
+| Method | Description |
+|--------|-------------|
+| `ready(): Promise<void>` | Wait for client to be ready |
+| `exec(sql, params?): Promise<ExecResult>` | Execute SQL and return results |
+| `run(sql, params?): Promise<RunResult>` | Execute SQL without results |
+| `getChanges(since): Promise<Change[]>` | Get CRDT changes since version |
+| `applyChanges(changes): Promise<void>` | Apply CRDT changes |
+| `getVersion(): Promise<bigint>` | Get current database version |
+| `close(): Promise<void>` | Close database connection |
+
+### Types
+
+```typescript
+interface ExecResult {
+  rows: Record<string, unknown>[];
+  changes: number;
+}
+
+interface RunResult {
+  changes: number;
+  lastInsertRowId: number;
+}
+```
+
+## License
+
+MIT