A page's send() queued behind a failing first connect hung forever — the
close handler dropped the ensureConnected() waiter without settling it, and
a throttled connect() was silently skipped, so nothing ever reconnected.
Symptom in apps: sidebar renders, page body stays blank until a reload.
- ensureConnected(): one waiter per outage, resolved by whichever attempt
succeeds next (no longer orphaned by a failed attempt)
- connect(): a call that lands on the reconnect throttle is retried when the
window opens instead of being dropped
- a replaced (connect(true)) or destroy()ed socket's late error/close no
longer wipes the live socket's state or schedules a reconnect
- destroy() cancels a pending auto-reconnect
- new opt-in `rejectOnDisconnect`: a send already written to a socket that
closes rejects with { message, code: 'connection_lost' } instead of
hanging (default off — unchanged behaviour for existing consumers)
- node:test suite (`npm test`) with a scripted fake socket covering each case
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
- AGENTS.md: canonical client reference — factories + the app `ws` singleton, send()
(streaming via the 4th progress arg, no-timeout caveat), listen/listenWhileMounted,
the EventTarget mechanics, the setAppReady() gate, the SSR pattern, and a footgun checklist.
- package.json: add AGENTS.md to files[] so it ships to node_modules in consumer installs.
- README: correct the ApiClient method table — `bearerToken` getter / getBackendUrl() /
setBearer(null) (getBearer/getServerUrl/clearBearer never existed) + accurate verb signatures.
Fabian @ Blax Software