@adobe/data-persistence 0.9.90

package/dist/backend/persistence-backend.d.ts

@@ -0,0 +1,54 @@
+import type { RandomAccessFile } from "./random-access-file.js";
+/**
+ * Capability flags for a `PersistenceBackend`. Declared optionally by
+ * backends so that higher-level code can adapt its strategy.
+ */
+export interface PersistenceBackendCapabilities {
+    /**
+     * Whether the backend supports partial byte-range writes via
+     * `RandomAccessFile.writeAt`. When `false` the service should prefer
+     * whole-file snapshot writes (e.g. for cloud blob stores). Currently
+     * informational — the existing journal/checkpoint strategy is used
+     * regardless.
+     */
+    readonly byteRangeWrites: boolean;
+}
+/**
+ * A directory of RandomAccessFile handles, rooted at some host-defined
+ * location (an OPFS directory, a Node fs path, or an in-memory map).
+ *
+ * All paths are relative to the root and validated by {@link validateRelPath}
+ * to prevent path traversal.
+ */
+export interface PersistenceBackend {
+    /**
+     * Optional capability advertisement. Omit (or omit individual fields) to
+     * indicate the backend has the same capabilities as the default
+     * (`byteRangeWrites: true`).
+     */
+    readonly capabilities?: Partial<PersistenceBackendCapabilities>;
+    /**
+     * Open (and create if missing) a file at `relPath`.
+     */
+    open(relPath: string): Promise<RandomAccessFile>;
+    /**
+     * List entries directly under `relPath`. Returns names only, not full paths.
+     */
+    list(relPath: string): Promise<readonly string[]>;
+    /**
+     * Remove a file. No-op if the file does not exist.
+     */
+    remove(relPath: string): Promise<void>;
+    /**
+     * Atomic rename within the root.
+     */
+    rename(from: string, to: string): Promise<void>;
+    /**
+     * Optional teardown hook. Backends that hold process-wide resources
+     * — a single-writer lock file, a sync access handle, an open
+     * directory descriptor — release them here. The router calls this
+     * during `close()`. Backends without persistent resources can omit
+     * it.
+     */
+    dispose?(): Promise<void>;
+}

package/dist/backend/persistence-backend.js

@@ -0,0 +1,3 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export {};
+//# sourceMappingURL=persistence-backend.js.map

package/dist/backend/persistence-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence-backend.js","sourceRoot":"","sources":["../../src/backend/persistence-backend.ts"],"names":[],"mappings":"AAAA,uDAAuD"}

package/dist/backend/random-access-file.conformance.d.ts

@@ -0,0 +1,20 @@
+import { RandomAccessFile } from "./random-access-file.js";
+/**
+ * Conformance suite for RandomAccessFile implementations. Invoke from a
+ * thin per-runtime test file with the appropriate factory:
+ *
+ *     // memory-file.test.ts
+ *     runRandomAccessFileConformance("memory", () => createMemoryFile());
+ *
+ *     // node-fs-file.node.test.ts
+ *     runRandomAccessFileConformance("node-fs", async () => {
+ *         const tmp = await fs.mkdtemp(...);
+ *         return createNodeFsFile(path.join(tmp, "f.bin"));
+ *     });
+ *
+ *     // opfs-sync-file.browser.test.ts
+ *     runRandomAccessFileConformance("opfs", async () => createOpfsSyncFile(...));
+ *
+ * All implementations must satisfy identical semantics.
+ */
+export declare const runRandomAccessFileConformance: (name: string, createFile: () => RandomAccessFile | Promise<RandomAccessFile>) => void;

package/dist/backend/random-access-file.conformance.js

