@byokit/pair 0.9.0 → 0.10.1

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 0.10.1 (2026-10-16)
+
+- FIX: the browser pairing test opens the pairing page over the test browser's own private CDP pipe once Chromium answers there, not from the launch command line. On a slow first start Chromium's network service quits after 15 s unanswered and took the launch page's request with it, so the test silently sat out its 180 s deadline; the page now loads after Chromium restarts the service, and a page Chromium cannot open fails at once with Chromium's own navigation error.
+- FIX: pairing and setup checks split "can't reach the computer" from "the computer is slow": a socket that never opens within the timeout reports `unreachable` ("Check the phone and computer are on the same network, and that no firewall is blocking the connection."), while an open socket with no answer reports the new `slow` code ("Your computer is slow to answer. Wait a moment and try again."). Consumers relay the codes unchanged.
+
+## 0.10.0 (2026-10-12)
+
+- DOCS: the "Checking reachability before pairing" section now shows both sides: setup self-checks its own advertised URLs with `check()` before printing the tick, and the phone re-checks the scanned offer before consent. The probe still spends nothing, so a checked offer pairs afterwards.
+- ADD: `ndjson(stream)` sends and receives whole JSON messages over a pair stream, one per `\n`-terminated line, through the existing credit window. Chunks split at any byte boundary reassemble before decoding, a line past `NDJSON_MAX_LINE` (1 MiB, configurable per stream) ends the stream with `line-too-long` on both ends, and a non-JSON line ends it with `failed`.
+- FIX: every wait in the link end-to-end suite is bounded: each test carries a one-minute deadline, so a request stalled past its reconnect window (twice it parked the whole full-suite run at 0% CPU until killed) fails by its test name instead of hanging every lane and release behind the shared test lock. The file still passes in about 10 s alone; nothing about the protocol changed.
+
 ## 0.9.0 (2026-10-09)
 
 - FIX: a phone killed while the person at the computer decides now resumes against the pinned computer, for compact and version 1 QRs alike. `pairWithOffer` takes `onPending(grant)`, which hands over the pending grant to keep before the computer can approve this device, and `pendingGrant` accepts a compact QR given the authenticated `host` key, and `parseOffer` reads a compact QR for inspection (expiry, addresses, name, role) without one. Before, `pendingGrant` refused compact QRs, and even a version 1 pending grant never came online after a real kill. A socket that drops once the computer has taken the code now ends pairing with `unreachable` instead of trying the next address, where the spent code or ticket could only be refused as `wrong-code` or `expired`. A socket that closes while `onPending` is still saving ends pairing at once with that close; a version 1 `onPending` that never settles times out. The compact QR is unchanged: 109 characters for one relay address and the name Umer.

package/README.md

@@ -1,7 +1,7 @@
-<h1 align="center">@byokit/link</h1>
+<h1 align="center">@byokit/pair</h1>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/@byokit/link"><img alt="npm" src="https://img.shields.io/npm/v/@byokit/link?style=flat&label=npm" /></a>
+  <a href="https://www.npmjs.com/package/@byokit/pair"><img alt="npm" src="https://img.shields.io/npm/v/@byokit/pair?style=flat&label=npm" /></a>
   <a href="https://github.com/umeranjum17/byokit/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/umeranjum17/byokit/ci.yml?style=flat&branch=main" /></a>
   <a href="LICENSE"><img alt="Apache 2.0" src="https://img.shields.io/badge/license-Apache--2.0-666?style=flat" /></a>
   <img alt="Node | browsers | React Native" src="https://img.shields.io/badge/platform-Node%20%7C%20browsers%20%7C%20React%20Native-666?style=flat" />
@@ -12,8 +12,11 @@ One encrypted link between the two. The computer (the <strong>host</strong>) kee
 only its own key and a grant, and asks the host to do things. For apps that reach a person's own computer from their
 phone or browser.</p>
 
+This package was published as `@byokit/link` up to 0.8.x. `@byokit/link` still re-exports it unchanged through
+0.8.x and is removed in 0.9.0; new installs use `@byokit/pair`.
+
 <p align="center">
