@crowdedkingdomstudios/crowdyjs 2.1.2 → 4.0.0

package/README.md

@@ -1,818 +1,224 @@
-# CrowdyJS SDK
+# CrowdyJS
 
-Client SDK for the Crowded Kingdoms GraphQL API with UDP proxy support.
-Handles authentication, real-time subscriptions, and all replication-server
-communication through a single `CrowdyClient` instance.
+The official browser-first TypeScript SDK for **Crowded Kingdoms**. CrowdyJS gives you one typed client that handles auth, the world/replication GraphQL API, and the UDP proxy subscription stream behind a single shared session.
 
-## Links 
-
-- [NPM](https://www.npmjs.com/package/@crowdedkingdomstudios/crowdyjs)  
-- [GitHub](https://github.com/CrowdedKingdoms/CrowdyJS)  
-- [Discord](https://discord.gg/crowdedkingdoms)
-- [YouTube](https://www.youtube.com/@CrowdedKingdoms)
-
-
-## Installation
+## Install
 
 ```bash
 npm install @crowdedkingdomstudios/crowdyjs
 ```
 
-### Node.js
-
-The SDK uses the browser-native `WebSocket` API. In Node.js you need a
-polyfill such as the `ws` package:
-
-```bash
-npm install ws
-```
-
-```javascript
-import WebSocket from 'ws';
-globalThis.WebSocket = WebSocket;
-```
-
-Place this **before** importing `CrowdyClient`.
-
-### Browser
-
-No extra setup needed -- the SDK uses the built-in `WebSocket`.
-
-## Quick Start
-
-```javascript
-import { CrowdyClient } from '@crowdedkingdomstudios/crowdyjs';
-
-const client = new CrowdyClient({
-  graphqlEndpoint: 'https://your-server.com/graphql',
-  wsEndpoint: 'wss://your-server.com/graphql',
-});
-```
-
-If omitted, both endpoints default to `localhost:3000/graphql`.
-
-## Connection Lifecycle
-
-The SDK follows a four-step lifecycle that matches the server protocol:
-
-```
-1. Login         -->  obtain a game token
-2. Subscribe     -->  auto-opens UDP proxy session
-3. Register      -->  tell the game server your chunk position
-4. Send updates  -->  replicated to other clients in range
-```
-
-### 1. Login
-
-```javascript
-const auth = await client.login('user@example.com', 'password');
-// auth.token      -- 64-char hex game token (set automatically)
-// auth.user.email -- logged-in user
-```
-
-Or register a new account:
-
-```javascript
-const auth = await client.register('user@example.com', 'password', 'MyGamertag');
-```
-
-### 2. Subscribe to Notifications
-
-Register one or more notification handlers. The first handler automatically
-opens a WebSocket subscription and a UDP proxy session to the game server --
-no explicit `connectUdpProxy()` call is needed.
-
-```javascript
-const unsub = client.onActorUpdate((notification) => {
-  console.log('Actor:', notification.uuid);
-  console.log('State:', notification.state);
-  console.log('Chunk:', notification.chunkX, notification.chunkY, notification.chunkZ);
-  console.log('Time:', notification.epochMillis);
-});
-```
-
-Handlers are unsubscribed by calling the returned function:
-
-```javascript
-unsub(); // stop receiving ActorUpdateNotification
-```
-
-When all handlers are removed the WebSocket is closed automatically.
-
-### 3. Register in a Chunk
-
-Before other clients can see you, send an initial actor update so the game
-server knows which chunk you occupy. Use a minimal base64 payload (the
-server requires a non-empty `state`).
-
-#### Generating a UUID
-
-Every client must create its own UUID as a **random 32-byte UTF-8 string**.
-This ensures each client produces a globally unique identifier without
-relying on a central registry.
-
-```javascript
-// Node.js
-const MY_UUID = crypto.randomBytes(32).toString('hex').slice(0, 32);
-
-// Browser
-const MY_UUID = Array.from(crypto.getRandomValues(new Uint8Array(16)))
-  .map((b) => b.toString(16).padStart(2, '0'))
-  .join('');
-```
-
-```javascript
-await client.sendActorUpdate({
-  appId: 0,
-  chunk: { x: 0, y: 0, z: 0 },
-  distance: 8,
-  uuid: MY_UUID,
-  state: 'AA==',            // minimal base64 payload for registration
-  sequenceNumber: 1,
-});
-```
-
-Every actor in every client must do this. After registration, the game
-server fans out subsequent updates to all registered clients in range.
-
-### 4. Send Actor Updates
-
-```javascript
-// Build your binary state and base64-encode it
-const stateBuffer = new ArrayBuffer(96);
-const view = new DataView(stateBuffer);
-view.setFloat32(0, posX, true);
-view.setFloat32(4, posY, true);
-view.setFloat32(8, posZ, true);
-// ... fill remaining fields
-
-const base64State = btoa(String.fromCharCode(...new Uint8Array(stateBuffer)));
-
-await client.sendActorUpdate({
-  appId: 0,
-  chunk: { x: 0, y: 0, z: 0 },
-  distance: 8,
-  decayRate: 0,
-  uuid: MY_UUID,
-  state: base64State,
-  sequenceNumber: 2,
-});
-```
-
-### 5. Disconnect
-
-```javascript
-await client.disconnectUdpProxy(); // release the UDP session
-client.close();                    // close WebSocket + clear state
-```
-
-Unsubscribing from notifications stops delivery but does **not** release
-the UDP session. Call `disconnectUdpProxy()` explicitly, or the server
-will release it after 30 seconds of inactivity.
-
-## Request / Notification Mapping
-
-Every accepted spatial request is fanned out by the game server as a
-notification to all clients in range, **including the sender**. Treat
-your own arrival as the round-trip echo for that send (correlate by
-`uuid` + `sequenceNumber`).
-
-| Mutation (you send)         | Notification (everyone in range receives) |
-|-----------------------------|-------------------------------------------|
-| `sendActorUpdate(...)`      | `ActorUpdateNotification`                 |
-| `sendVoxelUpdate(...)`      | `VoxelUpdateNotification`                 |
-| `sendAudioPacket(...)`      | `ClientAudioNotification`                 |
-| `sendTextPacket(...)`       | `ClientTextNotification`                  |
-| `sendClientEvent(...)`      | `ClientEventNotification`                 |
-| *(generic spatial)*         | *(generic spatial)*                       |
-
-`ServerEventNotification` is server-originated (no matching client
-mutation). `GenericErrorResponse` carries failures for any of the above
-— correlate to the offending send via `sequenceNumber`. The legacy
-`ActorUpdateResponse` and `VoxelUpdateResponse` ack types are retired
-on the wire; rely on the self-fanout notification (and
-`GenericErrorResponse` for failures) instead.
-
-> *Generic spatial* refers to wire type `GENERIC_SPATIAL_1` (an arbitrary
-> client-defined payload routed through the same spatial fan-out as the
-> typed messages above). It is not currently exposed by this SDK.
-
-## Subscription Handlers
-
-All spatial notification types share a uniform header:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `appId` | `string` | App ID (tenant / world identifier) |
-| `chunkX` | `string` | Chunk X coordinate |
-| `chunkY` | `string` | Chunk Y coordinate |
-| `chunkZ` | `string` | Chunk Z coordinate |
-| `distance` | `number` | Replication distance (0-8) |
-| `decayRate` | `number` | Delivery decay (0-5) |
-| `uuid` | `string` | Random 32-byte UTF-8 sender UUID |
-| `sequenceNumber` | `number` | uint8 (0-255), wraps |
-| `epochMillis` | `string` | Server UTC timestamp in ms |
-
-Each handler receives a fully-typed notification object:
-
-```javascript
-client.onActorUpdate((n) => { /* n: ActorUpdateNotification -- adds: state */ });
-client.onActorUpdateResponse((n) => { /* n: ActorUpdateResponse */ });
-client.onVoxelUpdate((n) => { /* n: VoxelUpdateNotification -- adds: voxelX/Y/Z, voxelType, voxelState */ });
-client.onVoxelUpdateResponse((n) => { /* n: VoxelUpdateResponse */ });
-client.onClientAudio((n) => { /* n: ClientAudioNotification -- adds: audioData */ });
-client.onClientText((n) => { /* n: ClientTextNotification -- adds: text */ });
-client.onClientEvent((n) => { /* n: ClientEventNotification -- adds: eventType, state */ });
-client.onServerEvent((n) => { /* n: ServerEventNotification -- adds: eventType, state */ });
-client.onGenericError((e) => { /* e: GenericErrorResponse -- sequenceNumber, errorCode only */ });
-```
-
-`GenericErrorResponse` is the only type without the spatial header; it has
-just `sequenceNumber` and `errorCode`.
-
-## Input Parameters
-
-### Common fields
-
-All mutation inputs share these fields:
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `appId` | `number` | yes | -- | App ID (tenant / world identifier) |
-| `chunk` | `{ x, y, z }` | yes | -- | Chunk coordinates (numbers) |
-| `uuid` | `string` | yes | -- | Random 32-byte UTF-8 string (see [Generating a UUID](#generating-a-uuid)) |
-| `distance` | `number` | no | `8` | Replication range (0-8 chunks, Chebyshev) |
-| `decayRate` | `number` | no | `0` | Delivery decay (see table below) |
-| `sequenceNumber` | `number` | no | `0` | uint8 (0-255) for correlation |
-
-### `decayRate` values
-
-| Value | Name | Behavior |
-|-------|------|----------|
-| 0 | None | All clients within `distance` receive every message |
-| 1 | Exponential | Each ring receives half the messages of the previous ring |
-| 2 | Linear 50% | Furthest ring receives 50% of messages |
-| 3 | Linear 25% | Furthest ring receives 25% of messages |
-| 4 | Linear 10% | Furthest ring receives 10% of messages |
-| 5 | Linear 5% | Furthest ring receives 5% of messages |
-
-### `sendActorUpdate`
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `state` | `string` | Base64-encoded binary state (must be non-empty) |
-
-### `sendVoxelUpdate`
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `voxel` | `{ x, y, z }` | Voxel position within the chunk |
-| `voxelType` | `number` | Voxel type ID |
-| `voxelState` | `string` | Base64-encoded voxel state |
-
-### `sendAudioPacket`
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `audioData` | `string` | Base64-encoded compressed audio |
-
-### `sendTextPacket`
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `text` | `string` | Chat message text |
-
-### `sendClientEvent`
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `eventType` | `number` | Custom event type ID |
-| `state` | `string` | Base64-encoded event state |
+CrowdyJS v4 targets browsers by default and uses native `fetch`, `WebSocket`, `crypto`, `btoa`, and `atob`. Node tools can still use the SDK, but must provide browser-compatible globals when opening realtime connections.
 
-## Complete Example
+## Quick start
 
-```javascript
-import WebSocket from 'ws';
-globalThis.WebSocket = WebSocket;
+```ts
+import {
+  BrowserLocalStorageTokenStore,
+  createCrowdyClient,
+} from '@crowdedkingdomstudios/crowdyjs';
 
-import { CrowdyClient } from '@crowdedkingdomstudios/crowdyjs';
-
-const client = new CrowdyClient({
-  graphqlEndpoint: 'https://your-server.com/graphql',
-  wsEndpoint: 'wss://your-server.com/graphql',
-});
-
-const MY_UUID = crypto.randomBytes(32).toString('hex').slice(0, 32);
-
-// 1. Login
-await client.login('user@example.com', 'password');
-
-// 2. Subscribe (auto-opens UDP proxy session)
-const unsubActors = client.onActorUpdate((n) => {
-  console.log(`Actor ${n.uuid} at chunk (${n.chunkX},${n.chunkY},${n.chunkZ})`);
-  console.log(`  state=${n.state} seq=${n.sequenceNumber} t=${n.epochMillis}`);
-});
-
-const unsubErrors = client.onGenericError((e) => {
-  console.error(`Error: ${e.errorCode} (seq ${e.sequenceNumber})`);
-});
-
-// 3. Register in chunk
-await client.sendActorUpdate({
-  appId: 0,
-  chunk: { x: 0, y: 0, z: 0 },
-  distance: 8,
-  uuid: MY_UUID,
-  state: 'AA==',
-  sequenceNumber: 1,
+const client = createCrowdyClient({
+  // Game API (world data + UDP proxy)
+  httpUrl: 'https://game.example.com',
+  wsUrl: 'wss://game.example.com',
+  // Management API (login, register, profile)
+  managementUrl: 'https://management.example.com',
+  tokenStore: new BrowserLocalStorageTokenStore(),
+  realtime: {
+    retryAttempts: 8,
+    waitTimeoutMs: 5000,
+  },
 });
 
-// 4. Send updates in a loop
-let seq = 2;
-const interval = setInterval(async () => {
-  const buf = new Uint8Array(96);
-  crypto.getRandomValues(buf);
-  const state = btoa(String.fromCharCode(...buf));
-
-  await client.sendActorUpdate({
-    appId: 0,
-    chunk: { x: 0, y: 0, z: 0 },
-    distance: 8,
-    uuid: MY_UUID,
-    state,
-    sequenceNumber: seq++ % 256,
-  });
-}, 100);
-
-// 5. Cleanup
-clearInterval(interval);
-unsubActors();
-unsubErrors();
-await client.disconnectUdpProxy();
-client.close();
-```
-
-## Building a Real-Time Game
-
-The Quick Start above is enough to send and receive packets. Once you wire
-the SDK into an actual game these patterns will save you a lot of debugging
-time. 
-
-### Decouple the network from the render loop
-
-Browsers throttle `requestAnimationFrame` aggressively when the tab is
-backgrounded — often to ~1 fps or fully paused. If your `sendActorUpdate`
-cadence is driven by the render loop, your character will appear frozen
-to other players the moment a user switches tabs. Drive sends with
-`setInterval` (which keeps firing in background tabs):
-
-```javascript
-const SEND_INTERVAL_MS = 100; // 10 Hz
-const sendId = setInterval(async () => {
-  await client.sendActorUpdate({
-    appId, chunk: getCurrentChunk(),
-    uuid: MY_UUID,
-    state: encodeLocalPose(),
-    sequenceNumber: nextSeq(),
-  });
-}, SEND_INTERVAL_MS);
-```
-
-Apply incoming notifications **inside the WS callback**, not buffered for
-the next frame. That keeps your data model in sync with real network
-arrivals even while the render loop is paused:
-
-```javascript
-client.onActorUpdate((notification) => {
-  registry.applyRemote(notification, performance.now()); // synchronous
-});
-```
-
-The renderer should treat the registry as a *view source* — sprites
-interpolate toward registry-held targets each frame, but the registry
-itself is mutated only by the network layer.
-
-### Verify the round-trip with self-fanout
-
-The game server fans out every accepted actor update to all clients in
-the chunk, **including the sender**. Use your own arrival as the WS
-round-trip echo (correlate by `uuid` + `sequenceNumber`):
-
-```javascript
-let lastSendAt = null, lastSendSeq = null;
-let lastEchoAt = null, lastEchoSeq = null;
-
-async function sendOnce() {
-  const seq = nextSeq();
-  const ok = await client.sendActorUpdate({ /* ... */, sequenceNumber: seq });
-  if (ok) { lastSendAt = performance.now(); lastSendSeq = seq; }
+// Restore a previous session if there is one, otherwise log in.
+await client.session.restore();
+if (!client.session.getToken()) {
+  await client.auth.login({ email: 'player@example.com', password: 'secret' });
 }
 
-client.onActorUpdate((n) => {
-  if (n.uuid === MY_UUID) {
-    lastEchoAt = performance.now();
-    lastEchoSeq = n.sequenceNumber;
-    return;          // don't render ourselves as a remote
-  }
-  registry.applyRemote(n);
-});
+// Fetch the per-app bootstrap (version requirements, UDP availability, spatial limits).
+const bootstrap = await client.serverStatus.gameClientBootstrap('1');
+console.log(bootstrap.versionInfo.minimumClientVersion);
 ```
 
-`ActorUpdateResponse` is retired on the wire — the self-uuid notification
-is the canonical ack. `GenericErrorResponse` carries failures (correlate
-via `sequenceNumber`).
+Both endpoints share a single `AuthState`, so once `client.auth.login()` returns, every subsequent SDK call (against either endpoint) carries the bearer token automatically.
 
-### Keep the UDP session alive
+If `managementUrl` is omitted, the SDK falls back to `httpUrl` for backwards-compat with the single-endpoint deployment.
 
-The server times the UDP proxy session out after **30 s** of inactivity in
-either direction. A 10 Hz send loop trivially keeps it warm. If your
-sender pauses (e.g. no local input → no diff to send), the next mutation
-will lazily re-establish via `ensureUdpProxyConnection` — `connectUdpProxy()`
-is idempotent. There is no need for a separate keepalive.
+## Sub-clients at a glance
 
-### Detect and recover from connection drops
+| Sub-client | What it does |
+|---|---|
+| `client.auth` | Register, log in, log out, password reset, email confirmation. |
+| `client.users` | `me`, `updateGamertag`, profile reads. |
+| `client.session` | Token store, `restore()`, `getToken()`, manual `setToken()`. |
+| `client.serverStatus` | `gameClientBootstrap(appId)` — per-app version info, UDP status, spatial limits. |
+| `client.chunks`, `client.voxels`, `client.actors`, `client.avatars`, `client.state` | World data reads + writes. |
+| `client.teleport` | Teleport requests. |
+| `client.udp` | UDP proxy subscriptions + spatial mutations (`sendActorUpdate`, `sendVoxelUpdate`, `sendAudioPacket`, `sendTextPacket`, `sendClientEvent`). |
+| `client.realtime` | Connection status, manual `connect()` / `disconnect()`, `onStatus()` listener. |
+| `client.world(appId)` | Higher-level helpers for browser games (`actor.join`, `actor.sendState`, `actor.sendText`). |
 
-The SDK does not auto-reconnect a dropped WebSocket: `onclose` only nulls
-the internal client. Track wall-clock arrival time of *any* notification
-and force a fresh subscription if it goes silent:
+Auth and user reads always target `managementUrl`. Everything else targets `httpUrl` / `wsUrl`.
 
-```javascript
-let lastNotificationAt = performance.now();
-function bumpActivity() { lastNotificationAt = performance.now(); }
+## Game-loop lifecycle
 
-// Wire bumpActivity into every handler you register (actor, voxel, text,
-// audio, event, server event, error). Or wrap your subscribe call.
-client.onActorUpdate((n) => { bumpActivity(); /* ... */ });
-client.onGenericError((e) => { bumpActivity(); /* ... */ });
+1. Authenticate with `client.auth.login()` or restore a previous token through `client.session.restore()`.
+2. Subscribe to UDP proxy notifications with `client.udp.subscribe()` (the SDK will open the realtime socket on demand).
+3. Join a chunk by sending an initial actor update.
+4. Send actor, voxel, text, audio, and client-event updates through `client.udp` or the higher-level `client.world(appId)` helpers.
+5. Call `client.udp.disconnect()` when leaving the world.
+6. Call `client.close()` when disposing the SDK instance.
 
-setInterval(() => {
-  if (performance.now() - lastNotificationAt > 8000) {
-    forceResubscribe();    // see below
-  }
-}, 1000);
-```
+## Per-app routing
 
-To force a fresh subscription, call your unsubscribe handles and
-`subscribe()` again — the SDK opens a new WebSocket on a fresh subscribe.
-Then send one `sendActorUpdate` to re-register your chunk position so
-others see you immediately.
+When a player is about to join an app, query its routing fields on the management API first:
 
-```javascript
-function forceResubscribe() {
-  unsubAll();
-  unsubAll = installSubscriptions(); // re-registers handlers
-  void client.sendActorUpdate({ /* re-register */ });
+```graphql
+query AppForRouting($id: BigInt!) {
+  app(id: $id) {
+    appId
+    splitMode
+    gameApiUrl
+  }
 }
 ```
 
-### Visibility-driven heal
-
-Browsers sometimes kill the WebSocket while a tab is hidden. Listen for
-`visibilitychange` and trigger a heal on return. Pause your stale-actor
-reaper (next section) while hidden so you don't drop remotes during a
-period when you couldn't have heard from them anyway.
-
-```javascript
-document.addEventListener('visibilitychange', () => {
-  if (document.hidden) {
-    pauseReaper('tab_hidden');
-    return;
-  }
-  forceResubscribe();
-  resumeReaperWithGrace('tab_hidden', 5000);
+If `splitMode && gameApiUrl`, the app lives behind its own Game API deployment. Build a **second** `CrowdyClient` with `httpUrl: gameApiUrl` (and the matching `wsUrl`) **sharing the same `tokenStore` as the first client**, then drive gameplay through that client. Apps without `splitMode` keep working against the default `httpUrl` you configured.
+
+## Realtime notifications
+
+```ts
+const unsubscribe = client.udp.subscribe({
+  actorUpdate: (event) => {
+    console.log(event.uuid, event.state);
+  },
+  voxelUpdate: (event) => { /* ... */ },
+  text: (event) => { /* ... */ },
+  audio: (event) => { /* ... */ },
+  clientEvent: (event) => { /* ... */ },
+  serverEvent: (event) => { /* ... */ },
+  singleActorMessage: (event) => {
+    // A direct actor-to-actor message addressed to you.
+    console.log(event.uuid, event.payload); // payload is base64
+  },
+  genericError: (event) => {
+    console.warn(event.sequenceNumber, event.errorCode);
+  },
+  connectionEvent: (event) => {
+    console.warn(event.code, event.message);
+  },
+  error: (error) => {
+    console.error(error.code, error.message);
+  },
 });
-```
-
-### Track presence with timestamps
-
-There is no live "who is in this chunk" query — `client.actors.list({ chunk })`
-returns the persisted DB roster, not the live UDP set. Each remote actor's
-presence is inferred from the last notification you saw from them:
 
-```javascript
-const remotes = new Map(); // uuid -> { firstSeenAt, lastUpdateAt, pose }
-
-client.onActorUpdate((n) => {
-  if (n.uuid === MY_UUID) return;
-  const now = performance.now();
-  const existing = remotes.get(n.uuid);
-  if (!existing) {
-    remotes.set(n.uuid, { firstSeenAt: now, lastUpdateAt: now, pose: decode(n.state) });
-  } else {
-    existing.lastUpdateAt = now;
-    existing.pose = decode(n.state);
-  }
+client.realtime.onStatus((status) => {
+  console.log('realtime:', status);
 });
-```
 
-Periodically reap remotes that stopped sending. **Suspend reaping while
-the tab is hidden or the WS is unhealthy** — otherwise you will evict
-remotes simply because you couldn't have heard from them.
-
-```javascript
-const STALE_TIMEOUT_MS = 10_000;
-setInterval(() => {
-  if (document.hidden || isWsStale()) return;
-  const now = performance.now();
-  for (const [uuid, r] of remotes) {
-    if (now - r.lastUpdateAt > STALE_TIMEOUT_MS) remotes.delete(uuid);
-  }
-}, 3000);
+// Later:
+unsubscribe();
 ```
 
-Grant a grace window after every heal (visibility return, force-resubscribe)
-before reaping resumes — that lets remotes re-broadcast on their own
-cadence first.
-
-### Suggested module layout
+The SDK uses the `graphql-transport-ws` protocol through `graphql-ws`, reconnects with backoff, re-reads the current token before reconnecting, and resubscribes automatically.
 
-A clean separation makes the rest much easier:
+## Spatial sends
 
-```
-GameSession (singleton, lives above your scenes / views)
-├── ActorRegistry       data + emitter; mutated only in WS callbacks
-├── ActorSender         setInterval sends; reads pose from your game
-├── NetworkHealth       visibility / WS-stale monitor + heal
-└── (uses) CrowdyClient
-```
-
-Sprites and HUD become *views* over `ActorRegistry`. Scene shutdown only
-destroys sprites; the singleton session and registry persist, so revisiting
-the scene (or returning from a hidden tab) does not lose presence state.
-Recreating sprites on scene re-entry walks the existing registry entries.
-
-### Diagnostics worth logging
-
-When something goes wrong, these are the values you'll wish you had:
-
-- `sendCount`, `lastSendAt`, `lastSendSeq` — your local sender's history.
-- `echoCount`, `lastEchoAt`, `lastEchoSeq`, `msSinceLastEcho` — the WS
-  round-trip via self-fanout. If `echoCount` flatlines while `sendCount`
-  climbs, the WS path is wedged.
-- `notificationsByType` — map of `__typename` to arrival count. Useful for
-  confirming what the server is actually emitting.
-- Per-remote `lastUpdateAt` / `msSinceUpdate`.
-- `visibilityState`, `hidden`, `lastWsResubscribeAt`, `reaperPaused`.
-
-Expose them on a global handle (e.g. `window.__MYGAME_NET__.snapshot()`)
-during development — a structured JSON snapshot is far easier to triage
-than a wall of streaming logs.
-
-## API Reference
-
-### Constructor
-
-```typescript
-new CrowdyClient(config?: CrowdyClientConfig)
-```
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `graphqlEndpoint` | `string` | `http://localhost:3000/graphql` | HTTP endpoint for mutations/queries |
-| `wsEndpoint` | `string` | `ws://localhost:3000/graphql` | WebSocket endpoint for subscriptions |
-| `timeout` | `number` | `60000` | HTTP request timeout in ms |
-
-### Authentication
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `login(email, password)` | `Promise<AuthResponse>` | Login and store the game token |
-| `register(email, password, gamertag?)` | `Promise<AuthResponse>` | Register and store the game token |
-| `getAuthToken()` | `string \| null` | Get the current game token |
-
-### UDP Proxy
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `connectUdpProxy()` | `Promise<UdpProxyConnectionStatus>` | Open a UDP session (idempotent: returns the existing status if one is open). Optional — `udpNotifications` and any `send*` mutation also create a session lazily. |
-| `disconnectUdpProxy()` | `Promise<boolean>` | Release the UDP session and complete the current `udpNotifications` stream. To force a fresh socket: call `disconnectUdpProxy()` then `connectUdpProxy()`. |
-| `getConnectionStatus()` | `Promise<UdpProxyConnectionStatus>` | Check if a UDP session is active |
-
-### Mutations
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `sendActorUpdate(input)` | `Promise<boolean>` | Send an actor state update |
-| `sendVoxelUpdate(input)` | `Promise<boolean>` | Modify a voxel in a chunk |
-| `sendAudioPacket(input)` | `Promise<boolean>` | Send voice audio data |
-| `sendTextPacket(input)` | `Promise<boolean>` | Send chat text |
-| `sendClientEvent(input)` | `Promise<boolean>` | Send a custom event |
-
-### Subscriptions
-
-| Method | Handler receives | Description |
-|--------|-----------------|-------------|
-| `onActorUpdate(handler)` | `ActorUpdateNotification` | Another client's actor state |
-| `onActorUpdateResponse(handler)` | `ActorUpdateResponse` | Server ack for your actor update |
-| `onVoxelUpdate(handler)` | `VoxelUpdateNotification` | A voxel was modified |
-| `onVoxelUpdateResponse(handler)` | `VoxelUpdateResponse` | Server ack for your voxel update |
-| `onClientAudio(handler)` | `ClientAudioNotification` | Voice audio from another client |
-| `onClientText(handler)` | `ClientTextNotification` | Chat text from another client |
-| `onClientEvent(handler)` | `ClientEventNotification` | Custom event from another client |
-| `onServerEvent(handler)` | `ServerEventNotification` | Event from the game server |
-| `onGenericError(handler)` | `GenericErrorResponse` | Error from the server |
-
-All subscription methods return an `UnsubscribeFn` -- call it to remove
-the handler.
-
-### Cleanup
-
-| Method | Description |
-|--------|-------------|
-| `close()` | Close the WebSocket, remove all handlers, clear auth state |
-
-## Domain APIs
-
-In addition to the replication-focused methods documented above, the
-client exposes a set of typed *domain wrappers* that cover the rest of
-the Crowded Kingdoms GraphQL API. Each wrapper is mounted on the
-`CrowdyClient` instance and uses the same auth token / base URL as the
-replication API. Operation inputs and return shapes are generated from
-the live `schema.gql` via `graphql-codegen`, so they stay in lockstep
-with the server.
-
-```javascript
-const client = new CrowdyClient({ graphqlEndpoint: '...' });
-await client.auth.login({ email, password });
-```
-
-### `client.auth` -- authentication & session lifecycle
-
-```javascript
-await client.auth.register({ email, password, gamertag });
-await client.auth.login({ email, password });
-await client.auth.confirmEmail('...token...');
-await client.auth.requestPasswordReset('user@example.com');
-await client.auth.resetPassword({ token: '...', newPassword: '...' });
-await client.auth.resendConfirmationEmail('user@example.com');
-await client.auth.changePassword('old', 'new');
-await client.auth.logout();
-await client.auth.logoutAllDevices();
-```
-
-The legacy shortcuts `client.login(email, password)` and
-`client.register(email, password, gamertag?)` are kept for backwards
-compatibility and delegate to `client.auth`.
-
-### `client.users` -- user directory & profile
-
-```javascript
-const me   = await client.users.me();
-const u    = await client.users.byId('123');
-const all  = await client.users.list();
-const list = await client.users.byGamertag('Gandalf');
-const list2 = await client.users.byEmail('a@b.c');
-
-await client.users.updateGamertag({ gamertag: 'Newname', disambiguation: '0001' });
-await client.users.updateUserState({ state: 'base64...' });
-```
-
-### `client.orgs` -- organizations / studios
-
-```javascript
-const org = await client.orgs.create({ name: 'Acme', slug: 'acme' });
-const byId   = await client.orgs.byId(org.orgId);
-const bySlug = await client.orgs.bySlug('acme');
-const members = await client.orgs.members(org.orgId);
-
-await client.orgs.inviteMember({ orgId: org.orgId, userId: '42' });
-const token = await client.orgs.createOrgToken({ orgId: org.orgId, label: 'CI' });
-```
-
-### `client.appAccess` -- app access tiers and grants
-
-```javascript
-const tiers = await client.appAccess.listTiers(appId);
-const mine  = await client.appAccess.myAccess(appId);
-
-await client.appAccess.createTier({ appId, name: 'Pro', isFree: false, tierOrder: 2 });
-await client.appAccess.grant({ appId, userId: '42', tierId });
-await client.appAccess.revoke(appId, '42');
-```
-
-### `client.billing` -- wallets & app budgets
-
-```javascript
-const wallet = await client.billing.balance(orgId);
-const txns   = await client.billing.transactions({ orgId, limit: 50, offset: 0 });
-const budget = await client.billing.appBudget(orgId, appId);
+```ts
+const response = await client.udp.sendActorUpdateAndWait({
+  appId: '1',
+  chunk: { x: '0', y: '0', z: '0' },
+  uuid: '0123456789abcdef0123456789abcdef',
+  state: 'AA==',           // base64-encoded payload
+  distance: 8,
+  decayRate: 1,
+});
 
-await client.billing.setAppBudget({ orgId, appId, monthlyLimitCents: '5000' });
+console.log(response.__typename, response.sequenceNumber);
 ```
 
-### `client.quotas` -- per-org / per-app service quotas
+The plain `sendActorUpdate`, `sendVoxelUpdate`, `sendAudioPacket`, `sendTextPacket`, and `sendClientEvent` methods return the GraphQL mutation result immediately. The `AndWait` variants allocate a `sequenceNumber` when one is missing and wait for either a matching notification or `GenericErrorResponse`.
 
-```javascript
-const orgQ = await client.quotas.byOrg(orgId);
-const appQ = await client.quotas.byApp(appId);
+### Actor-to-actor messages
 
-const q = await client.quotas.set({
-  orgId,
-  appId,
-  metric: 'voxel_updates',
-  limitValue: '1000000',
-  period: 'month',
+```ts
+// Delivered only to the actor whose UUID matches `targetUuid`; you must know
+// that actor's current chunk. Fire-and-forget — the sender gets no echo, so
+// there is no `AndWait` variant. The target receives a
+// `SingleActorMessageNotification` on its subscription.
+await client.udp.sendSingleActorMessage({
+  appId: '1',
+  chunk: { x: '7', y: '1', z: '2' }, // the TARGET actor's chunk
+  targetUuid: '0123456789abcdef0123456789abcdef',
+  payload: 'aGVsbG8=', // base64; embed sender identity here if you need it
 });
-await client.quotas.delete(q.quotaId);
 ```
 
-### `client.chunks` -- chunk + LOD queries and admin mutations
+## World helpers
 
-```javascript
-const chunk    = await client.chunks.get({ appId, coordinates: { x: '0', y: '0', z: '0' } });
-const lods     = await client.chunks.getLods({ appId, coordinates, lodLevels: [0, 1, 2] });
-const nearby   = await client.chunks.byDistance({ appId, centerCoordinate: coordinates, maxDistance: 4 });
-const voxels   = await client.chunks.voxelList({ appId, coordinates });
+```ts
+const world = client.world('1');
+const actor = world.actor();
 
-await client.chunks.update({ appId, coordinates, voxels: '...base64...' });
-await client.chunks.updateState({ appId, coordinates, chunkState: '...' });
-await client.chunks.updateLods({ appId, coordinates, lods: [{ level: 0, data: '...' }] });
-```
-
-### `client.voxels` -- voxel queries, history, rollback
+await actor.join({ x: '0', y: '0', z: '0' });
+await actor.sendState('AA==');
+await actor.sendText('hello nearby players');
 
-```javascript
-await client.voxels.list({ appId, coordinates });
-await client.voxels.listByDistance({ appId, centerCoordinate: coordinates, maxDistance: 2 });
-await client.voxels.update({ appId, coordinates, location, voxelType: 5, state: '...' });
-await client.voxels.history({ appId, userId: '42', limit: 100 });
-await client.voxels.rollback({ appId, userId: '42', from, to, dryRun: true });
+// Direct message to one other actor (you supply its UUID + current chunk):
+await actor.sendToActor(
+  '0123456789abcdef0123456789abcdef',
+  'aGVsbG8=', // base64 payload
+  { x: '7', y: '1', z: '2' },
+);
 ```
 
-### `client.actors` -- persisted actors (CRUD)
+The world helpers are thin wrappers over `client.udp.*` with the appId pre-bound — convenient for browser games. Advanced callers can always use `client.udp.*` with the generated GraphQL input types directly.
 
-```javascript
-const a = await client.actors.create({
-  appId, uuid: '...', chunk: { x: '0', y: '0', z: '0' },
-});
-await client.actors.get(a.uuid);
-await client.actors.list({ appId });
-await client.actors.batchLookup({ uuids: [a.uuid] });
-await client.actors.update(a.uuid, { publicState: '...' });
-await client.actors.updateState(a.uuid, { publicState: '...' });
-await client.actors.delete(a.uuid);
-```
+## Errors
 
-For high-frequency replication, continue to use the existing
-`client.sendActorUpdate(...)` UDP path -- it is unchanged.
+Transport and protocol failures throw structured error classes:
 
-### `client.teleport`
+- `CrowdyHttpError` — non-2xx response from a GraphQL endpoint.
+- `CrowdyGraphQLError` — preserves every GraphQL error including `path` and `extensions.code`.
+- `CrowdyNetworkError` — network-level failure (DNS, TLS, connection refused).
+- `CrowdyTimeoutError` — request or `AndWait` timed out.
+- `CrowdyRealtimeError` — realtime subscription couldn't be established or was dropped.
+- `CrowdyProtocolError` — server response failed schema validation.
 
-```javascript
-const result = await client.teleport.request({
-  appId,
-  chunkAddress: { x: '0', y: '0', z: '0' },
-  voxelAddress: { x: 0, y: 0, z: 0 },
-  UUID: '...',
-});
-```
+## Auth notes
 
-### `client.state` -- per-user, per-app state
+- Use `client.auth.setToken(token)` if you need to seed a token externally (e.g. when restoring auth from a non-default storage).
+- `client.session.restore()` reads from the configured `tokenStore`. `BrowserLocalStorageTokenStore` is provided; bring your own for SSR or Node usage.
+- A single `AuthState` is observed by both the HTTP client and the realtime socket, so HTTP and WebSocket auth can never drift.
 
-```javascript
-await client.state.update({ appId, state: 'base64...' });
-await client.state.getOne(appId);
-await client.state.getAll();
-await client.state.delete(appId);
-```
+## What's NOT in CrowdyJS
 
-### `client.serverStatus`
+CrowdyJS focuses on the **game-client surface**: auth, world data, UDP proxy, profile reads. The following operations are **not** exposed by the SDK and should be called against the management GraphQL API directly (with a server-side token, typically from a studio backend):
 
-```javascript
-await client.serverStatus.serverWithLeastClients();
-await client.serverStatus.listAll();
-await client.serverStatus.listActiveGraphqlServers();
-await client.serverStatus.versionInfo();
-```
+- Org / app / billing / payments / quotas operations
+- Access-tier and runtime-permission administration
+- Game-token issuance / revocation
+- Marketplace and catalog management
 
-### `client.apps`
+The SDK is intentionally scoped to client-side, end-user-facing flows.
 
-The current schema does not expose direct CRUD for the App entity --
-apps are provisioned out of band. `client.apps` exists as a stable
-namespace for future additions; in the meantime use `client.appAccess`,
-`client.state`, `client.billing`, `client.chunks`, and `client.voxels`
-for app-scoped functionality.
+## Low-level GraphQL access
 
-## Codegen
+Game-client methods are first-class, but generated operation documents are also available through a transport escape hatch:
 
-Operations live as `.graphql` files under `src/operations/<domain>/`.
-After editing them or pulling a new schema, regenerate the typed
-documents:
+```ts
+import { VersionInfoDocument } from '@crowdedkingdomstudios/crowdyjs/generated';
 
-```bash
-npm run codegen        # one-shot
-npm run codegen:watch  # watch mode
+const data = await client.graphql.request(VersionInfoDocument);
 ```
 
-`npm run build` runs codegen automatically via `prebuild`.
+Most consumers should prefer the typed methods on `client.auth`, `client.users`, `client.udp`, `client.serverStatus`, and `client.world()`.
 
-## TypeScript
+## Migration
 
-The SDK is written in TypeScript and ships type declarations. All
-notification interfaces, input types, and handler signatures are fully
-typed for IDE autocomplete and compile-time safety. Schema-derived
-input/output types (e.g. `CreateOrganizationInput`, `Organization`,
-`AppBudget`) are re-exported from the package root.
+See [MIGRATION.md](MIGRATION.md) for breaking changes between SDK majors.
 
 ## License