knitting 0.1.56 → 0.1.61

package/BROWSER.md

@@ -0,0 +1,134 @@
+# Browser limitations
+
+`knitting/browser` runs the same pool API over web workers and
+`SharedArrayBuffer`. Tasks, typed-array payloads, parallel calls, abort signals,
+and shutdown all behave as they do on Node, Deno, and Bun.
+
+This page is the other half: what a page cannot do, what happens when you try,
+and why. Everything below was checked against headless Chromium, and every
+quoted message is the one the runtime actually produces.
+
+## Two hard requirements
+
+### The page must be cross-origin isolated
+
+Browsers only expose `SharedArrayBuffer` to pages served with both:
+
+```
+Cross-Origin-Opener-Policy: same-origin
+Cross-Origin-Embedder-Policy: require-corp
+```
+
+Without them `createPool` throws:
+
+> SharedArrayBuffer is unavailable: serve the page cross-origin isolated
+> (Cross-Origin-Opener-Policy: same-origin, Cross-Origin-Embedder-Policy:
+> require-corp).
+
+This is not a knitting policy and cannot be worked around: no shared memory
+means no pool. It also constrains the rest of the page — every cross-origin
+subresource needs `Cross-Origin-Resource-Policy` or CORS, or the browser refuses
+to load it once isolation is on.
+
+### Task modules must call `setModuleUrl(import.meta.url)`
+
+On Node, Deno, and Bun a task discovers its own module by walking the stack.
+Bundlers erase the paths that depends on, so in a browser the module has to say
+where it lives:
+
+```js
+import { setModuleUrl, task } from "knitting/browser";
+
+setModuleUrl(import.meta.url);
+
+export const square = task({ f: (value) => value * value });
+```
+
+Without it the worker cannot import the module that defines the tasks.
+
+## Not available in a browser
+
+| Feature                                                              | What happens                                                     |
+| -------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| Process workers (`worker.runtime: "process"`, `processRuntime`)      | throws `process workers are unavailable in the browser build`    |
+| Compiled / Porffor workers (`runtime: "compiled"`, `.knt` artifacts) | throws `compiled workers are unavailable in the browser build`   |
+| `BufferReference`                                                    | throws `BufferReference cannot run in runtime "browser"`         |
+| `ProcessSharedBuffer`, named shared memory                           | throws `ProcessSharedBuffer is unavailable in the browser build` |
+| Native addons, FFI, file descriptors                                 | unreachable; nothing in a page can load them                     |
+| `checkCompiledWorker`                                                | not exported from `knitting/browser`                             |
+| Permissions (`permission: {...}`)                                    | **silently ignored** — see below                                 |
+
+All of these need a filesystem, a process to spawn, or FFI. The browser build
+replaces them with stubs that raise the errors above rather than failing deeper
+in with a confusing one.
+
+### Permissions are inert, and that is a security boundary
+
+The `permission` option is accepted and then skipped entirely. There is no
+filesystem to restrict, no process to sandbox, and no runtime flags to pass, so
+a strict policy that would constrain a Node worker constrains nothing here.
+
+A web worker runs with the privileges of the page that spawned it: same origin,
+same `fetch` reach, same storage. **Task code you would not trust with your
+origin must not run in a browser pool.** Isolation there is the browser's job —
+a sandboxed iframe on a separate origin — not knitting's.
+
+### `SharedArrayBuffer` as a task argument
+
+This one differs from every other runtime, so it is worth calling out
+separately. Passing a `SharedArrayBuffer` _as an argument to a task_ works on
+Node, Deno, and Bun, and throws in a browser:
+
+```
+KNT_ERROR_3: Unsupported payload type; BufferReference cannot run in runtime "browser"
+```
+
+The SAB payload path shares buffers by pinning a process-local pointer through
+FFI, which a page cannot do. The pool's own transport is unaffected — that is
+how the workers talk at all — this is only about SABs you pass yourself.
+
+Nothing prevents a browser-native path here: SABs are structured-cloneable in a
+cross-origin isolated context, so `postMessage` could carry them without any
+pointer. It simply is not implemented.
+
+## Behaves differently, but works
+
+- **Workers boot by message, not by `workerData`.** The pool posts the boot
+  payload after constructing the worker. Invisible in the API; relevant if you
+  are reading worker startup code.
+- **`KNITTING_DEBUG` is ignored.** The env gate reads `Deno.env` or
+  `process.env`, neither of which exists in a page. Pass the `debug` option to
+  `createPool` explicitly instead.
+- **`threads` still defaults to 1.** There is no auto-sizing on any runtime; in
+  a browser `navigator.hardwareConcurrency` is the number to reach for.
+- **Every worker loads the whole bundle.** The worker URL is the bundle's own
+  URL, so each thread parses the library again. Memory cost scales with thread
+  count.
+
+## Not browser limitations
+
+These fail the same way on Node, so do not go looking for a browser cause:
+
+- `BigInt` payloads — `Do not know how to serialize a BigInt`
+- `Map` / `Set` payloads — `Unsupported object type`
+- Functions as payloads — `KNT_ERROR_0: Function is not a valid type`
+- `Error` values round-trip as `{ name }`, dropping the message
+
+## Where this is tested
+
+The browser lane (`npm run test:browser`) drives headless Chromium through two
+layouts — one bundle containing tasks and library, and the standalone
+single-file bundle loaded from a script tag next to a separate task module.
+
+**Chromium is the only engine covered.** Firefox and Safari support the same
+primitives (workers, `SharedArrayBuffer` under cross-origin isolation) and are
+expected to work, but nothing here has been verified against them.
+
+## How the browser build is produced
+
+`knitting/browser` ships as one self-contained minified file (~94 KB, ~32 KB
+gzipped). The Node-only subsystems are swapped for stubs at bundle time by
+[`scripts/browser-stubs/plugin.ts`](scripts/browser-stubs/plugin.ts); each stub
+keeps the behaviour the real module already had in a page — return nothing,
+answer false, or throw the message quoted above — which is why the errors in
+this document are precise rather than generic.