-  <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/docs/images/herdr-kit-host.png" width="420" alt="A terminal running npm start -- --herdr &quot;$(command -v herdr)&quot; --via lan --name 'Kitchen computer', showing a large pairing QR code, then: On the phone, scan this. If its page is already open there, type K3J8-CJZ7-SE4R instead. Codes last five minutes. Press Enter for new ones. Connecting to Herdr… Connected to Herdr. (stand-in Herdr)" />
+  <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/docs/images/herdr-kit-host.png" width="420" alt="A terminal running npm start -- --herdr &quot;$(command -v herdr)&quot; --via lan --name 'Kitchen computer', showing a large pairing QR code, then: On the phone, scan this, or open http://192.168.1.144:7310/ and type K3J8-CJZ7-SE4R. Codes last five minutes. Press Enter for new ones. Connecting to Herdr… Connected to Herdr. (stand-in Herdr)" />
   <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/examples/herdr-kit/docs/2-compare.png" width="240" alt="A phone page titled Agents, under Pair this phone: Check your computer shows these two words, then say yes there. The words are coast comet." />
 </p>
 <p align="center"><sub>Left: the host terminal of <a href="https://github.com/umeranjum17/byokit/tree/main/examples/herdr-kit">examples/herdr-kit</a> (<code>npm start -- --herdr "$(command -v herdr)" --via lan --name 'Kitchen computer'</code>, pictured against the kit's stand-in Herdr, <code>BYOKIT_EXAMPLE_FAKE=1</code>) showing the QR and the typed code. Right: the phone in the same example showing the two words to compare.</sub></p>
@@ -27,26 +30,26 @@ Host policy and streams are available; relay routing is in [`@byokit/relay`](../
 ## Install
 
 ```sh
-npm install @byokit/link
+npm install @byokit/pair
 ```
 
-[![npm](https://img.shields.io/npm/v/@byokit/link?style=flat&label=)](https://www.npmjs.com/package/@byokit/link) · [Latest release](https://github.com/umeranjum17/byokit/releases?q=link-v) · [All releases](https://github.com/umeranjum17/byokit/releases)
+[![npm](https://img.shields.io/npm/v/@byokit/pair?style=flat&label=)](https://www.npmjs.com/package/@byokit/pair) · [Latest release](https://github.com/umeranjum17/byokit/releases?q=pair-v) · [All releases](https://github.com/umeranjum17/byokit/releases)
 
 ## Quickstart
 
 ```sh
-npm install @byokit/link ws
+npm install @byokit/pair ws
 ```
 
 `ws` is only the WebSocket server for this example; any server works. A host and a device in one file, on loopback:
 
 ```ts
 import { WebSocketServer } from 'ws';
-import { DeviceLink, Host, keyPair, pairWithOffer } from '@byokit/link';
+import { DeviceLink, Host, keyPair, pairWithOffer } from '@byokit/pair';
 
 // The computer: it keeps the credentials and answers requests.
 const host = await Host.open({
-  keys: keyPair(),                       // keep it with hostKeyFile() from '@byokit/link/node' in a real app
+  keys: keyPair(),                       // keep it with hostKeyFile() from '@byokit/pair/node' in a real app
   name: 'Kitchen computer',
   confirm: ({ name, words }) => { console.log(`host: pair ${name}? it shows "${words}"`); return true; },
   handle: (req, device) => ({ echo: req.args, from: device.name }),
@@ -89,13 +92,13 @@ answer: { echo: { text: 'hi' }, from: 'Pixel 9' }
 | `LinkError`, `PublicLinkError`, `LINK_WORDS` | Failures with a plain `message` and a `code`; a handler error safe to show; the plain message for each failure code |
 | `secureDeviceStore`, `browserDeviceStore` | Where a device keeps its grant on a phone or in a browser |
 | `keyPair`, `keyPairFrom`, `hostId`, `b64url`, `unb64url`, `normalizeCode` | Keys, the host id, base64url and typed-code helpers |
-| `hostKeyFile`, `fileDeviceStore` (`@byokit/link/node`) | Node only: the host's key file, and a computer's device store |
+| `hostKeyFile`, `fileDeviceStore` (`@byokit/pair/node`) | Node only: the host's key file, and a computer's device store |
 
 ## Host
 
 ```ts
-import { Host } from '@byokit/link';
-import { hostKeyFile } from '@byokit/link/node';
+import { Host } from '@byokit/pair';
+import { hostKeyFile } from '@byokit/pair/node';
 
 const host = await Host.open({
   keys: hostKeyFile('./link-secret/host.key'), // made once in its own 0700 folder; or use your keychain
@@ -112,7 +115,7 @@ const { code } = host.code({ role: 'view' });     // or a code to type: "7KQ4-M2
 host.devices(); await host.revoke(id); host.broadcast(event);
 ```
 
-`hostKeyFile(path)` from `@byokit/link/node` wants a path in its own private (`0700`) folder; it refuses an
+`hostKeyFile(path)` from `@byokit/pair/node` wants a path in its own private (`0700`) folder; it refuses an
 existing folder with another mode rather than changing its permissions.
 
 More host policy, all optional:
@@ -127,6 +130,9 @@ More host policy, all optional:
   handlers with transactional effects can store it alongside the effect to avoid repeating work after a crash between
   the handler and `answers.put`.
 - `handshakes: { perMinute, perPeer }` limits new handshakes; pass `host.accept(ws, { peer: ip })` to count per source.
+- `onGrantRemoved(grant, why)` runs at the one boundary where a grant is durably gone — `revoked`, `expired` or
+  `changed` — so an app can delete its copy. Access is already withdrawn when it runs, a socket drop does not
+  trigger it, and a failing cleanup never restores access.
 
 `compactOffer` is the QR text: the same secret a typed code carries (same single use, life, words and
 approval) plus the addresses to try, packed binary, so a standard offer fits a QR version 4 or lower.
@@ -186,7 +192,7 @@ old connections, and changed expiry reschedules access. A failed load rejects an
 A `GrantStore` may provide `subscribe(changed): unsubscribe`; the host reloads automatically on notification,
 reports reload failures through `onError`, and unsubscribes on `close()`.
 
-Node apps can use `fileGrantStore(path)` from `@byokit/link/node`. It touches the app's chosen file, temporary
+Node apps can use `fileGrantStore(path)` from `@byokit/pair/node`. It touches the app's chosen file, temporary
 files and a sibling `.lock` only, writes atomically at 0600 in a 0700 folder, rejects symlinks/nonprivate files on read, and polls
 for cross-process replace/remove (default 100 ms; second argument changes the interval). Cooperating writers
 use an exclusive lock and reject a stale loaded snapshot instead of overwriting an external revoke. Load again
@@ -207,7 +213,7 @@ The **handle** step authorizes the already-paired inviter, **offer** records the
 then **confirm** checks that metadata before approving the new peer:
 
 ```ts
-import { Host, keyPair, PublicLinkError } from '@byokit/link';
+import { Host, keyPair, PublicLinkError } from '@byokit/pair';
 
 // Supply the app's human approval UI.
 declare const ui: { ask(message: string): Promise<boolean> };
@@ -235,7 +241,7 @@ const host: Host = await Host.open({
 });
 ```
 
-Import `Host`, `keyPair` and `PublicLinkError` from `@byokit/link`; `ui.ask` is the app's approval UI. The app
+Import `Host`, `keyPair` and `PublicLinkError` from `@byokit/pair`; `ui.ask` is the app's approval UI. The app
 chooses metadata on the host, never from an untrusted invitee. This composition is delegated pairing:
 the approved control device requests a constrained invitation; a peer cannot widen its terms. Check the
 inviter's current grant, including expiry, in both `handle` and `confirm`. Apply capability scope in `allow`
@@ -247,7 +253,7 @@ long-lived or host-offline signed invitation.
 ## Device
 
 To keep several paired computers, use `secureDeviceStores(secureStore, prefix?)` or
-`browserDeviceStores(databaseName?)` from `@byokit/link`. Both offer `list()` (entry names), `load(name)`,
+`browserDeviceStores(databaseName?)` from `@byokit/pair`. Both offer `list()` (entry names), `load(name)`,
 `save(name, grant)`, `remove(name)`, and `store(name)` (the one-entry adapter for `DeviceLink`). Names use
 letters, digits, dots, underscores and dashes, up to 120 characters. A secure collection uses
 `<prefix>.index` and `<prefix>.grant.<name>`; existing single-entry stores stay independent. Calls sharing
@@ -257,7 +263,7 @@ The browser collection enumerates existing `browserDeviceStore` entries in its d
 non-extractable wrapping keys and forgotten-grant protection; removed tombstones stay out of `list()`.
 
 ```ts
-import { DeviceLink, secureDeviceStores, type DeviceGrant, type SecureStoreLike } from '@byokit/link';
+import { DeviceLink, secureDeviceStores, type DeviceGrant, type SecureStoreLike } from '@byokit/pair';
 
 // Supply the platform secure-storage module and a grant returned by pairing.
 declare const SecureStore: SecureStoreLike;
@@ -271,7 +277,7 @@ await computers.remove('kitchen');
 ```
 
 ```ts
-import { DeviceLink, pairWithOffer, pairWithCode } from '@byokit/link';
+import { DeviceLink, pairWithOffer, pairWithCode } from '@byokit/pair';
 
 const grant = await pairWithOffer(scanned, { name: 'Pixel 9', onWords: (w) => show(w) });
 // Or pairWithCode(url, typed, { name: 'Pixel 9', onWords: (w) => show(w) });
@@ -317,7 +323,7 @@ One store per paired computer, each with `load()` for the next start:
 |---|---|---|
 | Phone | `secureDeviceStore(SecureStore, 'byokit.link.home')` with `expo-secure-store` | Keychain on iOS, Keystore on Android; the grant is about 300 bytes, one value. |
 | Browser or PWA | `browserDeviceStore('home')` | IndexedDB, sealed with AES-GCM by a non-extractable browser key. The stored record alone opens nothing, but scripts running on the same origin can still use the key to decrypt it; keep untrusted scripts off the page. |
-| Computer (Node, Electron's main process) | `fileDeviceStore(path, safeStorage?)` from `@byokit/link/node` | A 0600 file in a newly created 0700 folder (an existing folder keeps its permissions), sealed with Electron's `safeStorage` when given. Without `safeStorage`, the file contains the grant in plaintext. |
+| Computer (Node, Electron's main process) | `fileDeviceStore(path, safeStorage?)` from `@byokit/pair/node` | A 0600 file in a newly created 0700 folder (an existing folder keeps its permissions), sealed with Electron's `safeStorage` when given. Without `safeStorage`, the file contains the grant in plaintext. |
 
 ```ts
 const store = secureDeviceStore(SecureStore, 'byokit.link.home');
@@ -329,7 +335,7 @@ const link = new DeviceLink(grant, { store, onStatus });
 ### React Native
 
 Install a `crypto.getRandomValues` polyfill such as `react-native-get-random-values` (or use `expo-crypto`) and
-import it **before** `@byokit/link`. Metro resolves `sodium-universal` to `sodium-javascript` through its browser
+import it **before** `@byokit/pair`. Metro resolves `sodium-universal` to `sodium-javascript` through its browser
 field. The device uses the platform's WebSocket and needs no Node globals. See [`examples/expo`](../../examples/expo).
 
 ## Streams
@@ -357,6 +363,13 @@ s.end();
 View-only devices open only the streams `allow` permits (or `canView` when `allow` is absent). A host without `stream`
 tells devices so (`LinkError` `not-supported`), and so does a host older than streams.
 
+For whole JSON messages instead of bytes, `ndjson(stream)` sends one object per `\n`-terminated line and delivers
+each complete message in order: `const j = ndjson(s); await j.send({ text: 'hi' }); j.onMessage((m) => …)`.
+Messages split at any byte boundary arrive whole, including a multi-byte character split across two chunks, and a
+returned handler promise holds the sender back through the same credit window. A line past `NDJSON_MAX_LINE`
+(1 MiB, `ndjson(s, { maxLine })` changes it) ends the stream with `'line-too-long'` on both ends and is never
+delivered, so nothing is buffered without bound; a line that is not JSON ends it with `failed`.
+
 On a direct socket, stream bytes go as binary WebSocket messages (without base64 overhead); through a relay, whose
 host wrapper is text, the same frames go as base64 text. The host says which in `ready`; everything else stays text.
 
@@ -376,7 +389,7 @@ Frames are the same bytes on every path; a relay only routes them and cannot rea
 - The relay authenticates the host's socket and limits abuse its own way. Link routing needs no device id: the host
   checks devices itself on every handshake.
 
-`@byokit/link` does not include a relay server; use [`@byokit/relay`](../relay) for the standalone server,
+`@byokit/pair` does not include a relay server; use [`@byokit/relay`](../relay) for the standalone server,
 reconnecting host client and device code lookup.
 
 ## Migrating pre-kit phone pairings
@@ -415,10 +428,10 @@ share one key across machines. Muxr parity beyond this migration is tracked sepa
 ## Checking reachability before pairing
 
 ```ts
-import { check, parseOffer } from '@byokit/link';
+import { check, parseOffer } from '@byokit/pair';
 
-// Before asking the person to approve, the phone probes the offer's URLs (the host probes its own advertised
-// URLs the same way, as a self-check only). Results come back in input order.
+// Phone: before asking the person to approve, probe the scanned offer's URLs.
+// Results come back in input order.
 export async function precheck(scanned: string): Promise<void> {
   const { urls } = parseOffer(scanned);
   const results = await check(urls, { timeoutMs: 5000 });
@@ -428,6 +441,22 @@ export async function precheck(scanned: string): Promise<void> {
 }
 ```
 
+Setup runs the same probe on its own advertised URLs before printing the tick, so a dead
+address never becomes a QR. The phone runs it again after scanning, before consent:
+
+```ts
+import { check } from '@byokit/pair';
+
+// Setup: self-check the offer's URLs first; only print the tick when one answers.
+export async function selfcheck(urls: string[]): Promise<boolean> {
+  const results = await check(urls, { timeoutMs: 5000 });
+  for (const r of results) {
+    if (!r.ok) console.log(`${r.url}: ${r.message}`);
+  }
+  return results.some((r) => r.ok);
+}
+```
+
 Probed four at a time by default (`concurrency` changes that). The probe answers read-only: it sends no ticket,
 so a checked offer still pairs afterwards, and the reply carries nothing but the fact a link host is there. It
 works in Node, browsers and React Native, and through a relay with no relay change (devices speak bare frames
@@ -479,13 +508,13 @@ untrusted address, never a trusted machine key. A malicious lookup pointing at a
 fails the commitment check. QR offers and legacy `host.code()` remain compatible; callers of
 the latter do not get this additional machine-key pinning.
 
-Runnable loopback example (Node 22.18+, `npm install @byokit/link ws`; save as `pair.ts`, run
+Runnable loopback example (Node 22.18+, `npm install @byokit/pair ws`; save as `pair.ts`, run
 `node pair.ts`). In an app, show the code on the computer and let the phone type it:
 
 ```ts
 import { createInterface } from 'node:readline/promises';
 import { WebSocketServer } from 'ws';
-import { DeviceLink, Host, keyPair, pairWithCode } from '@byokit/link';
+import { DeviceLink, Host, keyPair, pairWithCode } from '@byokit/pair';
 
 const terminal = createInterface({ input: process.stdin, output: process.stdout });
 const host = await Host.open({

package/SECURITY.md

@@ -1,4 +1,4 @@
-# @byokit/link: threat model and review checklist
+# @byokit/pair: threat model and review checklist
 
 Muxr parity is tracked separately.
 
@@ -132,7 +132,7 @@ A home computer (the **host**) holds AI sign-ins and other credentials. Phones,
       authenticates with it.
 - [x] The handshake limiter runs before any Diffie-Hellman.
 - [x] Nothing in the main entry reads or writes files, environment variables or other programs.
-      `@byokit/link/node` `hostKeyFile(path)` touches only that path: 0600 in 0700, atomic, never replaces a file it
+      `@byokit/pair/node` `hostKeyFile(path)` touches only that path: 0600 in 0700, atomic, never replaces a file it
       can't read, refuses symlinks.
 
 - [ ] Presence fires once on first/last sockets, including failed/successful unpair, reload, expiry and close.

package/dist/channel.js

@@ -14,7 +14,7 @@ import Noise from 'noise-handshake';
 import { chacha20poly1305 } from '@noble/ciphers/chacha.js';
 import dh from 'noise-handshake/dh.js';
 import sodium from 'sodium-universal';
-import { CONFIRM_WORDS } from "./confirm-words.js";
+import { CONFIRM_WORDS } from './confirm-words.js';
 /** Mixed into every handshake, so a v2 of this protocol can never be confused with v1. */
 export const PROLOGUE = 'byokit-link-v1';
 const CHUNK = 60_000; // a Noise message is at most 65535 bytes; larger payloads go in pieces

package/dist/check.d.ts

@@ -28,7 +28,7 @@ export type CheckOptions = {
         onerror: unknown;
     };
 };
-/** Probe each URL for a link host, in input order. Only `unreachable` (nothing there), `timeout` (something there
- *  that never answered) and `wrong-host` (something else answered) can come back, each with its LINK_WORDS sentence;
- *  no new codes were needed. Never sends a ticket, so offers stay usable. */
+/** Probe each URL for a link host, in input order. Only `unreachable` (nothing there: same network or firewall),
+ *  `slow` (something there that never answered: wait and try again) and `wrong-host` (something else answered) can
+ *  come back, each with its LINK_WORDS sentence. Never sends a ticket, so offers stay usable. */
 export declare function check(urls: string[], o?: CheckOptions): Promise<CheckResult[]>;

package/dist/check.js

@@ -1,7 +1,7 @@
 // A per-URL reachability probe for onboarding: before pairing, the phone checks the offer's URLs (and the host
 // checks its own advertised URL) without claiming or burning the one-time offer. No platform APIs: the same code
 // runs in Node, browsers and React Native on the platform WebSocket, like `dial` in device.ts.
-import { LINK_WORDS } from "./device.js";
+import { LINK_WORDS } from './device.js';
 /** The first frame a probe sends. The host answers with LINK_PROBE_OK and closes; it touches no ticket, code,
 // grant or counter, so a checked offer still pairs afterwards. Relayed devices speak bare frames, so the same
 // exchange works through a relay with no relay change. */
@@ -24,7 +24,7 @@ function probe(url, o, timeoutMs) {
             catch { }
             resolve(r);
         };
-        const timer = setTimeout(() => finish(fail(url, opened ? 'timeout' : 'unreachable')), timeoutMs);
+        const timer = setTimeout(() => finish(fail(url, opened ? 'slow' : 'unreachable')), timeoutMs);
         timer.unref?.();
         try {
             const WS = o.WebSocket ?? globalThis.WebSocket;
@@ -55,9 +55,9 @@ function probe(url, o, timeoutMs) {
         };
     });
 }
-/** Probe each URL for a link host, in input order. Only `unreachable` (nothing there), `timeout` (something there
- *  that never answered) and `wrong-host` (something else answered) can come back, each with its LINK_WORDS sentence;
- *  no new codes were needed. Never sends a ticket, so offers stay usable. */
+/** Probe each URL for a link host, in input order. Only `unreachable` (nothing there: same network or firewall),
+ *  `slow` (something there that never answered: wait and try again) and `wrong-host` (something else answered) can
+ *  come back, each with its LINK_WORDS sentence. Never sends a ticket, so offers stay usable. */
 export async function check(urls, o = {}) {
     const timeoutMs = o.timeoutMs ?? 8000;
     const out = new Array(urls.length);

package/dist/device.d.ts

@@ -41,24 +41,25 @@ export type Dial = {
 };
 /** Every way the link can fail, in words a person can act on. */
 export declare const LINK_WORDS: {
-    readonly unreachable: "Can't reach your computer. Check it's on and connected.";
+    readonly unreachable: "Can't reach your computer. Check the phone and computer are on the same network, and that no firewall is blocking the connection.";
     readonly 'wrong-host': "Something other than your computer answered, so this device didn't connect.";
     readonly 'wrong-code': "That code didn't match. Check it, or show a new one on your computer.";
-    readonly expired: "That pairing code has run out. Show a new one on your computer.";
-    readonly declined: "Your computer said no to this device.";
-    readonly full: "Your computer has all the devices it allows. Remove one there first.";
+    readonly expired: 'That pairing code has run out. Show a new one on your computer.';
+    readonly declined: 'Your computer said no to this device.';
+    readonly full: 'Your computer has all the devices it allows. Remove one there first.';
     readonly 'not-paired': "Your computer doesn't know this device any more. Pair it again.";
-    readonly removed: "This device was removed on your computer.";
-    readonly 'view-only': "This device can watch but not make changes.";
+    readonly removed: 'This device was removed on your computer.';
+    readonly 'view-only': 'This device can watch but not make changes.';
     readonly timeout: "Your computer didn't answer in time.";
+    readonly slow: 'Your computer is slow to answer. Wait a moment and try again.';
     readonly failed: "Your computer couldn't do that.";
-    readonly busy: "Your computer is still catching up. Try again in a moment.";
-    readonly stopped: "This link is stopped. Try connecting again.";
+    readonly busy: 'Your computer is still catching up. Try again in a moment.';
+    readonly stopped: 'This link is stopped. Try connecting again.';
     readonly 'not-supported': "The app on your computer can't do this yet. Update it there.";
     readonly ended: "This device's access has run out. Pair it again on your computer.";
     readonly 'not-allowed': "This device isn't allowed to do that.";
     readonly 'too-late': "That reached your computer too late, so it wasn't done.";
-    readonly unsupported: "Your computer needs an update for that.";
+    readonly unsupported: 'Your computer needs an update for that.';
 };
 export type LinkProblem = keyof typeof LINK_WORDS;
 /** A failure with a plain `message` and a `code` for the app. `sealed` means the host said it inside the encrypted

package/dist/device.js

@@ -2,12 +2,12 @@
 // the host's credentials. It pairs once (scan or typed code), then keeps one socket open, reconnecting on its own, and
 // its requests survive a reconnect: each carries a key, so a retried tap runs once. Uses only the platform's
 // WebSocket, so the same code runs in browsers, React Native and Node.
-import { Handshake, b64, b64url, keyPair, keyPairFrom, random, unb64url } from "./channel.js";
-import { cleanName, codeKey, decodeCompactOffer, parseCode, parseOffer, parseV1Offer, shortKey, COMPACT_TAG } from "./pairing.js";
-import { Streams } from "./stream.js";
+import { Handshake, b64, b64url, keyPair, keyPairFrom, random, unb64url } from './channel.js';
+import { cleanName, codeKey, decodeCompactOffer, parseCode, parseOffer, parseV1Offer, shortKey, COMPACT_TAG } from './pairing.js';
+import { Streams } from './stream.js';
 /** Every way the link can fail, in words a person can act on. */
 export const LINK_WORDS = {
-    unreachable: "Can't reach your computer. Check it's on and connected.",
+    unreachable: "Can't reach your computer. Check the phone and computer are on the same network, and that no firewall is blocking the connection.",
     'wrong-host': "Something other than your computer answered, so this device didn't connect.",
     'wrong-code': "That code didn't match. Check it, or show a new one on your computer.",
     expired: 'That pairing code has run out. Show a new one on your computer.',
@@ -17,6 +17,7 @@ export const LINK_WORDS = {
     removed: 'This device was removed on your computer.',
     'view-only': 'This device can watch but not make changes.',
     timeout: "Your computer didn't answer in time.",
+    slow: 'Your computer is slow to answer. Wait a moment and try again.',
     failed: "Your computer couldn't do that.",
     busy: 'Your computer is still catching up. Try again in a moment.',
     stopped: 'This link is stopped. Try connecting again.',
@@ -79,7 +80,8 @@ async function dial(url, me, host, hello, o, on = { message: () => { }, close: (
             }
             catch { }
         };
-        let timer = later(o.timeoutMs ?? 8000, () => fail(new LinkError('timeout')));
+        let opened = false;
+        let timer = later(o.timeoutMs ?? 8000, () => fail(new LinkError(opened ? 'slow' : 'unreachable')));
         try {
             ws = new WS(target);
             ws.binaryType = 'arraybuffer';
@@ -92,7 +94,12 @@ async function dial(url, me, host, hello, o, on = { message: () => { }, close: (
             ws.send(f); };
         const data = (s, d) => { for (const f of ch.sealData(s, d))
             ws.send(binary ? f : b64(f)); };
-        ws.onopen = () => ws.send(hs.write(mode === 'ik' ? { v: 1 } : {}));
+        ws.onopen = () => { opened = true; try {
+            ws.send(hs.write(mode === 'ik' ? { v: 1 } : {}));
+        }
+        catch {
+            fail(new LinkError('unreachable'));
+        } };
         ws.onerror = () => fail(new LinkError('unreachable'));
         // Before the handshake finishes nothing is authenticated, so these only choose what to say, never what to forget.
         ws.onclose = (e) => fail(new LinkError(ch ? 'unreachable' : e?.code === 4401 && mode === 'code' ? 'wrong-code' : e?.code === 4403 ? 'wrong-host' : 'unreachable'));
@@ -120,7 +127,7 @@ async function dial(url, me, host, hello, o, on = { message: () => { }, close: (
                         if (pairing) { // now a person at the host decides; give them time
                             o.onWords?.(hs.words);
                             clearTimeout(timer);
-                            timer = later(6 * 60_000, () => fail(new LinkError('timeout')));
+                            timer = later(6 * 60_000, () => fail(new LinkError('slow')));
                         }
                     };
                     if (!host.pin)
@@ -213,7 +220,7 @@ export async function pairWithOffer(scanned, o) {
                 if (!(e instanceof LinkError))
                     throw e; // the app's own onPending failure, as it said it
                 last = e;
-                if (taken || (last.code !== 'unreachable' && last.code !== 'timeout' && last.code !== 'wrong-host'))
+                if (taken || (last.code !== 'unreachable' && last.code !== 'slow' && last.code !== 'timeout' && last.code !== 'wrong-host'))
                     break;
             }
         }
@@ -232,7 +239,7 @@ export async function pairWithOffer(scanned, o) {
         }
         catch (e) {
             last = e instanceof LinkError ? e : new LinkError('unreachable');
-            if (taken || (last.code !== 'unreachable' && last.code !== 'timeout' && last.code !== 'wrong-host'))
+            if (taken || (last.code !== 'unreachable' && last.code !== 'slow' && last.code !== 'timeout' && last.code !== 'wrong-host'))
                 break;
         }
     }

package/dist/host.js

@@ -1,11 +1,11 @@
 // The host: the computer that owns the credentials. It pairs devices (scanned or typed code, then a person says yes),
 // keeps one durable grant per device, answers their requests, and removes them. It never listens on anything itself:
 // the app hands it WebSockets (`accept`), or one relay socket that carries many devices (`relay`).
-import { Handshake, b64, b64url, firstFrame, hostId, messageBytes, random, unb64url } from "./channel.js";
-import { bindCode, cleanName, codeKey, encodeCompactOffer, newCode, normalizeCode, offerText } from "./pairing.js";
-import { PublicLinkError } from "./device.js";
-import { LINK_PROBE, LINK_PROBE_OK } from "./check.js";
-import { MAX_STREAMS, Streams } from "./stream.js";
+import { Handshake, b64, b64url, firstFrame, hostId, messageBytes, random, unb64url } from './channel.js';
+import { bindCode, cleanName, codeKey, encodeCompactOffer, newCode, normalizeCode, offerText } from './pairing.js';
+import { PublicLinkError } from './device.js';
+import { LINK_PROBE, LINK_PROBE_OK } from './check.js';
+import { MAX_STREAMS, Streams } from './stream.js';
 const HANDSHAKE_MS = 15_000;
 const MAX_TRIES = 5; // wrong codes before every open code is withdrawn
 const MAX_ANSWERS = 1000;

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { hostId, keyPair, keyPairFrom, b64url, unb64url, type KeyPair } from './
 export { Host, type AnswerStore, type Grant, type GrantStore, type GrantTerms, type HostOptions, type LinkRequest, type PairRequest, type Role, type Socket, } from './host.ts';
 export { DeviceLink, LINK_WORDS, LinkError, PublicLinkError, pairWithCode, pairWithOffer, pendingGrant, type DeviceGrant, type DeviceStore, type Dial, type LinkOptions, type LinkProblem, type LinkStatus, type RequestOptions, } from './device.ts';
 export { cleanName, decodeCompactOffer, decodeOffer, encodeCompactOffer, encodeOffer, normalizeCode, offerText, parseOffer, parseV1Offer, COMPACT_TAG } from './pairing.ts';
-export { LinkStream, WINDOW } from './stream.ts';
+export { LinkStream, NDJSON_LINE_TOO_LONG, NDJSON_MAX_LINE, WINDOW, ndjson, type NdjsonOptions, type NdjsonStream } from './stream.ts';
 export { check, LINK_PROBE, LINK_PROBE_OK, type CheckOptions, type CheckResult } from './check.ts';
 export type { CompactOffer, PairOffer } from './pairing.ts';
 export { browserDeviceStore, browserDeviceStores, secureDeviceStore, secureDeviceStores, type DeviceStores, type KeptDevice, type SecureStoreLike } from './stores.ts';

package/dist/index.js

@@ -1,8 +1,8 @@
-export { hostId, keyPair, keyPairFrom, b64url, unb64url } from "./channel.js";
-export { Host, } from "./host.js";
-export { DeviceLink, LINK_WORDS, LinkError, PublicLinkError, pairWithCode, pairWithOffer, pendingGrant, } from "./device.js";
-export { cleanName, decodeCompactOffer, decodeOffer, encodeCompactOffer, encodeOffer, normalizeCode, offerText, parseOffer, parseV1Offer, COMPACT_TAG } from "./pairing.js";
-export { LinkStream, WINDOW } from "./stream.js";
-export { check, LINK_PROBE, LINK_PROBE_OK } from "./check.js";
-export { browserDeviceStore, browserDeviceStores, secureDeviceStore, secureDeviceStores } from "./stores.js";
-export { migrateGrant, GrantMigrationError } from "./migrate.js";
+export { hostId, keyPair, keyPairFrom, b64url, unb64url } from './channel.js';
+export { Host, } from './host.js';
+export { DeviceLink, LINK_WORDS, LinkError, PublicLinkError, pairWithCode, pairWithOffer, pendingGrant, } from './device.js';
+export { cleanName, decodeCompactOffer, decodeOffer, encodeCompactOffer, encodeOffer, normalizeCode, offerText, parseOffer, parseV1Offer, COMPACT_TAG } from './pairing.js';
+export { LinkStream, NDJSON_LINE_TOO_LONG, NDJSON_MAX_LINE, WINDOW, ndjson } from './stream.js';
+export { check, LINK_PROBE, LINK_PROBE_OK } from './check.js';
+export { browserDeviceStore, browserDeviceStores, secureDeviceStore, secureDeviceStores } from './stores.js';
+export { migrateGrant, GrantMigrationError } from './migrate.js';

package/dist/migrate.js

@@ -1,4 +1,4 @@
-import { b64, b64url, hash, unb64 } from "./channel.js";
+import { b64, b64url, hash, unb64 } from './channel.js';
 /** A migration failure. Neither the message nor the error retains the input or its keys. */
 export class GrantMigrationError extends Error {
     code;

package/dist/node.js

@@ -1,7 +1,7 @@
 // Node only (`@byokit/pair/node`): host key and device grant files. Kept out of the main entry for browsers and React Native.
 import { closeSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, unlinkSync, unwatchFile, watchFile, writeFileSync, writeSync } from 'node:fs';
 import { dirname } from 'node:path';
-import { b64url, keyPair, keyPairFrom, random, unb64url } from "./channel.js";
+import { b64url, keyPair, keyPairFrom, random, unb64url } from './channel.js';
 /** The host's key pair, kept in `path` (0600, in a 0700 folder, written atomically). The first call makes it.
  *  A file that exists but can't be read as a key is never replaced: a new key would silently cut off every paired
  *  device, so it throws and a person decides. */

package/dist/pairing.js

@@ -1,6 +1,6 @@
 // What pairing puts in front of a person: the QR's text (or a link that carries it), and the typed code.
 import b4a from 'b4a';
-import { b64url, hash, random, unb64url } from "./channel.js";
+import { b64url, hash, random, unb64url } from './channel.js';
 const TAG = 'byokit-link:1:';
 const UNSAFE = /[\u0000-\u001f\u007f\u200e\u200f\u202a-\u202e\u2066-\u2069]/gu; // control and direction-flipping characters
 /** A device or host name as a person should see it: no hidden characters, at most 60 of them. */

package/dist/stream.d.ts

@@ -53,6 +53,29 @@ export declare class LinkStream {
     ended(error?: string): void;
     waitOpened(): Promise<LinkStream>;
 }
+/** The longest one JSON line `ndjson` buffers, in bytes (a line is its UTF-8 bytes up to `\n`). */
+export declare const NDJSON_MAX_LINE: number;
+/** The stream error an `ndjson` reader ends its stream with when a line runs past its cap. Both sides see it. */
+export declare const NDJSON_LINE_TOO_LONG = "line-too-long";
+export type NdjsonOptions = {
+    /** The longest one line buffered before the stream ends with `NDJSON_LINE_TOO_LONG`. Defaults to `NDJSON_MAX_LINE`. */
+    maxLine?: number;
+};
+export type NdjsonStream = {
+    /** The byte stream underneath, for `onEnd`, `end` and anything else not about JSON. */
+    readonly stream: LinkStream;
+    /** Sends one JSON message (`JSON.stringify` plus `\n`) through the stream's credit window. */
+    send(message: unknown): Promise<void>;
+    /** Each whole JSON message, in order. Returning a promise holds the sender back until it settles. */
+    onMessage(fn: (message: unknown) => void | Promise<void>): void;
+    /** Ends the stream both ways: after the sends already made, or at once with an error. */
+    end(error?: string): void;
+};
+/** Whole JSON messages over a byte `LinkStream`, one `\n`-terminated line each. Chunks split at any byte
+ *  boundary reassemble before decoding, so a multi-byte character split across two chunks still arrives whole.
+ *  A line past the cap ends the stream with `NDJSON_LINE_TOO_LONG` and is never delivered, so nothing is buffered
+ *  without bound; a line that is not JSON ends it with `failed` through the stream's usual handler-error path. */
+export declare function ndjson(stream: LinkStream, opts?: NdjsonOptions): NdjsonStream;
 /** One connection's streams. */
 export declare class Streams {
     private all;

package/dist/stream.js

@@ -178,6 +178,79 @@ export class LinkStream {
         return new Promise((resolve, reject) => { this.settle = { resolve, reject: (e) => reject(e) }; });
     }
 }
+/** The longest one JSON line `ndjson` buffers, in bytes (a line is its UTF-8 bytes up to `\n`). */
+export const NDJSON_MAX_LINE = 1024 * 1024;
+/** The stream error an `ndjson` reader ends its stream with when a line runs past its cap. Both sides see it. */
+export const NDJSON_LINE_TOO_LONG = 'line-too-long';
+/** Whole JSON messages over a byte `LinkStream`, one `\n`-terminated line each. Chunks split at any byte
+ *  boundary reassemble before decoding, so a multi-byte character split across two chunks still arrives whole.
+ *  A line past the cap ends the stream with `NDJSON_LINE_TOO_LONG` and is never delivered, so nothing is buffered
+ *  without bound; a line that is not JSON ends it with `failed` through the stream's usual handler-error path. */
+export function ndjson(stream, opts = {}) {
+    const maxLine = opts.maxLine ?? NDJSON_MAX_LINE;
+    if (!Number.isInteger(maxLine) || maxLine < 1)
+        throw new Error('bad ndjson maxLine');
+    const decode = new TextDecoder();
+    let parts = [];
+    let buffered = 0;
+    let failed = false;
+    const untilNewline = () => {
+        let at = 0;
+        for (const p of parts) {
+            const i = p.indexOf(10);
+            if (i !== -1)
+                return at + i;
+            at += p.byteLength;
+        }
+        return -1;
+    };
+    const take = (n) => {
+        const out = new Uint8Array(n);
+        for (let at = 0; at < n;) {
+            const p = parts[0];
+            const k = Math.min(p.byteLength, n - at);
+            out.set(p.subarray(0, k), at);
+            at += k;
+            parts = k === p.byteLength ? parts.slice(1) : [p.subarray(k), ...parts.slice(1)];
+        }
+        return out;
+    };
+    return {
+        stream,
+        send(message) {
+            const line = JSON.stringify(message);
+            if (line === undefined)
+                throw new Error('ndjson cannot send undefined');
+            return stream.write(`${line}\n`);
+        },
+        onMessage(fn) {
+            stream.onData = async (chunk) => {
+                if (failed)
+                    return;
+                parts.push(chunk);
+                buffered += chunk.byteLength;
+                for (;;) {
+                    const at = untilNewline();
+                    if (at === -1) {
+                        if (buffered > maxLine) {
+                            failed = true;
+                            parts = [];
+                            buffered = 0;
+                            stream.end(NDJSON_LINE_TOO_LONG);
+                        }
+                        return;
+                    }
+                    const line = decode.decode(take(at));
+                    take(1); // the '\n'
+                    buffered -= at + 1;
+                    if (line.length > 0)
+                        await fn(JSON.parse(line));
+                }
+            };
+        },
+        end(error) { stream.end(error); },
+    };
+}
 const count = (n, max) => {
     if (!Number.isInteger(n) || n < 0 || n > max)
         throw new Error('bad stream message');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/pair",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "Scan a code to pair a phone or browser with the home computer over one encrypted link (Noise IK over WebSocket).",
   "license": "Apache-2.0",
   "type": "module",