@optimystic/db-p2p-storage-web 1.5.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optimystic/db-p2p-storage-web",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "type": "module",
   "description": "Browser IndexedDB storage backend for @optimystic/db-p2p",
   "main": "dist/src/index.js",
@@ -54,8 +54,8 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@optimystic/db-core": "^1.5.0",
-    "@optimystic/db-p2p": "^1.5.0",
+    "@optimystic/db-core": "^1.6.0",
+    "@optimystic/db-p2p": "^1.6.0",
     "debug": "^4.4.3",
     "idb": "^8.0.3"
   },

package/src/identity.ts

@@ -1,29 +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;
-}
+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

@@ -1,4 +1,4 @@
-export * from './db.js';
-export * from './indexeddb-storage.js';
-export * from './indexeddb-kv-store.js';
-export * from './identity.js';
+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

@@ -1,49 +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;
-	}
-}
+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

@@ -1,210 +1,210 @@
-import type { ActionId, BlockId } from '@optimystic/db-core';
-import { KvRawStorage, identityForHandle, type RawStoreDriver, type StoreIdentity } from '@optimystic/db-p2p';
-import type { OptimysticWebDBHandle } from './db.js';
-import { createLogger } from './logger.js';
-
-const log = createLogger('storage:indexeddb');
-
-/**
- * IndexedDB {@link RawStoreDriver}: the six logical block-storage stores mapped
- * to the six IndexedDB object stores (`metadata`, `revisions`, `pending`,
- * `transactions`, `proofs`, `materialized`) with their compound array keys.
- *
- * `KvRawStorage` now owns all JSON serialization, so this driver only ever
- * reads/writes `Uint8Array` values — IndexedDB stores a typed array natively via
- * structured clone and returns a `Uint8Array`, so no codec lives here. Everything
- * IndexedDB-specific stays: the range/key cursors (drained snapshot-first before
- * yielding), and the single `readwrite` transaction that makes `promote` atomic.
- */
-export class IndexedDBStoreDriver implements RawStoreDriver {
-	// NOTE: identity is the HANDLE object, so two handles opened over the same IndexedDB database
-	// NAME read as two identities. Resolving that would mean naming the underlying database,
-	// which `OptimysticWebDBHandle` does not expose. The package opener (`db.ts`) hands out one
-	// handle per database name in practice, so this is the reachable case, not the complete one.
-	private readonly identity: StoreIdentity;
-
-	constructor(private readonly db: OptimysticWebDBHandle) {
-		this.identity = identityForHandle('idb-handle', db);
-	}
-
-	storeIdentity(): StoreIdentity {
-		return this.identity;
-	}
-
-	// --- metadata ---
-
-	async getMetadata(blockId: BlockId): Promise<Uint8Array | undefined> {
-		return this.db.get('metadata', blockId);
-	}
-
-	async putMetadata(blockId: BlockId, value: Uint8Array): Promise<void> {
-		await this.db.put('metadata', value, blockId);
-	}
-
-	// --- revisions ---
-
-	async getRevision(blockId: BlockId, rev: number): Promise<Uint8Array | undefined> {
-		return this.db.get('revisions', [blockId, rev]);
-	}
-
-	async putRevision(blockId: BlockId, rev: number, value: Uint8Array): Promise<void> {
-		await this.db.put('revisions', value, [blockId, rev]);
-	}
-
-	async *rangeRevisions(blockId: BlockId, lo: number, hi: number, reverse: boolean): AsyncIterable<[number, Uint8Array]> {
-		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 the consumer's awaits (the kernel's drain-before-yield
-		// contract). Do NOT switch to lazy yielding mid-transaction.
-		const results: [number, Uint8Array][] = [];
-		let cursor = await store.openCursor(range, reverse ? 'prev' : 'next');
-		while (cursor) {
-			results.push([(cursor.key as [BlockId, number])[1], cursor.value]);
-			cursor = await cursor.continue();
-		}
-		await tx.done;
-		for (const result of results) {
-			yield result;
-		}
-	}
-
-	// --- pending ---
-
-	async getPending(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
-		return this.db.get('pending', [blockId, actionId]);
-	}
-
-	async putPending(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
-		await this.db.put('pending', value, [blockId, actionId]);
-	}
-
-	async deletePending(blockId: BlockId, actionId: ActionId): Promise<void> {
-		await this.db.delete('pending', [blockId, actionId]);
-	}
-
-	async *listPendingActionIds(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');
-		// Snapshot-first, same rationale as rangeRevisions.
-		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;
-		}
-	}
-
-	// --- transactions ---
-
-	async getTransaction(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
-		return this.db.get('transactions', [blockId, actionId]);
-	}
-
-	async putTransaction(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
-		await this.db.put('transactions', value, [blockId, actionId]);
-	}
-
-	// --- proofs (keyed [blockId, rev] like revisions; no delete — see RawStoreDriver.getProof) ---
-
-	async getProof(blockId: BlockId, rev: number): Promise<Uint8Array | undefined> {
-		return this.db.get('proofs', [blockId, rev]);
-	}
-
-	async putProof(blockId: BlockId, rev: number, value: Uint8Array): Promise<void> {
-		await this.db.put('proofs', value, [blockId, rev]);
-	}
-
-	// --- materialized ---
-
-	async getMaterialized(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
-		return this.db.get('materialized', [blockId, actionId]);
-	}
-
-	async putMaterialized(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
-		await this.db.put('materialized', value, [blockId, actionId]);
-	}
-
-	// The kernel owns the put-or-delete branch of `saveMaterializedBlock`, so the
-	// driver exposes delete as a separate op.
-	async deleteMaterialized(blockId: BlockId, actionId: ActionId): Promise<void> {
-		await this.db.delete('materialized', [blockId, actionId]);
-	}
-
-	// --- promote (the only cross-key atomic op) ---
-
-	async promote(blockId: BlockId, actionId: ActionId): Promise<void> {
-		const key: [BlockId, ActionId] = [blockId, actionId];
-		// Single readwrite transaction over both stores IS the atomic move: a crash
-		// leaves either the pending or the committed entry, never both/neither.
-		const tx = this.db.transaction(['pending', 'transactions'], 'readwrite');
-		const pendingStore = tx.objectStore('pending');
-		const transactionsStore = tx.objectStore('transactions');
-		const value = await pendingStore.get(key);
-		if (!value) {
-			// Settle the transaction before throwing so the failed promote does not
-			// leak an open transaction — keep this ordering.
-			await tx.done.catch(() => undefined);
-			throw new Error(`Pending action ${actionId} not found for block ${blockId}`);
-		}
-		await transactionsStore.put(value, key);
-		await pendingStore.delete(key);
-		await tx.done;
-	}
-
-	// --- optional passthroughs ---
-
-	async *listBlockIds(): AsyncIterable<BlockId> {
-		// The `metadata` store is keyed by blockId directly, so its keys ARE the
-		// distinct block ids. getAllKeys reads them under an implicit readonly
-		// transaction and returns an already-materialized array — no cursor held
-		// across yields (same rationale as the cursor scans' snapshot-first pattern).
-		const keys = await this.db.getAllKeys('metadata');
-		for (const key of keys) {
-			yield key as BlockId;
-		}
-	}
-
-	async approximateBytesUsed(): Promise<number> {
-		try {
-			const estimate = await navigator.storage?.estimate?.();
-			return estimate?.usage ?? 0;
-		} catch (err) {
-			log('navigator.storage.estimate() failed: %o', err);
-			return 0;
-		}
-	}
-}
-
-/**
- * IndexedDB-backed {@link IRawStorage} for browser peers, now a thin shell over
- * the shared {@link KvRawStorage} kernel driven by an {@link IndexedDBStoreDriver}.
- * The public name/constructor (`new IndexedDBRawStorage(handle)`) is unchanged so
- * existing imports keep resolving; the kernel supplies the `IRawStorage` surface
- * and the driver supplies IndexedDB behavior.
- *
- * `listBlockIds`/`getApproximateBytesUsed` are re-declared here as always-present
- * (the IndexedDB driver always implements them, so the kernel constructor always
- * wires them) — the base declares them optional, but every web consumer relies
- * on them.
- */
-export class IndexedDBRawStorage extends KvRawStorage {
-	declare listBlockIds: () => AsyncIterable<BlockId>;
-	declare getApproximateBytesUsed: () => Promise<number>;
-	declare getStoreIdentity: () => StoreIdentity;
-
-	constructor(db: OptimysticWebDBHandle) {
-		super(new IndexedDBStoreDriver(db));
-	}
-}
+import type { ActionId, BlockId } from '@optimystic/db-core';
+import { KvRawStorage, identityForHandle, type RawStoreDriver, type StoreIdentity } from '@optimystic/db-p2p';
+import type { OptimysticWebDBHandle } from './db.js';
+import { createLogger } from './logger.js';
+
+const log = createLogger('storage:indexeddb');
+
+/**
+ * IndexedDB {@link RawStoreDriver}: the six logical block-storage stores mapped
+ * to the six IndexedDB object stores (`metadata`, `revisions`, `pending`,
+ * `transactions`, `proofs`, `materialized`) with their compound array keys.
+ *
+ * `KvRawStorage` now owns all JSON serialization, so this driver only ever
+ * reads/writes `Uint8Array` values — IndexedDB stores a typed array natively via
+ * structured clone and returns a `Uint8Array`, so no codec lives here. Everything
+ * IndexedDB-specific stays: the range/key cursors (drained snapshot-first before
+ * yielding), and the single `readwrite` transaction that makes `promote` atomic.
+ */
+export class IndexedDBStoreDriver implements RawStoreDriver {
+	// NOTE: identity is the HANDLE object, so two handles opened over the same IndexedDB database
+	// NAME read as two identities. Resolving that would mean naming the underlying database,
+	// which `OptimysticWebDBHandle` does not expose. The package opener (`db.ts`) hands out one
+	// handle per database name in practice, so this is the reachable case, not the complete one.
+	private readonly identity: StoreIdentity;
+
+	constructor(private readonly db: OptimysticWebDBHandle) {
+		this.identity = identityForHandle('idb-handle', db);
+	}
+
+	storeIdentity(): StoreIdentity {
+		return this.identity;
+	}
+
+	// --- metadata ---
+
+	async getMetadata(blockId: BlockId): Promise<Uint8Array | undefined> {
+		return this.db.get('metadata', blockId);
+	}
+
+	async putMetadata(blockId: BlockId, value: Uint8Array): Promise<void> {
+		await this.db.put('metadata', value, blockId);
+	}
+
+	// --- revisions ---
+
+	async getRevision(blockId: BlockId, rev: number): Promise<Uint8Array | undefined> {
+		return this.db.get('revisions', [blockId, rev]);
+	}
+
+	async putRevision(blockId: BlockId, rev: number, value: Uint8Array): Promise<void> {
+		await this.db.put('revisions', value, [blockId, rev]);
+	}
+
+	async *rangeRevisions(blockId: BlockId, lo: number, hi: number, reverse: boolean): AsyncIterable<[number, Uint8Array]> {
+		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 the consumer's awaits (the kernel's drain-before-yield
+		// contract). Do NOT switch to lazy yielding mid-transaction.
+		const results: [number, Uint8Array][] = [];
+		let cursor = await store.openCursor(range, reverse ? 'prev' : 'next');
+		while (cursor) {
+			results.push([(cursor.key as [BlockId, number])[1], cursor.value]);
+			cursor = await cursor.continue();
+		}
+		await tx.done;
+		for (const result of results) {
+			yield result;
+		}
+	}
+
+	// --- pending ---
+
+	async getPending(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
+		return this.db.get('pending', [blockId, actionId]);
+	}
+
+	async putPending(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
+		await this.db.put('pending', value, [blockId, actionId]);
+	}
+
+	async deletePending(blockId: BlockId, actionId: ActionId): Promise<void> {
+		await this.db.delete('pending', [blockId, actionId]);
+	}
+
+	async *listPendingActionIds(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');
+		// Snapshot-first, same rationale as rangeRevisions.
+		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;
+		}
+	}
+
+	// --- transactions ---
+
+	async getTransaction(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
+		return this.db.get('transactions', [blockId, actionId]);
+	}
+
+	async putTransaction(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
+		await this.db.put('transactions', value, [blockId, actionId]);
+	}
+
+	// --- proofs (keyed [blockId, rev] like revisions; no delete — see RawStoreDriver.getProof) ---
+
+	async getProof(blockId: BlockId, rev: number): Promise<Uint8Array | undefined> {
+		return this.db.get('proofs', [blockId, rev]);
+	}
+
+	async putProof(blockId: BlockId, rev: number, value: Uint8Array): Promise<void> {
+		await this.db.put('proofs', value, [blockId, rev]);
+	}
+
+	// --- materialized ---
+
+	async getMaterialized(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
+		return this.db.get('materialized', [blockId, actionId]);
+	}
+
+	async putMaterialized(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
+		await this.db.put('materialized', value, [blockId, actionId]);
+	}
+
+	// The kernel owns the put-or-delete branch of `saveMaterializedBlock`, so the
+	// driver exposes delete as a separate op.
+	async deleteMaterialized(blockId: BlockId, actionId: ActionId): Promise<void> {
+		await this.db.delete('materialized', [blockId, actionId]);
+	}
+
+	// --- promote (the only cross-key atomic op) ---
+
+	async promote(blockId: BlockId, actionId: ActionId): Promise<void> {
+		const key: [BlockId, ActionId] = [blockId, actionId];
+		// Single readwrite transaction over both stores IS the atomic move: a crash
+		// leaves either the pending or the committed entry, never both/neither.
+		const tx = this.db.transaction(['pending', 'transactions'], 'readwrite');
+		const pendingStore = tx.objectStore('pending');
+		const transactionsStore = tx.objectStore('transactions');
+		const value = await pendingStore.get(key);
+		if (!value) {
+			// Settle the transaction before throwing so the failed promote does not
+			// leak an open transaction — keep this ordering.
+			await tx.done.catch(() => undefined);
+			throw new Error(`Pending action ${actionId} not found for block ${blockId}`);
+		}
+		await transactionsStore.put(value, key);
+		await pendingStore.delete(key);
+		await tx.done;
+	}
+
+	// --- optional passthroughs ---
+
+	async *listBlockIds(): AsyncIterable<BlockId> {
+		// The `metadata` store is keyed by blockId directly, so its keys ARE the
+		// distinct block ids. getAllKeys reads them under an implicit readonly
+		// transaction and returns an already-materialized array — no cursor held
+		// across yields (same rationale as the cursor scans' snapshot-first pattern).
+		const keys = await this.db.getAllKeys('metadata');
+		for (const key of keys) {
+			yield key as BlockId;
+		}
+	}
+
+	async approximateBytesUsed(): Promise<number> {
+		try {
+			const estimate = await navigator.storage?.estimate?.();
+			return estimate?.usage ?? 0;
+		} catch (err) {
+			log('navigator.storage.estimate() failed: %o', err);
+			return 0;
+		}
+	}
+}
+
+/**
+ * IndexedDB-backed {@link IRawStorage} for browser peers, now a thin shell over
+ * the shared {@link KvRawStorage} kernel driven by an {@link IndexedDBStoreDriver}.
+ * The public name/constructor (`new IndexedDBRawStorage(handle)`) is unchanged so
+ * existing imports keep resolving; the kernel supplies the `IRawStorage` surface
+ * and the driver supplies IndexedDB behavior.
+ *
+ * `listBlockIds`/`getApproximateBytesUsed` are re-declared here as always-present
+ * (the IndexedDB driver always implements them, so the kernel constructor always
+ * wires them) — the base declares them optional, but every web consumer relies
+ * on them.
+ */
+export class IndexedDBRawStorage extends KvRawStorage {
+	declare listBlockIds: () => AsyncIterable<BlockId>;
+	declare getApproximateBytesUsed: () => Promise<number>;
+	declare getStoreIdentity: () => StoreIdentity;
+
+	constructor(db: OptimysticWebDBHandle) {
+		super(new IndexedDBStoreDriver(db));
+	}
+}

package/src/logger.ts

@@ -1,11 +1,11 @@
-import debug from 'debug';
-import { registerDebugModule } from '@optimystic/db-core';
-
-const BASE_NAMESPACE = 'optimystic:db-p2p-storage-web';
-
-// So `enableOptimysticLogging` reaches this package's copy of `debug`, which may be no one else's.
-registerDebugModule('db-p2p-storage-web', debug);
-
-export function createLogger(subNamespace: string): debug.Debugger {
-	return debug(`${BASE_NAMESPACE}:${subNamespace}`);
-}
+import debug from 'debug';
+import { registerDebugModule } from '@optimystic/db-core';
+
+const BASE_NAMESPACE = 'optimystic:db-p2p-storage-web';
+
+// So `enableOptimysticLogging` reaches this package's copy of `debug`, which may be no one else's.
+registerDebugModule('db-p2p-storage-web', debug);
+
+export function createLogger(subNamespace: string): debug.Debugger {
+	return debug(`${BASE_NAMESPACE}:${subNamespace}`);
+}