@optimystic/db-p2p-storage-web 0.13.4

package/README.md

@@ -0,0 +1,104 @@
+# @optimystic/db-p2p-storage-web
+
+IndexedDB-backed storage backend for Optimystic browser peers. Provides:
+
+- **`IndexedDBRawStorage`** — implements `IRawStorage` so a browser node persists
+  block metadata, revisions, pending transactions, committed transactions, and
+  materialized blocks across page reloads.
+- **`IndexedDBKVStore`** — implements `IKVStore` for the persistent transaction
+  state used to recover crashed two-phase commits.
+- **`loadOrCreateBrowserPeerKey`** — generates an Ed25519 libp2p private key on
+  first run and persists it in the same IndexedDB database, giving the browser
+  peer a stable, reload-surviving identity.
+
+This package is browser-only — it imports no Node built-ins. Counterparts:
+
+- `@optimystic/db-p2p-storage-rn` — React Native (MMKV)
+- `@optimystic/db-p2p-storage-fs` — Node filesystem
+
+## Install
+
+```bash
+yarn add @optimystic/db-p2p-storage-web @optimystic/db-p2p @optimystic/db-core
+```
+
+`@optimystic/db-p2p` is consumed via its `react-native` / `./rn` entry point so
+the Node-only filesystem code does not get bundled into the browser:
+
+```ts
+import { createLibp2pNode } from '@optimystic/db-p2p/rn';
+```
+
+## Usage
+
+```ts
+import { createLibp2pNode } from '@optimystic/db-p2p/rn';
+import {
+  openOptimysticWebDb,
+  IndexedDBRawStorage,
+  IndexedDBKVStore,
+  loadOrCreateBrowserPeerKey,
+} from '@optimystic/db-p2p-storage-web';
+
+const db = await openOptimysticWebDb();          // single shared handle
+const rawStorage = new IndexedDBRawStorage(db);  // → IRawStorage
+const kvStore = new IndexedDBKVStore(db);        // → IKVStore (txn recovery)
+const privateKey = await loadOrCreateBrowserPeerKey(db);
+
+const libp2p = await createLibp2pNode({
+  bootstrapNodes: [/* … */],
+  networkName: 'my-network',
+  privateKey,
+});
+```
+
+The same `IDBPDatabase` handle is shared by all three consumers — IndexedDB
+permits concurrent transactions across disjoint object stores, so the storage
+layer parallelises naturally.
+
+## Persistence semantics
+
+The package opens a single IndexedDB database (`optimystic` by default) with
+six object stores:
+
+| Store          | Key                  | Value                  |
+|----------------|----------------------|------------------------|
+| `metadata`     | `blockId`            | `BlockMetadata`        |
+| `revisions`    | `[blockId, rev]`     | `ActionId`             |
+| `pending`      | `[blockId, actionId]`| `Transform`            |
+| `transactions` | `[blockId, actionId]`| `Transform`            |
+| `materialized` | `[blockId, actionId]`| `IBlock`               |
+| `kv`           | `key`                | `string` or `Uint8Array` |
+
+`listRevisions` and `listPendingTransactions` use real IndexedDB range cursors
+— never `getAllKeys()` + JS filter — so list latency stays bounded as the store
+grows. `promotePendingTransaction` runs as a single `readwrite` transaction
+spanning `pending` and `transactions`, so the move is atomic across crashes.
+
+`getApproximateBytesUsed()` returns `(await navigator.storage.estimate()).usage`,
+which is **per-origin**, not per-database. That is adequate for `StorageMonitor`
+— which uses the figure as an advisory ring-selection input — but is not a
+precise per-database accounting.
+
+## Identity
+
+`loadOrCreateBrowserPeerKey(db, keyName?)` writes the libp2p private key as
+raw protobuf bytes (`Uint8Array`) under `keyName` in the `kv` store
+(default `peer-private-key`). IndexedDB stores typed arrays natively, so no
+base64 round-trip is needed. To rotate the identity, delete that one key:
+
+```ts
+await db.delete('kv', 'peer-private-key');
+```
+
+To wipe the entire backing store (debugging / dev reset):
+
+```ts
+indexedDB.deleteDatabase('optimystic');
+```
+
+## Tests
+
+`yarn test` runs the spec suite under [`fake-indexeddb`](https://www.npmjs.com/package/fake-indexeddb)
+in Node so CI doesn't need a real browser. Production code only uses the
+IndexedDB W3C API, so fake-indexeddb is a faithful behavioural surrogate.

package/dist/src/db.d.ts

@@ -0,0 +1,57 @@
+import { type DBSchema, type IDBPDatabase } from 'idb';
+import type { ActionId, BlockId, IBlock, Transform } from '@optimystic/db-core';
+import type { BlockMetadata } from '@optimystic/db-p2p';
+/**
+ * IndexedDB schema for the Optimystic browser storage backend.
+ *
+ * - `metadata`: per-block `BlockMetadata` keyed by `blockId`.
+ * - `revisions`: revision lookup keyed by `[blockId, rev]` mapping to an `ActionId`.
+ *   Range scans use `IDBKeyRange.bound([blockId, startRev], [blockId, endRev])`.
+ * - `pending`: pending transforms keyed by `[blockId, actionId]`. Listing pending
+ *   transactions for a block uses a key cursor over `[blockId, ...]`.
+ * - `transactions`: committed transforms keyed by `[blockId, actionId]`.
+ * - `materialized`: materialized blocks keyed by `[blockId, actionId]`. Saving
+ *   `undefined` deletes the row.
+ * - `kv`: a generic string keyspace shared by `IndexedDBKVStore` and the
+ *   identity helper. Identity keys are stored as raw `Uint8Array` blobs (under
+ *   a separate logical store from string-only `IKVStore` data, but the same
+ *   IndexedDB object store — IndexedDB stores typed arrays natively).
+ */
+export interface OptimysticWebDB extends DBSchema {
+    metadata: {
+        key: BlockId;
+        value: BlockMetadata;
+    };
+    revisions: {
+        key: [BlockId, number];
+        value: ActionId;
+    };
+    pending: {
+        key: [BlockId, ActionId];
+        value: Transform;
+    };
+    transactions: {
+        key: [BlockId, ActionId];
+        value: Transform;
+    };
+    materialized: {
+        key: [BlockId, ActionId];
+        value: IBlock;
+    };
+    kv: {
+        key: string;
+        value: string | Uint8Array;
+    };
+}
+export declare const DEFAULT_DB_NAME = "optimystic";
+export declare const DEFAULT_DB_VERSION = 1;
+export type OptimysticWebDBHandle = IDBPDatabase<OptimysticWebDB>;
+/**
+ * Opens (and creates if necessary) the Optimystic IndexedDB database used by
+ * `IndexedDBRawStorage`, `IndexedDBKVStore`, and `loadOrCreateBrowserPeerKey`.
+ *
+ * The same handle can be safely shared across all three — IndexedDB connections
+ * support concurrent transactions across disjoint object stores.
+ */
+export declare function openOptimysticWebDb(name?: string, version?: number): Promise<OptimysticWebDBHandle>;
+//# sourceMappingURL=db.d.ts.map

package/dist/src/db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/db.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,QAAQ,EAAE,KAAK,YAAY,EAAE,MAAM,KAAK,CAAC;AAC/D,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,eAAgB,SAAQ,QAAQ;IAChD,QAAQ,EAAE;QACT,GAAG,EAAE,OAAO,CAAC;QACb,KAAK,EAAE,aAAa,CAAC;KACrB,CAAC;IACF,SAAS,EAAE;QACV,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACvB,KAAK,EAAE,QAAQ,CAAC;KAChB,CAAC;IACF,OAAO,EAAE;QACR,GAAG,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACzB,KAAK,EAAE,SAAS,CAAC;KACjB,CAAC;IACF,YAAY,EAAE;QACb,GAAG,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACzB,KAAK,EAAE,SAAS,CAAC;KACjB,CAAC;IACF,YAAY,EAAE;QACb,GAAG,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACzB,KAAK,EAAE,MAAM,CAAC;KACd,CAAC;IACF,EAAE,EAAE;QACH,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC;KAC3B,CAAC;CACF;AAED,eAAO,MAAM,eAAe,eAAe,CAAC;AAC5C,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC,MAAM,MAAM,qBAAqB,GAAG,YAAY,CAAC,eAAe,CAAC,CAAC;AAElE;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACxC,IAAI,GAAE,MAAwB,EAC9B,OAAO,GAAE,MAA2B,GAClC,OAAO,CAAC,qBAAqB,CAAC,CAuBhC"}

package/dist/src/db.js

@@ -0,0 +1,35 @@
+import { openDB } from 'idb';
+export const DEFAULT_DB_NAME = 'optimystic';
+export const DEFAULT_DB_VERSION = 1;
+/**
+ * Opens (and creates if necessary) the Optimystic IndexedDB database used by
+ * `IndexedDBRawStorage`, `IndexedDBKVStore`, and `loadOrCreateBrowserPeerKey`.
+ *
+ * The same handle can be safely shared across all three — IndexedDB connections
+ * support concurrent transactions across disjoint object stores.
+ */
+export async function openOptimysticWebDb(name = DEFAULT_DB_NAME, version = DEFAULT_DB_VERSION) {
+    return openDB(name, version, {
+        upgrade(db) {
+            if (!db.objectStoreNames.contains('metadata')) {
+                db.createObjectStore('metadata');
+            }
+            if (!db.objectStoreNames.contains('revisions')) {
+                db.createObjectStore('revisions');
+            }
+            if (!db.objectStoreNames.contains('pending')) {
+                db.createObjectStore('pending');
+            }
+            if (!db.objectStoreNames.contains('transactions')) {
+                db.createObjectStore('transactions');
+            }
+            if (!db.objectStoreNames.contains('materialized')) {
+                db.createObjectStore('materialized');
+            }
+            if (!db.objectStoreNames.contains('kv')) {
+                db.createObjectStore('kv');
+            }
+        },
+    });
+}
+//# sourceMappingURL=db.js.map

package/dist/src/db.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.js","sourceRoot":"","sources":["../../src/db.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAoC,MAAM,KAAK,CAAC;AA+C/D,MAAM,CAAC,MAAM,eAAe,GAAG,YAAY,CAAC;AAC5C,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAIpC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACxC,OAAe,eAAe,EAC9B,UAAkB,kBAAkB;IAEpC,OAAO,MAAM,CAAkB,IAAI,EAAE,OAAO,EAAE;QAC7C,OAAO,CAAC,EAAE;YACT,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC/C,EAAE,CAAC,iBAAiB,CAAC,UAAU,CAAC,CAAC;YAClC,CAAC;YACD,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;gBAChD,EAAE,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;YACnC,CAAC;YACD,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC9C,EAAE,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;YACjC,CAAC;YACD,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;gBACnD,EAAE,CAAC,iBAAiB,CAAC,cAAc,CAAC,CAAC;YACtC,CAAC;YACD,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;gBACnD,EAAE,CAAC,iBAAiB,CAAC,cAAc,CAAC,CAAC;YACtC,CAAC;YACD,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBACzC,EAAE,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;YAC5B,CAAC;QACF,CAAC;KACD,CAAC,CAAC;AACJ,CAAC"}

package/dist/src/identity.d.ts

@@ -0,0 +1,15 @@
+import type { PrivateKey } from '@libp2p/interface';
+import type { OptimysticWebDBHandle } from './db.js';
+export declare const DEFAULT_PEER_KEY_NAME = "peer-private-key";
+/**
+ * Loads the persisted browser peer's libp2p private key, or generates a fresh
+ * Ed25519 key on first call and persists it.
+ *
+ * Stores the key as raw protobuf bytes (a `Uint8Array`) under `keyName` in the
+ * `kv` object store. IndexedDB stores typed arrays natively — no base64 round-trip.
+ *
+ * The returned `PrivateKey` can be passed directly to `createLibp2pNode({ privateKey })`,
+ * giving a browser peer a stable, reload-surviving identity.
+ */
+export declare function loadOrCreateBrowserPeerKey(db: OptimysticWebDBHandle, keyName?: string): Promise<PrivateKey>;
+//# sourceMappingURL=identity.d.ts.map

package/dist/src/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/identity.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAErD,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AAExD;;;;;;;;;GASG;AACH,wBAAsB,0BAA0B,CAC/C,EAAE,EAAE,qBAAqB,EACzB,OAAO,GAAE,MAA8B,GACrC,OAAO,CAAC,UAAU,CAAC,CASrB"}

package/dist/src/identity.js

@@ -0,0 +1,23 @@
+import { generateKeyPair, privateKeyFromProtobuf, privateKeyToProtobuf } from '@libp2p/crypto/keys';
+export const DEFAULT_PEER_KEY_NAME = 'peer-private-key';
+/**
+ * Loads the persisted browser peer's libp2p private key, or generates a fresh
+ * Ed25519 key on first call and persists it.
+ *
+ * Stores the key as raw protobuf bytes (a `Uint8Array`) under `keyName` in the
+ * `kv` object store. IndexedDB stores typed arrays natively — no base64 round-trip.
+ *
+ * The returned `PrivateKey` can be passed directly to `createLibp2pNode({ privateKey })`,
+ * giving a browser peer a stable, reload-surviving identity.
+ */
+export async function loadOrCreateBrowserPeerKey(db, keyName = DEFAULT_PEER_KEY_NAME) {
+    const stored = await db.get('kv', keyName);
+    if (stored instanceof Uint8Array) {
+        return privateKeyFromProtobuf(stored);
+    }
+    const key = await generateKeyPair('Ed25519');
+    const bytes = privateKeyToProtobuf(key);
+    await db.put('kv', bytes, keyName);
+    return key;
+}
+//# sourceMappingURL=identity.js.map

package/dist/src/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../src/identity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAIpG,MAAM,CAAC,MAAM,qBAAqB,GAAG,kBAAkB,CAAC;AAExD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC/C,EAAyB,EACzB,UAAkB,qBAAqB;IAEvC,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC3C,IAAI,MAAM,YAAY,UAAU,EAAE,CAAC;QAClC,OAAO,sBAAsB,CAAC,MAAM,CAAC,CAAC;IACvC,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,eAAe,CAAC,SAAS,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,oBAAoB,CAAC,GAAG,CAAC,CAAC;IACxC,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IACnC,OAAO,GAAG,CAAC;AACZ,CAAC"}

package/dist/src/index.d.ts

@@ -0,0 +1,5 @@
+export * from './db.js';
+export * from './indexeddb-storage.js';
+export * from './indexeddb-kv-store.js';
+export * from './identity.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,eAAe,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,5 @@
+export * from './db.js';
+export * from './indexeddb-storage.js';
+export * from './indexeddb-kv-store.js';
+export * from './identity.js';
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,eAAe,CAAC"}

package/dist/src/indexeddb-kv-store.d.ts

@@ -0,0 +1,20 @@
+import type { IKVStore } from '@optimystic/db-p2p';
+import type { OptimysticWebDBHandle } from './db.js';
+/**
+ * IndexedDB-backed `IKVStore` adapter for browser peers.
+ *
+ * Stored keys are namespaced with `prefix` so the `kv` object store can be
+ * shared with the identity helper without collisions. `list(prefix)` uses a
+ * range-bounded key cursor — never `getAllKeys()` — so a large `kv` store
+ * does not pay an O(n) JS-side filter cost.
+ */
+export declare class IndexedDBKVStore implements IKVStore {
+    private readonly db;
+    private readonly prefix;
+    constructor(db: OptimysticWebDBHandle, prefix?: string);
+    get(key: string): Promise<string | undefined>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix: string): Promise<string[]>;
+}
+//# sourceMappingURL=indexeddb-kv-store.d.ts.map

