opfs-worker 2.0.0 → 2.1.0

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;

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":"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"}

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/README.md

@@ -0,0 +1,30 @@
+# Docs
+
+New here? Start with [Choosing a mode](./choosing-a-mode.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)

package/docs/api/backend.md

@@ -0,0 +1,36 @@
+# Backend API
+
+Classes from `opfs-worker/pure` (also re-exported from `/sync`, `/async`, `/sharedworker` where it makes sense). Bytes only — no encoding helpers.
+
+```
+BaseOPFS     mkdir, stat, readDir, watch, index, createIndex, …
+  ├─ 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`, `createIndex`, `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)
+
+## Escape hatch
+
+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,52 @@
+# OPFSFacade
+
+Node-ish API: encodings, auto-detect by extension, path as `string` or `URL`. You normally get one from [`createOPFS*`](./create.md); you can also `new OPFSFacade({ fs, worker?, dispose })`.
+
+`fs.promises === fs`.
+
+## Escape hatch
+
+| 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 |
+| `importStream` | Stream / Blob / File — [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>` |
+| `createIndex` | Bulk `[path, string \| Uint8Array \| Blob][]` |
+
+## Watch & lifecycle
+
+| Method | Notes |
+| ------ | ----- |
+| `watch` | Returns `() => void` |
+| `unwatch` | |
+| `setOptions` | [Hashing](../guides/hashing.md) and friends |
+| `dispose` | Tear down 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`.
+
+Full story: [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                                                       | Reach for it when…              | FD        | Comlink |
+| ----- | --------------------------------------------------------- | ------------------------------- | --------- | ------- |
+| **1** | [`createOPFSDedicated()`](./guides/dedicated.md)          | You want a normal `fs`-like API | yes       | yes     |
+| **2** | [`OPFSSync` / `OPFSAsync` from `/pure`](./guides/pure.md) | You’re already in a worker      | sync only | no      |
+| **3** | [`createOPFSAsync()`](./guides/async.md)                  | You don’t want a worker at all  | no        | no      |
+| **4** | [`createOPFSShared()`](./guides/sharedworker.md)          | All tabs should share one fs    | no        | yes     |
+
+Need the raw bytes API or the browser Worker? Use `fs.backend` / `fs.worker` on any facade — no separate factory.
+
+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).

package/docs/file-descriptors.md

@@ -1,23 +1,22 @@
 # File Descriptors
 
-This document covers working with file descriptors in OPFS Worker, which provides low-level file I/O operations similar to POSIX file descriptors.
+Low-level positional I/O, POSIX-style.
+
+> Needs the **dedicated / sync** backend (`createOPFSDedicated` / `createOPFS`, or `OPFSSync` from `/pure`). Async and SharedWorker throw `ENOTSUP`.
 
 ## Requirements
 
-**Important**: When using file descriptors from the main window (browser), you must import and use `Comlink` for proper buffer handling:
+If you talk to **`fs.backend`** from the main thread for FD `read`/`write`, transfer buffers with Comlink:
 
 ```typescript
 import { transfer } from 'comlink';
 ```
 
-## Overview
+The [facade](./api/facade.md) methods do this for you.
 
-File descriptors provide efficient, low-level access to files for reading, writing, and manipulating file data. They're particularly useful for:
+## Overview
 
-- **Large file operations**: Reading/writing files in chunks without loading entire content into memory
-- **Streaming operations**: Processing files sequentially or in specific positions
-- **Performance-critical applications**: Direct file access without the overhead of high-level methods
-- **Binary data manipulation**: Working with raw bytes at specific file positions
+Useful when you need chunks, random access, or to avoid loading a whole file into memory.
 
 ## Table of Contents
 
@@ -170,7 +169,7 @@ console.log('read:', text);
 #### From Worker (Direct Usage)
 
 ```typescript
-// When using OPFSWorker directly in a worker
+// When using OPFSSync directly in a worker
 const buffer = new Uint8Array(64);
 const { bytesRead, buffer: modifiedBuffer } = await fs.read(fd, buffer, 0, buffer.length, null);
 

package/docs/guides/async.md

