@tonytomo/gosocket-client 0.0.0-stage → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,98 @@
+# Changelog
+
+All notable changes to the Browser WebSocket Client SDK (`@ws-server/ws-client`) will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.4.0] - 2026-10-29
+
+### Added — JS SDK Phase J4 (Final Phase)
+
+- **Error Classification & Recovery Policy (PROTOCOL.md §4.7)**:
+  - 18-row classification table mapping every protocol `ErrorCode` to SDK recovery actions (`fatal`, `drop_intent`, `app_prompt`, `retry_backoff`, `ignore`).
+  - Pure `classifyError(code, frame?, overrides?)` function supporting caller overrides via `ClientConfig.errorPolicy`.
+  - `errorClassified` event emitted immediately before raw `error` frames with code, action, retry delay, and optional raw frame.
+  - `AUTH_FAILED` ↔ `UNAUTHORIZED` unification: browser auth heuristic emits `errorClassified { code: 'UNAUTHORIZED', action: 'fatal' }` before emitting `fatal { code: 'AUTH_FAILED' }`.
+- **Round-Trip Latency (RTT) Tracking & Ping API**:
+  - `client.ping(timeoutMs?)`: Explicit on-demand ping returning measured round-trip time in milliseconds, serialized to prevent interleaving.
+  - `client.rttStats()`: Latency summary (`last`, `min`, `max`, `mean` via exponential moving average $\alpha = 0.2$, `samples`), reset on every reconnect cycle and client close.
+  - Passive heartbeat RTT sampling enabled by default (opt-out via `heartbeat: { trackRtt: false }`).
+  - `rtt` event emitted with `{ sample, source: 'heartbeat' | 'on_demand', stats }`.
+- **Local Pre-Send Validation (PROTOCOL.md §§3.1, 3.6)**:
+  - Strict validation of room names (`^[a-zA-Z0-9_-]{1,64}$`) and channel names (`^[a-zA-Z0-9_-]{1,32}$`).
+  - Rejection of reserved `'presence'` channel name for outbound message publishing.
+  - Maximum text payload limit (`maxTextPayloadBytes: 65024`, reserving 512 bytes for message envelope).
+  - Maximum binary payload limit (`maxBinaryPayloadBytes: 65535`).
+  - Client-side validation throwing `ValidationError` with field, rule, limit, and truncated value.
+  - Escape hatches: `validation: { enabled: false }` or direct `client.send(frame)` bypassing local validation to test raw wire frames.
+- **Capability-Driven Pre-Flight Checks (PROTOCOL.md §8)**:
+  - Synchronous pre-flight checks in `createRoom()` against advertised `welcome.capabilities.limits`:
+    - `max_metadata_bytes`: JSON-encoded byte size check.
+    - `max_channels_per_room`: effective channel count check including `'presence'`, room preset channels, and custom channels.
+    - `max_rooms_per_key`: tracks owned rooms created on current connection, rejecting creation exceeding server limits before sending frames.
+  - Rejections throw `CapabilityLimitError` locally without sending wire frames or emitting `errorClassified`.
+- **Live Conformance Suite & CI Runner**:
+  - Live conformance suite running in Vitest against real server binaries in `test/live/` with `ws` Node polyfill.
+  - Conformance test runner `scripts/live-conformance-js.sh` orchestrating primary (18080), binary-disabled (18081), and policy-violation (18082) server instances.
+  - GitHub Actions CI workflow running JS unit tests and live conformance suite.
+
+## [0.3.0] - 2026-10-29
+
+### Added — JS SDK Phase J3
+
+- **Binary Channels (PROTOCOL.md §7)**:
+  - `BinaryMapBuilder` and `validateBinaryMap` ensuring channel IDs are integers in $[1, 254]$, rejecting reserved names (`""`, `"presence"`) and duplicate IDs/channels with construction-time validation.
+  - Global binary-ID uniqueness across rooms on a single connection (`binaryOwner` registry) with proactive pre-wire collision checks and `binaryIdCollision` event dispatch.
+  - Transactional reservation rollback when server join requests fail or reject.
+  - Inbound binary frame parsing using `ws.binaryType = 'arraybuffer'`, decoding 1-byte channel prefix and dispatching `binaryMessage` or `binaryUnknownChannel`.
+  - Binary publishing via `publishBinary` routing through reliable/unreliable lanes, shared token-bucket rate limiting, server backoff, and frame-type-distinct coalescing slots (`${room}:${channel}:binary`).
+- **Presence Cache (PROTOCOL.md §6)**:
+  - Local cached roster tracking with typed events: `presenceJoin`, `presenceLeave`, `presenceInvalidated`, `roomDeleted`.
+  - Self-exclusion filtering in `knownMembers(room)` and `selfLabel` connection tracking from welcome frames.
+  - Server count tracking in `lastServerMemberCount(room)`.
+  - Protocol violation detection (`self presence event`, `unknown presence event`, `presence event missing who`, `malformed presence payload`, `empty binary frame`, `binary frame on presence channel`).
+  - Automatic reconnection invalidation marking presence caches stale (`invalidReason: 'reconnected'`) and requiring explicit `resetPresence(room)` to clear.
+- **Sequence-Gap Detection (PROTOCOL.md §5.6)**:
+  - Per-`(room, channel)` monotonic sequence number tracking across text message frames.
+  - Forward sequence gap detection emitting `sequenceGap` with `prev`, `current`, `missed`, and `reliable` lane flag.
+  - Silent re-baselining on reconnection, backward sequences (e.g. room re-creation), duplicate sequences, and sequence 0.
+  - Optional `autoInvalidateOnReliableGap` configuration invalidating room presence caches when a sequence gap occurs on the reliable `presence` channel.
+- **Delete Room Ackless Semantics**:
+  - `deleteRoom` resolves cleanly on incoming `room_deleted` presence frames with caller identification, removing room intents and executing complete state cleanup via `clearRoomState(room)`.
+- **Comprehensive Cleanup Hooks (`clearRoomState`)**:
+  - Centralized eviction of binary owners, presence states, sequence states, rate limiters, coalescing slots, and applied policies upon room leave, delete, or session restore drop.
+- **New Events & Errors**:
+  - Events: `binaryMessage`, `binaryUnknownChannel`, `binaryIdCollision`, `binaryMappingChanged`, `presenceJoin`, `presenceLeave`, `presenceInvalidated`, `roomDeleted`, `sequenceGap`, `protocolViolation`.
+  - Errors: `BinaryMapValidationError`, `BinaryMapExhaustedError`, `BinaryIdCollisionError`, `BinaryChannelUnmappedError`, `BinaryPayloadTooLargeError`.
+
+## [0.2.0] - 2026-10-29
+
+### Added — JS SDK Phase J2
+
+- **Two-Lane Outbound Pipeline**: Reliable lane (bounded FIFO, drop-newest or close on overflow) and Unreliable lane (bounded FIFO, drop-oldest) matching server delivery semantics in PROTOCOL.md §5.4.
+- **Channel Policy System**: `ChannelPolicy`, `PolicyProvider`, and `presetsFor(kind, overrides)` reproducing PROTOCOL.md §5.2 room presets for `chat`, `game`, and `custom` room templates.
+- **Client-Side Token Bucket Rate Limiting**: Per `(room, channel)` limiters enforcing `rate = maxRate` and `burst = max(2, maxRate * 2)` to cooperatively preempt server rate violations.
+- **Inbound RATE_LIMITED Backoff Correlation**: Reader pauses local publishing on channels receiving server `RATE_LIMITED` frames, inferring target rooms from recent publish tracking.
+- **Message Coalescing**: Outbound state coalescing on unreliable channels with `'timer'` and browser-native `'raf'` (`requestAnimationFrame`) drivers and customizable `merge` functions.
+- **Writer Loop Scheduler**: Single async event loop writer pump with burst draining (reliable 32, unreliable 8) and microtask yields (`await Promise.resolve()`) per frame to avoid blocking UI rendering.
+- **Transport Backpressure Management**: Cooperative monitoring of `WebSocket.bufferedAmount` with high ($1 \text{ MiB}$) and low ($512 \text{ KiB}$) watermarks and hysteresis, pausing unreliable flushes under saturation.
+- **Generation-Scoped Queues**: Outbound queues discard pending frames on reconnect to prevent stale message delivery contradicting restored room states, emitting `queuesDiscarded` before session restore begins.
+- **Public API Additions**: Added `publish(req)`, `setChannelPolicy(room, channel, policy)`, `queueDepth()`, `bufferedAmount()`, and test seam `__flushNow()`.
+- **New Events & Errors**: Added events (`rateLimited`, `reliableOverflow`, `unreliableDropped`, `coalesced`, `queuesDiscarded`, `backpressure`, `policyApplied`) and errors (`NotReadyError`, `ChannelNotReliableError`, `RateLimitedError`).
+
+## [0.1.0] - 2026-10-29
+
+### Added — JS SDK Phase J1
+
+- **Connection Lifecycle State Machine**: Full lifecycle management covering `idle`, `connecting`, `awaiting_welcome`, `ready`, `reconnecting`, and `closed` states with typed event notifications.
+- **Browser-Native Authentication**: Query parameter authentication (`?key=...`) with mandatory key redaction in logs and error frames.
+- **401 Detection Heuristic**: Intelligent classification of browser-masked abnormal close (`1006`) errors into `AUTH_FAILED` fatal halts versus retryable network failures, supporting `'heuristic'`, `'never-fatal'`, and `'always-fatal'` modes alongside an `onAmbiguousAuth` callback.
+- **Exponential Reconnection**: Full-jitter, equal-jitter, and non-jitter exponential backoff with configurable base delays, maximum ceilings, retry ceilings, and `shouldReconnect` overrides.
+- **Serialized Session Restore**: Automatic rejoining of active room memberships upon reconnection in alphabetical room order, handling `ROOM_NOT_FOUND`, `FORBIDDEN_SCOPE`, `INVALID_PASSCODE`, `ROOM_FULL` (with `'drop'` and `'retry'` policies), and per-room deadlines.
+- **Heartbeat Management**: Application-level ping/pong liveness verification with configurable intervals and timeouts, forcing connection resets on missed deadlines.
+- **Capabilities Discovery**: Caching of server `welcome.capabilities` preserving S2 `null`-means-disabled semantics and emitting `capabilitiesChanged` on server version or capacity upgrades.
+- **Core Protocol API**: Async convenience wrappers for `createRoom`, `joinRoom`, `leaveRoom`, `deleteRoom`, `listRooms`, and low-level `send`.
+- **Error Hierarchy**: ES2022 error taxonomy rooted at `SdkError`, including `AuthError`, `ConnectError`, `PolicyViolationError`, `RequestTimeoutError`, `ConcurrentRequestError`, and `ServerError`.
+- **Transport & Clock Abstractions**: Dependency-injected `Transport` and `Clock` interfaces powering deterministic zero-wall-clock test suites with 100% fake-timer execution.
+

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tony Tomo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MIGRATION.md