package/dist/src/indexeddb-kv-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexeddb-kv-store.d.ts","sourceRoot":"","sources":["../../src/indexeddb-kv-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAErD;;;;;;;GAOG;AACH,qBAAa,gBAAiB,YAAW,QAAQ;IAE/C,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADN,EAAE,EAAE,qBAAqB,EACzB,MAAM,GAAE,MAA0B;IAG9C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAK7C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAkB7C"}

package/dist/src/indexeddb-kv-store.js

@@ -0,0 +1,45 @@
+/**
+ * IndexedDB-backed `IKVStore` adapter for browser peers.
+ *
+ * Stored keys are namespaced with `prefix` so the `kv` object store can be
+ * shared with the identity helper without collisions. `list(prefix)` uses a
+ * range-bounded key cursor — never `getAllKeys()` — so a large `kv` store
+ * does not pay an O(n) JS-side filter cost.
+ */
+export class IndexedDBKVStore {
+    db;
+    prefix;
+    constructor(db, prefix = 'optimystic:txn:') {
+        this.db = db;
+        this.prefix = prefix;
+    }
+    async get(key) {
+        const value = await this.db.get('kv', this.prefix + key);
+        return typeof value === 'string' ? value : undefined;
+    }
+    async set(key, value) {
+        await this.db.put('kv', value, this.prefix + key);
+    }
+    async delete(key) {
+        await this.db.delete('kv', this.prefix + key);
+    }
+    async list(prefix) {
+        const fullPrefix = this.prefix + prefix;
+        // '￿' is the highest BMP code unit; appending it produces a string
+        // that is >= every string starting with `fullPrefix`. IndexedDB compares
+        // strings by UTF-16 code units, so this bound is exact.
+        const range = IDBKeyRange.bound(fullPrefix, fullPrefix + '￿');
+        const tx = this.db.transaction('kv', 'readonly');
+        const store = tx.objectStore('kv');
+        const keys = [];
+        let cursor = await store.openKeyCursor(range);
+        while (cursor) {
+            const fullKey = cursor.key;
+            keys.push(fullKey.slice(this.prefix.length));
+            cursor = await cursor.continue();
+        }
+        await tx.done;
+        return keys;
+    }
+}
+//# sourceMappingURL=indexeddb-kv-store.js.map