package/README.md

@@ -15,7 +15,8 @@ Website: [knittingdocs.netlify.app](https://knittingdocs.netlify.app/)
 
 If you are an agent trying to understand the project, the website also serves an
 [`llms.txt`](https://knittingdocs.netlify.app/llms.txt) file with a compact map
-of the docs.
+of the docs, plus a full inlined version at
+[`llms-full.txt`](https://knittingdocs.netlify.app/llms-full.txt).
 
 Knitting is a worker pool built on shared-memory IPC for Node.js, Deno, and Bun.
 It lets you call work running on other threads or processes as if it were a
@@ -60,7 +61,8 @@ cross-runtime shared memory.
 
 ## Requirements
 
-- Node.js 22+
+- Node.js 22+; native features support Node.js 22 and 24 through prebuilt
+  addons, and Node.js 26 through experimental `node:ffi`
 - Deno 2+
 - Bun 1+
 
@@ -235,6 +237,9 @@ export const countUntilStopped = task({
 });
 ```
 
+The signal also carries `signal.now()`, a monotonic millisecond clock for
+measuring elapsed time inside the task.
+
 The pool also has an `abortSignalCapacity` option for sizing the shared abort
 signal storage when many abort-aware calls may be in flight.
 
@@ -335,19 +340,29 @@ Common options you might tweak:
 | `worker.resolveAfterFinishingAll` | Let submitted calls finish before shutdown resolves.                                                                              |
 | `worker.bootstrap`                | Privileged async hook imported and awaited before task modules load.                                                              |
 | `worker.hardTimeoutMs`            | Force pool shutdown when a task exceeds this many milliseconds.                                                                   |
-| `worker.runtime`                  | Choose `"thread"` or `"process"` workers.                                                                                         |
+| `worker.runtime`                  | Choose `"thread"`, `"process"`, or experimental `"compiled"` workers.                                                             |
+| `worker.processRuntime`           | Choose `"node"`, `"deno"`, or `"bun"`; standalone `"porffor"` selects compilation and rebuilds once per pool.                    |
 | `worker.processSharedMemory`      | Process-worker memory discovery: `"inherit"` by default on POSIX, or `"named"` for wrappers/containers that cannot preserve fd 0. |
 | `permission`                      | Runtime permission policy for workers.                                                                                            |
 | `host.dispatcher`                 | Experimental host dispatcher topology: `"per-thread"` or `"serial-channel"`.                                                      |
+| `host.steal`                      | Shared-submit work stealing for multi-worker thread pools; enabled by default. Set `false` to use private submit lanes.            |
 | `debug`                           | Enable diagnostics (`host`, `globals`, `signals`, `imports`, `lifecycle`) or use `KNITTING_DEBUG`.                                |
 | `source`                          | Worker source override for advanced runtimes.                                                                                     |
 
-Most users can leave `host.dispatcher` alone. The current default is
-experimental: Bun and single-worker pools use `"per-thread"`, while multi-worker
-Node/Deno pools use `"serial-channel"` because it tends to behave well for
-bursty HTTP-style fan-out. If you are tuning a server or comparing runtimes, you
-can force either mode with `KNITTING_DISPATCHER=per-thread` or
-`KNITTING_DISPATCHER=serial-channel`.
+Most users can leave `host.dispatcher` alone. It selects the dispatcher for
+private-lane pools: Bun and single-worker pools default to `"per-thread"`, while
+multi-worker Node/Deno pools use `"serial-channel"`. Selecting a dispatcher or
+balancer explicitly preserves that private-lane topology unless
+`host.steal: true` is also explicit.
+
+Ordinary multi-worker thread pools use shared-submit work stealing by default.
+It is not used by one-worker pools, the inliner, process workers, compiled/
+Porffor workers, or pools with an explicit balancer/dispatcher, so those modes
+retain their existing transport. Pools above the current 31-claimant protocol
+limit also fall back. Set `host: { steal: false }` or `KNITTING_STEAL=0` to opt
+out for uniformly cheap, low-concurrency workloads where arbitration has
+nothing to rebalance. `host: { steal: true }` or `KNITTING_STEAL=1` forces it
+for an otherwise compatible thread pool.
 
 ### Worker bootstrap
 
@@ -397,6 +412,27 @@ const pool = createPool({
 ```
 
 `processRuntime` can be `"node"`, `"deno"`, or `"bun"` and defaults to `"deno"`.
+Using `processRuntime: "porffor"` is shorthand for the compiled backend and
+forces one fresh native build whenever `createPool(...)` is called:
+
+```ts
+using pool = createPool({
+  worker: { processRuntime: "porffor" },
+})({ add });
+```
+
+Add `runtime: "compiled"` to reuse a compatible `.knt` instead. Missing or
+stale artifacts still build automatically:
+
+```ts
+using pool = createPool({
+  worker: {
+    runtime: "compiled",
+    processRuntime: "porffor",
+  },
+})({ add });
+```
+
 You can also provide a `processCommandPrefix` when workers need to be launched
 through a wrapper such as a package manager, container command, or runtime shim.
 
@@ -445,6 +481,112 @@ const pool = createPool({
 })({ add });
 ```
 
+### Experimental compiled workers
+
+A native worker uses the same task declaration and pool call syntax. For a
+task module named tasks.ts, Knitting looks for tasks.knt plus tasks.knt.json.
+If they are missing, incompatible, or older than the task module, the first
+pool builds them automatically with a pinned Porffor compiler; later pools
+reuse the validated artifact:
+
+| Worker settings | Compilation behavior |
+| --- | --- |
+| `runtime: "compiled"` | Reuse a compatible `.knt`; build when missing, stale, or incompatible. |
+| `processRuntime: "porffor"` | Select the compiled backend and always rebuild once per pool. |
+| `runtime: "compiled", processRuntime: "porffor"` | Reuse a compatible `.knt`; build when missing, stale, or incompatible. |
+
+For example, this bare-function form uses `hello.knt` when it is current:
+
+```ts
+import { createPool, isMain } from "knitting";
+
+export const hello = (name: string) => "Hello " + name;
+
+using pool = createPool({
+  worker: {
+    runtime: "compiled",
+    processRuntime: "porffor",
+  },
+})({ hello });
+
+if (isMain) console.log(await pool.call.hello("World!"));
+```
+
+Remove `runtime: "compiled"` from that example when you want a fresh build on
+every `createPool(...)`. A multi-worker pool still compiles only once, then
+starts every native worker from the resulting artifact.
+
+The `task(...)` declaration form works the same way:
+
+```ts
+import { createPool, isMain, task } from "knitting";
+
+export const addOne = task<number, number>({
+  f: (value) => value + 1,
+});
+
+if (isMain) {
+  using pool = createPool({
+    threads: 2,
+    worker: { runtime: "compiled" },
+  })({ addOne });
+
+  console.log(await pool.call.addOne(41)); // 42
+}
+```
+
+Use worker.compiled.artifact when artifacts live in a build directory:
+
+```ts
+const pool = createPool({
+  worker: {
+    runtime: "compiled",
+    compiled: { artifact: "./build/tasks-linux-x64.knt" },
+  },
+})({ addOne });
+```
+
+`worker.compiled.manifest` selects a non-default sidecar location.
+`worker.compiled.build` controls generation directly:
+
+- `true` or omitted: build only when the artifact cannot be reused.
+- `false`: never build; fail if the prebuilt artifact is unavailable.
+- `"always"`: rebuild once whenever a pool is created.
+
+The extension is .knt rather than .out because it identifies a Knitting worker
+artifact; executability is never inferred from the suffix alone. Knitting also
+requires the sidecar to match the protocol version, current platform and
+architecture, source module, source timestamp, and requested task names before
+spawning it. `checkCompiledWorker(...)` remains a read-only way to inspect that
+state without building or executing anything.
+
+Automatic builds use Porffor main from `worker.compiled.compiler`,
+`PORFFOR_MAIN`/`PORF`, or `porf` on PATH. If none exists, Knitting downloads a
+pinned compiler into `$XDG_CACHE_HOME/knitting`, or `~/.cache/knitting` when
+`XDG_CACHE_HOME` is unset. Native builds use Porffor `-O3` and parallel LTO.
+Set `worker.compiled.build: false` for deployment environments that must use
+only a prebuilt artifact.
+
+To build ahead of time, run
+`bun run build:compiled --module tasks.ts --out tasks.knt --tasks addOne`.
+
+Treat this backend as experimental. Porffor is a young ahead-of-time compiler,
+the artifact format is pre-release and changes without a compatibility path, and
+the executable is native, unsandboxed code — only run artifacts you trust.
+
+Compiled workers accept synchronous JSON-compatible primitives, arrays, and
+plain objects up to 1 MiB per call, plus `ArrayBuffer`, `DataView`, and typed
+arrays, which are copied. A `ProcessSharedBuffer` is mapped by the worker rather
+than copied. BMP Unicode is supported; supplementary code points and async
+results are not.
+
+Abort-aware tasks work on POSIX: the pool shares an abort bitmap through named
+shared memory, so `signal.hasAborted()` and `signal.now()` are native reads
+inside the worker. Windows has no implementation yet. Task timeouts, bootstrap
+hooks, permission policies, and host inlining still fail during pool creation or
+invocation; `worker.hardTimeoutMs` remains available because the host enforces
+it.
+
 ### Windows process workers
 
 On Windows, Knitting automatically uses named shared memory for the
@@ -499,6 +641,84 @@ const pool = createPool({
 })({ add });
 ```
 
+## Browsers
+
+Knitting also runs in the browser, where the pool spawns web workers over
+`SharedArrayBuffer` instead of threads. Two rules apply there and nowhere else.
+
+**The page must be cross-origin isolated.** Browsers hand out
+`SharedArrayBuffer` only under these two response headers, and `createPool`
+fails with a clear error when they are missing:
+
+```
+Cross-Origin-Opener-Policy: same-origin
+Cross-Origin-Embedder-Policy: require-corp
+```
+
+**Task modules must declare their own URL.** On Node, Deno, and Bun a task
+finds its module by walking the stack; a bundler erases the paths that depends
+on, so call `setModuleUrl(import.meta.url)` in the module that exports tasks:
+
+```ts
+import { createPool, isMain, setModuleUrl, task } from "knitting/browser";
+
+setModuleUrl(import.meta.url);
+
+export const square = task({ f: (value: number) => value * value });
+
+if (isMain) {
+  const pool = createPool({ threads: 4 })({ square });
+  console.log(await pool.call.square(7)); // 49
+  await pool.shutdown();
+}
+```
+
+Bundle that module with any browser-targeting bundler. The result is
+self-hosting: the page loads it, and every worker the pool spawns loads the
+same file, which is why both sides agree on the module URL.
+
+`knitting/browser` ships as one self-contained file, so it also works without a
+bundler at all — serve it next to a plain task module:
+
+```html
+<script type="module" src="./tasks.js"></script>
+```
+
+```js
+// tasks.js
+import { createPool, isMain, setModuleUrl, task } from "./knitting.browser.js";
+
+setModuleUrl(import.meta.url);
+
+export const square = task({ f: (value) => value * value });
+
+if (isMain) {
+  const pool = createPool({ threads: 2 })({ square });
+  console.log(await pool.call.square(7)); // 49
+  await pool.shutdown();
+}
+```
+
+It is the same API as the main entry without the compiled worker (Porffor)
+helpers, which need a filesystem. Process workers, native addons, FFI, and the
+permission system are inert in a browser — permissions are skipped entirely,
+since there is no filesystem or process to police.
+
+Process workers, compiled workers, native addons, FFI, `BufferReference`, and
+`ProcessSharedBuffer` are all unavailable in a page, and permissions are
+skipped rather than enforced. [BROWSER.md](BROWSER.md) documents every one of
+those, with the error each raises.
+
+The published file is bundled and minified, with the Node-only subsystems
+(process workers, compiled workers, native addons, FFI, permissions) replaced
+by stubs that keep their browser behaviour — roughly 94 KB, 32 KB over gzip.
+Both layouts above are covered by the browser test lane:
+
+```bash
+npm run build:browser   # build/knitting.browser.js and .min.js
+npm run test:browser    # end-to-end checks in headless Chromium
+```
+
 ## Permissions
 
 Knitting defaults to a strict worker permission policy:
@@ -507,8 +727,9 @@ Knitting defaults to a strict worker permission policy:
 permission: { mode: "strict", allowImport: true }
 ```
 
-That default is meant to be safe enough for normal task imports without giving
-workers broad ambient access.
+For process workers, that default is translated through the selected runtime's
+permission model. If a runtime cannot enforce one of the implicit defaults,
+Knitting warns once. Do not treat the default as an OS sandbox.
 
 For trusted local scripts, you can opt out:
 
@@ -518,7 +739,8 @@ const pool = createPool({
 })({ add });
 ```
 
-For production or plugin-like workloads, prefer an explicit policy:
+For production or plugin-like workloads, prefer an explicit policy. This example
+is fully representable by a Deno process worker:
 
 ```ts
 const pool = createPool({
@@ -534,9 +756,45 @@ const pool = createPool({
 })({ add });
 ```
 
-Permissions are enforced using the runtime features available in Node.js, Deno,
-and Bun. The exact mechanics vary by runtime, so treat them as a guardrail, not
-as the only security boundary for hostile code.
+Before a process worker is spawned, Knitting checks explicit restrictions
+against the selected runtime. A restriction that would be broader than requested
+or ignored is rejected synchronously. Implicit strict-default gaps remain
+backward compatible and produce a once-per-runtime warning.
+
+| Process-worker permission | Deno                | Node 22/24          | Node 26+                   | Bun         |
+| ------------------------- | ------------------- | ------------------- | -------------------------- | ----------- |
+| Filesystem allow-list     | Scoped              | Scoped              | Scoped                     | Unsupported |
+| Filesystem deny-list      | Scoped              | Unsupported         | Unsupported                | Unsupported |
+| Network                   | Scoped allow/deny   | Unsupported         | Deny-all or allow-all only | Unsupported |
+| Environment allow/deny    | Scoped              | Unsupported         | Unsupported                | Unsupported |
+| Child processes           | Scoped allow/deny   | All-or-none         | All-or-none                | Unsupported |
+| Worker creation           | Unsupported         | All-or-none         | All-or-none                | Unsupported |
+| Import hosts              | Scoped              | Unsupported         | Unsupported                | Unsupported |
+| System information        | Scoped              | Unsupported         | Unsupported                | Unsupported |
+| WASI denial               | Unsupported         | All-or-none         | All-or-none                | Unsupported |
+| Native code / FFI denial  | Transport exception | Transport exception | Transport exception        | Unsupported |
+
+“All-or-none” means an explicit scoped list fails closed. Node 26's
+`--allow-net` switch is emitted for `net: true`, but a host allow-list still
+cannot be represented. When a wrapper or cross-runtime host hides the target
+Node version, Knitting uses the conservative Node 22/24 capability set.
+
+These compatibility checks currently cover process workers. Thread workers use
+the host runtime's worker behavior and should not be treated as a sandbox.
+Runtime permissions are guardrails, not the only security boundary for hostile
+code.
+
+The top-level `ffi` permission is the explicit cross-runtime native-code
+capability. On Node it enables both native addons and `node:ffi`; Node's
+`--allow-ffi` permission is currently unrestricted. The legacy/runtime-specific
+`node.allowAddons` and `node.allowFfi` switches are independent—enabling addons
+does not silently enable FFI.
+
+Node process workers are a transport exception: Knitting needs `--allow-addons`
+on Node 22/24 or `--allow-ffi` on Node 26 to map their shared memory. Deno
+process workers likewise need `--allow-ffi`. Those capabilities apply to the
+entire worker process, including task code, so explicit native-code denial fails
+closed. Use an OS sandbox when task code is hostile.
 
 ## Payloads
 
@@ -607,12 +865,12 @@ if (isMain) {
 The body is generic — `Envelope<Header, Body>` — and accepts any of the binary
 shapes the transport understands:
 
-| Body                 | Copy?                | Workers          | Notes                                            |
-| -------------------- | -------------------- | ---------------- | ------------------------------------------------ |
-| `ArrayBuffer`        | copied               | thread + process | The default body; works everywhere.              |
-| `SharedArrayBuffer`  | zero-copy, shared    | thread only      | Shared by reference; process workers reject it.  |
-| `ProcessSharedBuffer`| zero-copy, shared    | thread + process | Cross-process shared memory.                     |
-| `BufferReference`    | zero-copy, moved     | thread only      | From `knitting/unsafe`; same constraints as bare `BufferReference`. |
+| Body                  | Copy?             | Workers          | Notes                                                               |
+| --------------------- | ----------------- | ---------------- | ------------------------------------------------------------------- |
+| `ArrayBuffer`         | copied            | thread + process | The default body; works everywhere.                                 |
+| `SharedArrayBuffer`   | zero-copy, shared | thread only      | Shared by reference; process workers reject it.                     |
+| `ProcessSharedBuffer` | zero-copy, shared | thread + process | Cross-process shared memory.                                        |
+| `BufferReference`     | zero-copy, moved  | thread only      | From `knitting/unsafe`; same constraints as bare `BufferReference`. |
 
 The header keeps its fast paths regardless of the body: a small header is
 written inline, and only large headers spill to the dynamic payload region. A
@@ -840,6 +1098,24 @@ worker. It is the same-process counterpart to `ProcessSharedBuffer`: reach for
 it when you hold a large `ArrayBuffer` or typed array and the copy cost to a
 thread worker actually matters.
 
+The ownership and revocation paths are hardened against ordinary
+use-after-free: sources are detached on move, aliases are detached before a
+borrow is released, and outstanding borrowed returns are revoked during pool
+shutdown. This is still an **unsafe capability**, not a memory-safety or
+security boundary. Do not accept `BufferReferenceMetadata` or raw pointer data
+from untrusted code, and do not mutate the same bytes concurrently without
+your own synchronization.
+
+| Path | Node 22/24 owning addon | Node 26 FFI | Deno/Bun FFI |
+| --- | --- | --- | --- |
+| Forward input | Moved, zero-copy | Moved, zero-copy alias | Moved, zero-copy alias |
+| Default returned reference | Co-owned, zero-copy | One safe copy | One safe copy |
+| `BufferReferenceReturn: "borrow"` | Revocable borrow | Revocable borrow | Revocable borrow |
+| Worker shutdown | Outstanding borrows revoked | Copy while readable, then revoke | Copy while readable, then revoke |
+
+Older Node addons without the owning primitives use the non-owning fallback and
+therefore follow the copy/borrow rules rather than the owning-addon row.
+
 ```ts
 import { createPool, isMain, task } from "knitting";
 import { BufferReference } from "knitting/unsafe";
@@ -874,33 +1150,36 @@ Read these constraints before reaching for it:
 - **Move semantics.** Constructing a `BufferReference` detaches its source — the
   original buffer is empty afterward, and reads/writes through it are gone. The
   bytes now belong to the reference; to get a result back, the worker returns
-  its own `BufferReference`. Each handle is one-shot. Forward inputs the worker
+  its own `BufferReference`. Each source ownership transfer is one-shot, but an
+  active reference may be read more than once. Forward inputs the worker
   materializes with `.toArrayBuffer()`/`.toUint8Array()` are borrowed for the
   duration of the call and detached once it settles; do not keep using them from
   fire-and-forget work after the task returns.
-- **Forward is zero-copy everywhere; the return is zero-copy on Node.** Sending
-  a buffer to the worker never copies. On Node the returned buffer is also
-  handed back with no copy (the engine co-owns the backing store across
-  threads); on Deno and Bun the host takes a single copy of the returned bytes,
-  because their FFI cannot co-own a worker-thread backing store. Both are far
-  cheaper than serializing a large buffer through the transport.
-- **Borrowed Deno/Bun returns are opt-in.** The default is
+- **Forward is zero-copy everywhere.** Sending a buffer to the worker never
+  copies. Node 22 and 24 with the owning addon also return the buffer without
+  copying because the addon co-owns the V8 backing store. Node 26, Deno, and Bun
+  take one safe copy on return because their FFI aliases cannot own the worker's
+  backing store.
+- **Borrowed FFI returns are opt-in.** The default on Node 26, Deno, and Bun is
   `unsafe: { BufferReferenceReturn: "copy" }` — the safe single copy described
-  above. Set it to `"borrow"` on `createPool` to skip that copy on Deno/Bun by
-  borrowing the worker's backing store until the returned `BufferReference` is
-  released. Call `ref.release()` or use `using`, and do it before shutting down
-  the producing worker. **After `release()` the borrowed bytes are gone —
-  reading the reference, or any view you took from it, is a use-after-free.**
-  If the bytes escape into HTTP responses, streams, timers, callbacks, or caches,
-  copy them before the borrowed reference is released.
+  above. Set it to `"borrow"` to skip that copy by borrowing the worker's
+  backing store until the returned `BufferReference` is released. Call
+  `ref.release()` or use `using`. Releasing **revokes** the borrow: the
+  reference and every view taken from it are detached first, so later reads see
+  empty views or throw instead of touching freed memory. A reference that is
+  never released drops its borrow only once it and all of its views are
+  unreachable. Pool shutdown revokes outstanding borrows too — references you
+  still hold survive on a private copy, while stale views read as empty. If the
+  bytes escape into HTTP responses, streams, timers, callbacks, or caches, copy
+  them before the borrowed reference is released, or they will read as empty
+  afterward.
 - **Unsafe escape hatch.** This is not a security boundary. Forged metadata or
   unsynchronized host/worker mutation can still be unsafe.
-- **Node uses a native addon.** Bun and Deno go through their FFI; Node uses the
-  `knitting_buffer_pointer` prebuild shipped with the package (or
-  `bun run build:native` when developing on a new ABI). Without it, constructing
-  a `BufferReference` on Node throws.
+- **Node backend depends on the Node line.** Node 22 and 24 use the
+  `knitting_buffer_pointer` addon. Node 26 uses `node:ffi` and therefore needs
+  `--experimental-ffi`.
 
-Borrowed returns, end to end (Node is always zero-copy; this opts Deno/Bun in):
+Borrowed returns, end to end (this opts Node 26, Deno, and Bun in):
 
 ```ts
 using pool = createPool({
@@ -914,7 +1193,7 @@ using pool = createPool({
   using result = await pool.call.invert(new BufferReference(pixels));
   const out = result.toUint8Array(); // borrowed — valid only while `result` lives
   console.log([...out]);
-} // `using` releases the borrow here; do not read `out` after this point
+} // `using` releases the borrow here; `out` is detached and reads as empty now
 ```
 
 When in doubt, a plain `ArrayBuffer` or typed-array payload — which knitting
@@ -927,10 +1206,32 @@ pointer setup tends to cost more than just copying, so the plain transport wins.
 
 Knitting supports Node.js 22+, Deno 2+, and Bun 1+ on Linux, macOS, and Windows.
 
-Thread workers work without native pieces. Process workers and
-`ProcessSharedBuffer` use the platform's shared-memory APIs. Release packages
-include the native prebuilds needed for the supported Node targets and Windows
-FFI path; if you are developing locally on a new Node ABI or architecture, run:
+Plain Node thread workers work without native pieces. Node process workers,
+`ProcessSharedBuffer`, and `BufferReference` use native support. Release
+packages currently include Node prebuilds for:
+
+- Node.js 22 (ABI 127) and Node.js 24 (ABI 137)
+- Linux x64
+- macOS x64 and arm64
+- Windows x64
+
+Odd-numbered Node releases are not supported by packaged native features.
+Node.js 26 uses `node:ffi` instead of another ABI-specific addon. Start the host
+with:
+
+```bash
+node --experimental-ffi app.js
+```
+
+When using Node's Permission Model, also grant `--allow-ffi`. Knitting passes
+the experimental FFI flag to Node process workers it starts, but the host must
+be started with the flag so it can create the shared mappings. The FFI backend
+uses external `ArrayBuffer` mappings, so `ProcessSharedBuffer.view()`,
+`.getBuffer()`, and `.bytes()` work; `.getSAB()` is available only on the Node
+22/24 addon backend.
+
+If you are developing locally on another Node ABI or architecture, you can
+compile the current V8 addon for that exact runtime:
 
 ```bash
 bun run build:native

package/knitting.browser.d.ts

@@ -0,0 +1,6 @@
+import { workerMainLoop } from "./src/worker/loop.ts";
+import { createPool, importTask, isMain, setModuleUrl, task } from "./src/api.ts";
+import { Envelope } from "./src/common/envelope.ts";
+import { isNumericArray, NumericArray } from "./src/connections/numeric-array.ts";
+export { createPool as createPool, Envelope as Envelope, importTask as importTask, isMain as isMain, isNumericArray as isNumericArray, NumericArray as NumericArray, setModuleUrl as setModuleUrl, task as task, workerMainLoop as workerMainLoop, };
+export type { EnvelopeBody as EnvelopeBody, EnvelopeHeader as EnvelopeHeader, } from "./src/common/envelope.ts";