sliftutils 1.2.39 → 1.3.1

package/storage/BulkDatabase2/mergeLock.ts

@@ -0,0 +1,47 @@
+// Best-effort "only one tab merges this collection at a time" guard, layered ON TOP of the manifest
+// scheme (which guarantees correctness on its own). This is purely an efficiency measure: it stops two
+// tabs doing the same compaction at once and racing to orphan each other's output. It uses
+// localStorage (shared across same-origin tabs) and is a no-op where localStorage is unavailable
+// (Node) — there the manifest backstop alone keeps things correct, which is also what the Node stress
+// tests exercise. localStorage has no atomic compare-and-swap, so we write-then-reread to shrink the
+// race window, and a TTL frees a lock left behind by a tab that crashed or closed mid-merge.
+
+const LOCK_TTL_MS = 30 * 1000;
+
+function getLocalStorage(): Storage | undefined {
+    try {
+        return typeof localStorage !== "undefined" ? localStorage : undefined;
+    } catch {
+        return undefined; // accessing localStorage can throw (e.g. disabled cookies)
+    }
+}
+
+function lockKey(collection: string): string {
+    return "bulkDatabase2-merge:" + collection;
+}
+
+// Returns true if we now hold the lock (or there's no localStorage to coordinate through, in which
+// case we proceed and rely on the manifest backstop). Returns false if another tab holds a fresh lock.
+export function tryAcquireMergeLock(collection: string, holderId: string): boolean {
+    const ls = getLocalStorage();
+    if (!ls) return true;
+    const key = lockKey(collection);
+    const now = Date.now();
+    const existing = ls.getItem(key);
+    if (existing) {
+        const t = parseInt(existing.slice(existing.lastIndexOf(":") + 1), 10);
+        if (Number.isFinite(t) && now - t < LOCK_TTL_MS) return false;
+    }
+    const token = holderId + ":" + now;
+    ls.setItem(key, token);
+    // Re-read to catch a racing setItem from another tab (best-effort, not atomic).
+    return ls.getItem(key) === token;
+}
+
+export function releaseMergeLock(collection: string, holderId: string): void {
+    const ls = getLocalStorage();
+    if (!ls) return;
+    const key = lockKey(collection);
+    const existing = ls.getItem(key);
+    if (existing && existing.startsWith(holderId + ":")) ls.removeItem(key);
+}

package/storage/BulkDatabase2/streamLog.d.ts

@@ -0,0 +1,25 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import { BaseBulkDatabaseReader } from "./BulkDatabaseFormat";
+export declare const STREAM_EXTENSION = ".stream";
+export type StreamEntry = {
+    time: number;
+    row?: Record<string, unknown>;
+    deletedKey?: string;
+};
+export declare function frameRows(entries: {
+    time: number;
+    row: Record<string, unknown>;
+}[]): Buffer;
+export declare function frameDeletes(entries: {
+    time: number;
+    key: string;
+}[]): Buffer;
+export declare function parseStream(buffer: Buffer): {
+    entries: StreamEntry[];
+    badBytes: number;
+};
+export declare function streamReaderFromEntries(entries: StreamEntry[], totalBytes: number): {
+    reader: BaseBulkDatabaseReader;
+    times: Map<string, number>;
+};

package/storage/BulkDatabase2/streamLog.ts

