@taladb/web 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taladb/web",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "TalaDB WASM bindings — document queries and vector search in the browser",
   "main": "pkg/taladb_web.js",
   "types": "pkg/taladb_web.d.ts",

package/pkg/package.json

@@ -5,7 +5,7 @@
     "thinkgrid-labs"
   ],
   "description": "TalaDB browser WASM bindings (wasm-bindgen + OPFS)",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "license": "MIT",
   "files": [
     "taladb_web_bg.wasm",

package/pkg/taladb_web.d.ts

@@ -16,10 +16,13 @@ export class CollectionWasm {
     /**
      * Create a vector index on `field`.
      *
-     * `dimensions` — expected vector length.
-     * `metric`     — optional string: `"cosine"` (default), `"dot"`, or `"euclidean"`.
+     * `dimensions`           — expected vector length.
+     * `metric`               — optional: `"cosine"` (default), `"dot"`, or `"euclidean"`.
+     * `index_type`           — optional: `"flat"` (default) or `"hnsw"`.
+     * `hnsw_m`               — HNSW connectivity (default 16).
+     * `hnsw_ef_construction` — build quality (default 200).
      */
-    createVectorIndex(field: string, dimensions: number, metric?: string | null): void;
+    createVectorIndex(field: string, dimensions: number, metric?: string | null, index_type?: string | null, hnsw_m?: number | null, hnsw_ef_construction?: number | null): void;
     /**
      * Delete all matching documents. Returns the count deleted.
      */
@@ -33,7 +36,7 @@ export class CollectionWasm {
      */
     dropIndex(field: string): void;
     /**
-     * Drop a vector index.
+     * Drop a vector index (and its HNSW graph if present).
      */
     dropVectorIndex(field: string): void;
     /**
@@ -69,6 +72,10 @@ export class CollectionWasm {
      * Update the first matching document. Returns true if a document was updated.
      */
     updateOne(filter: any, update: any): boolean;
+    /**
+     * Rebuild the HNSW graph from the current flat vector table.
+     */
+    upgradeVectorIndex(field: string): void;
 }
 
 export class TalaDBWasm {
@@ -119,9 +126,14 @@ export class WorkerDB {
     createFtsIndex(collection: string, field: string): void;
     createIndex(collection: string, field: string): void;
     /**
-     * Create a vector index. `metric_str`: `"cosine"` | `"dot"` | `"euclidean"` (default cosine).
+     * Create a vector index.
+     *
+     * - `metric_str`: `"cosine"` (default) | `"dot"` | `"euclidean"`
+     * - `index_type`: `"flat"` (default) | `"hnsw"`
+     * - `hnsw_m`: HNSW connectivity (default 16, only used when `index_type = "hnsw"`)
+     * - `hnsw_ef_construction`: build-time quality (default 200, only used when `index_type = "hnsw"`)
      */
-    createVectorIndex(collection: string, field: string, dimensions: number, metric_str?: string | null): void;
+    createVectorIndex(collection: string, field: string, dimensions: number, metric_str?: string | null, index_type?: string | null, hnsw_m?: number | null, hnsw_ef_construction?: number | null): void;
     /**
      * Delete all matching documents. Returns the count deleted.
      */
@@ -133,9 +145,16 @@ export class WorkerDB {
     dropFtsIndex(collection: string, field: string): void;
     dropIndex(collection: string, field: string): void;
     /**
-     * Drop a vector index.
+     * Drop a vector index (and its HNSW graph if present).
      */
     dropVectorIndex(collection: string, field: string): void;
+    /**
+     * Serialize the entire in-memory database to bytes for persistence.
+     *
+     * Pass the returned bytes to `idbSaveSnapshot` to persist across page reloads.
+     * On next open, pass the same bytes to `openWithSnapshot` to restore all data.
+     */
+    exportSnapshot(): Uint8Array;
     /**
      * Find documents. Returns a JSON array of document objects.
      */
@@ -156,6 +175,11 @@ export class WorkerDB {
      * Insert many documents. Returns a JSON array of ULID strings.
      */
     insertMany(collection: string, docs_json: string): string;
+    /**
+     * Returns a JSON string `{ btree: string[], fts: string[], vector: string[] }`
+     * listing all indexes on the given collection.
+     */
+    listIndexes(collection: string): string;
     /**
      * Open an in-memory database (for tests and OPFS-unavailable fallback).
      */
@@ -170,6 +194,18 @@ export class WorkerDB {
      * ```
      */
     static openWithOpfs(sync_handle: FileSystemSyncAccessHandle): WorkerDB;
+    /**
+     * Open a database, restoring from a previously exported snapshot if provided.
+     *
+     * Pass the bytes returned by `WorkerDB.exportSnapshot()` (or `null`/`undefined`
+     * for a fresh empty database). Used by the IndexedDB fallback path.
+     *
+     * ```js
+     * const bytes = await idbLoadSnapshot(dbName);   // null on first open
+     * const workerDb = WorkerDB.openWithSnapshot(bytes);
+     * ```
+     */
+    static openWithSnapshot(data?: Uint8Array | null): WorkerDB;
     /**
      * Update all matching documents. Returns the count updated.
      */
@@ -178,17 +214,24 @@ export class WorkerDB {
      * Update the first matching document. Returns `true` / `false`.
      */
     updateOne(collection: string, filter_json: string, update_json: string): boolean;
+    /**
+     * Rebuild the HNSW graph for a vector index from the current flat vector
+     * table.  Use after bulk inserts or when ANN recall has degraded.
+     *
+     * No-op when the `vector-hnsw` feature is disabled or the index is flat-only.
+     */
+    upgradeVectorIndex(collection: string, field: string): void;
 }
 
 /**
  * Load a previous database snapshot from IndexedDB.
- * Returns None if no snapshot exists yet.
+ * Returns `None` if no snapshot exists yet (first open) or IDB is unavailable.
  */
 export function idb_load_snapshot(db_name: string): Promise<Uint8Array | undefined>;
 
 /**
- * Persist a database snapshot to IndexedDB (via localStorage for simplicity in v1).
- * In v2 this should use a proper IDBObjectStore for binary data.
+ * Persist a database snapshot to IndexedDB.
+ * Returns `true` on success, `false` on any failure.
  */
 export function idb_save_snapshot(db_name: string, data: Uint8Array): Promise<boolean>;
 
@@ -237,26 +280,30 @@ export interface InitOutput {
     readonly workerdb_count: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
     readonly workerdb_createFtsIndex: (a: number, b: number, c: number, d: number, e: number) => [number, number];
     readonly workerdb_createIndex: (a: number, b: number, c: number, d: number, e: number) => [number, number];
-    readonly workerdb_createVectorIndex: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number];
+    readonly workerdb_createVectorIndex: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number) => [number, number];
     readonly workerdb_deleteMany: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
     readonly workerdb_deleteOne: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
     readonly workerdb_dropFtsIndex: (a: number, b: number, c: number, d: number, e: number) => [number, number];
     readonly workerdb_dropIndex: (a: number, b: number, c: number, d: number, e: number) => [number, number];
     readonly workerdb_dropVectorIndex: (a: number, b: number, c: number, d: number, e: number) => [number, number];
+    readonly workerdb_exportSnapshot: (a: number) => [number, number, number, number];
     readonly workerdb_find: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
     readonly workerdb_findNearest: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number) => [number, number, number, number];
     readonly workerdb_findOne: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
     readonly workerdb_insert: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
     readonly workerdb_insertMany: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
+    readonly workerdb_listIndexes: (a: number, b: number, c: number) => [number, number, number, number];
     readonly workerdb_openInMemory: () => [number, number, number];
     readonly workerdb_openWithOpfs: (a: any) => [number, number, number];
+    readonly workerdb_openWithSnapshot: (a: number, b: number) => [number, number, number];
     readonly workerdb_updateMany: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number, number];
     readonly workerdb_updateOne: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number, number];
+    readonly workerdb_upgradeVectorIndex: (a: number, b: number, c: number, d: number, e: number) => [number, number];
     readonly __wbg_collectionwasm_free: (a: number, b: number) => void;
     readonly __wbg_taladbwasm_free: (a: number, b: number) => void;
     readonly collectionwasm_count: (a: number, b: any) => [number, number, number];
     readonly collectionwasm_createIndex: (a: number, b: number, c: number) => [number, number];
-    readonly collectionwasm_createVectorIndex: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number];
+    readonly collectionwasm_createVectorIndex: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number) => [number, number];
     readonly collectionwasm_deleteMany: (a: number, b: any) => [number, number, number];
     readonly collectionwasm_deleteOne: (a: number, b: any) => [number, number, number];
     readonly collectionwasm_dropIndex: (a: number, b: number, c: number) => [number, number];
@@ -268,21 +315,24 @@ export interface InitOutput {
     readonly collectionwasm_insertMany: (a: number, b: any) => [number, number, number];
     readonly collectionwasm_updateMany: (a: number, b: any, c: any) => [number, number, number];
     readonly collectionwasm_updateOne: (a: number, b: any, c: any) => [number, number, number];
+    readonly collectionwasm_upgradeVectorIndex: (a: number, b: number, c: number) => [number, number];
     readonly taladbwasm_collection: (a: number, b: number, c: number) => number;
     readonly taladbwasm_exportSnapshot: (a: number) => [number, number, number, number];
     readonly taladbwasm_openInMemory: () => [number, number, number];
     readonly taladbwasm_openWithSnapshot: (a: number, b: number) => [number, number, number];
     readonly init: () => void;
-    readonly idb_load_snapshot: (a: number, b: number) => any;
-    readonly idb_save_snapshot: (a: number, b: number, c: number, d: number) => any;
     readonly is_opfs_available: () => any;
     readonly opfs_delete_snapshot: (a: number, b: number) => any;
     readonly opfs_flush_snapshot: (a: number, b: number, c: number, d: number) => any;
     readonly opfs_load_snapshot: (a: number, b: number) => any;
     readonly opfs_open_backend: (a: number, b: number) => any;
+    readonly idb_load_snapshot: (a: number, b: number) => any;
+    readonly idb_save_snapshot: (a: number, b: number, c: number, d: number) => any;
     readonly wasm_bindgen__closure__destroy__h1411c0b1433bd547: (a: number, b: number) => void;
+    readonly wasm_bindgen__closure__destroy__h7d7554216ff39279: (a: number, b: number) => void;
     readonly wasm_bindgen__convert__closures_____invoke__h4bd31e7387ab665d: (a: number, b: number, c: any) => [number, number];
     readonly wasm_bindgen__convert__closures_____invoke__h675f15260128efbc: (a: number, b: number, c: any, d: any) => void;
+    readonly wasm_bindgen__convert__closures_____invoke__h98155e79a0a742d1: (a: number, b: number, c: any) => void;
     readonly __wbindgen_malloc: (a: number, b: number) => number;
     readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_exn_store: (a: number) => void;

package/pkg/taladb_web.js

@@ -45,18 +45,26 @@ export class CollectionWasm {
     /**
      * Create a vector index on `field`.
      *
-     * `dimensions` — expected vector length.
-     * `metric`     — optional string: `"cosine"` (default), `"dot"`, or `"euclidean"`.
+     * `dimensions`           — expected vector length.
+     * `metric`               — optional: `"cosine"` (default), `"dot"`, or `"euclidean"`.
+     * `index_type`           — optional: `"flat"` (default) or `"hnsw"`.
+     * `hnsw_m`               — HNSW connectivity (default 16).
+     * `hnsw_ef_construction` — build quality (default 200).
      * @param {string} field
      * @param {number} dimensions
      * @param {string | null} [metric]
+     * @param {string | null} [index_type]
+     * @param {number | null} [hnsw_m]
+     * @param {number | null} [hnsw_ef_construction]
      */
-    createVectorIndex(field, dimensions, metric) {
+    createVectorIndex(field, dimensions, metric, index_type, hnsw_m, hnsw_ef_construction) {
         const ptr0 = passStringToWasm0(field, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         const len0 = WASM_VECTOR_LEN;
         var ptr1 = isLikeNone(metric) ? 0 : passStringToWasm0(metric, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         var len1 = WASM_VECTOR_LEN;
-        const ret = wasm.collectionwasm_createVectorIndex(this.__wbg_ptr, ptr0, len0, dimensions, ptr1, len1);
+        var ptr2 = isLikeNone(index_type) ? 0 : passStringToWasm0(index_type, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        var len2 = WASM_VECTOR_LEN;
+        const ret = wasm.collectionwasm_createVectorIndex(this.__wbg_ptr, ptr0, len0, dimensions, ptr1, len1, ptr2, len2, isLikeNone(hnsw_m) ? 0x100000001 : (hnsw_m) >>> 0, isLikeNone(hnsw_ef_construction) ? 0x100000001 : (hnsw_ef_construction) >>> 0);
         if (ret[1]) {
             throw takeFromExternrefTable0(ret[0]);
         }
@@ -98,7 +106,7 @@ export class CollectionWasm {
         }
     }
     /**
-     * Drop a vector index.
+     * Drop a vector index (and its HNSW graph if present).
      * @param {string} field
      */
     dropVectorIndex(field) {
@@ -218,6 +226,18 @@ export class CollectionWasm {
         }
         return ret[0] !== 0;
     }
+    /**
+     * Rebuild the HNSW graph from the current flat vector table.
+     * @param {string} field
+     */
+    upgradeVectorIndex(field) {
+        const ptr0 = passStringToWasm0(field, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.collectionwasm_upgradeVectorIndex(this.__wbg_ptr, ptr0, len0);
+        if (ret[1]) {
+            throw takeFromExternrefTable0(ret[0]);
+        }
+    }
 }
 if (Symbol.dispose) CollectionWasm.prototype[Symbol.dispose] = CollectionWasm.prototype.free;
 
@@ -370,20 +390,30 @@ export class WorkerDB {
         }
     }
     /**
-     * Create a vector index. `metric_str`: `"cosine"` | `"dot"` | `"euclidean"` (default cosine).
+     * Create a vector index.
+     *
+     * - `metric_str`: `"cosine"` (default) | `"dot"` | `"euclidean"`
+     * - `index_type`: `"flat"` (default) | `"hnsw"`
+     * - `hnsw_m`: HNSW connectivity (default 16, only used when `index_type = "hnsw"`)
+     * - `hnsw_ef_construction`: build-time quality (default 200, only used when `index_type = "hnsw"`)
      * @param {string} collection
      * @param {string} field
      * @param {number} dimensions
      * @param {string | null} [metric_str]
+     * @param {string | null} [index_type]
+     * @param {number | null} [hnsw_m]
+     * @param {number | null} [hnsw_ef_construction]
      */
-    createVectorIndex(collection, field, dimensions, metric_str) {
+    createVectorIndex(collection, field, dimensions, metric_str, index_type, hnsw_m, hnsw_ef_construction) {
         const ptr0 = passStringToWasm0(collection, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         const len0 = WASM_VECTOR_LEN;
         const ptr1 = passStringToWasm0(field, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         const len1 = WASM_VECTOR_LEN;
         var ptr2 = isLikeNone(metric_str) ? 0 : passStringToWasm0(metric_str, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         var len2 = WASM_VECTOR_LEN;
-        const ret = wasm.workerdb_createVectorIndex(this.__wbg_ptr, ptr0, len0, ptr1, len1, dimensions, ptr2, len2);
+        var ptr3 = isLikeNone(index_type) ? 0 : passStringToWasm0(index_type, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        var len3 = WASM_VECTOR_LEN;
+        const ret = wasm.workerdb_createVectorIndex(this.__wbg_ptr, ptr0, len0, ptr1, len1, dimensions, ptr2, len2, ptr3, len3, isLikeNone(hnsw_m) ? 0x100000001 : (hnsw_m) >>> 0, isLikeNone(hnsw_ef_construction) ? 0x100000001 : (hnsw_ef_construction) >>> 0);
         if (ret[1]) {
             throw takeFromExternrefTable0(ret[0]);
         }
@@ -451,7 +481,7 @@ export class WorkerDB {
         }
     }
     /**
-     * Drop a vector index.
+     * Drop a vector index (and its HNSW graph if present).
      * @param {string} collection
      * @param {string} field
      */
@@ -465,6 +495,22 @@ export class WorkerDB {
             throw takeFromExternrefTable0(ret[0]);
         }
     }
+    /**
+     * Serialize the entire in-memory database to bytes for persistence.
+     *
+     * Pass the returned bytes to `idbSaveSnapshot` to persist across page reloads.
+     * On next open, pass the same bytes to `openWithSnapshot` to restore all data.
+     * @returns {Uint8Array}
+     */
+    exportSnapshot() {
+        const ret = wasm.workerdb_exportSnapshot(this.__wbg_ptr);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        var v1 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+        wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+        return v1;
+    }
     /**
      * Find documents. Returns a JSON array of document objects.
      * @param {string} collection
@@ -612,6 +658,32 @@ export class WorkerDB {
             wasm.__wbindgen_free(deferred4_0, deferred4_1, 1);
         }
     }
+    /**
+     * Returns a JSON string `{ btree: string[], fts: string[], vector: string[] }`
+     * listing all indexes on the given collection.
+     * @param {string} collection
+     * @returns {string}
+     */
+    listIndexes(collection) {
+        let deferred3_0;
+        let deferred3_1;
+        try {
+            const ptr0 = passStringToWasm0(collection, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            const len0 = WASM_VECTOR_LEN;
+            const ret = wasm.workerdb_listIndexes(this.__wbg_ptr, ptr0, len0);
+            var ptr2 = ret[0];
+            var len2 = ret[1];
+            if (ret[3]) {
+                ptr2 = 0; len2 = 0;
+                throw takeFromExternrefTable0(ret[2]);
+            }
+            deferred3_0 = ptr2;
+            deferred3_1 = len2;
+            return getStringFromWasm0(ptr2, len2);
+        } finally {
+            wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+        }
+    }
     /**
      * Open an in-memory database (for tests and OPFS-unavailable fallback).
      * @returns {WorkerDB}
@@ -641,6 +713,28 @@ export class WorkerDB {
         }
         return WorkerDB.__wrap(ret[0]);
     }
+    /**
+     * Open a database, restoring from a previously exported snapshot if provided.
+     *
+     * Pass the bytes returned by `WorkerDB.exportSnapshot()` (or `null`/`undefined`
+     * for a fresh empty database). Used by the IndexedDB fallback path.
+     *
+     * ```js
+     * const bytes = await idbLoadSnapshot(dbName);   // null on first open
+     * const workerDb = WorkerDB.openWithSnapshot(bytes);
+     * ```
+     * @param {Uint8Array | null} [data]
+     * @returns {WorkerDB}
+     */
+    static openWithSnapshot(data) {
+        var ptr0 = isLikeNone(data) ? 0 : passArray8ToWasm0(data, wasm.__wbindgen_malloc);
+        var len0 = WASM_VECTOR_LEN;
+        const ret = wasm.workerdb_openWithSnapshot(ptr0, len0);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return WorkerDB.__wrap(ret[0]);
+    }
     /**
      * Update all matching documents. Returns the count updated.
      * @param {string} collection
@@ -681,12 +775,30 @@ export class WorkerDB {
         }
         return ret[0] !== 0;
     }
+    /**
+     * Rebuild the HNSW graph for a vector index from the current flat vector
+     * table.  Use after bulk inserts or when ANN recall has degraded.
+     *
+     * No-op when the `vector-hnsw` feature is disabled or the index is flat-only.
+     * @param {string} collection
+     * @param {string} field
+     */
+    upgradeVectorIndex(collection, field) {
+        const ptr0 = passStringToWasm0(collection, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(field, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.workerdb_upgradeVectorIndex(this.__wbg_ptr, ptr0, len0, ptr1, len1);
+        if (ret[1]) {
+            throw takeFromExternrefTable0(ret[0]);
+        }
+    }
 }
 if (Symbol.dispose) WorkerDB.prototype[Symbol.dispose] = WorkerDB.prototype.free;
 
 /**
  * Load a previous database snapshot from IndexedDB.
- * Returns None if no snapshot exists yet.
+ * Returns `None` if no snapshot exists yet (first open) or IDB is unavailable.
  * @param {string} db_name
  * @returns {Promise<Uint8Array | undefined>}
  */
@@ -698,8 +810,8 @@ export function idb_load_snapshot(db_name) {
 }
 
 /**
- * Persist a database snapshot to IndexedDB (via localStorage for simplicity in v1).
- * In v2 this should use a proper IDBObjectStore for binary data.
+ * Persist a database snapshot to IndexedDB.
+ * Returns `true` on success, `false` on any failure.
  * @param {string} db_name
  * @param {Uint8Array} data
  * @returns {Promise<boolean>}
@@ -876,14 +988,14 @@ function __wbg_get_imports() {
         __wbg__wbg_cb_unref_6b5b6b8576d35cb1: function(arg0) {
             arg0._wbg_cb_unref();
         },
+        __wbg_apply_ac9afb97ca32f169: function() { return handleError(function (arg0, arg1, arg2) {
+            const ret = arg0.apply(arg1, arg2);
+            return ret;
+        }, arguments); },
         __wbg_arrayBuffer_7ff5e58aa85a64f7: function(arg0) {
             const ret = arg0.arrayBuffer();
             return ret;
         },
-        __wbg_buffer_60b8043cd926067d: function(arg0) {
-            const ret = arg0.buffer;
-            return ret;
-        },
         __wbg_call_2d781c1f4d5c0ef8: function() { return handleError(function (arg0, arg1, arg2) {
             const ret = arg0.call(arg1, arg2);
             return ret;
@@ -942,13 +1054,6 @@ function __wbg_get_imports() {
             const ret = arg0.getFile();
             return ret;
         },
-        __wbg_getItem_a7cc1d4f154f2e6f: function() { return handleError(function (arg0, arg1, arg2, arg3) {
-            const ret = arg1.getItem(getStringFromWasm0(arg2, arg3));
-            var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-            var len1 = WASM_VECTOR_LEN;
-            getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
-            getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
-        }, arguments); },
         __wbg_getRandomValues_3f44b700395062e5: function() { return handleError(function (arg0, arg1) {
             globalThis.crypto.getRandomValues(getArrayU8FromWasm0(arg0, arg1));
         }, arguments); },
@@ -968,10 +1073,6 @@ function __wbg_get_imports() {
             const ret = arg0[arg1 >>> 0];
             return ret;
         },
-        __wbg_get_index_87179971b8d350e4: function(arg0, arg1) {
-            const ret = arg0[arg1 >>> 0];
-            return ret;
-        },
         __wbg_get_unchecked_329cfe50afab7352: function(arg0, arg1) {
             const ret = arg0[arg1 >>> 0];
             return ret;
@@ -1096,10 +1197,6 @@ function __wbg_get_imports() {
             const ret = arg0.length;
             return ret;
         },
-        __wbg_localStorage_51c38b3b222e1ed2: function() { return handleError(function (arg0) {
-            const ret = arg0.localStorage;
-            return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);
-        }, arguments); },
         __wbg_navigator_9cebf56f28aa719b: function(arg0) {
             const ret = arg0.navigator;
             return ret;
@@ -1124,6 +1221,24 @@ function __wbg_get_imports() {
             const ret = new Object();
             return ret;
         },
+        __wbg_new_d098e265629cd10f: function(arg0, arg1) {
+            try {
+                var state0 = {a: arg0, b: arg1};
+                var cb0 = (arg0, arg1) => {
+                    const a = state0.a;
+                    state0.a = 0;
+                    try {
+                        return wasm_bindgen__convert__closures_____invoke__h675f15260128efbc(a, state0.b, arg0, arg1);
+                    } finally {
+                        state0.a = a;
+                    }
+                };
+                const ret = new Promise(cb0);
+                return ret;
+            } finally {
+                state0.a = state0.b = 0;
+            }
+        },
         __wbg_new_from_slice_22da9388ac046e50: function(arg0, arg1) {
             const ret = new Uint8Array(getArrayU8FromWasm0(arg0, arg1));
             return ret;
@@ -1165,6 +1280,10 @@ function __wbg_get_imports() {
         __wbg_prototypesetcall_d62e5099504357e6: function(arg0, arg1, arg2) {
             Uint8Array.prototype.set.call(getArrayU8FromWasm0(arg0, arg1), arg2);
         },
+        __wbg_push_e87b0e732085a946: function(arg0, arg1) {
+            const ret = arg0.push(arg1);
+            return ret;
+        },
         __wbg_queueMicrotask_0c399741342fb10f: function(arg0) {
             const ret = arg0.queueMicrotask;
             return ret;
@@ -1180,9 +1299,6 @@ function __wbg_get_imports() {
             const ret = Promise.resolve(arg0);
             return ret;
         },
-        __wbg_setItem_5f84aeef0d7f3c17: function() { return handleError(function (arg0, arg1, arg2, arg3, arg4) {
-            arg0.setItem(getStringFromWasm0(arg1, arg2), getStringFromWasm0(arg3, arg4));
-        }, arguments); },
         __wbg_set_282384002438957f: function(arg0, arg1, arg2) {
             arg0[arg1 >>> 0] = arg2;
         },
@@ -1243,31 +1359,36 @@ function __wbg_get_imports() {
             return ret;
         },
         __wbindgen_cast_0000000000000001: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { dtor_idx: 217, function: Function { arguments: [Externref], shim_idx: 218, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+            // Cast intrinsic for `Closure(Closure { dtor_idx: 422, function: Function { arguments: [Externref], shim_idx: 423, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
             const ret = makeMutClosure(arg0, arg1, wasm.wasm_bindgen__closure__destroy__h1411c0b1433bd547, wasm_bindgen__convert__closures_____invoke__h4bd31e7387ab665d);
             return ret;
         },
-        __wbindgen_cast_0000000000000002: function(arg0) {
+        __wbindgen_cast_0000000000000002: function(arg0, arg1) {
+            // Cast intrinsic for `Closure(Closure { dtor_idx: 63, function: Function { arguments: [Externref], shim_idx: 64, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, wasm.wasm_bindgen__closure__destroy__h7d7554216ff39279, wasm_bindgen__convert__closures_____invoke__h98155e79a0a742d1);
+            return ret;
+        },
+        __wbindgen_cast_0000000000000003: function(arg0) {
             // Cast intrinsic for `F64 -> Externref`.
             const ret = arg0;
             return ret;
         },
-        __wbindgen_cast_0000000000000003: function(arg0) {
+        __wbindgen_cast_0000000000000004: function(arg0) {
             // Cast intrinsic for `I64 -> Externref`.
             const ret = arg0;
             return ret;
         },
-        __wbindgen_cast_0000000000000004: function(arg0, arg1) {
+        __wbindgen_cast_0000000000000005: function(arg0, arg1) {
             // Cast intrinsic for `Ref(String) -> Externref`.
             const ret = getStringFromWasm0(arg0, arg1);
             return ret;
         },
-        __wbindgen_cast_0000000000000005: function(arg0) {
+        __wbindgen_cast_0000000000000006: function(arg0) {
             // Cast intrinsic for `U64 -> Externref`.
             const ret = BigInt.asUintN(64, arg0);
             return ret;
         },
-        __wbindgen_cast_0000000000000006: function(arg0, arg1) {
+        __wbindgen_cast_0000000000000007: function(arg0, arg1) {
             var v0 = getArrayU8FromWasm0(arg0, arg1).slice();
             wasm.__wbindgen_free(arg0, arg1 * 1, 1);
             // Cast intrinsic for `Vector(U8) -> Externref`.
@@ -1290,6 +1411,10 @@ function __wbg_get_imports() {
     };
 }
 
+function wasm_bindgen__convert__closures_____invoke__h98155e79a0a742d1(arg0, arg1, arg2) {
+    wasm.wasm_bindgen__convert__closures_____invoke__h98155e79a0a742d1(arg0, arg1, arg2);
+}
+
 function wasm_bindgen__convert__closures_____invoke__h4bd31e7387ab665d(arg0, arg1, arg2) {
     const ret = wasm.wasm_bindgen__convert__closures_____invoke__h4bd31e7387ab665d(arg0, arg1, arg2);
     if (ret[1]) {

package/pkg/taladb_web_bg.wasm.d.ts

@@ -5,26 +5,30 @@ export const __wbg_workerdb_free: (a: number, b: number) => void;
 export const workerdb_count: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
 export const workerdb_createFtsIndex: (a: number, b: number, c: number, d: number, e: number) => [number, number];
 export const workerdb_createIndex: (a: number, b: number, c: number, d: number, e: number) => [number, number];
-export const workerdb_createVectorIndex: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number];
+export const workerdb_createVectorIndex: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number) => [number, number];
 export const workerdb_deleteMany: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
 export const workerdb_deleteOne: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
 export const workerdb_dropFtsIndex: (a: number, b: number, c: number, d: number, e: number) => [number, number];
 export const workerdb_dropIndex: (a: number, b: number, c: number, d: number, e: number) => [number, number];
 export const workerdb_dropVectorIndex: (a: number, b: number, c: number, d: number, e: number) => [number, number];
+export const workerdb_exportSnapshot: (a: number) => [number, number, number, number];
 export const workerdb_find: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
 export const workerdb_findNearest: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number) => [number, number, number, number];
 export const workerdb_findOne: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
 export const workerdb_insert: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
 export const workerdb_insertMany: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
+export const workerdb_listIndexes: (a: number, b: number, c: number) => [number, number, number, number];
 export const workerdb_openInMemory: () => [number, number, number];
 export const workerdb_openWithOpfs: (a: any) => [number, number, number];
+export const workerdb_openWithSnapshot: (a: number, b: number) => [number, number, number];
 export const workerdb_updateMany: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number, number];
 export const workerdb_updateOne: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number, number];
+export const workerdb_upgradeVectorIndex: (a: number, b: number, c: number, d: number, e: number) => [number, number];
 export const __wbg_collectionwasm_free: (a: number, b: number) => void;
 export const __wbg_taladbwasm_free: (a: number, b: number) => void;
 export const collectionwasm_count: (a: number, b: any) => [number, number, number];
 export const collectionwasm_createIndex: (a: number, b: number, c: number) => [number, number];
-export const collectionwasm_createVectorIndex: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number];
+export const collectionwasm_createVectorIndex: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number) => [number, number];
 export const collectionwasm_deleteMany: (a: number, b: any) => [number, number, number];
 export const collectionwasm_deleteOne: (a: number, b: any) => [number, number, number];
 export const collectionwasm_dropIndex: (a: number, b: number, c: number) => [number, number];
@@ -36,21 +40,24 @@ export const collectionwasm_insert: (a: number, b: any) => [number, number, numb
 export const collectionwasm_insertMany: (a: number, b: any) => [number, number, number];
 export const collectionwasm_updateMany: (a: number, b: any, c: any) => [number, number, number];
 export const collectionwasm_updateOne: (a: number, b: any, c: any) => [number, number, number];
+export const collectionwasm_upgradeVectorIndex: (a: number, b: number, c: number) => [number, number];
 export const taladbwasm_collection: (a: number, b: number, c: number) => number;
 export const taladbwasm_exportSnapshot: (a: number) => [number, number, number, number];
 export const taladbwasm_openInMemory: () => [number, number, number];
 export const taladbwasm_openWithSnapshot: (a: number, b: number) => [number, number, number];
 export const init: () => void;
-export const idb_load_snapshot: (a: number, b: number) => any;
-export const idb_save_snapshot: (a: number, b: number, c: number, d: number) => any;
 export const is_opfs_available: () => any;
 export const opfs_delete_snapshot: (a: number, b: number) => any;
 export const opfs_flush_snapshot: (a: number, b: number, c: number, d: number) => any;
 export const opfs_load_snapshot: (a: number, b: number) => any;
 export const opfs_open_backend: (a: number, b: number) => any;
+export const idb_load_snapshot: (a: number, b: number) => any;
+export const idb_save_snapshot: (a: number, b: number, c: number, d: number) => any;
 export const wasm_bindgen__closure__destroy__h1411c0b1433bd547: (a: number, b: number) => void;
+export const wasm_bindgen__closure__destroy__h7d7554216ff39279: (a: number, b: number) => void;
 export const wasm_bindgen__convert__closures_____invoke__h4bd31e7387ab665d: (a: number, b: number, c: any) => [number, number];
 export const wasm_bindgen__convert__closures_____invoke__h675f15260128efbc: (a: number, b: number, c: any, d: any) => void;
+export const wasm_bindgen__convert__closures_____invoke__h98155e79a0a742d1: (a: number, b: number, c: any) => void;
 export const __wbindgen_malloc: (a: number, b: number) => number;
 export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
 export const __wbindgen_exn_store: (a: number) => void;

package/worker/taladb.worker.js

@@ -43,10 +43,26 @@
  * dropIndex     { collection, field }
  * createFtsIndex    { collection, field }
  * dropFtsIndex      { collection, field }
- * createVectorIndex { collection, field, dimensions, metric? }
+ * listIndexes       { collection }  → JSON { btree, fts, vector }
+ * createVectorIndex { collection, field, dimensions, metric?, indexType?, hnswM?, hnswEfConstruction? }
  * dropVectorIndex   { collection, field }
+ * upgradeVectorIndex { collection, field }
  * findNearest       { collection, field, queryJson, topK, filterJson? }
  * close             {}
+ *
+ * Multi-tab live queries (BroadcastChannel)
+ * -----------------------------------------
+ * When a write op (insert/insertMany/updateOne/updateMany/deleteOne/deleteMany) commits, the worker
+ * posts a `"taladb:changed"` message on a BroadcastChannel named
+ * `"taladb:<dbName>"`.  Other tabs listening on the same channel re-trigger
+ * their active `subscribe()` pollers immediately, bypassing the 300 ms tick.
+ *
+ * IndexedDB fallback (no OPFS)
+ * ----------------------------
+ * When OPFS is unavailable (cross-origin iframes, Firefox without storage
+ * access) the worker opens an in-memory database seeded from the last snapshot
+ * stored in IndexedDB.  After every write it flushes a new snapshot back to
+ * IndexedDB so data survives page reloads.
  */
 
 // ---------------------------------------------------------------------------
@@ -56,6 +72,27 @@
 /** @type {import('../pkg/taladb_web').WorkerDB | null} */
 let db = null;
 
+/**
+ * WorkerDB constructor — hoisted to module scope so snapshot reloads in
+ * IDB-fallback mode can call WorkerDB.openWithSnapshot without re-importing.
+ * @type {typeof import('../pkg/taladb_web').WorkerDB | null}
+ */
+let WorkerDB = null;
+
+/**
+ * Set to true by the BroadcastChannel listener (fallback mode) when the
+ * primary tab commits a write. Cleared at the start of the next dispatch.
+ * @type {boolean}
+ */
+let snapshotDirty = false;
+
+/**
+ * Resolve function set when a fallback tab is waiting for the primary tab to
+ * export a snapshot via BroadcastChannel. Cleared once resolved or timed out.
+ * @type {(() => void) | null}
+ */
+let pendingSnapshotResolve = null;
+
 /**
  * Deduplicates concurrent init calls for the same dbName within one worker.
  * @type {Map<string, Promise<void>>}
@@ -76,6 +113,99 @@ const warn = isDev ? console.warn.bind(console, '[TalaDB Worker]') : () => {};
  */
 let releaseLock = null;
 
+/**
+ * BroadcastChannel used to notify sibling tabs of writes.
+ * Created in doInit; null until the channel name is known.
+ * @type {BroadcastChannel | null}
+ */
+let broadcastChannel = null;
+
+/**
+ * True when running in IDB-fallback mode (OPFS unavailable).
+ * In this mode every write flushes a snapshot back to IndexedDB.
+ * @type {boolean}
+ */
+let idbFallback = false;
+
+// ---------------------------------------------------------------------------
+// IndexedDB helpers (used only when OPFS is unavailable)
+// ---------------------------------------------------------------------------
+
+const IDB_DB_NAME = 'taladb';
+const IDB_STORE = 'snapshots';
+const IDB_VERSION = 1;
+
+/** Open (or upgrade) the "taladb" IDB database and return the IDBDatabase. */
+function idbOpen() {
+  return new Promise((resolve, reject) => {
+    const req = self.indexedDB.open(IDB_DB_NAME, IDB_VERSION);
+    req.onupgradeneeded = () => {
+      // Create the object store the very first time.
+      if (!req.result.objectStoreNames.contains(IDB_STORE)) {
+        req.result.createObjectStore(IDB_STORE);
+      }
+    };
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+  });
+}
+
+/**
+ * Load a snapshot Uint8Array from IndexedDB for `dbName`.
+ * Returns null if no snapshot is stored yet.
+ * @param {string} dbName
+ * @returns {Promise<Uint8Array | null>}
+ */
+async function idbLoadSnapshot(dbName) {
+  if (!self.indexedDB) return null;
+  try {
+    const idb = await idbOpen();
+    return new Promise((resolve) => {
+      const tx = idb.transaction(IDB_STORE, 'readonly');
+      const store = tx.objectStore(IDB_STORE);
+      const req = store.get(dbName);
+      req.onsuccess = () => resolve(req.result ?? null);
+      req.onerror = () => resolve(null);
+    });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Persist a snapshot Uint8Array to IndexedDB for `dbName` (fire-and-forget).
+ * @param {string} dbName
+ * @param {Uint8Array} bytes
+ */
+async function idbSaveSnapshot(dbName, bytes) {
+  if (!self.indexedDB) return;
+  try {
+    const idb = await idbOpen();
+    await new Promise((resolve, reject) => {
+      const tx = idb.transaction(IDB_STORE, 'readwrite');
+      tx.objectStore(IDB_STORE).put(bytes, dbName);
+      tx.oncomplete = resolve;
+      tx.onerror = reject;
+    });
+  } catch { /* best-effort persistence — ignore failures */ }
+}
+
+/**
+ * Notify sibling tabs of a write and, when in IDB-fallback mode, flush the
+ * updated snapshot to IndexedDB.  Must be called after every mutating op.
+ */
+function onWriteCommitted() {
+  broadcastChannel?.postMessage('taladb:changed');
+  // Always flush a snapshot to IDB after every write — this keeps other tabs'
+  // IDB-fallback instances in sync via BroadcastChannel + snapshotDirty reload.
+  if (db && activeDbName) {
+    try {
+      const bytes = db.exportSnapshot();
+      idbSaveSnapshot(activeDbName, bytes).catch(() => {});
+    } catch { /* ignore snapshot export errors */ }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Dedicated Worker message handler
 // ---------------------------------------------------------------------------
@@ -95,6 +225,16 @@ self.onmessage = async (e) => {
 // ---------------------------------------------------------------------------
 
 async function dispatch(op, args) {
+  // In IDB-fallback mode, reload the snapshot before each op when the primary
+  // tab has signalled a write via BroadcastChannel. This keeps reads fresh.
+  if (idbFallback && snapshotDirty && op !== 'init' && db && activeDbName && WorkerDB) {
+    snapshotDirty = false;
+    try {
+      const fresh = await idbLoadSnapshot(activeDbName);
+      if (fresh) db = WorkerDB.openWithSnapshot(fresh);
+    } catch { /* ignore reload errors — stale read is acceptable */ }
+  }
+
   if (op === 'init') {
     const { dbName } = args;
 
@@ -116,11 +256,17 @@ async function dispatch(op, args) {
   if (!db) throw new Error('TalaDB worker not initialised — call init first');
 
   switch (op) {
-    case 'insert':
-      return db.insert(args.collection, args.docJson);
+    case 'insert': {
+      const result = db.insert(args.collection, args.docJson);
+      onWriteCommitted();
+      return result;
+    }
 
-    case 'insertMany':
-      return db.insertMany(args.collection, args.docsJson);
+    case 'insertMany': {
+      const result = db.insertMany(args.collection, args.docsJson);
+      onWriteCommitted();
+      return result;
+    }
 
     case 'find':
       return db.find(args.collection, args.filterJson ?? 'null');
@@ -128,17 +274,29 @@ async function dispatch(op, args) {
     case 'findOne':
       return db.findOne(args.collection, args.filterJson ?? 'null');
 
-    case 'updateOne':
-      return db.updateOne(args.collection, args.filterJson, args.updateJson);
+    case 'updateOne': {
+      const result = db.updateOne(args.collection, args.filterJson, args.updateJson);
+      onWriteCommitted();
+      return result;
+    }
 
-    case 'updateMany':
-      return db.updateMany(args.collection, args.filterJson, args.updateJson);
+    case 'updateMany': {
+      const result = db.updateMany(args.collection, args.filterJson, args.updateJson);
+      onWriteCommitted();
+      return result;
+    }
 
-    case 'deleteOne':
-      return db.deleteOne(args.collection, args.filterJson);
+    case 'deleteOne': {
+      const result = db.deleteOne(args.collection, args.filterJson);
+      onWriteCommitted();
+      return result;
+    }
 
-    case 'deleteMany':
-      return db.deleteMany(args.collection, args.filterJson);
+    case 'deleteMany': {
+      const result = db.deleteMany(args.collection, args.filterJson);
+      onWriteCommitted();
+      return result;
+    }
 
     case 'count':
       return db.count(args.collection, args.filterJson ?? 'null');
@@ -159,14 +317,29 @@ async function dispatch(op, args) {
       db.dropFtsIndex(args.collection, args.field);
       return null;
 
+    case 'listIndexes':
+      return db.listIndexes(args.collection);
+
     case 'createVectorIndex':
-      db.createVectorIndex(args.collection, args.field, args.dimensions, args.metric ?? null);
+      db.createVectorIndex(
+        args.collection,
+        args.field,
+        args.dimensions,
+        args.metric ?? null,
+        args.indexType ?? null,
+        args.hnswM ?? null,
+        args.hnswEfConstruction ?? null,
+      );
       return null;
 
     case 'dropVectorIndex':
       db.dropVectorIndex(args.collection, args.field);
       return null;
 
+    case 'upgradeVectorIndex':
+      db.upgradeVectorIndex(args.collection, args.field);
+      return null;
+
     case 'findNearest':
       return db.findNearest(
         args.collection,
@@ -179,6 +352,9 @@ async function dispatch(op, args) {
     case 'close':
       // Release the Web Lock and close the sync handle gracefully.
       if (releaseLock) { releaseLock(); releaseLock = null; }
+      broadcastChannel?.close();
+      broadcastChannel = null;
+      idbFallback = false;
       db = null;
       return null;
 
@@ -195,12 +371,45 @@ async function doInit(dbName) {
   const wasm = await import('../pkg/taladb_web.js');
   await wasm.default();
 
-  const { WorkerDB } = wasm;
+  // Hoist to module scope so snapshot reloads in dispatch() can use it.
+  WorkerDB = wasm.WorkerDB;
+
+  // Open the BroadcastChannel now that we know the db name.
+  if (typeof BroadcastChannel !== 'undefined') {
+    broadcastChannel = new BroadcastChannel(`taladb:${dbName}`);
+    broadcastChannel.onmessage = async (e) => {
+      if (e.data === 'taladb:changed' && idbFallback) {
+        // Fallback tab: primary tab wrote — reload snapshot before next read.
+        snapshotDirty = true;
+      } else if (e.data === 'taladb:request-snapshot' && !idbFallback && db && activeDbName) {
+        // Primary (OPFS) tab: a new tab asked for a snapshot — export and save it.
+        try {
+          const bytes = db.exportSnapshot();
+          await idbSaveSnapshot(activeDbName, bytes);
+          broadcastChannel.postMessage('taladb:snapshot-ready');
+          log('Exported snapshot for waiting tab');
+        } catch { /* ignore */ }
+      } else if (e.data === 'taladb:snapshot-ready' && pendingSnapshotResolve) {
+        // Fallback tab: primary tab finished saving — wake up the waiting doInit.
+        const resolve = pendingSnapshotResolve;
+        pendingSnapshotResolve = null;
+        resolve();
+      }
+    };
+    log('BroadcastChannel opened:', `taladb:${dbName}`);
+  }
 
   const opfsAvailable = await checkOpfs();
   if (!opfsAvailable) {
-    warn('OPFS unavailable — falling back to in-memory');
-    db = WorkerDB.openInMemory();
+    warn('OPFS unavailable — falling back to IndexedDB-backed in-memory');
+    const snapshot = await idbLoadSnapshot(dbName);
+    db = WorkerDB.openWithSnapshot(snapshot);
+    idbFallback = true;
+    if (snapshot) {
+      log(`Restored from IndexedDB snapshot (${snapshot.byteLength} bytes)`);
+    } else {
+      log('New in-memory database — writes will be persisted to IndexedDB');
+    }
     return;
   }
 
@@ -217,12 +426,43 @@ async function doInit(dbName) {
     return;
   }
 
-  // Acquire an exclusive lock on the database file.
-  // If another tab's worker already holds it, this call blocks until that
-  // worker calls close() or the tab is terminated (lock auto-released).
+  // Try to acquire the exclusive OPFS lock immediately (ifAvailable).
+  // If another tab already holds it, fall back to IDB snapshot right away so
+  // this tab is immediately usable instead of blocking until the other tab closes.
+  // The primary (OPFS) tab flushes a snapshot to IDB after every write, and
+  // this tab's BroadcastChannel listener sets snapshotDirty so dispatch()
+  // reloads the snapshot before the next read — keeping data fresh across tabs.
   const lockName = `taladb:${fileName}`;
   await new Promise((resolve, reject) => {
-    navigator.locks.request(lockName, async () => {
+    navigator.locks.request(lockName, { ifAvailable: true }, async (lock) => {
+      if (lock === null) {
+        // Lock is held by another tab — use IDB snapshot so this tab loads immediately.
+        warn('OPFS lock held by another tab — falling back to IndexedDB snapshot (live-sync via BroadcastChannel)');
+        let snapshot = await idbLoadSnapshot(dbName);
+
+        if (!snapshot && broadcastChannel) {
+          // No IDB snapshot yet — ask the primary tab to export one now.
+          log('No IDB snapshot — requesting one from the primary tab...');
+          const gotIt = await new Promise(res => {
+            pendingSnapshotResolve = res;
+            setTimeout(() => { pendingSnapshotResolve = null; res(false); }, 2000);
+            broadcastChannel.postMessage('taladb:request-snapshot');
+          });
+          if (gotIt !== false) snapshot = await idbLoadSnapshot(dbName);
+        }
+
+        db = WorkerDB.openWithSnapshot(snapshot ?? null);
+        idbFallback = true;
+        if (snapshot) {
+          log(`Restored from IDB snapshot (${snapshot.byteLength} bytes)`);
+        } else {
+          log('No IDB snapshot yet — starting with empty in-memory database');
+        }
+        resolve();
+        return; // Do not hold the lock; returning releases it back to the queue.
+      }
+
+      // Acquired the lock — use OPFS.
       try {
         const syncHandle = await fileHandle.createSyncAccessHandle();
         db = WorkerDB.openWithOpfs(syncHandle);