@tonytomo/gosocket-client 1.0.0 → 1.0.1

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.

package/README.md

@@ -1,4 +1,4 @@
-# @ws-server/ws-client (`ws-client-js`)
+# @tonytomo/gosocket-client (`gosocket-client`)
 
 Browser-first TypeScript / JavaScript client SDK for the Universal WebSocket Server (Complete SDK: Phases J1, J2, J3 & J4).
 
@@ -27,7 +27,7 @@ This SDK runs natively in modern web browsers (HTML5 `WebSocket`) with **zero ru
 - [Round-trip time (RTT) & ping API](#round-trip-time-rtt--ping-api)
 - [Local validation vs. server validation](#local-validation-vs-server-validation)
 - [Capability pre-flight checks](#capability-pre-flight-checks)
-- [What the SDK does *not* do](#what-the-sdk-does-not-do)
+- [What the SDK does _not_ do](#what-the-sdk-does-not-do)
 - [Usage Guide](#usage-guide)
 - [Live Conformance](#live-conformance)
 
@@ -59,27 +59,31 @@ Because the browser hides the HTTP 401 status code behind an ambiguous abnormal
 The SDK implements an authentication heuristic mirrored from the reference Go SDK:
 
 ### Default Heuristic (`'heuristic'`)
+
 - If the socket closes with code `1006` **before** the initial `welcome` frame has been received on the very first connect attempt, the SDK classifies the failure as `AUTH_FAILED`.
 - The client emits a `fatal` event with `{ code: 'AUTH_FAILED', message: '...' }`, transitions to `closed`, and does **not** attempt automatic reconnection.
 - Once the first successful `welcome` frame has arrived in a session, subsequent `1006` closures are recognized as mid-stream disconnects and will trigger automatic reconnection.
 - The heuristic state is reset whenever `client.close()` is called followed by a fresh `client.connect()`.
 
 ### Alternative Auth Failure Modes
+
 You can configure `authFailureMode` in `ClientConfig`:
+
 - `'heuristic'` (default): Treat pre-welcome `1006` on the first attempt as `AUTH_FAILED`.
 - `'never-fatal'`: Never classify a pre-welcome `1006` as an authentication failure. Reconnect backoff will always engage. Useful when connecting over notoriously unstable networks where initial drops are common and the caller accepts the cost of retry loops.
 - `'always-fatal'`: Treat **any** pre-welcome close (regardless of close code) on the first attempt as an authentication failure. Useful in controlled production environments with reliable networking where handshake failure indicates invalid credentials.
 
 ### Ambiguous Auth Escape Hatch (`onAmbiguousAuth`)
+
 If your application requires custom classification logic, provide an `onAmbiguousAuth` callback:
 
 ```ts
 const client = new Client({
-  url: 'wss://example.com/ws',
-  apiKey: 'k_alice_123',
+  url: "wss://example.com/ws",
+  apiKey: "k_alice_123",
   onAmbiguousAuth: (closeCode, reason) => {
     // Return 'fatal' to abort immediately or 'retry' to engage reconnection
-    return closeCode === 1006 ? 'fatal' : 'retry';
+    return closeCode === 1006 ? "fatal" : "retry";
   },
 });
 ```
@@ -94,13 +98,16 @@ $$\text{backoff} = \min(\text{maxDelayMs}, \text{baseDelayMs} \times 2^{\text{at
 $$\text{delay} = \text{random}(0, \text{backoff})$$
 
 ### Default Configuration
+
 - `baseDelayMs`: `500` ms
 - `maxDelayMs`: `30000` ms (30 s)
 - `maxAttempts`: `Infinity`
 - `jitter`: `'full'` (also supports `'equal'` and `'none'`)
 
 ### Reconnect Triggers
+
 Automatic reconnection engages on:
+
 - `1006` (Abnormal Closure, post-welcome or in `'never-fatal'` mode)
 - `1001` (Going Away, indicating server graceful shutdown recovery per PROTOCOL.md §9.2)
 - `1000` (Unexpected normal closure initiated by the server without prior client `close()`)
@@ -108,7 +115,9 @@ Automatic reconnection engages on:
 - Heartbeat ping/pong deadline timeouts
 
 ### Non-Reconnect (Fatal) Triggers
+
 Reconnection is **halted** and state transitions to `closed` on:
+
 - Explicit caller termination via `client.close()`
 - `1008` (Policy Violation, such as rate abuse, reliable queue overflow, or server read timeouts) — surfaces `fatal` with `{ code: 'POLICY_VIOLATION' }`
 - Initial handshake classification of `AUTH_FAILED`
@@ -124,18 +133,23 @@ The attempt counter resets to `0` upon each successful `welcome` frame.
 The SDK automatically restores room memberships following connection recovery without re-transmitting business traffic.
 
 ### In-Memory Only
+
 > [!IMPORTANT]
 > **No Local Storage Persistence**:
 > Room intents and authentication credentials exist **in memory only**. The SDK intentionally never writes API keys, passcodes, or room states to `localStorage`, `sessionStorage`, or `IndexedDB`. If the user navigates away or refreshes the page, all state is lost and must be re-initialized.
 
 ### Serialized Execution
+
 The wire protocol contains no multiplexed request correlation identifiers. Because of this:
+
 - **The session restore loop is strictly serialized**: The client issues `join_room` for intent $N$, waits for the server's `room_joined` confirmation (or error), and only then sends `join_room` for intent $N+1$.
 - Parallel restore joins are forbidden to prevent protocol race conditions.
 - On recovery, room intents are sorted alphabetically by room name to ensure deterministic order across connections.
 
 ### Per-Intent Recovery Outcomes
+
 When rejoining each room on reconnect:
+
 - `room_joined` $\rightarrow$ Membership restored.
 - `ROOM_NOT_FOUND` $\rightarrow$ Intent deleted from memory, emits `intentFailed{ room, code: 'ROOM_NOT_FOUND' }`.
 - `FORBIDDEN_SCOPE` $\rightarrow$ Intent deleted from memory, emits `intentFailed{ room, code: 'FORBIDDEN_SCOPE' }`.
@@ -179,6 +193,7 @@ Phase J2 replaces direct socket writing with a prioritised two-lane async outbou
 ```
 
 ### Lane Characteristics
+
 1. **Reliable Lane (`reliable: true`)**:
    - Default buffer capacity: `256` frames.
    - Enforces strict FIFO ordering.
@@ -191,7 +206,9 @@ Phase J2 replaces direct socket writing with a prioritised two-lane async outbou
    - **Overflow Behavior**: Drops the **oldest** frame in the queue to admit the newest frame. Emits `unreliableDropped{ depth }`.
 
 ### Writer Loop Scheduling
+
 Because browsers lack background writer goroutines, the writer is driven by an async pump loop running on the event loop:
+
 - Drains up to `reliableBurst` (default: 32) frames from the reliable lane.
 - Drains up to `unreliableBurst` (default: 8) frames from the unreliable lane or coalesce slots.
 - Performs a microtask yield (`await Promise.resolve()`) per frame to avoid blocking UI rendering or starve incoming WebSocket frames.
@@ -204,10 +221,12 @@ Because browsers lack background writer goroutines, the writer is driven by an a
 On unreliable channels opted in via `policy.coalesce = true`, rapid updates sent before the transport flushes are coalesced into a single slot instead of consuming FIFO slots.
 
 ### Drivers: `'timer'` vs. `'raf'`
+
 - `'timer'` (default): Drains on the next microtask turn. Suitable for general high-frequency state streams and maintains behavioral parity with the Go SDK.
 - `'raf'` (`requestAnimationFrame`): Browser-native driver that aligns outbound state flushes with the monitor refresh rate (typically 60 Hz or 120 Hz). All state updates generated within an animation frame are coalesced into one wire transmission. In Node or test environments where `requestAnimationFrame` is undefined, the SDK falls back to a 16 ms timer scheduled via `Clock`.
 
 ### Merge Semantics (`merge`)
+
 By default, the newest update replaces the previous pending update (last-writer-wins). Applications can supply a custom `merge` function to combine or filter updates:
 
 ```ts
@@ -215,7 +234,7 @@ const policy: ChannelPolicy = {
   reliable: false,
   maxRate: 0,
   coalesce: true,
-  coalesceDriver: 'raf',
+  coalesceDriver: "raf",
   merge: (prev: unknown, next: unknown) => {
     const p = prev as { x: number; y: number; seq: number };
     const n = next as { x: number; y: number; seq: number };
@@ -228,6 +247,7 @@ const policy: ChannelPolicy = {
   },
 };
 ```
+
 - If `skip: true`, the new message is discarded and the previous message is retained in the slot, emitting `coalesced{ merged: false, skipped: true }`.
 - If `skip: false`, `value` replaces the slot and `coalesced{ merged: true, skipped: false }` is emitted.
 - Flipping a channel's policy to `coalesce: false` via `setChannelPolicy` immediately flushes any pending slot as an individual write without emitting a `coalesced` event.
@@ -237,14 +257,17 @@ const policy: ChannelPolicy = {
 ## Rate limiting — cooperative, not authoritative
 
 Rate limiting is enforced locally per `(room, channel)` using an exact client-side token bucket matching the server algorithm in PROTOCOL.md §5.5:
+
 - **Rate**: `maxRate` tokens per second.
 - **Burst Capacity**: $\max(2, \text{maxRate} \times 2)$.
 - `maxRate = 0` bypasses rate limiting (unlimited).
 
 ### Role of the Client Limiter
+
 The client-side limiter is **cooperative, not authoritative**. Its primary role is to intercept excess outbound traffic before it hits the wire, preventing the client from accumulating rate violations that would cause the server to forcibly terminate the connection with code `1008` (`rate limit abuse`).
 
 ### Local vs. Server Events
+
 - `rateLimited{ source: 'local', room, channel, retryAfterMs }`: Emitted when the local token bucket is exhausted or during an active server-instructed pause. The `publish()` call rejects locally with a `RateLimitedError`.
 - `rateLimited{ source: 'server', room, channel, retryAfterMs }`: Emitted when the server returns an `error` frame with code `RATE_LIMITED`. The SDK pauses local publishing on that channel for the instructed duration (`retry_after_ms`, typically 250 ms).
 
@@ -255,6 +278,7 @@ The client-side limiter is **cooperative, not authoritative**. Its primary role
 Unlike server-side runtimes, web browsers expose `WebSocket.bufferedAmount`—the byte count of queued data in the browser's internal network buffer. If the client publishes faster than the socket can transmit over the network, `bufferedAmount` will grow unboundedly.
 
 The SDK monitors backpressure cooperatively:
+
 - **High Water Mark (`highWaterMarkBytes`, default $1 \text{ MiB}$)**: When `bufferedAmount >= highWaterMarkBytes`, the writer pauses unreliable lane draining and emits `backpressure{ state: 'high', bufferedAmount }`.
 - **Low Water Mark (`lowWaterMarkBytes`, default $512 \text{ KiB}$)**: When `bufferedAmount <= lowWaterMarkBytes`, backpressure clears, `backpressure{ state: 'low', bufferedAmount }` is emitted, and the writer resumes.
 - **Hysteresis**: Fluctuations between the low and high thresholds do not trigger flapping events.
@@ -281,7 +305,9 @@ Outbound queues and coalesce slots belong strictly to the active **connection ge
 Upon each successful connection, the server synchronously sends a `welcome` frame containing a `capabilities` descriptor advertising its runtime limits and supported features.
 
 ### S2 `null`-means-disabled Semantics
+
 The SDK preserves the authoritative wire semantics from PROTOCOL.md §2.4 and S2:
+
 - An integer value indicates an enforced maximum (e.g. `max_rooms: 1000`, `max_channels_per_room: 32`).
 - A `null` value indicates that the limit is **explicitly disabled** (unlimited) by server configuration (e.g. `max_rooms_per_key: null`).
 - `undefined` indicates that the connected server is a legacy version that does not advertise capabilities.
@@ -295,41 +321,49 @@ Capabilities are cached on `client.capabilities`. When a reconnect yields a diff
 Binary frames allow high-throughput, low-overhead transmission of packed binary data (such as physics snapshots, audio streams, or state deltas) without JSON serialization overhead (PROTOCOL.md §7).
 
 ### Wire Format & Mapping
+
 - Wire format: `[channel_id: 1 byte][payload: N bytes]`.
 - Channels map names to a 1-byte identifier in $[1, 254]$ (`0` is reserved for JSON control frames, and `255` is reserved for presence).
 - Channel `"presence"` cannot be mapped to binary (`RESERVED_CHANNEL_NAME`).
 
 ### Builder Construction
+
 Use `BinaryMapBuilder` to construct and validate mappings:
 
 ```ts
-import { BinaryMapBuilder } from 'ws-client-js';
+import { BinaryMapBuilder } from "gosocket-client";
 
 const binMap = new BinaryMapBuilder()
-  .set('state', 1)
-  .set('actions', 2)
-  .autoSet('telemetry') // assigns smallest available ID (e.g. 3)
+  .set("state", 1)
+  .set("actions", 2)
+  .autoSet("telemetry") // assigns smallest available ID (e.g. 3)
   .build();
 ```
 
 Construction-time validation enforces:
+
 - Channel name non-empty and `!= 'presence'`.
 - ID integer in $[1, 254]$.
 - No duplicate IDs and no duplicate channel names in the builder.
 - Returns an immutable, frozen mapping object.
 
 ### Global Binary-ID Uniqueness Rule
+
 Because the wire binary frame does not carry a room identifier, the client connection enforces global ID uniqueness across all rooms joined on that connection.
 
 If room B attempts to map an ID already assigned to room A:
+
 - `joinRoomWithBinary` rejects locally before touching the wire with `BinaryIdCollisionError`.
 - Emits a `binaryIdCollision` event with `{ id, existing, rejected }`.
 
 ### Update via Re-Join
+
 Calling `joinRoomWithBinary` on an already-joined room updates that room's binary mappings in place (`PROTOCOL.md` §3.2). IDs removed by the update are freed from `binaryOwner`, and newly added IDs are reserved. If the server rejects the join (e.g. `ROOM_NOT_FOUND`), tentative reservations are rolled back to the previous state.
 
 ### Binary Publishing & Coalescing
+
 Use `client.publishBinary({ room, channel, payload })`:
+
 - Payloads can be passed as `ArrayBuffer` or `Uint8Array`.
 - Routes through the channel's resolved policy (`reliable` vs `unreliable`).
 - Shares the same token-bucket rate limiter and server `RATE_LIMITED` backoff with text messages on that channel.
@@ -344,12 +378,14 @@ Room presence is managed automatically on the reserved `"presence"` channel (PRO
 
 > [!IMPORTANT]
 > **Presence Caveats**:
+>
 > - **Presence is a best-effort hint, not an authoritative source of truth.**
 > - Peers who joined before the current client joined are not visible in `knownMembers(room)` (the server sends `room_joined.members` count, but does not replay prior peer joins).
 > - Peers who left while this client was disconnected or reconnecting may still appear in `knownMembers(room)` until `resetPresence(room)` or room departure.
 > - The protocol does not provide an application-level roster sync. Applications requiring authoritative user rosters must perform their own sync over an application channel.
 
 ### Presence Inspection & APIs
+
 - `client.selfLabel`: The connection's unique client label assigned in `welcome.label`.
 - `client.knownMembers(room)`: Sorted array of peer labels observed joining since the last `resetPresence`, with `selfLabel` excluded.
 - `client.lastServerMemberCount(room)`: Last member count from `room_joined.members`, adjusted by subsequent `presenceJoin` (+1) and `presenceLeave` (-1) events. Returns `{ count: number, ok: boolean }`.
@@ -357,6 +393,7 @@ Room presence is managed automatically on the reserved `"presence"` channel (PRO
 - `client.resetPresence(room)`: Clears the `known` roster and invalidation flag while keeping `lastServerMemberCount`.
 
 ### Typed Events
+
 - `presenceJoin`: `{ room, who }`
 - `presenceLeave`: `{ room, who }`
 - `presenceInvalidated`: `{ room, reason }`
@@ -369,6 +406,7 @@ Room presence is managed automatically on the reserved `"presence"` channel (PRO
 The server sequences messages monotonically via a per-`(room, channel)` `seq` counter (PROTOCOL.md §5.6).
 
 ### Anomalous vs Expected
+
 - **Reliable Channels (`reliable: true`)**: Every sequence number must arrive contiguously without gaps ($1, 2, 3\dots$). A forward jump ($s > \text{last} + 1$) indicates dropped frames due to network error or server buffer eviction, emitting `sequenceGap` with `reliable: true`.
 - **Unreliable Channels (`reliable: false`)**: Frame loss is expected under network saturation or client rate limiting. Forward jumps emit `sequenceGap` with `reliable: false` for application telemetry.
 - **Re-baselining**: Reconnections, backward sequence numbers (e.g. room re-creation), duplicate sequence numbers, and unsequenced frames (`seq = 0`) silently establish or maintain baseline without emitting false gap alarms.
@@ -379,6 +417,7 @@ The server sequences messages monotonically via a per-`(room, channel)` `seq` co
 ## Reconnect invalidates presence and re-baselines seq
 
 When a connection disconnects and reconnects:
+
 1. **Queues Discarded**: Outbound queues are purged to avoid sending stale commands.
 2. **Presence Invalidated**: Before session restore begins, every live room intent is marked `presenceInvalidated(room) == true` with reason `"reconnected"`, and emits a `presenceInvalidated` event. The known roster is kept for inspection until `client.resetPresence(room)` is called.
 3. **Seq Re-baselined**: All sequence baselines are cleared (`hasBase = false`). The first message received on each channel after reconnect silently sets a fresh baseline.
@@ -391,9 +430,11 @@ When a connection disconnects and reconnects:
 In web browsers, the standard HTML5 `WebSocket` defaults to `binaryType = 'blob'`. Converting `Blob` payloads requires asynchronous `blob.arrayBuffer()` calls that cause microtask queue delays and GC overhead.
 
 This SDK automatically sets:
+
 ```ts
-this.ws.binaryType = 'arraybuffer';
+this.ws.binaryType = "arraybuffer";
 ```
+
 Inbound binary messages arrive synchronously as `ArrayBuffer` instances and are decoded without microtask lag into `Uint8Array` payloads on `binaryMessage` events.
 
 ---
@@ -401,17 +442,19 @@ Inbound binary messages arrive synchronously as `ArrayBuffer` instances and are
 ## Usage Guide
 
 ### Installation
+
 ```bash
-npm install ws-client-js
+npm install gosocket-client
 ```
 
 ### Complete Example (Lifecycle, Binary, Presence, Policies)
+
 ```ts
-import { Client, BinaryMapBuilder, presetsFor } from 'ws-client-js';
+import { Client, BinaryMapBuilder, presetsFor } from "gosocket-client";
 
 const client = new Client({
-  url: 'wss://your-server.example.com/ws',
-  apiKey: 'k_alice_123',
+  url: "wss://your-server.example.com/ws",
+  apiKey: "k_alice_123",
   heartbeat: { intervalMs: 25000, timeoutMs: 10000 },
   reconnect: { baseDelayMs: 500, maxDelayMs: 30000 },
   presence: { autoInvalidateOnReliableGap: true },
@@ -419,54 +462,55 @@ const client = new Client({
     reliableQueueSize: 256,
     unreliableQueueSize: 16,
     policyProvider: {
-      channelPolicy: (room, channel) => presetsFor('game')[channel],
+      channelPolicy: (room, channel) => presetsFor("game")[channel],
     },
   },
 });
 
 // Binary channel mapping
-const binMap = new BinaryMapBuilder()
-  .set('state', 1)
-  .set('actions', 2)
-  .build();
+const binMap = new BinaryMapBuilder().set("state", 1).set("actions", 2).build();
 
 // Inbound binary frames
-client.on('binaryMessage', ({ room, channel, payload }) => {
+client.on("binaryMessage", ({ room, channel, payload }) => {
   // payload is a Uint8Array
-  console.log(`Binary frame on ${room}/${channel} (${payload.byteLength} bytes)`);
+  console.log(
+    `Binary frame on ${room}/${channel} (${payload.byteLength} bytes)`,
+  );
 });
 
 // Presence events
-client.on('presenceJoin', ({ room, who }) => {
+client.on("presenceJoin", ({ room, who }) => {
   console.log(`Peer ${who} joined ${room}`);
-  console.log('Known roster:', client.knownMembers(room));
+  console.log("Known roster:", client.knownMembers(room));
 });
 
-client.on('presenceLeave', ({ room, who }) => {
+client.on("presenceLeave", ({ room, who }) => {
   console.log(`Peer ${who} left ${room}`);
 });
 
 // Sequence gaps
-client.on('sequenceGap', (ev) => {
-  console.warn(`Sequence gap on ${ev.room}/${ev.channel}: missed ${ev.missed} frames (reliable: ${ev.reliable})`);
+client.on("sequenceGap", (ev) => {
+  console.warn(
+    `Sequence gap on ${ev.room}/${ev.channel}: missed ${ev.missed} frames (reliable: ${ev.reliable})`,
+  );
 });
 
 // Connect and join with binary
 await client.connect();
 await client.joinRoomWithBinary({
-  room: 'arena-1',
+  room: "arena-1",
   binaryChannels: binMap,
 });
 
 // Publish binary state at 60 Hz (unreliable lane)
 await client.publishBinary({
-  room: 'arena-1',
-  channel: 'state',
+  room: "arena-1",
+  channel: "state",
   payload: new Uint8Array([0x01, 0x02, 0x03]),
 });
 
 // Clean room deletion
-await client.deleteRoom('arena-1');
+await client.deleteRoom("arena-1");
 ```
 
 ---
@@ -477,29 +521,30 @@ The SDK maps all 18 protocol error codes from `PROTOCOL.md` §4.7 into standardi
 
 ### Recovery Decision Table
 
-| Error Code | Action | Default Retry Delay | Application Recovery Guidance |
-| :--- | :--- | :--- | :--- |
-| `UNAUTHORIZED` | `fatal` | — | Halt connection; prompt user for valid API key |
-| `FORBIDDEN_SCOPE` | `fatal` | — | Halt connection; API key lacks required scope |
-| `NOT_ROOM_OWNER` | `drop_intent` | — | Discard intent; caller cannot manage room |
-| `BAD_REQUEST` | `drop_intent` | — | Discard intent; fix malformed request syntax |
-| `ROOM_NOT_FOUND` | `drop_intent` | — | Discard intent; room does not exist |
-| `ROOM_ALREADY_EXISTS` | `app_prompt` | — | Prompt user or generate alternate room name |
-| `INVALID_PASSCODE` | `app_prompt` | — | Prompt user to enter correct passcode |
-| `ROOM_FULL` | `retry_backoff` | 1000 ms | Wait for member departure; retry join |
-| `PASSCODE_RATE_LIMITED` | `retry_backoff` | `retry_after_ms` (fallback 60 s) | Pause passcode entry until lockout window expires |
-| `MAX_ROOMS_REACHED` | `retry_backoff` | 5000 ms | Wait or delete existing rooms |
-| `BINARY_NOT_ALLOWED` | `ignore` | — | Inform application; fallback to text frames |
-| `CHANNEL_NOT_RELIABLE` | `ignore` | — | Unreliable channel cannot guarantee delivery |
-| `CHANNEL_NOT_FOUND` | `ignore` | — | Channel not configured in room |
-| `RESERVED_CHANNEL_NAME` | `ignore` | — | Reserved name (`presence`) cannot be used |
-| `CHANNEL_READ_ONLY` | `ignore` | — | Channel is read-only |
-| `RATE_LIMITED` | `retry_backoff` | `retry_after_ms` (fallback 250 ms) | Back off outbound publishing |
-| `INTERNAL_ERROR` | `retry_backoff` | 2000 ms | Transient server issue; retry request |
+| Error Code              | Action          | Default Retry Delay                | Application Recovery Guidance                     |
+| :---------------------- | :-------------- | :--------------------------------- | :------------------------------------------------ |
+| `UNAUTHORIZED`          | `fatal`         | —                                  | Halt connection; prompt user for valid API key    |
+| `FORBIDDEN_SCOPE`       | `fatal`         | —                                  | Halt connection; API key lacks required scope     |
+| `NOT_ROOM_OWNER`        | `drop_intent`   | —                                  | Discard intent; caller cannot manage room         |
+| `BAD_REQUEST`           | `drop_intent`   | —                                  | Discard intent; fix malformed request syntax      |
+| `ROOM_NOT_FOUND`        | `drop_intent`   | —                                  | Discard intent; room does not exist               |
+| `ROOM_ALREADY_EXISTS`   | `app_prompt`    | —                                  | Prompt user or generate alternate room name       |
+| `INVALID_PASSCODE`      | `app_prompt`    | —                                  | Prompt user to enter correct passcode             |
+| `ROOM_FULL`             | `retry_backoff` | 1000 ms                            | Wait for member departure; retry join             |
+| `PASSCODE_RATE_LIMITED` | `retry_backoff` | `retry_after_ms` (fallback 60 s)   | Pause passcode entry until lockout window expires |
+| `MAX_ROOMS_REACHED`     | `retry_backoff` | 5000 ms                            | Wait or delete existing rooms                     |
+| `BINARY_NOT_ALLOWED`    | `ignore`        | —                                  | Inform application; fallback to text frames       |
+| `CHANNEL_NOT_RELIABLE`  | `ignore`        | —                                  | Unreliable channel cannot guarantee delivery      |
+| `CHANNEL_NOT_FOUND`     | `ignore`        | —                                  | Channel not configured in room                    |
+| `RESERVED_CHANNEL_NAME` | `ignore`        | —                                  | Reserved name (`presence`) cannot be used         |
+| `CHANNEL_READ_ONLY`     | `ignore`        | —                                  | Channel is read-only                              |
+| `RATE_LIMITED`          | `retry_backoff` | `retry_after_ms` (fallback 250 ms) | Back off outbound publishing                      |
+| `INTERNAL_ERROR`        | `retry_backoff` | 2000 ms                            | Transient server issue; retry request             |
 
 ### `AUTH_FAILED` vs `UNAUTHORIZED`
 
 Because native browser `WebSocket` obscures HTTP status codes on rejected handshakes (closing with code `1006` rather than providing `HTTP 401`), the SDK employs the auth heuristic:
+
 1. When a pre-welcome `1006` occurs on first connect, the SDK emits `errorClassified { code: 'UNAUTHORIZED', action: 'fatal', rawFrame: undefined }`.
 2. Immediately following `errorClassified`, it emits `fatal { code: 'AUTH_FAILED' }` and transitions to `closed`.
 
@@ -511,12 +556,12 @@ Applications can customize error classifications via `ClientConfig.errorPolicy.o
 
 ```ts
 const client = new Client({
-  url: 'wss://example.com/ws',
-  apiKey: 'k_123',
+  url: "wss://example.com/ws",
+  apiKey: "k_123",
   errorPolicy: {
     overrides: {
-      INTERNAL_ERROR: { action: 'fatal' },
-      ROOM_NOT_FOUND: { action: 'ignore' },
+      INTERNAL_ERROR: { action: "fatal" },
+      ROOM_NOT_FOUND: { action: "ignore" },
     },
   },
 });
@@ -527,6 +572,7 @@ const client = new Client({
 ## Round-trip time (RTT) & ping API
 
 ### On-Demand Ping
+
 Measure current connection round-trip latency at any time using `client.ping()`:
 
 ```ts
@@ -540,12 +586,15 @@ console.log(`Ping round-trip: ${rttMs}ms`);
 - Rejects with `RequestTimeoutError` if pong does not arrive within deadline.
 
 ### Latency Statistics (`rttStats()`)
+
 Get a snapshot of latency statistics over the active connection generation:
 
 ```ts
 const stats = client.rttStats();
 if (stats) {
-  console.log(`Last: ${stats.last}ms, Min: ${stats.min}ms, Max: ${stats.max}ms, Mean: ${stats.mean.toFixed(1)}ms (${stats.samples} samples)`);
+  console.log(
+    `Last: ${stats.last}ms, Min: ${stats.min}ms, Max: ${stats.max}ms, Mean: ${stats.mean.toFixed(1)}ms (${stats.samples} samples)`,
+  );
 }
 ```
 
@@ -555,12 +604,13 @@ $$\text{mean}_{\text{new}} = 0.8 \times \text{mean}_{\text{old}} + 0.2 \times \t
 Statistics reset to `undefined` on every reconnect cycle and client close.
 
 ### Passive Heartbeat RTT Sampling
+
 Every background heartbeat ping/pong cycle automatically computes an RTT sample and updates latency stats. Opt out via `heartbeat: { trackRtt: false }`.
 
 Both heartbeat and on-demand samples emit the `rtt` event:
 
 ```ts
-client.on('rtt', ({ sample, source, stats }) => {
+client.on("rtt", ({ sample, source, stats }) => {
   console.log(`RTT [${source}]: ${sample}ms (avg ${stats.mean.toFixed(1)}ms)`);
 });
 ```
@@ -571,15 +621,16 @@ client.on('rtt', ({ sample, source, stats }) => {
 
 The SDK provides fast, client-side pre-send validation to save network round-trips and provide immediate developer feedback:
 
-| Constraint | Validation Rule | Checked On | Error Thrown |
-| :--- | :--- | :--- | :--- |
-| Room name syntax | `^[a-zA-Z0-9_-]{1,64}$` | `createRoom`, `joinRoom`, `deleteRoom`, `forgetRoom`, `publish`, `publishBinary` | `ValidationError` (`field: 'room'`, `rule: 'name_syntax'`) |
-| Channel name syntax | `^[a-zA-Z0-9_-]{1,32}$` | `publish`, `publishBinary` | `ValidationError` (`field: 'channel'`, `rule: 'name_syntax'`) |
-| Reserved channel | Cannot publish to `'presence'` | `publish`, `publishBinary` | `ValidationError` (`field: 'channel'`, `rule: 'reserved_channel'`) |
-| Text payload size | Marshaled bytes $\le 65024$ (leaving 512B envelope budget) | `publish` | `ValidationError` (`field: 'payload'`, `rule: 'too_large'`) |
-| Binary payload size | Raw bytes $\le 65535$ | `publishBinary` | `ValidationError` / `BinaryPayloadTooLargeError` |
+| Constraint          | Validation Rule                                            | Checked On                                                                       | Error Thrown                                                       |
+| :------------------ | :--------------------------------------------------------- | :------------------------------------------------------------------------------- | :----------------------------------------------------------------- |
+| Room name syntax    | `^[a-zA-Z0-9_-]{1,64}$`                                    | `createRoom`, `joinRoom`, `deleteRoom`, `forgetRoom`, `publish`, `publishBinary` | `ValidationError` (`field: 'room'`, `rule: 'name_syntax'`)         |
+| Channel name syntax | `^[a-zA-Z0-9_-]{1,32}$`                                    | `publish`, `publishBinary`                                                       | `ValidationError` (`field: 'channel'`, `rule: 'name_syntax'`)      |
+| Reserved channel    | Cannot publish to `'presence'`                             | `publish`, `publishBinary`                                                       | `ValidationError` (`field: 'channel'`, `rule: 'reserved_channel'`) |
+| Text payload size   | Marshaled bytes $\le 65024$ (leaving 512B envelope budget) | `publish`                                                                        | `ValidationError` (`field: 'payload'`, `rule: 'too_large'`)        |
+| Binary payload size | Raw bytes $\le 65535$                                      | `publishBinary`                                                                  | `ValidationError` / `BinaryPayloadTooLargeError`                   |
 
 ### Bypassing Local Validation
+
 - Set `validation: { enabled: false }` in `ClientConfig` to disable local validation and allow invalid frames to reach the wire for negative testing.
 - Direct calls to `client.send(frame)` bypass local validation entirely.
 
@@ -597,7 +648,7 @@ Pre-flight checks fail synchronously before wire frames are dispatched and do **
 
 ---
 
-## What the SDK does *not* do
+## What the SDK does _not_ do
 
 To preserve architectural clarity and adhere to browser constraints, the SDK explicitly does **not**:
 
@@ -615,12 +666,14 @@ To preserve architectural clarity and adhere to browser constraints, the SDK exp
 The SDK includes a comprehensive live conformance test suite running against real Go server instances using the `ws` library polyfill in Node.js.
 
 ### Running Live Conformance
+
 ```bash
 # Run the complete live conformance suite
 bash scripts/live-conformance-js.sh
 ```
 
 The runner:
+
 1. Compiles the Go server binary from `./cmd/server`.
 2. Starts three isolated test server instances:
    - Primary server on port `18080` (full capabilities, rate limits, timeouts).
@@ -629,3 +682,7 @@ The runner:
 3. Executes the Vitest live suite in `test/live/`.
 4. Performs graceful SIGTERM shutdown and verifies clean process exit.
 
+## Documentation
+
+- [Migrating from raw WebSocket](MIGRATION.md) — a phased swap for existing
+  clients.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tonytomo/gosocket-client",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Browser WebSocket client SDK for Universal WebSocket Server: reconnect, session restore, rate limiting, binary channels, presence, and capability pre-flight.",
   "type": "module",
   "license": "MIT",
@@ -43,6 +43,7 @@
   "files": [
     "dist",
     "README.md",
+    "MIGRATION.md",
     "CHANGELOG.md"
   ],
   "scripts": {