@@ -0,0 +1,128 @@
+import cborx from "cbor-x";
+import { ABSENT, BaseBulkDatabaseReader } from "./BulkDatabaseFormat";
+
+// Tier-0 streaming format: an append log of whole-row writes and deletes (row-format, not columnar),
+// so small mutations are a single cheap append instead of rewriting a columnar file. Each block is:
+//
+//   [u32 len][CBOR({ t, v })  or  CBOR({ t, d })][u32 len]
+//
+// `t` is a per-write unique timestamp (getTimeUnique); `v` is a set row; `d` is a deleted key. Because
+// every thread streams to its own file, the only way to recover the global mutation order — needed
+// for newest-wins — is a per-write timestamp, with ties broken by file name. The trailing length must
+// match the leading one; a torn/incomplete append leaves a mismatched or missing suffix, so we stop
+// there and report trailing bad bytes instead of throwing. structuredClone preserves typed arrays.
+
+export const STREAM_EXTENSION = ".stream";
+
+const cborEncoder = new cborx.Encoder({ structuredClone: true });
+
+export type StreamEntry = { time: number; row?: Record<string, unknown>; deletedKey?: string };
+
+function frame(payload: Buffer): Buffer {
+    let len = Buffer.alloc(4);
+    len.writeUInt32LE(payload.length, 0);
+    return Buffer.concat([len, payload, len]);
+}
+
+// We deliberately do NOT batch/debounce writes here — each write is framed and appended (and flushed)
+// immediately. If a caller makes many individual writes and that causes lag, the fix is for them to
+// call writeBatch/deleteBatch with the whole set, not for us to silently coalesce. Caller-side
+// batching is strictly faster than anything we could do (it knows the full set up front), and not
+// batching gives the lowest possible latency for callers who genuinely want single writes — which
+// matters because the tab can be closed at any moment, so we want each write on disk as soon as
+// possible rather than sitting in a pending buffer that a close would lose.
+
+// Times are assigned by the caller (BulkDatabase2) so the exact same timestamp lands on disk, in the
+// in-memory overlay, and in the cross-tab broadcast — keeping the global write order consistent.
+export function frameRows(entries: { time: number; row: Record<string, unknown> }[]): Buffer {
+    return Buffer.concat(entries.map(e => frame(Buffer.from(cborEncoder.encode({ t: e.time, v: e.row })))));
+}
+
+export function frameDeletes(entries: { time: number; key: string }[]): Buffer {
+    return Buffer.concat(entries.map(e => frame(Buffer.from(cborEncoder.encode({ t: e.time, d: e.key })))));
+}
+
+export function parseStream(buffer: Buffer): { entries: StreamEntry[]; badBytes: number } {
+    let entries: StreamEntry[] = [];
+    let pos = 0;
+    while (pos + 4 <= buffer.length) {
+        let len = buffer.readUInt32LE(pos);
+        let payloadStart = pos + 4;
+        let suffixStart = payloadStart + len;
+        if (suffixStart + 4 > buffer.length) break;
+        if (buffer.readUInt32LE(suffixStart) !== len) break;
+        let decoded: { t: number; v?: Record<string, unknown>; d?: string } | undefined;
+        try {
+            decoded = cborEncoder.decode(buffer.subarray(payloadStart, suffixStart));
+        } catch {
+            break;
+        }
+        if (decoded && decoded.d !== undefined) entries.push({ time: decoded.t, deletedKey: decoded.d });
+        else if (decoded && decoded.v) entries.push({ time: decoded.t, row: decoded.v });
+        pos = suffixStart + 4;
+    }
+    return { entries, badBytes: buffer.length - pos };
+}
+
+// Wraps streamed entries (already ordered oldest-first) as a BaseBulkDatabaseReader. Each set MERGES
+// its fields onto the key's current row (so a partial write/update only changes the columns it
+// includes); a delete tombstones the key (exposed via deletedKeys so the join suppresses it in older
+// bulk readers) and resets the merge. A column the merged row never set reads as ABSENT, so the join
+// falls through to older readers for it. Also returns the latest timestamp seen per key (live or
+// deleted), used for cross-tab conflict resolution.
+export function streamReaderFromEntries(entries: StreamEntry[], totalBytes: number): { reader: BaseBulkDatabaseReader; times: Map<string, number> } {
+    let byKey = new Map<string, Record<string, unknown>>();
+    let deletedKeys = new Set<string>();
+    let times = new Map<string, number>();
+    for (let entry of entries) {
+        if (entry.deletedKey !== undefined) {
+            byKey.delete(entry.deletedKey);
+            deletedKeys.add(entry.deletedKey);
+            times.set(entry.deletedKey, entry.time);
+        } else if (entry.row) {
+            let key = entry.row.key as string;
+            byKey.set(key, { ...byKey.get(key), ...entry.row });
+            deletedKeys.delete(key);
+            times.set(key, entry.time);
+        }
+    }
+    let keys = [...byKey.keys()];
+    let columnNames: string[] = [];
+    let seen = new Set<string>();
+    for (let row of byKey.values()) {
+        for (let field of Object.keys(row)) {
+            if (seen.has(field)) continue;
+            seen.add(field);
+            columnNames.push(field);
+        }
+    }
+    let columns = columnNames.map(column => ({ column, byteSize: 0 }));
+    // Per-key tombstone times for the join's delete resolution.
+    let deleteTimes = new Map<string, number>();
+    for (let key of deletedKeys) deleteTimes.set(key, times.get(key) || 0);
+    let timeValues = [...times.values()];
+    let reader: BaseBulkDatabaseReader = {
+        totalBytes,
+        rowCount: keys.length,
+        minTime: timeValues.length ? Math.min(...timeValues) : 0,
+        maxTime: timeValues.length ? Math.max(...timeValues) : 0,
+        keys,
+        keyTimes: new Map(keys.map(key => [key, times.get(key) || 0])),
+        columns,
+        deleteTimes,
+        // A key's time is its latest write across all columns (per-key, not per-column). For a column
+        // it never set we return ABSENT so the join falls through to an older reader.
+        async getColumn(column) {
+            return keys.map(key => {
+                let row = byKey.get(key);
+                return { key, value: row && column in row ? row[column] : ABSENT, time: times.get(key) || 0 };
+            });
+        },
+        async getSingleField(key, column) {
+            let row = byKey.get(key);
+            if (!row || !(column in row)) return ABSENT;
+            return { value: row[column], time: times.get(key) || 0 };
+        },
+    };
+    return { reader, times };
+}

