opfs-worker 2.0.0 → 2.1.1

package/dist/types.d.ts

@@ -1,5 +1,4 @@
-import type { OPFSWorker } from './OPFSWorker';
-import type { Remote } from 'comlink';
+import type { OPFSSync } from './core/OPFSSync';
 /**
  * Type for paths that can be either a string or URI
  */
@@ -37,8 +36,14 @@ export interface WatchEvent {
     timestamp: string;
     hash?: string;
 }
-export type { OPFSWorker };
-export type RemoteOPFSWorker = Remote<OPFSWorker>;
+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.
+ */
+export type OPFSApi = {
+    [K in keyof OPFSSync]: OPFSSync[K];
+};
 export interface OPFSOptions {
     /** Root path for the file system (default: '/') */
     root?: string;
@@ -51,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,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEtC;;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,UAAU,EAAE,CAAC;AAC3B,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;AAElD,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/worker/createDedicatedWorker.d.ts

@@ -0,0 +1,30 @@
+import type { OPFSOptions, OPFSSync } from '../types';
+import type { Remote } from 'comlink';
+type RemoteOPFSSync = Remote<OPFSSync>;
+export interface DedicatedWorkerOptions extends OPFSOptions {
+    /**
+     * URL of the worker script, e.g. `import url from 'opfs-worker/dedicated.worker.js?url'` (Vite).
+     *
+     * Defaults to the inlined worker (no URL needed). Pass an explicit url when you
+     * prefer the self-contained file (strict CSP without `blob:`, or DIY hosting).
+     */
+    url?: string | URL;
+    /** Bring your own Worker instance (overrides `url`) */
+    worker?: Worker;
+}
+export interface RawWorker {
+    /** Comlink proxy to `OPFSSync` (bytes in / bytes out) */
+    fs: RemoteOPFSSync;
+    /** Underlying browser Worker */
+    worker: Worker;
+    /** Calls worker `dispose()` then `terminate()` */
+    dispose: () => void;
+}
+/**
+ * Internal helper: spawn a dedicated worker and wrap `OPFSSync` with Comlink.
+ * Prefer {@link createOPFSDedicated}; access the proxy / Worker via
+ * `facade.backend` / `facade.worker`.
+ */
+export declare function createDedicatedWorker(options?: DedicatedWorkerOptions): RawWorker;
+export {};
+//# sourceMappingURL=createDedicatedWorker.d.ts.map

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

@@ -0,0 +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"}

package/dist/worker/createSharedWorker.d.ts

@@ -0,0 +1,37 @@
+import type { OPFSAsync } from '../core/OPFSAsync';
+import type { OPFSOptions } from '../types';
+import type { Remote } from 'comlink';
+type RemoteOPFSAsync = Remote<OPFSAsync>;
+export interface SharedWorkerOptions extends OPFSOptions {
+    /**
+     * URL of the worker script, e.g. `import url from 'opfs-worker/shared.worker.js?url'` (Vite).
+     *
+     * Defaults to `new URL('./shared.worker.js', import.meta.url)`, which works when
+     * `opfs-worker` is served as-is (CDN, unbundled deps). When your bundler inlines
+     * the package into app chunks, pass the url explicitly.
+     */
+    url?: string | URL;
+    /** Bring your own SharedWorker instance (overrides `url`) */
+    worker?: SharedWorker;
+    /** Worker name — tabs with the same script URL + name share one instance (default: 'opfs-worker') */
+    name?: string;
+}
+export interface RawSharedWorker {
+    /** Comlink proxy to the `OPFSAsync` instance shared by all connected tabs */
+    fs: RemoteOPFSAsync;
+    /** Underlying browser SharedWorker */
+    worker: SharedWorker;
+    /** Closes this tab's port; the worker keeps running for other tabs */
+    dispose: () => void;
+}
+/**
+ * Internal helper: connect to the SharedWorker and wrap `OPFSAsync` with Comlink.
+ * Prefer {@link createOPFSShared}; access the proxy / SharedWorker via
+ * `facade.backend` / `facade.worker`.
+ *
+ * Note: `OPFSOptions` are applied via `setOptions()` on the shared instance, so
+ * they affect every connected tab — use the same options in all tabs.
+ */
+export declare function createSharedWorker(options?: SharedWorkerOptions): RawSharedWorker;
+export {};
+//# sourceMappingURL=createSharedWorker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"createSharedWorker.d.ts","sourceRoot":"","sources":["../../src/worker/createSharedWorker.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEtC,KAAK,eAAe,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;AAEzC,MAAM,WAAW,mBAAoB,SAAQ,WAAW;IACpD;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IACnB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,qGAAqG;IACrG,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC5B,6EAA6E;IAC7E,EAAE,EAAE,eAAe,CAAC;IACpB,sCAAsC;IACtC,MAAM,EAAE,YAAY,CAAC;IACrB,sEAAsE;IACtE,OAAO,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,eAAe,CA0BrF"}

package/dist/worker/dedicated.worker.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=dedicated.worker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dedicated.worker.d.ts","sourceRoot":"","sources":["../../src/worker/dedicated.worker.ts"],"names":[],"mappings":""}

package/dist/worker/shared.worker.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=shared.worker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shared.worker.d.ts","sourceRoot":"","sources":["../../src/worker/shared.worker.ts"],"names":[],"mappings":""}

package/docs/api/backend.md

@@ -0,0 +1,36 @@
+# Backend API
+
+Classes from `opfs-worker/pure` (also re-exported from `/sync`, `/async`, `/sharedworker`). Bytes only — no encoding helpers.
+
+```
+BaseOPFS     mkdir, stat, readDir, watch, index, importFiles, …
+  ├─ OPFSSync   sync access handles + FDs + writeStream
+  └─ OPFSAsync  getFile / createWritable + writeStream (no FDs)
+```
+
+`OPFSApi` = the `OPFSSync` method surface — both backends and Comlink proxies satisfy it.
+
+## Shared methods (`BaseOPFS`)
+
+Path ops: `mkdir`, `stat`, `readDir`, `exists`, `clear`, `remove`, `rename`, `copy`, `realpath`, `index`, `readBlob`, `importFiles`, `watch`, `unwatch`, `setOptions`, `dispose`.
+
+Subclasses implement:
+
+- `readFile` / `writeFile` / `appendFile`
+- `writeStream(path, stream, onProgress?)`
+
+## `OPFSSync`
+
+Dedicated-worker backend. Adds FD methods (`open` … `fsync`) and streams via chunked FD writes.
+
+→ [File descriptors](../file-descriptors.md), [dedicated guide](../guides/dedicated.md).
+
+## `OPFSAsync`
+
+Promise File System API. Streams via `createWritable()`. FDs always throw `OperationNotSupportedError`. Writes need Safari 26+ (or Chrome / Firefox).
+
+→ [Async guide](../guides/async.md).
+
+## Comlink
+
+Dedicated and SharedWorker facades expose the same backend surface on `fs.backend` (a Comlink proxy). For FD `read`/`write` from the main thread, transfer buffers with Comlink — the facade does that for you.

package/docs/api/create.md

@@ -0,0 +1,82 @@
+# Create helpers
+
+Factories from the package entries. For when to pick which: [Choosing a mode](../choosing-a-mode.md).
+
+## Facade
+
+| Function                        | From                   | Backend                       |
+| ------------------------------- | ---------------------- | ----------------------------- |
+| `createOPFSDedicated(options?)` | `.` or `/sync`         | Dedicated worker + `OPFSSync` |
+| `createOPFSAsync(options?)`     | `.` or `/async`        | In-process `OPFSAsync`        |
+| `createOPFSShared(options?)`    | `.` or `/sharedworker` | SharedWorker + `OPFSAsync`    |
+
+All return [`OPFSFacade`](./facade.md).
+
+```typescript
+import { createOPFSDedicated, createOPFSAsync, createOPFSShared } from 'opfs-worker';
+```
+
+On the main entry only:
+
+- `createOPFS` → `createOPFSDedicated`
+- `createWorker` → same (deprecated)
+- `OPFSFileSystem` → `OPFSFacade` (deprecated)
+
+## Backend access
+
+Every facade exposes:
+
+| Field        | Meaning                                                               |
+| ------------ | --------------------------------------------------------------------- |
+| `fs.backend` | Raw [`OPFSApi`](../types.md#opfsapi) — bytes in / bytes out           |
+| `fs.worker`  | `Worker` / `SharedWorker` when one was created; `undefined` for async |
+
+```typescript
+const fs = createOPFSDedicated({ root: '/my-app' });
+await fs.backend.writeFile('/a.bin', bytes);
+fs.worker; // Worker
+```
+
+## Options
+
+Passed to any `createOPFS*` (and to `setOptions()` later). Full type: [`OPFSOptions`](../types.md#opfsoptions).
+
+| 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                                                              |
+
+### 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`)                                        |
+
+### 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
+const fs = createOPFS({
+    root: '/my-app',
+    hashAlgorithm: 'SHA-256',
+    maxFileSize: 10 * 1024 * 1024,
+});
+```
+
+## Prebuilt scripts
+
+| Export                            | Hook up with                                             |
+| --------------------------------- | -------------------------------------------------------- |
+| `opfs-worker/dedicated.worker.js` | `new Worker(url, { type: 'module' })` or `{ url }`       |
+| `opfs-worker/shared.worker.js`    | `new SharedWorker(url, { type: 'module' })` or `{ url }` |
+
+Walkthroughs: [dedicated](../guides/dedicated.md), [sharedworker](../guides/sharedworker.md).

package/docs/api/facade.md

@@ -0,0 +1,53 @@
+# OPFSFacade
+
+Node-like API: encodings, auto-detect by extension, path as `string` or `URL`. Usually from [`createOPFS*`](./create.md); or `new OPFSFacade({ fs, worker?, dispose })`.
+
+`fs.promises === fs`.
+
+## Backend access
+
+| Field     | Notes                                                                        |
+| --------- | ---------------------------------------------------------------------------- |
+| `backend` | Raw [`OPFSApi`](../types.md#opfsapi) — same methods without encoding helpers |
+| `worker`  | `Worker` / `SharedWorker` if this facade owns one; `undefined` for async     |
+
+## File I/O
+
+| Method                                  | Notes                                                                                         |
+| --------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `readFile` / `writeFile` / `appendFile` | Encoding as string, `{ encoding }`, or auto                                                   |
+| `readBlob`                              | Disk-backed `Blob`, nothing copied into memory — [streaming](../guides/streaming.md)          |
+| `importStream`                          | Stream / Blob / File — [streaming](../guides/streaming.md)                                    |
+| `importFiles`                           | Bulk array / `Map` of `[path, data]` with rich progress — [streaming](../guides/streaming.md) |
+| `readText` / `writeText` / `appendText` | UTF-8 by default                                                                              |
+
+## Directories & metadata
+
+| Method                         | Notes                                                 |
+| ------------------------------ | ----------------------------------------------------- |
+| `mkdir`                        | `{ recursive }`; numeric mode is accepted and ignored |
+| `readDir`                      | `DirentData[]`                                        |
+| `stat` / `exists` / `realpath` |                                                       |
+| `remove`                       | `{ recursive, force }`                                |
+| `rename` / `copy`              | `copy` takes `{ recursive, overwrite }`               |
+| `clear`                        | Empty a dir (default `/`)                             |
+| `index`                        | `Map<path, FileStat>`                                 |
+
+## Watch & lifecycle
+
+| Method       | Notes                               |
+| ------------ | ----------------------------------- |
+| `watch`      | Returns `() => void`                |
+| `unwatch`    |                                     |
+| `setOptions` | See [hashing](../guides/hashing.md) |
+| `dispose`    | Dispose the backend                 |
+
+## Node aliases
+
+`unlink` / `rm` / `rmdir` → `remove`. `readdir` → `readDir`. `lstat` → `stat`. `chmod` is a no-op (no Unix modes in OPFS).
+
+## File descriptors
+
+`open`, `read`, `write`, `close`, `fstat`, `ftruncate`, `fsync` — dedicated / `OPFSSync` only. Async throws `ENOTSUP`.
+
+Details: [file descriptors](../file-descriptors.md).

package/docs/choosing-a-mode.md

@@ -0,0 +1,41 @@
+# Choosing a mode
+
+Sync access handles only work in a **dedicated** worker. Async writes (`createWritable`) work on the main thread and in SharedWorkers too, but Safari needs **26+** for writing.
+
+## Package entries
+
+| Entry                             | What you get                                                    |
+| --------------------------------- | --------------------------------------------------------------- |
+| `opfs-worker`                     | Everything (plus 1.x aliases)                                   |
+| `opfs-worker/sync`                | Dedicated worker only — `createOPFSDedicated`, `OPFSSync`       |
+| `opfs-worker/async`               | No worker — `createOPFSAsync`, `OPFSAsync`                      |
+| `opfs-worker/sharedworker`        | SharedWorker helpers                                            |
+| `opfs-worker/pure`                | Classes only — you own the thread                               |
+| `opfs-worker/dedicated.worker.js` | Prebuilt dedicated Worker script                                |
+| `opfs-worker/shared.worker.js`    | Prebuilt SharedWorker script                                    |
+
+## Modes
+
+|       | API                                                       | When                            | FD        | Comlink |
+| ----- | --------------------------------------------------------- | ------------------------------- | --------- | ------- |
+| **1** | [`createOPFSDedicated()`](./guides/dedicated.md)          | Normal `fs`-like API            | yes       | yes     |
+| **2** | [`OPFSSync` / `OPFSAsync` from `/pure`](./guides/pure.md) | Already in a worker             | sync only | no      |
+| **3** | [`createOPFSAsync()`](./guides/async.md)                  | No worker                       | no        | no      |
+| **4** | [`createOPFSShared()`](./guides/sharedworker.md)          | One fs shared by all tabs       | no        | yes     |
+
+For the raw bytes API or the browser Worker, use `fs.backend` / `fs.worker` on any facade.
+
+If size matters, import from `/sync`, `/async`, or `/sharedworker` instead of the main barrel.
+
+## Trade-offs
+
+|                           | Dedicated (`OPFSSync`)                                                                 | Async (`OPFSAsync`)            |
+| ------------------------- | -------------------------------------------------------------------------------------- | ------------------------------ |
+| File descriptors          | yes                                                                                    | `ENOTSUP`                      |
+| Safari writes             | yes (via the worker)                                                                   | 26+                            |
+| SharedWorker              | no                                                                                     | yes                            |
+| One instance for all tabs | no (unless you build SharedWorker yourself)                                            | Mode 4                         |
+| Bundle                    | ~80 KB inlined worker, or [prebuilt script](./guides/dedicated.md#diy-prebuilt-script) | small via `/async`             |
+| CSP without `blob:`       | pass `url` / prebuilt script                                                           | no worker, or SharedWorker URL |
+
+Aliases on the main entry: `createOPFS` / `createWorker` → `createOPFSDedicated`, `OPFSFileSystem` → `OPFSFacade`. See [Migration](./migration.md).