@@ -0,0 +1,156 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, test } from "vitest";
+/**
+ * Conformance suite for RandomAccessFile implementations. Invoke from a
+ * thin per-runtime test file with the appropriate factory:
+ *
+ *     // memory-file.test.ts
+ *     runRandomAccessFileConformance("memory", () => createMemoryFile());
+ *
+ *     // node-fs-file.node.test.ts
+ *     runRandomAccessFileConformance("node-fs", async () => {
+ *         const tmp = await fs.mkdtemp(...);
+ *         return createNodeFsFile(path.join(tmp, "f.bin"));
+ *     });
+ *
+ *     // opfs-sync-file.browser.test.ts
+ *     runRandomAccessFileConformance("opfs", async () => createOpfsSyncFile(...));
+ *
+ * All implementations must satisfy identical semantics.
+ */
+export const runRandomAccessFileConformance = (name, createFile) => {
+    describe(`RandomAccessFile conformance: ${name}`, () => {
+        test("size() of a new file is 0", async () => {
+            const file = await createFile();
+            try {
+                expect(await file.size()).toBe(0);
+            }
+            finally {
+                await file.close();
+            }
+        });
+        test("appendAt grows the file and returns the new size", async () => {
+            const file = await createFile();
+            try {
+                const newSize = await file.appendAt(new Uint8Array([1, 2, 3]));
+                expect(newSize).toBe(3);
+                expect(await file.size()).toBe(3);
+            }
+            finally {
+                await file.close();
+            }
+        });
+        test("writeAt then readAt round-trips at non-zero offset", async () => {
+            const file = await createFile();
+            try {
+                const payload = new Uint8Array([10, 20, 30, 40]);
+                await file.writeAt(8, payload);
+                expect(await file.size()).toBe(12);
+                const read = await file.readAt(8, 4);
+                expect(Array.from(read)).toEqual([10, 20, 30, 40]);
+            }
+            finally {
+                await file.close();
+            }
+        });
+        test("writeAt grows the file and zero-fills the gap", async () => {
+            const file = await createFile();
+            try {
+                await file.writeAt(4, new Uint8Array([99]));
+                expect(await file.size()).toBe(5);
+                const read = await file.readAt(0, 5);
+                expect(Array.from(read)).toEqual([0, 0, 0, 0, 99]);
+            }
+            finally {
+                await file.close();
+            }
+        });
+        test("readAt past EOF returns a short buffer", async () => {
+            const file = await createFile();
+            try {
+                await file.appendAt(new Uint8Array([1, 2, 3]));
+                const read = await file.readAt(2, 10);
+                expect(read.byteLength).toBe(1);
+                expect(read[0]).toBe(3);
+            }
+            finally {
+                await file.close();
+            }
+        });
+        test("readAt entirely past EOF returns an empty buffer", async () => {
+            const file = await createFile();
+            try {
+                const read = await file.readAt(10, 5);
+                expect(read.byteLength).toBe(0);
+            }
+            finally {
+                await file.close();
+            }
+        });
+        test("truncate shrinks reported size and zeroes the freed range when grown back", async () => {
+            const file = await createFile();
+            try {
+                await file.writeAt(0, new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]));
+                await file.truncate(4);
+                expect(await file.size()).toBe(4);
+                await file.truncate(8);
+                const read = await file.readAt(0, 8);
+                expect(Array.from(read)).toEqual([1, 2, 3, 4, 0, 0, 0, 0]);
+            }
+            finally {
+                await file.close();
+            }
+        });
+        test("multiple writeAt to disjoint ranges produce expected layout", async () => {
+            const file = await createFile();
+            try {
+                await Promise.all([
+                    file.writeAt(0, new Uint8Array([1, 2])),
+                    file.writeAt(8, new Uint8Array([3, 4])),
+                    file.writeAt(16, new Uint8Array([5, 6])),
+                ]);
+                expect(await file.size()).toBe(18);
+                const read = await file.readAt(0, 18);
+                expect(Array.from(read)).toEqual([
+                    1, 2, 0, 0, 0, 0, 0, 0,
+                    3, 4, 0, 0, 0, 0, 0, 0,
+                    5, 6,
+                ]);
+            }
+            finally {
+                await file.close();
+            }
+        });
+        test("operations after close() reject", async () => {
+            const file = await createFile();
+            await file.close();
+            await expect(file.size()).rejects.toThrow();
+        });
+        test("readAt returns a copy, not a reference into the buffer", async () => {
+            const file = await createFile();
+            try {
+                await file.writeAt(0, new Uint8Array([1, 2, 3]));
+                const a = await file.readAt(0, 3);
+                a[0] = 99;
+                const b = await file.readAt(0, 3);
+                expect(b[0]).toBe(1);
+            }
+            finally {
+                await file.close();
+            }
+        });
+        test("sync() does not throw and is idempotent", async () => {
+            const file = await createFile();
+            try {
+                await file.sync();
+                await file.appendAt(new Uint8Array([1]));
+                await file.sync();
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+        });
+    });
+};
+//# sourceMappingURL=random-access-file.conformance.js.map