package/dist/src/indexeddb-kv-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexeddb-kv-store.js","sourceRoot":"","sources":["../../src/indexeddb-kv-store.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,MAAM,OAAO,gBAAgB;IAEV;IACA;IAFlB,YACkB,EAAyB,EACzB,SAAiB,iBAAiB;QADlC,OAAE,GAAF,EAAE,CAAuB;QACzB,WAAM,GAAN,MAAM,CAA4B;IACjD,CAAC;IAEJ,KAAK,CAAC,GAAG,CAAC,GAAW;QACpB,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC;QACzD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IACtD,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,KAAa;QACnC,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC;IACnD,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACvB,MAAM,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC;IAC/C,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAAc;QACxB,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACxC,mEAAmE;QACnE,yEAAyE;QACzE,wDAAwD;QACxD,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,UAAU,EAAE,UAAU,GAAG,GAAG,CAAC,CAAC;QAC9D,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QACjD,MAAM,KAAK,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QACnC,MAAM,IAAI,GAAa,EAAE,CAAC;QAC1B,IAAI,MAAM,GAAG,MAAM,KAAK,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAC9C,OAAO,MAAM,EAAE,CAAC;YACf,MAAM,OAAO,GAAG,MAAM,CAAC,GAAa,CAAC;YACrC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;YAC7C,MAAM,GAAG,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC;QAClC,CAAC;QACD,MAAM,EAAE,CAAC,IAAI,CAAC;QACd,OAAO,IAAI,CAAC;IACb,CAAC;CACD"}