package/storage/BulkDatabase2/syncClient.d.ts

@@ -0,0 +1,9 @@
+export type RemoteWrite = {
+    key: string;
+    time: number;
+    deleted?: boolean;
+    value?: unknown;
+};
+export declare function isSyncSupported(): boolean;
+export declare function connect(collection: string, onWrite: (write: RemoteWrite) => void): Promise<RemoteWrite[]>;
+export declare function broadcast(collection: string, write: RemoteWrite): void;

package/storage/BulkDatabase2/syncClient.ts

@@ -0,0 +1,81 @@
+import { isNode } from "typesafecss";
+
+// Browser-side cross-tab write sync for BulkDatabase2, over BroadcastChannel (one channel per
+// collection, same-origin tabs). It does NOT persist anything — each tab writes to disk itself; this
+// just relays live writes to other open tabs and, when a tab starts up, asks peers for writes they've
+// made recently that may not be on disk yet. No-op in Node / where BroadcastChannel is unavailable, so
+// BulkDatabase2 can call these unconditionally. This is an optional feature, so there is no fallback.
+
+export type RemoteWrite = { key: string; time: number; deleted?: boolean; value?: unknown };
+
+// Writes older than this are assumed already flushed to disk (a freshly-opened tab gets those by
+// reading disk), so a tab only replays writes newer than this when a peer says hello.
+const RECENT_WINDOW_MS = 60_000;
+
+type Channel = {
+    bc: BroadcastChannel;
+    subscribers: ((write: RemoteWrite) => void)[];
+    // This tab's own recent writes, kept so it can answer another tab's "hello".
+    recent: RemoteWrite[];
+};
+
+const channels = new Map<string, Channel>();
+
+export function isSyncSupported(): boolean {
+    return !isNode() && typeof BroadcastChannel !== "undefined";
+}
+
+function pruneRecent(channel: Channel) {
+    const cutoff = Date.now() - RECENT_WINDOW_MS;
+    channel.recent = channel.recent.filter(w => w.time >= cutoff);
+}
+
+function deliver(channel: Channel, write: RemoteWrite) {
+    for (const sub of channel.subscribers) sub(write);
+}
+
+function ensure(collection: string): Channel | undefined {
+    if (!isSyncSupported()) return undefined;
+    let channel = channels.get(collection);
+    if (channel) return channel;
+    // BroadcastChannel never delivers a message back to the instance that sent it, so a tab never
+    // hears its own writes — only the other open tabs do.
+    const bc = new BroadcastChannel(`bulkDatabase2:${collection}`);
+    const created: Channel = { bc, subscribers: [], recent: [] };
+    bc.onmessage = (event: MessageEvent) => {
+        const msg = event.data as { type: string; write?: RemoteWrite; writes?: RemoteWrite[] };
+        if (!msg) return;
+        if (msg.type === "write" && msg.write) {
+            deliver(created, msg.write);
+        } else if (msg.type === "recent" && msg.writes) {
+            for (const write of msg.writes) deliver(created, write);
+        } else if (msg.type === "hello") {
+            // Another tab just started; replay our recent writes so it doesn't miss any. The reply goes
+            // to every tab, but peers that already have a write ignore it (its timestamp isn't newer
+            // than what they hold), so the redundant broadcast is harmless.
+            pruneRecent(created);
+            if (created.recent.length) created.bc.postMessage({ type: "recent", writes: created.recent });
+        }
+    };
+    channels.set(collection, created);
+    return created;
+}
+
+// Subscribe to remote writes for a collection. Recent writes from already-open tabs arrive through the
+// same onWrite callback (as the reply to our hello), so the returned array is always empty — it's kept
+// only for API compatibility with callers that await it.
+export function connect(collection: string, onWrite: (write: RemoteWrite) => void): Promise<RemoteWrite[]> {
+    const channel = ensure(collection);
+    if (!channel) return Promise.resolve([]);
+    channel.subscribers.push(onWrite);
+    channel.bc.postMessage({ type: "hello" });
+    return Promise.resolve([]);
+}
+
+export function broadcast(collection: string, write: RemoteWrite): void {
+    const channel = ensure(collection);
+    if (!channel) return;
+    channel.recent.push(write);
+    pruneRecent(channel);
+    channel.bc.postMessage({ type: "write", write });
+}