package/dist/backend/random-access-file.conformance.js.map

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

package/dist/backend/random-access-file.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Lowest-level file abstraction. The sole runtime seam between the
+ * persistence package and the host environment.
+ *
+ * Implementations:
+ *
+ *   MemoryFile         - ArrayBuffer-backed; tests and the in-process
+ *                        Node server option.
+ *   NodeFsFile         - wraps node:fs.promises.FileHandle.
+ *   OpfsSyncFile       - wraps FileSystemSyncAccessHandle (browser
+ *                        dedicated worker only).
+ *
+ * The interface is async to keep the contract uniform across runtimes;
+ * sync-handle implementations (OPFS) satisfy it with sync calls under
+ * the hood.
+ */
+export interface RandomAccessFile {
+    /**
+     * Read `length` bytes starting at `offset`. May return fewer bytes
+     * than requested if the read goes past EOF.
+     */
+    readAt(offset: number, length: number): Promise<Uint8Array>;
+    /**
+     * Write `bytes` starting at `offset`. Grows the file if necessary.
+     */
+    writeAt(offset: number, bytes: Uint8Array): Promise<void>;
+    /**
+     * Append `bytes` at the end of the file. Returns the new file size.
+     */
+    appendAt(bytes: Uint8Array): Promise<number>;
+    /** Current file size in bytes. */
+    size(): Promise<number>;
+    /** Truncate the file to `length` bytes (zero-fills if growing). */
+    truncate(length: number): Promise<void>;
+    /** Flush any buffered writes to durable storage. */
+    sync(): Promise<void>;
+    /** Close the file handle. Subsequent operations reject. */
+    close(): Promise<void>;
+}

package/dist/backend/random-access-file.js

@@ -0,0 +1,3 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export {};
+//# sourceMappingURL=random-access-file.js.map

package/dist/backend/random-access-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"random-access-file.js","sourceRoot":"","sources":["../../src/backend/random-access-file.ts"],"names":[],"mappings":"AAAA,uDAAuD"}

package/dist/backend/validate-rel-path.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Validate that a relative path is safe to use within a backend root.
+ * Rejects:
+ *
+ *   - empty paths
+ *   - absolute paths (leading '/' or drive letter)
+ *   - paths containing '..' segments (path traversal)
+ *   - null bytes
+ *   - backslashes (we normalize on '/')
+ *
+ * Defense-in-depth against the path-traversal class of vulnerabilities.
+ * See .cursor/rules/security-global/security-global-pathtraversal-prevention.mdc.
+ */
+export declare const validateRelPath: (relPath: string) => void;

package/dist/backend/validate-rel-path.js

@@ -0,0 +1,44 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/**
+ * Validate that a relative path is safe to use within a backend root.
+ * Rejects:
+ *
+ *   - empty paths
+ *   - absolute paths (leading '/' or drive letter)
+ *   - paths containing '..' segments (path traversal)
+ *   - null bytes
+ *   - backslashes (we normalize on '/')
+ *
+ * Defense-in-depth against the path-traversal class of vulnerabilities.
+ * See .cursor/rules/security-global/security-global-pathtraversal-prevention.mdc.
+ */
+export const validateRelPath = (relPath) => {
+    if (typeof relPath !== "string" || relPath.length === 0) {
+        throw new Error("Path must be a non-empty string");
+    }
+    if (relPath.includes("\0")) {
+        throw new Error(`Path contains a null byte: ${JSON.stringify(relPath)}`);
+    }
+    if (relPath.includes("\\")) {
+        throw new Error(`Path contains a backslash; use '/' as the separator: ${JSON.stringify(relPath)}`);
+    }
+    if (relPath.startsWith("/")) {
+        throw new Error(`Path must be relative (no leading '/'): ${JSON.stringify(relPath)}`);
+    }
+    // Reject Windows drive letters explicitly even though we never use
+    // them — consistent rejection regardless of host OS.
+    if (/^[A-Za-z]:/.test(relPath)) {
+        throw new Error(`Path looks like an absolute Windows path: ${JSON.stringify(relPath)}`);
+    }
+    const segments = relPath.split("/");
+    for (const segment of segments) {
+        if (segment === "" || segment === ".") {
+            // Tolerate trailing slash and self-references; they reduce to nothing.
+            continue;
+        }
+        if (segment === "..") {
+            throw new Error(`Path contains '..' segment (traversal): ${JSON.stringify(relPath)}`);
+        }
+    }
+};
+//# sourceMappingURL=validate-rel-path.js.map