package/dist/src/indexeddb-storage.d.ts

@@ -0,0 +1,31 @@
+import type { ActionId, ActionRev, BlockId, IBlock, Transform } from '@optimystic/db-core';
+import type { BlockMetadata, IRawStorage } from '@optimystic/db-p2p';
+import type { OptimysticWebDBHandle } from './db.js';
+/**
+ * IndexedDB-backed `IRawStorage` implementation for browser peers.
+ *
+ * Uses real range cursors for `listRevisions` and key cursors for
+ * `listPendingTransactions`, and runs `promotePendingTransaction` as a single
+ * `readwrite` transaction over the `pending` and `transactions` stores so the
+ * move is atomic.
+ */
+export declare class IndexedDBRawStorage implements IRawStorage {
+    private readonly db;
+    constructor(db: OptimysticWebDBHandle);
+    getMetadata(blockId: BlockId): Promise<BlockMetadata | undefined>;
+    saveMetadata(blockId: BlockId, metadata: BlockMetadata): Promise<void>;
+    getRevision(blockId: BlockId, rev: number): Promise<ActionId | undefined>;
+    saveRevision(blockId: BlockId, rev: number, actionId: ActionId): Promise<void>;
+    listRevisions(blockId: BlockId, startRev: number, endRev: number): AsyncIterable<ActionRev>;
+    getPendingTransaction(blockId: BlockId, actionId: ActionId): Promise<Transform | undefined>;
+    savePendingTransaction(blockId: BlockId, actionId: ActionId, transform: Transform): Promise<void>;
+    deletePendingTransaction(blockId: BlockId, actionId: ActionId): Promise<void>;
+    listPendingTransactions(blockId: BlockId): AsyncIterable<ActionId>;
+    getTransaction(blockId: BlockId, actionId: ActionId): Promise<Transform | undefined>;
+    saveTransaction(blockId: BlockId, actionId: ActionId, transform: Transform): Promise<void>;
+    getMaterializedBlock(blockId: BlockId, actionId: ActionId): Promise<IBlock | undefined>;
+    saveMaterializedBlock(blockId: BlockId, actionId: ActionId, block?: IBlock): Promise<void>;
+    getApproximateBytesUsed(): Promise<number>;
+    promotePendingTransaction(blockId: BlockId, actionId: ActionId): Promise<void>;
+}
+//# sourceMappingURL=indexeddb-storage.d.ts.map

