opfs-worker 2.1.0 → 2.1.2

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { BaseOPFS } from './core/BaseOPFS';
 import type { OPFSSync } from './core/OPFSSync';
 /**
  * Type for paths that can be either a string or URI
@@ -38,12 +39,11 @@ export interface WatchEvent {
 }
 export type { OPFSSync };
 /**
- * Promise-based fs API surface shared by all backends: a Comlink proxy to
- * `OPFSSync` in a worker, or an in-process `OPFSAsync` instance.
+ * Public bytes API shared by all backends (`OPFSSync`, `OPFSAsync`, or a
+ * Comlink proxy to one of them). Declared on {@link BaseOPFS}; subclasses
+ * implement the abstract I/O and FD methods.
  */
-export type OPFSApi = {
-    [K in keyof OPFSSync]: OPFSSync[K];
-};
+export type OPFSApi = Pick<BaseOPFS, keyof BaseOPFS>;
 export interface OPFSOptions {
     /** Root path for the file system (default: '/') */
     root?: string;
@@ -56,6 +56,39 @@ export interface OPFSOptions {
     /** Custom name for the broadcast channel (default: 'opfs-worker') */
     broadcastChannel?: string | BroadcastChannel | null;
 }
+/** Payload accepted by {@link importFiles} for a single entry. */
+export type ImportFileData = string | Uint8Array | Blob;
+/**
+ * Entries for {@link importFiles}: an array of `[path, data]` tuples, a `Map`,
+ * or any iterable that yields the same pairs.
+ */
+export type ImportFilesEntries = Iterable<[string, ImportFileData]> | Map<string, ImportFileData>;
+/** Progress event fired while {@link importFiles} writes entries. */
+export interface ImportFilesProgress {
+    /** Path of the file currently being written */
+    path: string;
+    /** 0-based index of the current file */
+    index: number;
+    /** Total number of entries in this import */
+    count: number;
+    /** Bytes written for the current file so far */
+    bytesWritten: number;
+    /** Size of the current file in bytes */
+    bytesTotal: number;
+    /** Bytes written across all files so far */
+    totalBytesWritten: number;
+    /** Sum of all entry sizes in bytes */
+    totalBytes: number;
+}
+/** Result of a finished {@link importFiles} call. */
+export interface ImportFilesResult {
+    /** Paths written, in import order */
+    paths: string[];
+    /** Number of files imported (`paths.length`) */
+    count: number;
+    /** Total bytes written across all files */
+    bytesWritten: number;
+}
 export interface RenameOptions {
     /** Whether to overwrite existing files (default: false) */
     overwrite?: boolean;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,GAAG,CAAC;AAEpC,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG,WAAW,CAAC;AAExC,MAAM,MAAM,cAAc,GAAG,OAAO,GAChC,MAAM,GACN,OAAO,GACP,SAAS,GACT,UAAU,GACV,MAAM,GACN,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,KAAK,CAAC;AAEV,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;AAEtC,MAAM,MAAM,QAAQ,GAAG,cAAc,GAAG,cAAc,CAAC;AAEvD,MAAM,WAAW,QAAQ;IACrB,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;IACrB,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;CACxB;AAED,oBAAY,cAAc;IACtB,KAAK,UAAU;IACf,OAAO,YAAY;IACnB,OAAO,YAAY;CACtB;AAED,MAAM,WAAW,UAAU;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,cAAc,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,YAAY,EAAE,QAAQ,EAAE,CAAC;AAEzB;;;GAGG;AACH,MAAM,MAAM,OAAO,GAAG;KAAG,CAAC,IAAI,MAAM,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC;CAAE,CAAC;AAE7D,MAAM,WAAW,WAAW;IACxB,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kFAAkF;IAClF,aAAa,CAAC,EAAE,IAAI,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IACpF,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAAC;CACvD;AAED,MAAM,WAAW,aAAa;IAC1B,2DAA2D;IAC3D,SAAS,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IACzB,mDAAmD;IACnD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC5B,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACrB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/utils/helpers.d.ts

@@ -5,17 +5,26 @@ import type { Encoding } from '../types';
  * @throws {OPFSNotSupportedError} If the browser does not support the OPFS API
  */
 export declare function checkOPFSSupport(): void;
+/**
+ * Join a mount `root` with an API path into an absolute OPFS path.
+ *
+ * Lock keys and cross-instance coordination use this so `/x.txt` under
+ * `root: '/app'` and `/app/x.txt` under `root: '/'` resolve to the same file.
+ */
+export declare function absoluteOpfsPath(root: string, path: string): string;
 /**
  * Run a callback while holding an exclusive lock on a path
  *
  * Locks are always exclusive: OPFS permits a single sync access handle per file,
- * so readers can't share access either.
+ * so readers can't share access either. The lock key is the absolute OPFS path
+ * (`root` + API `path`) so different mounts of the same file serialize correctly.
  *
- * @param path - The path to lock
+ * @param path - The API path to lock (relative to `root`)
  * @param fn - The callback to run while holding the lock
+ * @param root - Mount root (default: `/`)
  * @returns The value returned by the callback
  */
-export declare function withLock<T>(path: string, fn: () => Promise<T>): Promise<T>;
+export declare function withLock<T>(path: string, fn: () => Promise<T>, root?: string): Promise<T>;
 /**
  * Split a path into an array of segments
  *
@@ -174,6 +183,7 @@ export declare function removeEntry(parentHandle: FileSystemDirectoryHandle, pat
     recursive?: boolean;
     force?: boolean;
     useTrash?: boolean;
+    root?: string;
 }): Promise<void>;
 /**
  * Validate read/write arguments for file descriptor operations

package/dist/utils/helpers.d.ts.map

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

package/dist/worker/createDedicatedWorker.d.ts

@@ -9,7 +9,7 @@ export interface DedicatedWorkerOptions extends OPFSOptions {
      * prefer the self-contained file (strict CSP without `blob:`, or DIY hosting).
      */
     url?: string | URL;
-    /** Bring your own Worker instance (overrides `url`) */
+    /** Bring your own Worker instance (overrides `url`) — not pooled */
     worker?: Worker;
 }
 export interface RawWorker {
@@ -17,13 +17,18 @@ export interface RawWorker {
     fs: RemoteOPFSSync;
     /** Underlying browser Worker */
     worker: Worker;
-    /** Calls worker `dispose()` then `terminate()` */
+    /** Drops this facade's port; terminates the Worker when the last user of this pool entry disposes */
     dispose: () => void;
 }
 /**
- * Internal helper: spawn a dedicated worker and wrap `OPFSSync` with Comlink.
+ * Internal helper: spawn (or reuse) a dedicated worker and wrap `OPFSSync` with Comlink.
  * Prefer {@link createOPFSDedicated}; access the proxy / Worker via
  * `facade.backend` / `facade.worker`.
+ *
+ * Calls with the same `root` (and same `url`, if any) share one Worker on this page.
+ * Different roots get different Workers. Passing `worker` bypasses the pool.
+ *
+ * `setOptions` hits the shared instance — keep options consistent for the same root.
  */
 export declare function createDedicatedWorker(options?: DedicatedWorkerOptions): RawWorker;
 export {};

package/dist/worker/createDedicatedWorker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createDedicatedWorker.d.ts","sourceRoot":"","sources":["../../src/worker/createDedicatedWorker.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAItC,KAAK,cAAc,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;AAEvC,MAAM,WAAW,sBAAuB,SAAQ,WAAW;IACvD;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IACnB,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACtB,yDAAyD;IACzD,EAAE,EAAE,cAAc,CAAC;IACnB,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,OAAO,EAAE,MAAM,IAAI,CAAC;CACvB;AAeD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,sBAA2B,GAAG,SAAS,CAuBrF"}
+{"version":3,"file":"createDedicatedWorker.d.ts","sourceRoot":"","sources":["../../src/worker/createDedicatedWorker.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAItC,KAAK,cAAc,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;AAEvC,MAAM,WAAW,sBAAuB,SAAQ,WAAW;IACvD;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IACnB,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACtB,yDAAyD;IACzD,EAAE,EAAE,cAAc,CAAC;IACnB,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,qGAAqG;IACrG,OAAO,EAAE,MAAM,IAAI,CAAC;CACvB;AAmCD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,sBAA2B,GAAG,SAAS,CA2ErF"}

package/docs/README.md

@@ -1,30 +1,18 @@
 # Docs
 
-New here? Start with [Choosing a mode](./choosing-a-mode.md).
+- [API overview](./api/README.md) — entries, facade methods, options, trade-offs
+- [File descriptors](./api/file-descriptors.md) — positional `open` / `read` / `write`
+- [Types](./types.md)
+- [Migration from 1.x](./migration.md)
 
 ## Guides
 
-| Guide                                     | About                                              |
-| ----------------------------------------- | -------------------------------------------------- |
-| [Choosing a mode](./choosing-a-mode.md)   | Which entry / backend to pick                      |
-| [Dedicated worker](./guides/dedicated.md) | Default path + DIY worker script                   |
-| [Async (no worker)](./guides/async.md)    | `createOPFSAsync` on the current thread            |
-| [SharedWorker](./guides/sharedworker.md)  | One fs shared by all tabs                          |
-| [Pure classes](./guides/pure.md)          | Drop `OPFSSync` / `OPFSAsync` into your own worker |
-| [Streaming](./guides/streaming.md)        | Large files with `importStream`                    |
-| [Watching](./guides/watching.md)          | Change events over `BroadcastChannel`              |
-| [Hashing](./guides/hashing.md)            | etag vs SHA                                        |
-
-## API
-
-| Page                                      | About                                 |
-| ----------------------------------------- | ------------------------------------- |
-| [Create helpers](./api/create.md)         | `createOPFS*` + **options table**     |
-| [Facade](./api/facade.md)                 | Node-like methods and aliases         |
-| [Backend](./api/backend.md)               | `BaseOPFS` / `OPFSSync` / `OPFSAsync` |
-| [File descriptors](./file-descriptors.md) | `open` / `read` / `write` / …         |
-| [Types](./types.md)                       | Types and errors                      |
-
-## Migration
-
-[1.x → 2.x](./migration.md)
+| Guide                                     | About                                                     |
+| ----------------------------------------- | --------------------------------------------------------- |
+| [Dedicated worker](./guides/dedicated.md) | How to use OPFS via a dedicated worker (the default path) |
+| [Async](./guides/async.md)                | How to use OPFS on the main thread, without a worker      |
+| [SharedWorker](./guides/sharedworker.md)  | How to share one filesystem across all tabs               |
+| [Pure classes](./guides/pure.md)          | How to drop OPFS into a worker you already run            |
+| [Streaming](./guides/streaming.md)        | How to handle large files and bulk uploads                |
+| [Watching](./guides/watching.md)          | How to listen for file changes across tabs                |
+| [Hashing](./guides/hashing.md)            | How file hashes / etags work on `stat` and watch events   |

package/docs/api/README.md

@@ -0,0 +1,221 @@
+# API
+
+The sync backend works in every browser that has OPFS, but the browser only allows it inside a dedicated worker — `createOPFS()` / `createOPFSDedicated()` set that up for you. The async backend can run on the main thread or in a SharedWorker, but needs a modern browser — writes will not work in Safari before 26.
+
+## Package entries
+
+| Import from                | Worker                                     | Use it when                                                           |
+| -------------------------- | ------------------------------------------ | --------------------------------------------------------------------- |
+| `opfs-worker`              | Starts a dedicated worker                  | Default; fine if bundle size doesn’t matter or tree-shaking is set up |
+| `opfs-worker/sync`         | Starts a dedicated worker                  | Same as the default, without async / shared code in the bundle        |
+| `opfs-worker/async`        | Runs directly in the current thread        | Main thread or your own worker; Safari prior to 26 can’t write        |
+| `opfs-worker/sharedworker` | Starts one SharedWorker shared by all tabs | One shared fs process for every tab; Safari prior to 26 can’t write   |
+| `opfs-worker/pure`         | None                                       | Low-level classes to build your own custom worker                     |
+
+## Facade
+
+Every helper returns an `OPFSFacade` — the same Node-like API in all modes. The facade hides the actual work: depending on which helper you call, it either creates a dedicated worker and talks to it, works with OPFS directly in the current thread, or connects to a SharedWorker.
+
+Each takes optional `[options](#options)`.
+
+| Function           | From                                        | Under the hood                                   |
+| ------------------ | ------------------------------------------- | ------------------------------------------------ |
+| `createOPFS`       | `opfs-worker` or `opfs-worker/sync`         | Dedicated worker + `OPFSSync`                    |
+| `createOPFSAsync`  | `opfs-worker` or `opfs-worker/async`        | OPFS directly, `OPFSAsync` in the current thread |
+| `createOPFSShared` | `opfs-worker` or `opfs-worker/sharedworker` | SharedWorker + `OPFSAsync`                       |
+
+```typescript
+import { createOPFS, createOPFSAsync, createOPFSShared } from 'opfs-worker';
+
+const fs = createOPFS(); // or createOPFSAsync(), createOPFSShared({ url: '...' })
+```
+
+### File I/O
+
+Paths are `string | URL` everywhere below.
+
+| Method         | Parameters                                                     | Returns                                                                                        |
+| -------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------- | --------------- |
+| `readFile`     | `path`, optional `encoding` or `{ encoding }`                  | `Promise<string                                                                                | Uint8Array>` — auto by extension if omitted (`.txt`→ string,`.bin` → bytes) |
+| `writeFile`    | `path`, `data` (`string                                        | Uint8Array                                                                                     | ArrayBuffer                                                                 | Blob`), optional encoding                                                  | `Promise<void>` |
+| `appendFile`   | `path`, `data` (`string                                        | Uint8Array                                                                                     | ArrayBuffer                                                                 | Blob`), optional encoding                                                  | `Promise<void>` |
+| `readText`     | `path`, `encoding?` (default `'utf-8'`)                        | `Promise<string>`                                                                              |
+| `writeText`    | `path`, `text`, `encoding?` (default `'utf-8'`)                | `Promise<void>`                                                                                |
+| `appendText`   | `path`, `text`, `encoding?` (default `'utf-8'`)                | `Promise<void>`                                                                                |
+| `readBlob`     | `path`                                                         | `Promise<Blob>` — disk-backed, not copied into memory. See [streaming](../guides/streaming.md) |
+| `importStream` | `path`, `ReadableStream                                        | Blob                                                                                           | File`, optional `{ onProgress }`                                            | `Promise<number>` — bytes written. See [streaming](../guides/streaming.md) |
+| `importFiles`  | `[path, data][]` / `Map` / iterable, optional `{ onProgress }` | `Promise<ImportFilesResult>` — paths, count, bytes. See [streaming](../guides/streaming.md)    |
+
+For Node compatibility, `fs.promises` is the same instance (`fs.promises === fs`).
+
+### Directories & metadata
+
+| Method     | Parameters                                                           | Returns                                                             |
+| ---------- | -------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `mkdir`    | `path`, optional `{ recursive }` (numeric mode accepted and ignored) | `Promise<void>`                                                     |
+| `readDir`  | `path`                                                               | `Promise<DirentData[]>`                                             |
+| `stat`     | `path`                                                               | `Promise<FileStat>`                                                 |
+| `exists`   | `path`                                                               | `Promise<boolean>`                                                  |
+| `realpath` | `path`                                                               | `Promise<string>`                                                   |
+| `remove`   | `path`, optional `{ recursive, force }`                              | `Promise<void>`                                                     |
+| `rename`   | `oldPath`, `newPath`, optional `{ overwrite }`                       | `Promise<void>`                                                     |
+| `copy`     | `source`, `destination`, optional `{ recursive, overwrite }`         | `Promise<void>`                                                     |
+| `clear`    | `path?` (default `/`)                                                | `Promise<void>` — empties the directory, keeps the directory itself |
+| `index`    | —                                                                    | `Promise<Map<string, FileStat>>`                                    |
+
+### Watch & lifecycle
+
+| Method       | Parameters                                                            | Returns                                          |
+| ------------ | --------------------------------------------------------------------- | ------------------------------------------------ |
+| `watch`      | `path`, optional `{ recursive, include, exclude }`                    | `() => void` unsubscribe                         |
+| `unwatch`    | `path`                                                                | `void`                                           |
+| `setOptions` | `options` — see [Options](#options) / [hashing](../guides/hashing.md) | `Promise<void>`                                  |
+| `dispose`    | —                                                                     | `void` — tears down watches, backend, and worker |
+
+### File descriptors
+
+Dedicated / `OPFSSync` only — async throws `ENOTSUP`. Details: [file descriptors](./file-descriptors.md).
+
+| Method      | Parameters                                         | Returns                                     |
+| ----------- | -------------------------------------------------- | ------------------------------------------- |
+| `open`      | `path`, optional `{ create, exclusive, truncate }` | `Promise<number>` — file descriptor         |
+| `read`      | `fd`, `buffer`, `offset`, `length`, `position?`    | `Promise<{ bytesRead, buffer }>`            |
+| `write`     | `fd`, `buffer`, `offset?`, `length?`, `position?`  | `Promise<number>` — bytes written           |
+| `close`     | `fd`                                               | `Promise<void>`                             |
+| `fstat`     | `fd`                                               | `Promise<FileStat>`                         |
+| `ftruncate` | `fd`, `size?` (default `0`)                        | `Promise<void>`                             |
+| `fsync`     | `fd`                                               | `Promise<void>` — best-effort flush in OPFS |
+
+### Node aliases
+
+| Alias     | Parameters                              | Returns                                         |
+| --------- | --------------------------------------- | ----------------------------------------------- |
+| `unlink`  | `path`                                  | same as `remove(path)`                          |
+| `rm`      | `path`, optional `{ recursive, force }` | same as `remove`                                |
+| `rmdir`   | `path`                                  | same as `remove(path)`                          |
+| `readdir` | `path`                                  | same as `readDir`                               |
+| `lstat`   | `path`                                  | same as `stat`                                  |
+| `chmod`   | `path`, `mode`                          | `Promise<void>` — no-op (no Unix modes in OPFS) |
+
+### Backend access
+
+`fs.backend` is the raw bytes API the facade wraps — a Comlink proxy to the worker for dedicated / SharedWorker, or the in-process `OPFSAsync` instance for async. Same methods as the facade, but without encoding helpers (you pass / get `Uint8Array`).
+
+| Field        | Type                             | Notes                |
+| ------------ | -------------------------------- | -------------------- | ---------- | ---------------------------------------------------- |
+| `fs.backend` | `[OPFSApi](../types.md#opfsapi)` | bytes in / bytes out |
+| `fs.worker`  | `Worker                          | SharedWorker         | undefined` | set when a worker was created; `undefined` for async |
+
+## Options
+
+Passed to any `createOPFS*` (and to `setOptions()` later).
+
+| Option             | Default                 | What it does                                                                                                                   |
+| ------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `root`             | `'/'`                   | Scope all paths under this OPFS subdirectory                                                                                   |
+| `namespace`        | `'opfs-worker:${root}'` | Stamp on every [watch](../guides/watching.md) event                                                                            |
+| `hashAlgorithm`    | `'etag'`                | File hash on `stat` / `index` / watch — `'etag'`, `'SHA-*'`, or `null`/`false` to disable. See [hashing](../guides/hashing.md) |
+| `maxFileSize`      | `50MB`                  | Skip SHA- hashing above this size (`etag` ignores it)                                                                          |
+| `broadcastChannel` | `'opfs-worker'`         | Channel name, a `BroadcastChannel` instance, or `null` to disable                                                              |
+
+```typescript
+const fs = createOPFS({
+    root: '/my-app',
+    hashAlgorithm: 'SHA-256',
+    maxFileSize: 10 * 1024 * 1024,
+});
+```
+
+### Dedicated worker only
+
+| Option   | Type     | Default | What it does                                |
+| -------- | -------- | ------- | ------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `url`    | `string  | URL`    | inlined worker                              | Script URL for `opfs-worker/dedicated.worker.js` (or your own) instead of the blob |
+| `worker` | `Worker` | —       | Pass an existing `Worker` (overrides `url`) |
+
+Leave these unset unless you need them — the default inlined worker is enough.
+
+```typescript
+const fs = createOPFS({ root: '/my-app' });
+
+// Escape hatches only:
+// createOPFS({ root: '/my-app', url: workerUrl })           // CSP without blob:
+// createOPFS({ root: '/my-app', worker: existingWorker })   // bring your own Worker
+```
+
+### SharedWorker only
+
+| Option   | Type           | Default         | What it does                                            |
+| -------- | -------------- | --------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `url`    | `string        | URL`            | next to the package                                     | Script URL for `opfs-worker/shared.worker.js` — with Vite: `import url from '…/shared.worker.js?url'` |
+| `worker` | `SharedWorker` | —               | Pass an existing `SharedWorker` (overrides `url`)       |
+| `name`   | `string`       | `'opfs-worker'` | Tabs with the same script URL + name share one instance |
+
+```typescript
+import workerUrl from 'opfs-worker/shared.worker.js?url'; // Vite
+import { createOPFSShared } from 'opfs-worker/sharedworker';
+
+const fs = createOPFSShared({
+    root: '/my-app',
+    url: workerUrl,
+    name: 'opfs-worker',
+});
+```
+
+## Ready-made worker files
+
+These files already contain a backend (`OPFSSync` or `OPFSAsync`) wrapped in Comlink expose.
+
+| Export                            | Inside                | Start with                                               |
+| --------------------------------- | --------------------- | -------------------------------------------------------- |
+| `opfs-worker/dedicated.worker.js` | Comlink + `OPFSSync`  | `new Worker(url, { type: 'module' })` or `{ url }`       |
+| `opfs-worker/shared.worker.js`    | Comlink + `OPFSAsync` | `new SharedWorker(url, { type: 'module' })` or `{ url }` |
+
+### Use the facade with a worker URL
+
+This is required for SharedWorker. For dedicated workers, use it only when the default inlined worker is blocked by CSP or you want to host the script yourself.
+
+```typescript
+import workerUrl from 'opfs-worker/dedicated.worker.js?url';
+
+const fs = createOPFS({ root: '/my-app', url: workerUrl });
+```
+
+You can also create the `Worker` yourself and pass it to the facade. The facade still handles Comlink, options, encoding helpers, buffer transfers, and cleanup.
+
+```typescript
+const worker = new Worker(workerUrl, { type: 'module' });
+const fs = createOPFS({ root: '/my-app', worker });
+```
+
+### Use the worker without the facade
+
+Wrap it with Comlink and configure the backend manually. This exposes the bytes API directly: no encoding helpers, automatic FD buffer transfers, or automatic worker termination.
+
+```typescript
+import { wrap } from 'comlink';
+import type { OPFSApi } from 'opfs-worker';
+import workerUrl from 'opfs-worker/dedicated.worker.js?url';
+
+const worker = new Worker(workerUrl, { type: 'module' });
+const backend = wrap<OPFSApi>(worker);
+
+await backend.setOptions({ root: '/my-app' });
+await backend.writeFile('/hello.txt', new TextEncoder().encode('hello'));
+
+await backend.dispose();
+worker.terminate();
+```
+
+Guides: [Dedicated worker](../guides/dedicated.md), [SharedWorker](../guides/sharedworker.md).
+
+## Trade-offs
+
+|                                     | Dedicated (`OPFSSync`)                           | Async (`OPFSAsync`)          |
+| ----------------------------------- | ------------------------------------------------ | ---------------------------- |
+| File descriptors                    | yes                                              | throw `ENOTSUP`              |
+| Browser support                     | every browser that has OPFS                      | Safari before 26 can’t write |
+| SharedWorker                        | no                                               | yes                          |
+| One instance for all tabs           | no                                               | yes, with `createOPFSShared` |
+| Bundle                              | ~80 KB inlined worker, or ready-made worker file | small via `/async`           |
+| Works under strict CSP (no `blob:`) | pass a worker `url` instead of the inlined blob  | n/a                          |

package/docs/api/file-descriptors.md

@@ -0,0 +1,137 @@
+# File Descriptors
+
+Positional I/O on the **dedicated / sync** backend (`createOPFSDedicated` / `createOPFS`, or `OPFSSync` from `/pure`). Async and SharedWorker throw `ENOTSUP`.
+
+If you call FD `read`/`write` on **`fs.backend`** from the main thread, transfer buffers with Comlink. The [facade](./README.md#facade) does that for you.
+
+```typescript
+import { transfer } from 'comlink';
+```
+
+## `open(path, options?): Promise<number>`
+
+```typescript
+const fd = await fs.open('/data/config.json');
+const fd = await fs.open('/data/new.txt', { create: true });
+const fd = await fs.open('/data/unique.txt', { create: true, exclusive: true });
+const fd = await fs.open('/data/log.txt', { create: true, truncate: true });
+```
+
+| Option      | Default |                                                |
+| ----------- | ------- | ---------------------------------------------- |
+| `create`    | `false` | Create the file if missing                     |
+| `exclusive` | `false` | With `create`, fail if the file already exists |
+| `truncate`  | `false` | Truncate to zero length                        |
+
+Throws `AlreadyExistsError` (`exclusive`), `FileTypeError` (path is a directory), or `FileSystemOperationError`.
+
+`exclusive` is best-effort only — two workers can still race. OPFS has no real file locking.
+
+## `read(fd, buffer, offset, length, position?): Promise<{ bytesRead, buffer }>`
+
+```typescript
+const buffer = new Uint8Array(1024);
+const { bytesRead, buffer: out } = await fs.read(fd, buffer, 0, 1024, null);
+```
+
+- `position` `null` / `undefined` — current cursor, then advance
+- `position` number — that offset, cursor unchanged
+- Returns `bytesRead === 0` at EOF
+
+With a Comlink proxy, buffers are transferred both ways. Use the **returned** buffer; the original is detached after transfer.
+
+```typescript
+import { transfer } from 'comlink';
+
+const buffer = new Uint8Array(64);
+const { bytesRead, buffer: out } = await fs.read(
+    fd,
+    transfer(buffer, [buffer.buffer]),
+    0,
+    buffer.length,
+    null
+);
+```
+
+Inside a worker with `OPFSSync` directly, plain buffers are fine — no `transfer`.
+
+Chunked read from the main thread:
+
+```typescript
+const fd = await fs.open('/data/large-file.txt');
+const chunkSize = 1024;
+let buffer = new Uint8Array(chunkSize);
+
+try {
+    while (true) {
+        const result = await fs.read(
+            fd,
+            transfer(buffer, [buffer.buffer]),
+            0,
+            chunkSize,
+            null
+        );
+        if (result.bytesRead === 0) break;
+        processChunk(result.buffer.subarray(0, result.bytesRead));
+        buffer = new Uint8Array(chunkSize);
+    }
+} finally {
+    await fs.close(fd);
+}
+```
+
+Prefer small chunks over allocating a buffer the size of the whole file.
+
+## `write(fd, buffer, offset?, length?, position?): Promise<number>`
+
+```typescript
+const data = new TextEncoder().encode('Hello, World!');
+const bytesWritten = await fs.write(fd, data);
+const bytesWritten2 = await fs.write(fd, data2, 0, 10, 100);
+```
+
+Same `position` rules as `read`. Extends the file if you write past EOF. Triggers watch events.
+
+## Positioning
+
+```typescript
+await fs.read(fd, buf, 0, 10, null); // cursor 0 → 10
+await fs.read(fd, buf, 0, 10, null); // cursor 10 → 20
+await fs.read(fd, buf, 0, 10, 0);    // reads at 0, cursor stays 20
+```
+
+## `fstat` / `ftruncate` / `fsync`
+
+```typescript
+const stats = await fs.fstat(fd);
+await fs.ftruncate(fd, 5);
+await fs.fsync(fd);
+```
+
+`ftruncate` clamps the cursor if it sits past the new size, emits a watch event, and flushes.
+
+`fsync` is best-effort. Unlike POSIX, the browser does not guarantee durability on power loss.
+
+## `close(fd)`
+
+Always close in a `finally`. Pending writes are flushed; open FDs are also closed when the worker is disposed.
+
+```typescript
+const fd = await fs.open('/data/file.txt');
+try {
+    // …
+} finally {
+    await fs.close(fd);
+}
+```
+
+## Errors
+
+| Error                                  | When                              |
+| -------------------------------------- | --------------------------------- |
+| `AlreadyExistsError`                   | `exclusive: true` and file exists |
+| `ExistenceError`                       | Missing path                      |
+| `FileTypeError`                        | File vs directory mismatch        |
+| `ValidationError`                      | Bad offset / length / args        |
+| `FileSystemOperationError` / `IOError` | Underlying FS / I/O failure       |
+| `PermissionError`                      | Access denied                     |

package/docs/guides/async.md

@@ -1,6 +1,6 @@
-# Async (no worker)
+# Async
 
-`OPFSAsync` on the current thread — `getFile()` / `createWritable()`, no Comlink, no worker in the bundle.
+`OPFSAsync` on the **current** thread (main or a worker you already run). Does not create a worker. Uses `getFile()` / `createWritable()`, no Comlink.
 
 Same limits apply as SharedWorker (it’s the same backend).
 
@@ -16,7 +16,7 @@ await fs.appendText('/note.txt', '!');
 const text = await fs.readFile('/note.txt', 'utf-8');
 ```
 
-Import from `opfs-worker/async` if you care about bundle size — the main entry also carries the dedicated-worker path.
+Import from `opfs-worker/async` to keep the dedicated-worker code out of the bundle.
 
 ## Raw class
 
@@ -31,6 +31,6 @@ await fs.writeFile('/x.bin', new Uint8Array([1, 2, 3]));
 
 - **Writes** need `createWritable()` — Chrome, Firefox, Safari **26+**. Reads work anywhere OPFS does.
 - **No file descriptors** — `open` / `read` / `write` / … throw `ENOTSUP`.
-- Each write goes through a swap file and commits on close — fine for documents, awkward for tons of tiny random writes.
+- Each write goes through a swap file and commits on close — fine for documents, slow for many tiny random writes.
 
 Streaming still works: [streaming](./streaming.md). For one fs across tabs: [SharedWorker](./sharedworker.md).