package/dist/backend/validate-rel-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-rel-path.js","sourceRoot":"","sources":["../../src/backend/validate-rel-path.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,OAAe,EAAQ,EAAE;IACrD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACvD,CAAC;IACD,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,8BAA8B,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,wDAAwD,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACvG,CAAC;IACD,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,2CAA2C,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC1F,CAAC;IACD,mEAAmE;IACnE,qDAAqD;IACrD,IAAI,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,6CAA6C,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC5F,CAAC;IACD,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACpC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC7B,IAAI,OAAO,KAAK,EAAE,IAAI,OAAO,KAAK,GAAG,EAAE,CAAC;YACpC,uEAAuE;YACvE,SAAS;QACb,CAAC;QACD,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CAAC,2CAA2C,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC1F,CAAC;IACL,CAAC;AACL,CAAC,CAAC"}

package/dist/backend/validate-rel-path.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/backend/validate-rel-path.test.js

@@ -0,0 +1,37 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { validateRelPath } from "./validate-rel-path.js";
+describe("validateRelPath", () => {
+    it("accepts simple paths", () => {
+        expect(() => validateRelPath("file.bin")).not.toThrow();
+        expect(() => validateRelPath("dir/file.bin")).not.toThrow();
+        expect(() => validateRelPath("a/b/c/d.bin")).not.toThrow();
+    });
+    it("accepts trailing slash and self-references", () => {
+        expect(() => validateRelPath("dir/")).not.toThrow();
+        expect(() => validateRelPath("./file.bin")).not.toThrow();
+        expect(() => validateRelPath("dir/./file.bin")).not.toThrow();
+    });
+    it("rejects empty path", () => {
+        expect(() => validateRelPath("")).toThrow(/non-empty/);
+    });
+    it("rejects absolute paths", () => {
+        expect(() => validateRelPath("/etc/passwd")).toThrow(/relative/);
+    });
+    it("rejects '..' segments", () => {
+        expect(() => validateRelPath("..")).toThrow(/traversal/);
+        expect(() => validateRelPath("../etc")).toThrow(/traversal/);
+        expect(() => validateRelPath("a/../b")).toThrow(/traversal/);
+        expect(() => validateRelPath("a/b/..")).toThrow(/traversal/);
+    });
+    it("rejects null bytes", () => {
+        expect(() => validateRelPath("a\0b")).toThrow(/null byte/);
+    });
+    it("rejects backslashes", () => {
+        expect(() => validateRelPath("a\\b")).toThrow(/backslash/);
+    });
+    it("rejects Windows drive letters", () => {
+        expect(() => validateRelPath("C:/foo")).toThrow(/Windows/);
+    });
+});
+//# sourceMappingURL=validate-rel-path.test.js.map

package/dist/backend/validate-rel-path.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-rel-path.test.js","sourceRoot":"","sources":["../../src/backend/validate-rel-path.test.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,QAAQ,CAAC,iBAAiB,EAAE,GAAG,EAAE;IAC7B,EAAE,CAAC,sBAAsB,EAAE,GAAG,EAAE;QAC5B,MAAM,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QACxD,MAAM,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,cAAc,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QAC5D,MAAM,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;IAC/D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4CAA4C,EAAE,GAAG,EAAE;QAClD,MAAM,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QACpD,MAAM,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QAC1D,MAAM,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,gBAAgB,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;IAClE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oBAAoB,EAAE,GAAG,EAAE;QAC1B,MAAM,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC3D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wBAAwB,EAAE,GAAG,EAAE;QAC9B,MAAM,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IACrE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uBAAuB,EAAE,GAAG,EAAE;QAC7B,MAAM,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QACzD,MAAM,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QAC7D,MAAM,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QAC7D,MAAM,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACjE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oBAAoB,EAAE,GAAG,EAAE;QAC1B,MAAM,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qBAAqB,EAAE,GAAG,EAAE;QAC3B,MAAM,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACrC,MAAM,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;AACP,CAAC,CAAC,CAAC"}