package/dist/src/indexeddb-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexeddb-storage.d.ts","sourceRoot":"","sources":["../../src/indexeddb-storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAC3F,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAKrD;;;;;;;GAOG;AACH,qBAAa,mBAAoB,YAAW,WAAW;IAC1C,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,qBAAqB;IAEhD,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC;IAIjE,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAItE,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IAIzE,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7E,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,CAAC,SAAS,CAAC;IAsB5F,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAI3F,sBAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjG,wBAAwB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5E,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,CAAC,QAAQ,CAAC;IAoBnE,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAIpF,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1F,oBAAoB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAIvF,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS1F,uBAAuB,IAAI,OAAO,CAAC,MAAM,CAAC;IAU1C,yBAAyB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;CAcpF"}

package/dist/src/indexeddb-storage.js

@@ -0,0 +1,120 @@
+import { createLogger } from './logger.js';
+const log = createLogger('storage:indexeddb');
+/**
+ * IndexedDB-backed `IRawStorage` implementation for browser peers.
+ *
+ * Uses real range cursors for `listRevisions` and key cursors for
+ * `listPendingTransactions`, and runs `promotePendingTransaction` as a single
+ * `readwrite` transaction over the `pending` and `transactions` stores so the
+ * move is atomic.
+ */
+export class IndexedDBRawStorage {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async getMetadata(blockId) {
+        return this.db.get('metadata', blockId);
+    }
+    async saveMetadata(blockId, metadata) {
+        await this.db.put('metadata', metadata, blockId);
+    }
+    async getRevision(blockId, rev) {
+        return this.db.get('revisions', [blockId, rev]);
+    }
+    async saveRevision(blockId, rev, actionId) {
+        await this.db.put('revisions', actionId, [blockId, rev]);
+    }
+    async *listRevisions(blockId, startRev, endRev) {
+        const ascending = startRev <= endRev;
+        const lo = ascending ? startRev : endRev;
+        const hi = ascending ? endRev : startRev;
+        const range = IDBKeyRange.bound([blockId, lo], [blockId, hi]);
+        const tx = this.db.transaction('revisions', 'readonly');
+        const store = tx.objectStore('revisions');
+        // Snapshot first so we don't hold the transaction open across yields —
+        // IndexedDB auto-commits idle transactions, which would invalidate the
+        // cursor between awaits at the consumer.
+        const results = [];
+        let cursor = await store.openCursor(range, ascending ? 'next' : 'prev');
+        while (cursor) {
+            results.push({ rev: cursor.key[1], actionId: cursor.value });
+            cursor = await cursor.continue();
+        }
+        await tx.done;
+        for (const result of results) {
+            yield result;
+        }
+    }
+    async getPendingTransaction(blockId, actionId) {
+        return this.db.get('pending', [blockId, actionId]);
+    }
+    async savePendingTransaction(blockId, actionId, transform) {
+        await this.db.put('pending', transform, [blockId, actionId]);
+    }
+    async deletePendingTransaction(blockId, actionId) {
+        await this.db.delete('pending', [blockId, actionId]);
+    }
+    async *listPendingTransactions(blockId) {
+        // IndexedDB key ordering: array keys compare element-by-element, and a
+        // shorter prefix-equal array is less than a longer one; arrays sort
+        // above all primitive types. So `[blockId]` < `[blockId, anyActionId]`
+        // < `[blockId, []]`, which captures exactly every key for this block.
+        const range = IDBKeyRange.bound([blockId], [blockId, []]);
+        const tx = this.db.transaction('pending', 'readonly');
+        const store = tx.objectStore('pending');
+        const results = [];
+        let cursor = await store.openKeyCursor(range);
+        while (cursor) {
+            results.push(cursor.key[1]);
+            cursor = await cursor.continue();
+        }
+        await tx.done;
+        for (const actionId of results) {
+            yield actionId;
+        }
+    }
+    async getTransaction(blockId, actionId) {
+        return this.db.get('transactions', [blockId, actionId]);
+    }
+    async saveTransaction(blockId, actionId, transform) {
+        await this.db.put('transactions', transform, [blockId, actionId]);
+    }
+    async getMaterializedBlock(blockId, actionId) {
+        return this.db.get('materialized', [blockId, actionId]);
+    }
+    async saveMaterializedBlock(blockId, actionId, block) {
+        const key = [blockId, actionId];
+        if (block) {
+            await this.db.put('materialized', block, key);
+        }
+        else {
+            await this.db.delete('materialized', key);
+        }
+    }
+    async getApproximateBytesUsed() {
+        try {
+            const estimate = await navigator.storage?.estimate?.();
+            return estimate?.usage ?? 0;
+        }
+        catch (err) {
+            log('navigator.storage.estimate() failed: %o', err);
+            return 0;
+        }
+    }
+    async promotePendingTransaction(blockId, actionId) {
+        const key = [blockId, actionId];
+        const tx = this.db.transaction(['pending', 'transactions'], 'readwrite');
+        const pendingStore = tx.objectStore('pending');
+        const transactionsStore = tx.objectStore('transactions');
+        const transform = await pendingStore.get(key);
+        if (!transform) {
+            await tx.done.catch(() => undefined);
+            throw new Error(`Pending action ${actionId} not found for block ${blockId}`);
+        }
+        await transactionsStore.put(transform, key);
+        await pendingStore.delete(key);
+        await tx.done;
+    }
+}
+//# sourceMappingURL=indexeddb-storage.js.map