package/storage/DiskCollection.d.ts

@@ -6,6 +6,8 @@ import { TransactionStorage } from "./TransactionStorage";
 export declare class DiskCollection<T> implements IStorageSync<T> {
     private collectionName;
     private config?;
+    static getForceNoPrompt(): boolean;
+    static setForceNoPrompt(forceNoPrompt: boolean): void;
     constructor(collectionName: string, config?: {
         writeDelay?: number | undefined;
         cbor?: boolean | undefined;

package/storage/DiskCollection.ts

@@ -11,7 +11,23 @@ import { PrivateFileSystemStorage } from "./PrivateFileSystemStorage";
 import { isInChromeExtension, isInChromeExtensionBackground } from "../misc/environment";
 import { CBORStorage } from "./CBORStorage";
 
+const FORCE_NO_PROMPT_KEY = "DiskCollection_forceNoPrompt";
+
 export class DiskCollection<T> implements IStorageSync<T> {
+    // Globally forces every DiskCollection into noPrompt mode (browser only), overriding per-collection config.
+    public static getForceNoPrompt(): boolean {
+        if (isNode()) return false;
+        return !!localStorage.getItem(FORCE_NO_PROMPT_KEY);
+    }
+    public static setForceNoPrompt(forceNoPrompt: boolean) {
+        if (isNode()) return;
+        if (forceNoPrompt) {
+            localStorage.setItem(FORCE_NO_PROMPT_KEY, "1");
+        } else {
+            localStorage.removeItem(FORCE_NO_PROMPT_KEY);
+        }
+    }
+
     constructor(
         private collectionName: string,
         private config?: {
@@ -29,7 +45,7 @@ export class DiskCollection<T> implements IStorageSync<T> {
         // If a Chrome extension, just return null. 
         if (isInChromeExtensionBackground()) return null as any;
         let curCollection: IStorageRaw;
-        if (this.config?.noPrompt && !isNode()) {
+        if (!isNode() && (this.config?.noPrompt || DiskCollection.getForceNoPrompt())) {
             curCollection = await new PrivateFileSystemStorage(`collections/${this.collectionName}`);
         } else {
             let fileStorage = await getFileStorage();

package/storage/FileFolderAPI.d.ts

@@ -70,6 +70,52 @@ type DirectoryWrapper = {
     ]>;
 };
 export declare function setFileAPIKey(key: string): void;
+export declare class NodeJSFileHandleWrapper implements FileWrapper {
+    private filePath;
+    constructor(filePath: string);
+    getFile(): Promise<{
+        size: number;
+        lastModified: number;
+        arrayBuffer: () => Promise<ArrayBuffer>;
+        slice: (start: number, end: number) => {
+            arrayBuffer: () => Promise<ArrayBuffer>;
+        };
+    }>;
+    createWritable(config?: {
+        keepExistingData?: boolean;
+    }): Promise<{
+        seek: (offset: number) => Promise<void>;
+        write: (value: Buffer) => Promise<void>;
+        close: () => Promise<void>;
+    }>;
+}
+export declare class NodeJSDirectoryHandleWrapper implements DirectoryWrapper {
+    private rootPath;
+    constructor(rootPath: string);
+    removeEntry(key: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    getFileHandle(key: string, options?: {
+        create?: boolean;
+    }): Promise<FileWrapper>;
+    getDirectoryHandle(key: string, options?: {
+        create?: boolean;
+    }): Promise<DirectoryWrapper>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<[
+        string,
+        {
+            kind: "file";
+            name: string;
+            getFile(): Promise<FileWrapper>;
+        } | {
+            kind: "directory";
+            name: string;
+            getDirectoryHandle(key: string, options?: {
+                create?: boolean;
+            }): Promise<DirectoryWrapper>;
+        }
+    ]>;
+}
 export declare const getDirectoryHandle: {
     (): Promise<DirectoryWrapper>;
     reset(): void;
@@ -83,6 +129,14 @@ export declare const getFileStorageNested: {
     getAllKeys(): string[];
     get(key: string): Promise<FileStorage> | undefined;
 };
+export declare const getFileStorageNested2: {
+    (key: string): Promise<FileStorage>;
+    clear(key: string): void;
+    clearAll(): void;
+    forceSet(key: string, value: Promise<FileStorage>): void;
+    getAllKeys(): string[];
+    get(key: string): Promise<FileStorage> | undefined;
+};
 export declare const getFileStorage: {
     (): Promise<FileStorage>;
     reset(): void;
@@ -98,4 +152,6 @@ export type NestedFileStorage = {
 export type FileStorage = IStorageRaw & {
     folder: NestedFileStorage;
 };
+export declare function wrapHandle(handle: DirectoryWrapper): FileStorage;
+export declare function tryToLoadPointer(pointer: string): Promise<DirectoryWrapper | undefined>;
 export {};

package/storage/FileFolderAPI.tsx

@@ -96,7 +96,7 @@ class DirectoryPrompter extends preact.Component {
     }
 }
 
-class NodeJSFileHandleWrapper implements FileWrapper {
+export class NodeJSFileHandleWrapper implements FileWrapper {
     constructor(private filePath: string) {
     }
 
@@ -159,7 +159,7 @@ class NodeJSFileHandleWrapper implements FileWrapper {
     }
 }
 
-class NodeJSDirectoryHandleWrapper implements DirectoryWrapper {
+export class NodeJSDirectoryHandleWrapper implements DirectoryWrapper {
     constructor(private rootPath: string) {
     }
 
@@ -241,6 +241,7 @@ class NodeJSDirectoryHandleWrapper implements DirectoryWrapper {
 
 
 // NOTE: Blocks until the user provides a directory
+// NOTE: If you want to override the location, you can explicitly call getDirectoryHandle.set with your own directory wrapper. Which if your server side can be the Node.js directory handle wrapper, or if your client side it can just be a pointer from tryToLoadPointer/fileSystemPointer.ts.
 export const getDirectoryHandle = lazy(async function getDirectoryHandle(): Promise<DirectoryWrapper> {
     if (isNode()) {
         return new NodeJSDirectoryHandleWrapper(path.resolve("./data/"));
@@ -378,6 +379,33 @@ export const getFileStorageNested = cache(async function getFileStorage(path: st
     }
     return wrapHandle(base);
 });
+// Supports if the user selects the folder that contains the data folder or the data folder directly. If pathStr is an absolute path (and we're in nodejs) we use it directly.
+export const getFileStorageNested2 = cache(async function getFileStorage(pathStr: string): Promise<FileStorage> {
+    let base: DirectoryWrapper;
+    pathStr = pathStr.replaceAll("\\", "/");
+    if (isNode()) {
+        if (path.isAbsolute(pathStr)) {
+            return wrapHandle(new NodeJSDirectoryHandleWrapper(pathStr));
+        }
+        base = new NodeJSDirectoryHandleWrapper(path.resolve("./data/"));
+    } else {
+        base = await getDirectoryHandle();
+        let dirs: string[] = [];
+        for await (const [name, entry] of base) {
+            if (entry.kind === "directory") {
+                dirs.push(name);
+            }
+        }
+        if (dirs.includes(".git") || dirs.includes("data")) {
+            base = await base.getDirectoryHandle("data", { create: true });
+        }
+    }
+    for (let part of pathStr.split("/")) {
+        if (!part) continue;
+        base = await base.getDirectoryHandle(part, { create: true });
+    }
+    return wrapHandle(base);
+});
 export const getFileStorage = lazy(async function getFileStorage(): Promise<FileStorage> {
     if (USE_INDEXED_DB) {
         return await getFileStorageIndexDB();
@@ -434,40 +462,78 @@ async function fixedGetFileHandle(config: {
     return await config.handle.getFileHandle(config.key, { create: true });
 }
 
+// A file that genuinely does not exist. We must NOT retry these, otherwise reading many missing
+// files (a common pattern) gets catastrophically slow.
+function isMissingError(error: unknown): boolean {
+    let name = (error as { name?: string })?.name;
+    let code = (error as { code?: string })?.code;
+    return name === "NotFoundError" || code === "ENOENT";
+}
+
+const MAX_READ_RETRIES = 6;
+
+// The browser File System Access API can transiently fail reads under heavy load (it appears to
+// throttle when a page issues many reads at once). Those failures surface as errors OTHER than
+// "not found", so we retry them with backoff. A real missing file (NotFoundError / ENOENT) returns
+// undefined immediately with no retry.
+async function readWithRetry<T>(label: string, key: string, read: () => Promise<T>): Promise<T | undefined> {
+    let backoff = 25;
+    for (let attempt = 0; ; attempt++) {
+        try {
+            return await read();
+        } catch (error) {
+            if (isMissingError(error)) return undefined;
+            let name = (error as { name?: string })?.name || "Error";
+            let message = (error as { message?: string })?.message || String(error);
+            if (attempt >= MAX_READ_RETRIES) {
+                console.warn(`${label} gave up on ${JSON.stringify(key)} after ${attempt} retries (${name}): ${message.slice(0, 200)}`);
+                return undefined;
+            }
+            console.warn(`${label} retrying ${JSON.stringify(key)} (attempt ${attempt + 1}, ${name}): ${message.slice(0, 200)}`);
+            await new Promise(resolve => setTimeout(resolve, backoff));
+            backoff = Math.min(backoff * 2, 1000);
+        }
+    }
+}
+
 function wrapHandleFiles(handle: DirectoryWrapper): IStorageRaw {
     return {
         async getInfo(key: string) {
-            try {
+            return readWithRetry("getInfo", key, async () => {
                 const file = await handle.getFileHandle(key);
                 const fileContent = await file.getFile();
                 return {
                     size: fileContent.size,
                     lastModified: fileContent.lastModified,
                 };
-            } catch (error) {
-                return undefined;
-            }
+            });
         },
         async get(key: string): Promise<Buffer | undefined> {
-            try {
+            return readWithRetry("get", key, async () => {
                 const file = await handle.getFileHandle(key);
                 const fileContent = await file.getFile();
                 const arrayBuffer = await fileContent.arrayBuffer();
+                // Under load the FS Access API can resolve with a truncated buffer and no error.
+                //  Treat a short read as transient so readWithRetry retries it.
+                if (arrayBuffer.byteLength !== fileContent.size) {
+                    throw Object.assign(new Error(`Short read: got ${arrayBuffer.byteLength} of ${fileContent.size} bytes`), { name: "ShortReadError" });
+                }
                 return Buffer.from(arrayBuffer);
-            } catch (error) {
-                return undefined;
-            }
+            });
         },
 
         async getRange(key: string, config: { start: number; end: number }): Promise<Buffer | undefined> {
-            try {
+            return readWithRetry("getRange", key, async () => {
                 const file = await handle.getFileHandle(key);
                 const fileContent = await file.getFile();
+                const clampedStart = Math.min(Math.max(config.start, 0), fileContent.size);
+                const clampedEnd = Math.min(Math.max(config.end, clampedStart), fileContent.size);
                 const arrayBuffer = await fileContent.slice(config.start, config.end).arrayBuffer();
+                if (arrayBuffer.byteLength !== clampedEnd - clampedStart) {
+                    throw Object.assign(new Error(`Short range read: got ${arrayBuffer.byteLength} of ${clampedEnd - clampedStart} bytes`), { name: "ShortReadError" });
+                }
                 return Buffer.from(arrayBuffer);
-            } catch (error) {
-                return undefined;
-            }
+            });
         },
 
         async append(key: string, value: Buffer): Promise<void> {
@@ -496,10 +562,18 @@ function wrapHandleFiles(handle: DirectoryWrapper): IStorageRaw {
 
         async getKeys(includeFolders: boolean = false): Promise<string[]> {
             const keys: string[] = [];
-            for await (const [name, entry] of handle) {
-                if (entry.kind === "file" || includeFolders) {
-                    keys.push(entry.name);
+            try {
+                for await (const [name, entry] of handle) {
+                    if (entry.kind === "file" || includeFolders) {
+                        keys.push(entry.name);
+                    }
                 }
+            } catch (error) {
+                let name = (error as { name?: string })?.name || "Error";
+                let message = (error as { message?: string })?.message || String(error);
+                // A failure mid-iteration would silently truncate the listing, so surface it loudly.
+                console.error(`getKeys directory iteration failed after ${keys.length} entries (${name}): ${message.slice(0, 300)}`);
+                throw error;
             }
             return keys;
         },
@@ -544,14 +618,14 @@ function wrapHandleNested(handle: DirectoryWrapper): NestedFileStorage {
     };
 }
 
-function wrapHandle(handle: DirectoryWrapper): FileStorage {
+export function wrapHandle(handle: DirectoryWrapper): FileStorage {
     return {
         ...wrapHandleFiles(handle),
         folder: wrapHandleNested(handle),
     };
 }
 
-async function tryToLoadPointer(pointer: string) {
+export async function tryToLoadPointer(pointer: string) {
     let result = await getFileSystemPointer({ pointer });
     if (!result) return;
     let handle = await result?.onUserActivation();