@@ -0,0 +1,366 @@
+# Migrating from raw WebSocket to the SDK
+
+**Who this is for:** an app that already talks to the Universal WebSocket
+Server using the browser's native `WebSocket` and hand-rolled JSON, and wants
+to move to `@githubusername/ws-client` incrementally.
+
+**What this is not:** a tutorial for new SDK users (see `README.md`) or a wire
+protocol reference (see `PROTOCOL.md`). It assumes you know both your existing
+client and the protocol.
+
+The SDK is additive. Every feature it provides is optional at the call site.
+You can migrate in five independent steps and stop at any of them.
+
+---
+
+## TL;DR
+
+**Before** — your app drives the WebSocket directly:
+
+```js
+const ws = new WebSocket(`wss://host/ws?key=${key}`);
+let retries = 0;
+const rooms = new Set();
+
+ws.onopen = () => rooms.forEach((r) => send({ type: "join_room", room: r }));
+ws.onmessage = (e) => {
+  const f = JSON.parse(e.data);
+  if (f.type === "message") render(f);
+  if (f.channel === "presence") updateRoster(f.payload);
+  if (f.type === "error" && f.code === "ROOM_FULL") setTimeout(rejoin, 1000);
+};
+ws.onclose = () => {
+  if (++retries < 10) setTimeout(() => reconnect(), 500 * 2 ** retries);
+};
+
+function send(frame) {
+  ws.send(JSON.stringify(frame));
+}
+function join(room) {
+  rooms.add(room);
+  send({ type: "join_room", room });
+}
+function leave(room) {
+  rooms.delete(room);
+  send({ type: "leave_room", room });
+}
+```
+
+**After** — the SDK owns all of that:
+
+```js
+import { Client, presetsFor } from "@githubusername/ws-client";
+
+const client = new Client({
+  url: "wss://host/ws",
+  apiKey: key,
+  outbound: {
+    policyProvider: { channelPolicy: (_r, c) => presetsFor("game")[c] },
+  },
+});
+
+client.on("message", (f) => render(f));
+client.on("presenceJoin", (f) => addPlayer(f.who));
+client.on("presenceLeave", (f) => removePlayer(f.who));
+client.on("errorClassified", (f) => {
+  if (f.action === "retry_backoff")
+    setTimeout(() => rejoin(f.room), f.retryAfterMs);
+});
+
+await client.connect();
+await client.joinRoom({ room: "arena-1" });
+```
+
+Same wire traffic. Same server. The reconnect loop, room bookkeeping, presence
+roster, and error classification are now SDK-managed.
+
+---
+
+## Frame ↔ API mapping
+
+### Outbound (your app → server)
+
+| Raw frame you send today           | SDK equivalent                                                   | Notes                                                                                 |
+| ---------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `{"type":"create_room",...}`       | `await client.createRoom(req)`                                   | Resolves on `room_created`                                                            |
+| `{"type":"join_room",...}`         | `await client.joinRoom(req)` or `client.joinRoomWithBinary(req)` | Resolves on `room_joined`; second form replaces `binary_channels`                     |
+| `{"type":"leave_room",...}`        | `await client.leaveRoom(room)`                                   | Resolves on `room_left`                                                               |
+| `{"type":"delete_room",...}`       | `await client.deleteRoom(room)`                                  | Resolves on `room_deleted` **presence event** (no separate ack)                       |
+| `{"type":"list_rooms"}`            | `await client.listRooms()`                                       | First page / full response; use `limit`/`cursor` in the request if you paginate       |
+| `{"type":"publish",...}` (JSON)    | `await client.publish(req)`                                      | Routes through reliability lane and applies policy + client rate limiter + coalescing |
+| `{"type":"publish",...}` (binary)  | `await client.publishBinary(req)`                                | Prefixes `[id][payload]`; requires `joinRoomWithBinary` first                         |
+| `{"type":"ping"}`                  | `await client.ping()` or rely on heartbeat                       | `ping()` returns measured RTT                                                         |
+| `{"type":"send",...}` (deprecated) | `await client.publish(req)`                                      | Do not use the old form; the SDK doesn't expose `send` as a message type              |
+| Raw control frame                  | `client.send(frame)`                                             | Escape hatch; bypasses rate limit, coalescing, and validation                         |
+
+**`publish()` resolves on enqueue, not on-wire delivery.** The protocol has
+no per-message acks. If your app relies on "message has been delivered,"
+nothing changes — you never had that guarantee. If you need ack semantics,
+build it into your payload (server relays verbatim; peer acks; your app
+correlates).
+
+### Inbound (server → your app)
+
+| Raw frame you receive today                                                  | SDK event                         | Notes                                                          |
+| ---------------------------------------------------------------------------- | --------------------------------- | -------------------------------------------------------------- |
+| `{"type":"welcome",...}`                                                     | `connected`                       | Also returned by `connect()`                                   |
+| `{"type":"room_created",...}`                                                | resolved by `createRoom()`        | No event unless you listen to the promise result               |
+| `{"type":"room_joined",...}`                                                 | resolved by `joinRoom()`          |                                                                |
+| `{"type":"room_left",...}`                                                   | resolved by `leaveRoom()`         |                                                                |
+| `{"type":"room_list",...}`                                                   | resolved by `listRooms()`         |                                                                |
+| `{"type":"message","channel":"chat"}`                                        | `message`                         | Payload forwarded verbatim                                     |
+| `{"type":"message","channel":"presence","payload":{"event":"join"}}`         | `presenceJoin`                    | Also updates `knownMembers()`                                  |
+| `{"type":"message","channel":"presence","payload":{"event":"leave"}}`        | `presenceLeave`                   | Also updates `knownMembers()`                                  |
+| `{"type":"message","channel":"presence","payload":{"event":"room_deleted"}}` | `roomDeleted`                     | Also removes the intent; `deleteRoom()` promise resolves       |
+| Binary frame `[id][payload]`                                                 | `binaryMessage`                   | Payload is a `Uint8Array`; unknown id → `binaryUnknownChannel` |
+| `{"type":"error",...}`                                                       | `error` **and** `errorClassified` | Classification runs first, then the raw frame                  |
+| `{"type":"pong"}`                                                            | `rtt` (if `Heartbeat.trackRtt`)   | `ping()` also resolves                                         |
+
+---
+
+## Five behavior changes
+
+### 1. Reconnect is the SDK's job now
+
+**Was:** your `onclose` handler, your backoff math, your retry cap.
+
+**Now:** full-jitter exponential backoff, per-close-code policy, cancelled by
+`client.close()`. Configurable via `ClientConfig.reconnect`.
+
+**Do not add a second reconnect loop around `client.on('disconnected', ...)`.**
+You'll get two competing retry chains and double-connect. If you want to
+customize behavior, use `reconnect.shouldReconnect(ctx)`, not an outer loop.
+
+**Does not reconnect on:** `client.close()`, `1008` (policy violation),
+`AUTH_FAILED` (browser auth heuristic). Reconnects on `1006`, `1001`,
+unexpected `1000`, transport error, heartbeat timeout.
+
+### 2. Session restore is automatic
+
+**Was:** your code re-joined rooms in `onopen`.
+
+**Now:** the SDK keeps a per-`Client` in-memory list of joined rooms
+(passcodes, binary maps) and re-issues `join_room` for each one after a
+successful reconnect — **before** `connected` fires again. You do not need
+rejoin logic.
+
+**Emitted signal:** `sessionRestored { restored: string[], failed: [...] }`.
+Subscribe to it if you need to resync app state (pull fresh game state, clear
+stale UI).
+
+**Cleared on `client.close()`.** Session restore is for automatic reconnect,
+not for page reloads. If you want cross-reload persistence, write your own
+`sessionStorage` of `{room, passcode}` and call `joinRoom` on `connect()`.
+
+### 3. Presence is cached
+
+**Was:** your `Map<room, Set<label>>` populated from raw presence frames.
+
+**Now:** `client.knownMembers(room)` returns a sorted snapshot.
+`client.lastServerMemberCount(room)` returns the last `members` count from
+`room_joined`, adjusted by presence deltas. Both are **hints, not
+authoritative** — after a reconnect, `presenceInvalidated(room)` returns
+`true` because the protocol offers no roster snapshot and peers who left
+during your downtime never emitted a `leave` for you.
+
+**Call `resetPresence(room)` after your own out-of-band roster sync** to
+clear the invalidated flag.
+
+### 4. Rate limiting is cooperative on the client
+
+**Was:** you find out by getting disconnected with `1008`.
+
+**Now:** the SDK applies a per-`(room, channel)` token bucket mirroring the
+server's `max_rate` and burst. Publishes beyond the bucket reject with
+`RateLimitedError{ source: 'local' }` before touching the wire. The server's
+`RATE_LIMITED` response still arrives (as `rateLimited{ source: 'server' }`)
+if you disable the client limiter — which you might do in tests.
+
+**Implication:** `await client.publish()` can now **reject** for a reason
+that used to be a silent drop. Wrap your publish call if you were relying on
+fire-and-forget.
+
+### 5. Errors become actions
+
+**Was:** `if (frame.code === 'ROOM_FULL') setTimeout(rejoin, 1000);` —
+hand-coded per code.
+
+**Now:** `errorClassified { code, action, retryAfterMs }` on every server
+error. `action` is one of `'ignore' | 'drop_intent' | 'retry_backoff' |
+'reconnect' | 'fatal' | 'app_prompt'`.
+
+**Recommended pattern:**
+
+```js
+client.on("errorClassified", (e) => {
+  switch (e.action) {
+    case "retry_backoff":
+      setTimeout(retry, e.retryAfterMs ?? 1000);
+      break;
+    case "drop_intent":
+      client.forgetRoom(e.room);
+      break;
+    case "app_prompt":
+      showDialog(e.code, e.message);
+      break;
+    case "fatal":
+      showFatalScreen(e.code);
+      break;
+    case "ignore":
+      console.warn(e.code);
+      break;
+  }
+});
+```
+
+The classification table is stable and testable via the exported
+`classifyError(code, frame?, overrides?)` function. Use overrides in
+`ClientConfig.errorPolicy` to change individual codes without forking the
+SDK.
+
+---
+
+## Three things that stay the same
+
+1. **Your lifecycle flow.** `connect` → `createRoom` → `joinRoom` → `publish`
+   → `leaveRoom` → `close`. Same order, same server-side preconditions.
+
+2. **Your room names, channel names, payload schemas.** The SDK marshals your
+   `payload` verbatim; the server relays it verbatim. No schema registry, no
+   translation, no validation beyond the size limits you can configure in
+   `validation`.
+
+3. **The server.** No env-var changes, no `PROTOCOL.md` changes, no
+   re-deployment. The SDK speaks the same protocol your current client speaks.
+   You can run raw and SDK clients against the same server from day one.
+
+---
+
+## Migration path
+
+Five independently shippable steps. Each is reversible. Stop at any step.
+
+### Step 1 — swap the transport, keep everything else
+
+Replace `new WebSocket(...)` with `new Client(...)` and wire the SDK's `send`
+and `message` event to your existing handlers. Disable reconnect, heartbeat,
+lanes, presence cache, and classification by turning them off in `ClientConfig`
+during step 1. Your app should behave **byte-for-byte the same** as before.
+
+**Verify:** open the app, exercise every feature, compare DevTools network
+traffic before/after — same frames, same cadence.
+
+### Step 2 — turn on reconnect and session restore
+
+Enable `reconnect` and remove your `onclose` retry loop. Enable
+`restore` (default on) and remove your manual `onopen` rejoin code.
+
+**Verify:** kill the WebSocket from DevTools network panel (or `docker
+restart` the server). Watch `reconnecting` → `connected` → `sessionRestored`
+fire in order. Rooms come back automatically.
+
+### Step 3 — turn on outbound lanes and rate limiting
+
+Install `outbound.policyProvider` (usually `presetsFor(kind)`). Publish now
+goes through reliability lanes with the channel's configured behavior.
+
+**Verify:** subscribe to `reliableOverflow`, `unreliableDropped`,
+`rateLimited`. A fast-publish test should emit `rateLimited{ source: 'local' }`
+**before** the server's `RATE_LIMITED` fires — the local limiter preempts.
+
+### Step 4 — turn on presence cache and seq detection
+
+Replace your roster map with `knownMembers()` and subscribe to
+`presenceJoin` / `presenceLeave` / `presenceInvalidated` / `roomDeleted`.
+Subscribe to `sequenceGap` for observability.
+
+**Verify:** two clients in one room, one joins/leaves rapidly — roster in your
+UI matches `knownMembers()` after the dust settles. After a reconnect, check
+`presenceInvalidated(room)` is `true` and call `resetPresence(room)` after
+your roster resync.
+
+### Step 5 — turn on validation, pre-flight, and error classification
+
+Enable `validation` (default on) and `errorPolicy` (default table). Wire your
+error handlers to `errorClassified.action`. Enable capability pre-flight by
+leaving it on (it only fires when the server's `capabilities.limits` are set).
+
+**Verify:** submit a bad room name → `ValidationError` throws synchronously
+before wire traffic. A room-full scenario → `errorClassified{action:
+'retry_backoff'}` and your UI retries. `createRoom` with oversize metadata
+when the server exposes `max_metadata_bytes` → `CapabilityLimitError` fires
+locally.
+
+---
+
+## Caveats and gotchas
+
+**ESM-only.** `client-js` ships as `"type": "module"`. You need a bundler
+(Vite, Webpack 5, esbuild, Rollup, Parcel) or `<script type="module">`. If
+you're currently loading your client with a plain `<script src>`, add a
+bundler before step 1.
+
+**`publish()` resolves on enqueue, not delivery.** The protocol has no per-
+message ack. See the mapping table note above.
+
+**`deleteRoom()` resolves on the `roomDeleted` presence event.** The SDK also
+emits the event, so if you subscribe to `roomDeleted` **and** await
+`deleteRoom()`, both fire. Don't double-handle.
+
+**`send()` routes through the reliable lane (J2+).** In earlier raw usage
+your `ws.send()` was synchronous; the SDK's `send()` is fire-and-forget but
+buffered through a bounded (256) lane. Overflow drops newest by default. If
+you were sending bursts >256 control frames without yielding, throttle.
+
+**`binaryMessage.payload` is a `Uint8Array`, not an `ArrayBuffer`.** It's a
+defensive copy; you may mutate it without affecting the transport.
+
+**Binary channel IDs are globally unique per `Client` instance.** The wire
+format has no room field, so two rooms on the same connection can't share an
+ID. If you need per-room-independent IDs, use separate `Client` instances.
+
+**`capabilities` may be `undefined`.** Older servers (pre-S2) don't emit the
+field. Capability pre-flight silently skips when it's absent. Your app should
+tolerate `client.capabilities === undefined`.
+
+**`AUTH_FAILED` and `UNAUTHORIZED` both fire on auth failure.** The browser
+can't see the HTTP 401 status, so the SDK heuristically classifies the first
+pre-`welcome` `1006` close. Both events fire, `errorClassified` first:
+
+```js
+client.on("errorClassified", (e) => {
+  if (e.code === "UNAUTHORIZED") showLoginScreen(); // protocol name
+});
+client.on("fatal", (e) => {
+  if (e.code === "AUTH_FAILED") hideSpinner(); // browser name
+});
+```
+
+**Concurrent same-type requests on the same room are serialized.** Because
+the protocol has no request IDs, `joinRoom('arena')` called twice in quick
+succession rejects the second with `ConcurrentRequestError`. Different rooms
+in parallel are fine.
+
+**Session restore is in-memory only.** Page reload wipes intents. Persist
+`{room, passcode}` in `sessionStorage` yourself if you need that.
+
+**Heartbeat is on by default.** Every 25s the SDK sends `{"type":"ping"}` and
+expects a `pong` within 10s. If you're on a metered connection and want to
+disable it, set `heartbeat: { enabled: false }` — but then dead connections
+won't be detected until the transport's TCP timeout.
+
+---
+
+## Where to read more
+
+- **`client-js/README.md`** — full API reference. Every method, event, and
+  config option with the SDK's actual behavior.
+- **`PROTOCOL.md`** — wire contract. §4.7 for error codes, §5 for channels
+  and rate limits, §6 for presence, §7 for binary frames.
+- **`PROJECT.md`** — phase history (J1–J4 for the JS SDK). "What's not here"
+  lists SDK non-goals.
+- **`client-js/CHANGELOG.md`** — which feature landed in which version.
+
+If you're unsure whether a raw pattern you use has an SDK equivalent, the
+answer is usually in the mapping tables above. If it isn't, the SDK
+deliberately doesn't cover it — use `client.send()` as the escape hatch.