package/dist/src/indexeddb-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexeddb-storage.js","sourceRoot":"","sources":["../../src/indexeddb-storage.ts"],"names":[],"mappings":"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"}

package/dist/src/logger.d.ts

@@ -0,0 +1,3 @@
+import debug from 'debug';
+export declare function createLogger(subNamespace: string): debug.Debugger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/src/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAI1B,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,KAAK,CAAC,QAAQ,CAEjE"}

package/dist/src/logger.js

@@ -0,0 +1,6 @@
+import debug from 'debug';
+const BASE_NAMESPACE = 'optimystic:db-p2p-storage-web';
+export function createLogger(subNamespace) {
+    return debug(`${BASE_NAMESPACE}:${subNamespace}`);
+}
+//# sourceMappingURL=logger.js.map

package/dist/src/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,MAAM,cAAc,GAAG,+BAA+B,CAAC;AAEvD,MAAM,UAAU,YAAY,CAAC,YAAoB;IAChD,OAAO,KAAK,CAAC,GAAG,cAAc,IAAI,YAAY,EAAE,CAAC,CAAC;AACnD,CAAC"}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@optimystic/db-p2p-storage-web",
+  "version": "0.13.4",
+  "type": "module",
+  "description": "Browser IndexedDB storage backend for @optimystic/db-p2p",
+  "main": "dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "files": [
+    "src",
+    "dist",
+    "!dist/test",
+    "!**/*.tsbuildinfo"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gotchoices/optimystic.git",
+    "directory": "packages/db-p2p-storage-web"
+  },
+  "author": "Got Choices Foundation",
+  "license": "MIT",
+  "keywords": [
+    "optimystic",
+    "database",
+    "p2p",
+    "storage",
+    "browser",
+    "indexeddb"
+  ],
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsc",
+    "test": "node --import ./register.mjs node_modules/mocha/bin/mocha.js \"test/**/*.spec.ts\" --colors --reporter min",
+    "test:verbose": "node --import ./register.mjs node_modules/mocha/bin/mocha.js \"test/**/*.spec.ts\" --colors --reporter spec"
+  },
+  "devDependencies": {
+    "@libp2p/crypto": "^5.1.13",
+    "@libp2p/interface": "^3.1.0",
+    "@libp2p/peer-id": "^6.0.4",
+    "@types/chai": "^5.2.3",
+    "@types/debug": "^4.1.12",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^25.1.0",
+    "chai": "^6.2.2",
+    "fake-indexeddb": "^6.2.4",
+    "mocha": "^11.7.5",
+    "rimraf": "^6.1.2",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@optimystic/db-core": "^0.13.4",
+    "@optimystic/db-p2p": "^0.13.4",
+    "debug": "^4.4.3",
+    "idb": "^8.0.3"
+  },
+  "peerDependencies": {
+    "@libp2p/crypto": "^5.1.13",
+    "@libp2p/interface": "^3.1.0"
+  }
+}

package/src/db.ts

@@ -0,0 +1,86 @@
+import { openDB, type DBSchema, type IDBPDatabase } from 'idb';
+import type { ActionId, BlockId, IBlock, Transform } from '@optimystic/db-core';
+import type { BlockMetadata } from '@optimystic/db-p2p';
+
+/**
+ * IndexedDB schema for the Optimystic browser storage backend.
+ *
+ * - `metadata`: per-block `BlockMetadata` keyed by `blockId`.
+ * - `revisions`: revision lookup keyed by `[blockId, rev]` mapping to an `ActionId`.
+ *   Range scans use `IDBKeyRange.bound([blockId, startRev], [blockId, endRev])`.
+ * - `pending`: pending transforms keyed by `[blockId, actionId]`. Listing pending
+ *   transactions for a block uses a key cursor over `[blockId, ...]`.
+ * - `transactions`: committed transforms keyed by `[blockId, actionId]`.
+ * - `materialized`: materialized blocks keyed by `[blockId, actionId]`. Saving
+ *   `undefined` deletes the row.
+ * - `kv`: a generic string keyspace shared by `IndexedDBKVStore` and the
+ *   identity helper. Identity keys are stored as raw `Uint8Array` blobs (under
+ *   a separate logical store from string-only `IKVStore` data, but the same
+ *   IndexedDB object store — IndexedDB stores typed arrays natively).
+ */
+export interface OptimysticWebDB extends DBSchema {
+	metadata: {
+		key: BlockId;
+		value: BlockMetadata;
+	};
+	revisions: {
+		key: [BlockId, number];
+		value: ActionId;
+	};
+	pending: {
+		key: [BlockId, ActionId];
+		value: Transform;
+	};
+	transactions: {
+		key: [BlockId, ActionId];
+		value: Transform;
+	};
+	materialized: {
+		key: [BlockId, ActionId];
+		value: IBlock;
+	};
+	kv: {
+		key: string;
+		value: string | Uint8Array;
+	};
+}
+
+export const DEFAULT_DB_NAME = 'optimystic';
+export const DEFAULT_DB_VERSION = 1;
+
+export type OptimysticWebDBHandle = IDBPDatabase<OptimysticWebDB>;
+
+/**
+ * Opens (and creates if necessary) the Optimystic IndexedDB database used by
+ * `IndexedDBRawStorage`, `IndexedDBKVStore`, and `loadOrCreateBrowserPeerKey`.
+ *
+ * The same handle can be safely shared across all three — IndexedDB connections
+ * support concurrent transactions across disjoint object stores.
+ */
+export async function openOptimysticWebDb(
+	name: string = DEFAULT_DB_NAME,
+	version: number = DEFAULT_DB_VERSION,
+): Promise<OptimysticWebDBHandle> {
+	return openDB<OptimysticWebDB>(name, version, {
+		upgrade(db) {
+			if (!db.objectStoreNames.contains('metadata')) {
+				db.createObjectStore('metadata');
+			}
+			if (!db.objectStoreNames.contains('revisions')) {
+				db.createObjectStore('revisions');
+			}
+			if (!db.objectStoreNames.contains('pending')) {
+				db.createObjectStore('pending');
+			}
+			if (!db.objectStoreNames.contains('transactions')) {
+				db.createObjectStore('transactions');
+			}
+			if (!db.objectStoreNames.contains('materialized')) {
+				db.createObjectStore('materialized');
+			}
+			if (!db.objectStoreNames.contains('kv')) {
+				db.createObjectStore('kv');
+			}
+		},
+	});
+}