@@ -0,0 +1,36 @@
+# Async (no worker)
+
+`OPFSAsync` on the current thread — `getFile()` / `createWritable()`, no Comlink, no worker in the bundle.
+
+Same limits apply as SharedWorker (it’s the same backend).
+
+## Facade
+
+```typescript
+import { createOPFSAsync } from 'opfs-worker/async';
+
+const fs = createOPFSAsync({ root: '/my-app' });
+
+await fs.writeFile('/note.txt', 'hello');
+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.
+
+## Raw class
+
+```typescript
+import { OPFSAsync } from 'opfs-worker/async';
+
+const fs = new OPFSAsync({ root: '/my-app' });
+await fs.writeFile('/x.bin', new Uint8Array([1, 2, 3]));
+```
+
+## Limits
+
+- **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.
+
+Streaming still works: [streaming](./streaming.md). For one fs across tabs: [SharedWorker](./sharedworker.md).

package/docs/guides/dedicated.md

@@ -0,0 +1,76 @@
+# Dedicated worker
+
+The default path: `OPFSSync` inside a dedicated Web Worker. You get file descriptors and the fastest write path the browser allows for OPFS.
+
+See also [Choosing a mode](../choosing-a-mode.md).
+
+## Facade
+
+```typescript
+import { createOPFSDedicated } from 'opfs-worker';
+// or from 'opfs-worker/sync'
+
+const fs = createOPFSDedicated({ root: '/my-app' });
+
+await fs.writeFile('/config.json', JSON.stringify({ theme: 'dark' }));
+const config = await fs.readFile('/config.json'); // string — auto-detected
+```
+
+`createOPFS` is the same thing with a shorter name.
+
+The worker is inlined by default, so you don’t need a special bundler worker setup.
+
+## Raw backend
+
+Bytes in, bytes out — no encoding helpers. Same facade, just talk to `backend`:
+
+```typescript
+const fs = createOPFSDedicated({ root: '/my-app' });
+
+await fs.backend.writeFile('/config.json', new TextEncoder().encode('{}'));
+const bytes = await fs.backend.readFile('/config.json');
+
+// Browser Worker, if you ever need it:
+fs.worker; // Worker
+
+fs.dispose(); // dispose + terminate
+```
+
+## Loading a real worker file
+
+Pass `url` or `worker` when you can’t use the inline blob (strict CSP, custom hosting):
+
+```typescript
+import workerUrl from 'opfs-worker/dedicated.worker.js?url'; // Vite
+
+const fs = createOPFSDedicated({ root: '/my-app', url: workerUrl });
+```
+
+## DIY prebuilt script
+
+`opfs-worker/dedicated.worker.js` is a self-contained Worker (Comlink + `OPFSSync` already inside):
+
+```typescript
+import { wrap } from 'comlink';
+import { OPFSFacade } from 'opfs-worker';
+import workerUrl from 'opfs-worker/dedicated.worker.js?url';
+
+const worker = new Worker(workerUrl, { type: 'module' });
+const remote = wrap(worker);
+
+const fs = new OPFSFacade({
+    fs: remote,
+    worker,
+    dispose: () => {
+        void remote.dispose();
+        worker.terminate();
+    },
+});
+```
+
+## Heads-up
+
+- Each call gets its own worker. Tabs don’t share state — use [SharedWorker](./sharedworker.md) for that.
+- Sync access handles are a dedicated-worker-only browser API.
+
+More: [file descriptors](../file-descriptors.md), [streaming](./streaming.md), [create helpers](../api/create.md).

package/docs/guides/hashing.md

@@ -0,0 +1,34 @@
+# Hashing
+
+Set once via `hashAlgorithm` / `maxFileSize` in options or `setOptions()`. Shows up on `stat()`, `index()`, and [watch](./watching.md) events (files only).
+
+| Value | What you get |
+| ----- | ------------ |
+| `'etag'` (default) | Cheap tag from mtime + size — no content read |
+| `'SHA-1'` … `'SHA-512'` | Real content hash (Web Crypto) |
+| `null` / `false` | No `hash` field |
+
+`maxFileSize` (default 50MB) only limits SHA-\* hashing. Oversized files skip the hash.
+
+```typescript
+import { createOPFS } from 'opfs-worker';
+
+const fs = createOPFS();
+
+await fs.writeFile('/data.txt', 'Hello');
+console.log((await fs.stat('/data.txt')).hash); // etag-ish, e.g. "m1abc-c"
+
+await fs.setOptions({ hashAlgorithm: 'SHA-256' });
+console.log((await fs.stat('/data.txt')).hash); // hex digest
+```
+
+`root` scopes you under a subdirectory of OPFS. `namespace` is stamped on every watch event:
+
+```typescript
+const fs = createOPFS({
+    root: '/my-app',
+    namespace: 'my-app:fs',
+});
+```
+
+Full options table: [`create` helpers](../api/create.md#options).

package/docs/guides/pure.md

@@ -0,0 +1,46 @@
+# Pure classes
+
+Use the classes directly inside a worker (or thread) you already own. No nested worker, no Comlink `expose()` from this package — wiring to the main thread is on you.
+
+```typescript
+import { OPFSSync, OPFSAsync } from 'opfs-worker/pure';
+```
+
+| Class | Runs where | FD |
+| ----- | ---------- | -- |
+| `OPFSSync` | Dedicated worker only | yes |
+| `OPFSAsync` | Main thread, dedicated, or SharedWorker | no |
+| `BaseOPFS` | Shared base — usually you don’t instantiate it | — |
+
+## OPFSSync in your dedicated worker
+
+```typescript
+// my-app.worker.ts
+import { OPFSSync } from 'opfs-worker/pure';
+
+const fs = new OPFSSync({
+    root: '/my-app',
+    broadcastChannel: 'my-app-events', // name only — instances can’t cross the wire
+});
+
+await fs.writeFile('/config.json', new TextEncoder().encode('{}'));
+```
+
+`/pure` won’t hijack your worker’s message port.
+
+## OPFSAsync in a SharedWorker you write
+
+```typescript
+import { expose } from 'comlink';
+import { OPFSAsync } from 'opfs-worker/pure';
+
+const fs = new OPFSAsync({ root: '/my-app' });
+
+onconnect = (e) => {
+    expose(fs, e.ports[0]);
+};
+```
+
+Or skip the boilerplate and use the [SharedWorker guide](./sharedworker.md).
+
+Also: [backend API](../api/backend.md), [dedicated](./dedicated.md), [async](./async.md).