package/dist/browser/browser-worker-bootstrap.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/browser/browser-worker-bootstrap.js

@@ -0,0 +1,97 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+//
+// Worker bootstrap for the browser persistence runtime. Spawned by
+// the application via `new Worker(new URL(...), { type: "module" })`
+// and wrapped by {@link createBrowserWorkerTransport}.
+//
+// The script:
+//
+//   1. Acquires the OPFS root via `navigator.storage.getDirectory()`.
+//   2. Constructs an {@link createOpfsBackend} over that root.
+//   3. Constructs a {@link createPersistRouter}.
+//   4. Listens for `PersistOp` messages on `self`, dispatches each
+//      through the router, and posts back an `AckMessage`.
+//
+// The bootstrap runs entirely inside the worker and never touches the
+// DOM. Sync access handles (used by OpfsSyncFile) are only available
+// in dedicated workers — this module fails fast if loaded elsewhere.
+/// <reference lib="webworker" />
+import { createOpfsBackend } from "./opfs-backend.js";
+import { createPersistRouter } from "../transport/router.js";
+const getOpfsRoot = async () => {
+    // `navigator.storage` is universally available in dedicated
+    // workers in modern browsers, but we guard so a clear error
+    // surfaces if the bootstrap is loaded in a context without it.
+    const storage = navigator.storage;
+    if (storage === undefined || typeof storage.getDirectory !== "function") {
+        throw new Error("browser-worker-bootstrap: navigator.storage.getDirectory is unavailable in this worker");
+    }
+    return storage.getDirectory();
+};
+// Lazy-init: defer OPFS acquisition until the first message so the
+// bootstrap can't deadlock at module load (and so the parent gets a
+// crisp error if OPFS is unavailable, rather than a silent hang).
+let routerPromise = null;
+const getRouter = () => {
+    if (routerPromise === null) {
+        routerPromise = (async () => {
+            const root = await getOpfsRoot();
+            const backend = await createOpfsBackend(root);
+            return createPersistRouter(backend);
+        })();
+    }
+    return routerPromise;
+};
+const sendAck = (id, value, error) => {
+    const ack = error === undefined
+        ? { kind: "ack", id, value }
+        : { kind: "ack", id, error };
+    self.postMessage(ack);
+};
+// Serialize op handling so the parent's "send a sentinel and wait for
+// its ack" flush strategy is correct. Without this, async dispatch
+// interleaves router.handle() promises and the sentinel ack can race
+// ahead of an earlier op still doing I/O.
+let opChain = Promise.resolve();
+const handleSerially = (op) => {
+    const next = opChain.then(async () => {
+        try {
+            const router = await getRouter();
+            const value = await router.handle(op);
+            sendAck(op.id, value);
+        }
+        catch (err) {
+            sendAck(op.id, undefined, err instanceof Error ? err.message : String(err));
+        }
+    });
+    opChain = next;
+    return next;
+};
+self.addEventListener("message", (ev) => {
+    const msg = ev.data;
+    if (msg.kind === "shutdown") {
+        // Graceful: drain the in-flight op chain, close the router
+        // (releasing all OPFS access handles), ack the shutdown, then
+        // close the worker. The main thread waits for the ack before
+        // calling worker.terminate() so it can rely on file releases
+        // having happened.
+        const { id } = msg;
+        const finish = async () => {
+            try {
+                await opChain;
+                if (routerPromise !== null) {
+                    const r = await routerPromise;
+                    await r.close();
+                }
+            }
+            finally {
+                sendAck(id, undefined);
+                self.close();
+            }
+        };
+        void finish();
+        return;
+    }
+    void handleSerially(msg);
+});
+//# sourceMappingURL=browser-worker-bootstrap.js.map

package/dist/browser/browser-worker-bootstrap.js.map

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

package/dist/browser/browser-worker-transport.browser.test.d.ts

@@ -0,0 +1 @@
+export {};