package/src/identity.ts

@@ -0,0 +1,29 @@
+import { generateKeyPair, privateKeyFromProtobuf, privateKeyToProtobuf } from '@libp2p/crypto/keys';
+import type { PrivateKey } from '@libp2p/interface';
+import type { OptimysticWebDBHandle } from './db.js';
+
+export const DEFAULT_PEER_KEY_NAME = 'peer-private-key';
+
+/**
+ * Loads the persisted browser peer's libp2p private key, or generates a fresh
+ * Ed25519 key on first call and persists it.
+ *
+ * Stores the key as raw protobuf bytes (a `Uint8Array`) under `keyName` in the
+ * `kv` object store. IndexedDB stores typed arrays natively — no base64 round-trip.
+ *
+ * The returned `PrivateKey` can be passed directly to `createLibp2pNode({ privateKey })`,
+ * giving a browser peer a stable, reload-surviving identity.
+ */
+export async function loadOrCreateBrowserPeerKey(
+	db: OptimysticWebDBHandle,
+	keyName: string = DEFAULT_PEER_KEY_NAME,
+): Promise<PrivateKey> {
+	const stored = await db.get('kv', keyName);
+	if (stored instanceof Uint8Array) {
+		return privateKeyFromProtobuf(stored);
+	}
+	const key = await generateKeyPair('Ed25519');
+	const bytes = privateKeyToProtobuf(key);
+	await db.put('kv', bytes, keyName);
+	return key;
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './db.js';
+export * from './indexeddb-storage.js';
+export * from './indexeddb-kv-store.js';
+export * from './identity.js';

package/src/indexeddb-kv-store.ts

@@ -0,0 +1,49 @@
+import type { IKVStore } from '@optimystic/db-p2p';
+import type { OptimysticWebDBHandle } from './db.js';
+
+/**
+ * IndexedDB-backed `IKVStore` adapter for browser peers.
+ *
+ * Stored keys are namespaced with `prefix` so the `kv` object store can be
+ * shared with the identity helper without collisions. `list(prefix)` uses a
+ * range-bounded key cursor — never `getAllKeys()` — so a large `kv` store
+ * does not pay an O(n) JS-side filter cost.
+ */
+export class IndexedDBKVStore implements IKVStore {
+	constructor(
+		private readonly db: OptimysticWebDBHandle,
+		private readonly prefix: string = 'optimystic:txn:',
+	) {}
+
+	async get(key: string): Promise<string | undefined> {
+		const value = await this.db.get('kv', this.prefix + key);
+		return typeof value === 'string' ? value : undefined;
+	}
+
+	async set(key: string, value: string): Promise<void> {
+		await this.db.put('kv', value, this.prefix + key);
+	}
+
+	async delete(key: string): Promise<void> {
+		await this.db.delete('kv', this.prefix + key);
+	}
+
+	async list(prefix: string): Promise<string[]> {
+		const fullPrefix = this.prefix + prefix;
+		// '￿' is the highest BMP code unit; appending it produces a string
+		// that is >= every string starting with `fullPrefix`. IndexedDB compares
+		// strings by UTF-16 code units, so this bound is exact.
+		const range = IDBKeyRange.bound(fullPrefix, fullPrefix + '￿');
+		const tx = this.db.transaction('kv', 'readonly');
+		const store = tx.objectStore('kv');
+		const keys: string[] = [];
+		let cursor = await store.openKeyCursor(range);
+		while (cursor) {
+			const fullKey = cursor.key as string;
+			keys.push(fullKey.slice(this.prefix.length));
+			cursor = await cursor.continue();
+		}
+		await tx.done;
+		return keys;
+	}
+}

package/src/indexeddb-storage.ts

@@ -0,0 +1,134 @@
+import type { ActionId, ActionRev, BlockId, IBlock, Transform } from '@optimystic/db-core';
+import type { BlockMetadata, IRawStorage } from '@optimystic/db-p2p';
+import type { OptimysticWebDBHandle } from './db.js';
+import { createLogger } from './logger.js';
+
+const log = createLogger('storage:indexeddb');
+
+/**
+ * IndexedDB-backed `IRawStorage` implementation for browser peers.
+ *
+ * Uses real range cursors for `listRevisions` and key cursors for
+ * `listPendingTransactions`, and runs `promotePendingTransaction` as a single
+ * `readwrite` transaction over the `pending` and `transactions` stores so the
+ * move is atomic.
+ */
+export class IndexedDBRawStorage implements IRawStorage {
+	constructor(private readonly db: OptimysticWebDBHandle) {}
+
+	async getMetadata(blockId: BlockId): Promise<BlockMetadata | undefined> {
+		return this.db.get('metadata', blockId);
+	}
+
+	async saveMetadata(blockId: BlockId, metadata: BlockMetadata): Promise<void> {
+		await this.db.put('metadata', metadata, blockId);
+	}
+
+	async getRevision(blockId: BlockId, rev: number): Promise<ActionId | undefined> {
+		return this.db.get('revisions', [blockId, rev]);
+	}
+
+	async saveRevision(blockId: BlockId, rev: number, actionId: ActionId): Promise<void> {
+		await this.db.put('revisions', actionId, [blockId, rev]);
+	}
+
+	async *listRevisions(blockId: BlockId, startRev: number, endRev: number): AsyncIterable<ActionRev> {
+		const ascending = startRev <= endRev;
+		const lo = ascending ? startRev : endRev;
+		const hi = ascending ? endRev : startRev;
+		const range = IDBKeyRange.bound([blockId, lo], [blockId, hi]);
+		const tx = this.db.transaction('revisions', 'readonly');
+		const store = tx.objectStore('revisions');
+		// Snapshot first so we don't hold the transaction open across yields —
+		// IndexedDB auto-commits idle transactions, which would invalidate the
+		// cursor between awaits at the consumer.
+		const results: ActionRev[] = [];
+		let cursor = await store.openCursor(range, ascending ? 'next' : 'prev');
+		while (cursor) {
+			results.push({ rev: (cursor.key as [BlockId, number])[1], actionId: cursor.value });
+			cursor = await cursor.continue();
+		}
+		await tx.done;
+		for (const result of results) {
+			yield result;
+		}
+	}
+
+	async getPendingTransaction(blockId: BlockId, actionId: ActionId): Promise<Transform | undefined> {
+		return this.db.get('pending', [blockId, actionId]);
+	}
+
+	async savePendingTransaction(blockId: BlockId, actionId: ActionId, transform: Transform): Promise<void> {
+		await this.db.put('pending', transform, [blockId, actionId]);
+	}
+
+	async deletePendingTransaction(blockId: BlockId, actionId: ActionId): Promise<void> {
+		await this.db.delete('pending', [blockId, actionId]);
+	}
+
+	async *listPendingTransactions(blockId: BlockId): AsyncIterable<ActionId> {
+		// IndexedDB key ordering: array keys compare element-by-element, and a
+		// shorter prefix-equal array is less than a longer one; arrays sort
+		// above all primitive types. So `[blockId]` < `[blockId, anyActionId]`
+		// < `[blockId, []]`, which captures exactly every key for this block.
+		const range = IDBKeyRange.bound([blockId] as IDBValidKey, [blockId, []] as IDBValidKey);
+		const tx = this.db.transaction('pending', 'readonly');
+		const store = tx.objectStore('pending');
+		const results: ActionId[] = [];
+		let cursor = await store.openKeyCursor(range);
+		while (cursor) {
+			results.push((cursor.key as [BlockId, ActionId])[1]);
+			cursor = await cursor.continue();
+		}
+		await tx.done;
+		for (const actionId of results) {
+			yield actionId;
+		}
+	}
+
+	async getTransaction(blockId: BlockId, actionId: ActionId): Promise<Transform | undefined> {
+		return this.db.get('transactions', [blockId, actionId]);
+	}
+
+	async saveTransaction(blockId: BlockId, actionId: ActionId, transform: Transform): Promise<void> {
+		await this.db.put('transactions', transform, [blockId, actionId]);
+	}
+
+	async getMaterializedBlock(blockId: BlockId, actionId: ActionId): Promise<IBlock | undefined> {
+		return this.db.get('materialized', [blockId, actionId]);
+	}
+
+	async saveMaterializedBlock(blockId: BlockId, actionId: ActionId, block?: IBlock): Promise<void> {
+		const key: [BlockId, ActionId] = [blockId, actionId];
+		if (block) {
+			await this.db.put('materialized', block, key);
+		} else {
+			await this.db.delete('materialized', key);
+		}
+	}
+
+	async getApproximateBytesUsed(): Promise<number> {
+		try {
+			const estimate = await navigator.storage?.estimate?.();
+			return estimate?.usage ?? 0;
+		} catch (err) {
+			log('navigator.storage.estimate() failed: %o', err);
+			return 0;
+		}
+	}
+
+	async promotePendingTransaction(blockId: BlockId, actionId: ActionId): Promise<void> {
+		const key: [BlockId, ActionId] = [blockId, actionId];
+		const tx = this.db.transaction(['pending', 'transactions'], 'readwrite');
+		const pendingStore = tx.objectStore('pending');
+		const transactionsStore = tx.objectStore('transactions');
+		const transform = await pendingStore.get(key);
+		if (!transform) {
+			await tx.done.catch(() => undefined);
+			throw new Error(`Pending action ${actionId} not found for block ${blockId}`);
+		}
+		await transactionsStore.put(transform, key);
+		await pendingStore.delete(key);
+		await tx.done;
+	}
+}

package/src/logger.ts

@@ -0,0 +1,7 @@
+import debug from 'debug';
+
+const BASE_NAMESPACE = 'optimystic:db-p2p-storage-web';
+
+export function createLogger(subNamespace: string): debug.Debugger {
+	return debug(`${BASE_NAMESPACE}:${subNamespace}`);
+}