dredless 0.7.0 → 1.0.0

package/docs/BROWSER_API.md

@@ -1,100 +1,181 @@
-# Dredless Browser API
+# Browser setup
 
-This document covers the browser-specific top-level API: ambient browser sessions, browser cookie handling, and browser start/join helpers.
+[Documentation index](README.md) · [Getting started](GETTING_STARTED.md) · [API reference](API_REFERENCE.md)
 
-Use this entrypoint in browser contexts:
+## Contents
+
+- [Execution context](#execution-context)
+- [Bundled imports](#bundled-imports)
+- [Global script](#global-script)
+- [Session methods](#session-methods)
+- [Connection methods](#connection-methods)
+- [Attach to an existing socket](#attach-to-an-existing-socket)
+
+## Execution context
+
+Browser sessions use the browser's ambient cookie jar with `credentials: "include"`. They do not isolate identities like
+Node sessions. Changing an anonymous key affects the ambient session.
+
+Use a Drednot page integration or a content-script context with access to the site's cookies and origin. Background
+pages, popups, workers, and unrelated origins may lack that access. Importing the package does not bypass browser
+cookie, origin, or CORS restrictions.
+
+Browsers manage `Cookie` and `Set-Cookie` themselves. JavaScript cannot install a separate cookie jar or custom
+authentication headers on a browser WebSocket.
+
+## Bundled imports
 
 ```js
-import Dredless, { BrowserSession } from "dredless/browser";
+import Dredless, {BrowserSession, DredlessClient} from "dredless/browser";
 ```
 
-Normal browser usage:
+Prefer this explicit entrypoint for browser types. Shared machine constants and protocol tools are named exports; the
+default export is the runtime namespace, not the entire module.
+
+**Fragment:** use the site's existing login without creating a new anonymous identity:
 
 ```js
-const session = await Dredless.createAnonSession();
+const session = await Dredless.createSession();
 const servers = await Dredless.fetchServers();
-const ships = await Dredless.fetchShips(servers[0]);
-const client = await Dredless.startShip(servers[0], ships[0]);
+const server = servers[0];
+if (!server) throw new Error("No servers found");
+console.log(await session.fetchShips(server));
 ```
 
-The browser API uses the current browser cookie jar with `credentials: "include"`. Browser JavaScript cannot read `Set-Cookie`, cannot set the `Cookie` header, and cannot set custom WebSocket headers, so browser authentication is ambient rather than multi-session.
+## Global script
 
-Shared input shapes such as `Server`, `ServerRef`, `Ship`, `ShipRef`, and `ShipSpec` are documented in [API_REFERENCE.md](./API_REFERENCE.md#common-input-types). Shared client/world/entity/domain APIs are also documented in [API_REFERENCE.md](./API_REFERENCE.md).
+Run this only in an appropriate browser context. Use a bundle version that matches the API you intend to call; an
+unversioned CDN URL follows published releases rather than this repository's current checkout.
 
-## `DredlessBrowser` Namespace
+```html
 
-`dredless/browser` exports a browser-first namespace. It assumes the current browser cookie jar and does not expose `Session` or `AnonSession`.
+<script src="https://cdn.jsdelivr.net/npm/dredless/dist/browser/dredless.global.js"></script>
+<script>
+    (async () => {
+        const session = await Dredless.createSession();
+        console.log((await session.fetchAccountStatus()).account);
+    })().catch(console.error);
+</script>
+```
+
+The global is `Dredless`, containing the browser runtime namespace. It does not expose every named ESM export. Use
+bundled imports when you need additional named helpers.
+
+## Session methods
 
 ```ts
-interface DredlessBrowserNamespace {
-  BrowserSession: typeof BrowserSession;
-  Connection: typeof Connection;
-  DredlessClient: typeof DredlessClient;
-  browserSession: typeof browserSession;
-  createBrowserSession: typeof createBrowserSession;
-  createSession: typeof createSession;
-  createAnonSession: typeof createAnonSession;
-  createAnonToken: typeof createAnonToken;
-  fetchAnonKey: typeof fetchAnonKey;
-  setBrowserSession: typeof setBrowserSession;
-  fetchAccountStatus: typeof fetchAccountStatus;
-  fetchNoticeVersion: typeof fetchNoticeVersion;
-  fetchGameVersion: typeof fetchGameVersion;
-  fetchServers: typeof fetchServers;
-  fetchServerStatus: typeof fetchServerStatus;
-  fetchServerStatuses: typeof fetchServerStatuses;
-  fetchShips: typeof fetchShips;
-  fetchShipList: typeof fetchShipList;
-  joinShip: typeof joinShip;
-  startShip: typeof startShip;
-  startNewShip: typeof startNewShip;
-  joinInvite: typeof joinInvite;
-}
+new BrowserSession(baseUrl ? : string)
+:
+BrowserSession;
+Dredless.browserSession(baseUrl ? : string)
+:
+BrowserSession;
+Dredless.createBrowserSession(baseUrl ? : string)
+:
+BrowserSession;
+Dredless.setBrowserSession(session ? : BrowserSession | null)
+:
+BrowserSession | null;
+Dredless.createSession(noticeVersion ? : number | null, baseUrl ? : string)
+:
+Promise<BrowserSession>;
+Dredless.createAnonSession(anonKey ? : string | null, noticeVersion ? : number | null,
+    baseUrl ? : string)
+:
+Promise<BrowserSession>;
+Dredless.fetchAnonKey(noticeVersion ? : number | null, baseUrl ? : string)
+:
+Promise<string>;
+Dredless.createAnonToken(noticeVersion ? : number | null, baseUrl ? : string)
+:
+Promise<string>;
+
+session.fetchAccountStatus()
+:
+Promise<unknown>;
+session.readAnonKey()
+:
+Promise<string>;
+session.fetchAnonKey(noticeVersion ? : number | null)
+:
+Promise<string>;
 ```
 
-`createSession(noticeVersion?, baseUrl?)` initializes the ambient browser session, fetches account status, and returns the active `BrowserSession`.
+`createSession()` refreshes status on the ambient session. `createAnonSession()` applies a supplied key or posts an
+anonymous login, then refreshes status. `fetchAnonKey()`/`createAnonToken()` request a new key. Key retrieval uses
+`cookieStore` or `document.cookie`; it rejects when the key is not readable even if the login request succeeded.
 
-`createAnonSession(anonKey?, noticeVersion?, baseUrl?)` creates or applies an anonymous browser session. If `anonKey` is omitted, it posts to `/account/login/anon`, then reads `anon_key` through `cookieStore` or `document.cookie`. If the key cannot be read, it throws. If `anonKey` is provided, it is written to the ambient cookie jar when possible. The return value is still the active `BrowserSession`, not an isolated cookie jar.
+`BrowserSession` inherits [account methods](ACCOUNT.md), HTTP `request()`, ship reads, and client factories from the
+session API. It uses browser-owned cookies and does not expose a registered-account login flow. Its JavaScript-readable
+`gameSession`/`gameToken` properties may be empty even when browser authentication works.
 
-`fetchAnonKey(noticeVersion?, baseUrl?)` / `createAnonToken(noticeVersion?, baseUrl?)` posts to `/account/login/anon` and returns the JS-readable `anon_key`. It throws if the login succeeds but the key is not readable through `cookieStore` or `document.cookie`.
+## Connection methods
 
-Browser support is tested in page and content-script contexts on `drednot.io`. Background pages, popups, workers, and other non-page contexts are unlikely to expose `drednot.io` cookies to this API.
+Session methods have the same arguments as [Node session methods](NODE_API.md#join-start-and-invites). Top-level browser
+helpers take the ambient session as an optional final argument:
 
-`fetchShips(server)` and `fetchShipList(server)` use the default ambient `BrowserSession`. Pass an explicit `BrowserSession` as the last argument only when targeting a different `baseUrl`.
+```ts
+Dredless.fetchShips(server
+:
+ServerRef, session ? : BrowserSession | null
+):
+Promise<Ship[]>;
+Dredless.fetchShipList(server
+:
+ServerRef, session ? : BrowserSession | null
+):
+Promise<ShipList>;
+Dredless.fetchAccountStatus(session ? : BrowserSession | null)
+:
+Promise<unknown>;
+Dredless.joinShip(server
+:
+ServerRef, ship ? : ShipRef, session ? : BrowserSession | null
+):
+Promise<DredlessClient>;
+Dredless.startShip(server
+:
+ServerRef, ship ? : ShipRef, session ? : BrowserSession | null
+):
+Promise<DredlessClient>;
+Dredless.startNewShip(server
+:
+ServerRef, name ? : string, color ? : string,
+    session ? : BrowserSession | null
+):
+Promise<DredlessClient>;
+Dredless.joinInvite(server
+:
+ServerRef, code
+:
+string, session ? : BrowserSession | null
+):
+Promise<DredlessClient>;
+```
 
-`joinShip`, `startShip`, `startNewShip`, and `joinInvite` return ready `DredlessClient` instances just like the Node helpers.
+The HTTP join/start distinctions and readiness conditions are the same as Node. `fetchServers`, `fetchServerStatus`,
+`fetchServerStatuses`, `fetchGameVersion`, and `fetchNoticeVersion` are also on the browser namespace. The browser
+namespace does not contain the Node `Session`/`AnonSession` constructors.
 
-## `BrowserSession`
+## Attach to an existing socket
 
-`BrowserSession` is the browser counterpart to `Session`, but it is ambient-cookie based. It cannot read `Set-Cookie` and cannot set websocket headers, so authentication must be accepted by the browser's cookie jar.
+**Fragment:** `socket` is a WebSocket you already obtained from your integration. Attach early: Dredless cannot
+reconstruct frames the socket received before attachment.
 
-```ts
-class BrowserSession {
-  constructor(baseUrl?: string);
-  baseUrl: string;
-  ambientAuth: true;
-
-  readAnonKey(): Promise<string>;
-  fetchAnonKey(noticeVersion?: number | null): Promise<string>;
-  fetchAccountStatus(): Promise<unknown>;
-  fetchShips(server: ServerRef): Promise<Ship[]>;
-  fetchShipList(server: ServerRef): Promise<ShipList>;
-
-  joinShipConnection(server: ServerRef, ship?: ShipRef): Promise<Connection>;
-  startShipConnection(server: ServerRef, ship?: ShipRef): Promise<Connection>;
-  startNewShipConnection(server: ServerRef, name?: string, color?: string): Promise<Connection>;
-  joinInviteConnection(server: ServerRef, code: string): Promise<Connection>;
-
-  joinShip(server: ServerRef, ship?: ShipRef): Promise<DredlessClient>;
-  startShip(server: ServerRef, ship?: ShipRef): Promise<DredlessClient>;
-  startNewShip(server: ServerRef, name?: string, color?: string): Promise<DredlessClient>;
-  joinInvite(server: ServerRef, code: string): Promise<DredlessClient>;
-}
+```js
+const client = DredlessClient.attachWebSocket(socket, {mode: "readonly"});
+client.on("model", ({world}) => console.log(world.id, world.model.players()));
 ```
 
+| Mode                  | Writes   | Automatically sends hello/bootstrap/keepalive | `close()`                     |
+|-----------------------|----------|-----------------------------------------------|-------------------------------|
+| `"observe"` (default) | Allowed  | No                                            | Can close the attached socket |
+| `"bootstrap"`         | Allowed  | Yes                                           | Can close the attached socket |
+| `"readonly"`          | Rejected | No                                            | No-op                         |
 
-## Browser Connections
-
-Browser start/join helpers still produce `Connection` objects internally, but a browser `Connection` may have an empty `gameToken` when the token is only available through browser-managed cookies. `DredlessClient` uses the browser `WebSocket` implementation and relies on browser-managed cookies and origin headers.
+Use `readonly` for observation. `observe` permits explicit writes despite its name. Avoid two clients independently
+sending initialization or input to one socket.
 
-The shared `DredlessClient` API is documented in [API_REFERENCE.md](./API_REFERENCE.md#dredlessclient).
+For an already-initialized socket, `ready: true` and `sid` can supply known protocol readiness metadata. They do not
+recover missing world state. See [attachment options](CLIENT.md#attach-an-existing-websocket)
+and [event timing](EVENTS.md#ordering-and-listeners).

package/docs/CLIENT.md

@@ -0,0 +1,183 @@
+# Client lifecycle and networking
+
+[Documentation index](README.md) · [Events](EVENTS.md) · [API reference](API_REFERENCE.md)
+
+## Contents
+
+- [Construction and retention](#construction-and-retention)
+- [Completion and readiness](#completion-and-readiness)
+- [Attach an existing WebSocket](#attach-an-existing-websocket)
+- [Disconnects](#disconnects)
+- [Send commands and messages](#send-commands-and-messages)
+- [Inspect client state](#inspect-client-state)
+
+## Construction and retention
+
+Normally obtain a client from a [session factory](NODE_API.md#join-start-and-invites). Construct one yourself when you
+need listeners installed before the connection becomes ready:
+
+```ts
+new DredlessClient(connection: Connection, options?: DredlessClientOptions): DredlessClient;
+
+interface DredlessClientOptions {
+  connect?: boolean;            // true
+  packetHistory?: number;       // 200 packets
+  eventHistory?: number;        // 200 events per WorldState
+  modelPacketHistory?: number;  // 100 packets per WorldState
+  chunkHistory?: number;        // 64 chunks per WorldState
+}
+
+client.whenReady(): Promise<DredlessClient>;
+client.close(code?: number, reason?: string): DredlessClient;
+client.disconnect(code?: number, reason?: string): DredlessClient;
+```
+
+The constructor connects immediately unless `connect: false`. That option supports offline inspection; it does not
+provide a later public `connect()` method. History limits bound retained debugging buffers, not the live decoded world.
+`0` disables a buffer; `Infinity` makes it unbounded. Negative/non-finite values fall back to defaults, except the
+explicit `Infinity` case.
+
+`close()` defaults to code `1000` and reason `"client"`; `disconnect()` is an alias. Readonly attachments make closing a
+no-op. For writable clients, closure state changes when the socket close handler runs.
+
+## Completion and readiness
+
+`whenReady()` resolves when the server's ready packet arrives. Session client factories await it before returning. A
+close before readiness rejects with `DisconnectError`; connection/decoding setup failures can reject with other errors.
+
+Readiness is not a guarantee that all entities, model components, inventory, or interaction panels are populated.
+`currentShip()` and individual fields can be missing. Read existing caches and subscribe to
+relevant [events](EVENTS.md). Install listeners using the connection-descriptor pattern if you need the earliest
+packets.
+
+Most synchronous actions return the client and send or queue a command. They do not verify its effect. Commands
+generally queue until connected, ready, and carrying a session ID; decoded messages queue until connected and, by
+default, ready. Writes after a disconnect reject rather than being queued for reconnection. Promise-based
+management/menu methods have their own readiness checks, timeout, and overlap rules.
+
+| Example                     | Completion meaning                     |
+|-----------------------------|----------------------------------------|
+| `loader.configure(config)`  | Configuration sent/queued              |
+| `tips.choose(entity, text)` | Menu received and selection sent       |
+| `door.setRank("crew")`      | Requested rank observed in model state |
+| `management.rename(name)`   | Rename allowed and commit sent         |
+| `management.resetInvite()`  | A changed nonempty invite key observed |
+| `management.save()`         | Server closed with `DropReason.Saved`  |
+
+A timeout ends local waiting; it does not cancel an action already processed by the server. Do not automatically repeat
+a mutation solely because its confirmation timed out.
+
+## Attach an existing WebSocket
+
+```ts
+DredlessClient.attachWebSocket(socket: unknown, options?: AttachWebSocketOptions): DredlessClient;
+
+interface AttachWebSocketOptions {
+  mode?: "observe" | "bootstrap" | "readonly";
+  connected?: boolean | null;
+  ready?: boolean;
+  sid?: number | null;
+  baseUrl?: string | null;
+  session?: Session | null;
+  serverId?: number | null;
+  server?: Server | null;
+  netPort?: number | null;
+  gameToken?: string;
+}
+```
+
+Modes and browser ownership concerns are covered in [browser attachment](BROWSER_API.md#attach-to-an-existing-socket).
+Metadata does not reconstruct frames received before attachment. `ready: true`/`sid` should describe an
+already-initialized protocol session, not invent a new one.
+
+## Disconnects
+
+Listen to `"disconnect"` for normalized information:
+
+```ts
+interface DisconnectInfo {
+  readonly code: number;
+  readonly name: keyof typeof DropReason | null;
+  readonly reason: string;
+  readonly wasClean: boolean | null;
+}
+```
+
+**Fragment:**
+
+```js
+client.on("disconnect", (info) => {
+  console.log(info.name, info.code, info.reason);
+});
+```
+
+The close handler first marks the client disconnected/not ready, clears `sid`, pending writes, keepalive,
+management/panel state, and command acknowledgments. It sets `client.lastDisconnect` and `client.net.lastDisconnect`,
+then emits `"disconnect"` and the original `"close"` arguments. World data and historical buffers remain available as
+last-known state, not evidence of a live connection.
+
+There is no automatic reconnect. Create/join a new client and reinstall subscriptions when your application decides to
+reconnect.
+
+`DisconnectError` carries the normalized record in `.disconnect`. `normalizeDisconnect()` accepts a browser close event
+or Node-style code/reason. Missing codes become `1006`; unknown/standard codes have `name: null`. `wasClean` is `null`
+when the socket API does not supply it.
+
+| Code | `DropReason` name | Code | `DropReason` name |
+|------|-------------------|------|-------------------|
+| 4000 | ProtocolError     | 4010 | Idle              |
+| 4001 | BadVersion        | 4011 | ShipDestruct      |
+| 4002 | ConnectLimit      | 4012 | JoinBlocked       |
+| 4003 | ConnectRate       | 4013 | HardBanned        |
+| 4004 | TeamLimit         | 4014 | NoLoad            |
+| 4005 | FullPlayers       | 4015 | Saved             |
+| 4006 | FullTeams         | 4016 | InvalidInvite     |
+| 4007 | TeamNotAvailable  | 4017 | Shutdown          |
+| 4008 | Kicked            | 4018 | ServerError       |
+| 4009 | Banned            | 4019 | GTFO              |
+
+These exports are available from Node, browser, and `dredless/network`.
+
+## Send commands and messages
+
+Prefer player, machine, and management methods for normal actions. `client.net` is the lower-level transport domain:
+
+```ts
+client.net.send(command?: Command): DredlessClient;
+client.net.sendMessage(message: unknown, options?: {afterReady?: boolean}): DredlessClient;
+client.net.sendRaw(message: unknown, options?: {afterReady?: boolean}): DredlessClient;
+client.net.sendEntityCommand(cmd: string, args?: unknown[]): DredlessClient;
+client.net.sendUiConfig(data: unknown): DredlessClient;
+client.net.sendBlueprintPlacement(placement: BlueprintPlacement): DredlessClient;
+client.net.setOutfit(outfit: unknown): DredlessClient;
+```
+
+`send()` applies input settings, fills command defaults, and signs the command. It is for player-input packets.
+`sendMessage()` MessagePack-encodes a decoded protocol object. `afterReady` defaults to `true`.
+
+Despite its name, `sendRaw()` is an alias of `sendMessage()`: it does not transmit pre-encoded bytes unchanged. Do not
+pass the output of `encodeMsgpack()` to it expecting raw transport. UI config byte arrays are payloads passed to
+`sendUiConfig()`, not whole WebSocket frames.
+
+`net` also exposes `connected`, `ready`, `sid`, `packetCount`, `lastPacket`, and `lastDisconnect`. Direct client
+transport methods exist too; using the domain makes intent clearer.
+
+## Inspect client state
+
+```ts
+client.state(options?: {includeTiles?: boolean; includeModel?: boolean}): ClientSnapshot;
+client.snapshot(options?: {includeTiles?: boolean; includeModel?: boolean}): ClientSnapshot;
+```
+
+The implementation exposes `snapshot()` as well as `state()`. The result groups connection metadata, worlds, inventory,
+panels, management caches (including `crewLog`), recent packet/event buffers, acknowledgments, and decode errors. Full
+fields live in [ClientSnapshot](../src/index.d.ts).
+
+Client/world snapshots are not uniformly cloned or frozen. For example, `client.state().inventory` and management
+objects are shared references; don't mutate them. [World state](WORLD_STATE.md#live-reads-and-snapshots) distinguishes
+frozen entity snapshots from aggregate state. Snapshots may contain session credentials through `session`/`connection`;
+select fields before logging.
+
+`includeModel` includes raw model tables, and `includeTiles` includes tile values. For blocks, use a world snapshot with
+`includeBlocks: true`; the client snapshot implementation currently does not forward `includeBlocks`, even though its
+declaration lists the option.

package/docs/EVENTS.md

@@ -0,0 +1,136 @@
+# Event catalog
+
+[Documentation index](README.md) · [Client lifecycle](CLIENT.md) · [API reference](API_REFERENCE.md)
+
+## Contents
+
+- [Ordering and listeners](#ordering-and-listeners)
+- [Lifecycle and transport](#lifecycle-and-transport)
+- [World updates](#world-updates)
+- [Player and interaction updates](#player-and-interaction-updates)
+- [Management updates](#management-updates)
+- [Errors](#errors)
+
+## Ordering and listeners
+
+```ts
+client.on(type: string, callback: (...args: any[]) => void): DredlessClient;
+client.off(type: string, callback: (...args: any[]) => void): DredlessClient;
+client.once(type: string, callback: (...args: any[]) => void): DredlessClient;
+```
+
+Callbacks run synchronously. Returned promises are not awaited, so handle errors inside async listeners. Keep frequent
+model/packet listeners short. Ordinary listener exceptions are forwarded to an `"error"` listener when one exists;
+otherwise they can interrupt dispatch. Errors encountered during packet processing can be recorded as decode errors.
+
+Events are not replayed when you subscribe. Factory methods wait for readiness, so initial world, inventory, or
+management events may have happened before you receive the client. Subscribe and also read the corresponding cache. For
+earliest-event capture, construct a client from a [Connection descriptor](NODE_API.md#construct-a-client-yourself).
+
+**Fragment:** keep a callback reference to remove an `on()` listener:
+
+```js
+const report = () => console.log(client.management.crewLog()?.entries.length ?? 0);
+client.on("crew-log", report);
+report();
+// Later:
+client.off("crew-log", report);
+```
+
+`once()` removes its wrapper before invoking it. `off()` expects the registered function identity; it does not cancel a
+`once()` wrapper using the original callback. A manually emitted event does not update state or simulate an authentic
+server response.
+
+## Lifecycle and transport
+
+| Event        | Callback arguments                                 | Timing/meaning                                                                  |
+|--------------|----------------------------------------------------|---------------------------------------------------------------------------------|
+| `attach`     | `(client)`                                         | Attached socket initialized; can fire during `attachWebSocket()`                |
+| `open`       | `(client)`                                         | Socket marked connected; can fire during attachment                             |
+| `ready`      | `(client)`                                         | Ready packet processed, `sid`/world set, queued writes flushed                  |
+| `disconnect` | `(info: DisconnectInfo)`                           | Close cleanup completed; see [disconnects](CLIENT.md#disconnects)               |
+| `close`      | Browser `(event, reason)` or Node `(code, reason)` | Raw close arguments, after `disconnect`                                         |
+| `packet`     | `(packet)`                                         | Decoded inbound packet retained, before it is applied to world/management state |
+| `command`    | `(command)`                                        | Signed input sent; no server acknowledgment implied                             |
+| `message`    | `(message)`                                        | Decoded outgoing message encoded/sent; no server acknowledgment implied         |
+| `bootstrap`  | `(message)`                                        | Initial outfit/bootstrap message sent by an owning client                       |
+| `event`      | `(packet)`                                         | Inbound packet not handled by a more specific branch                            |
+
+WebSocket errors are distinct from a later close. A `ready` event does not mean every state component is present. Raw
+`packet` callbacks run before state application; read updated state from a specific update event instead.
+
+## World updates
+
+These events receive an update object with `.world` referencing the already-updated `WorldState`:
+
+| Event           | Callback arguments | Important fields                                                              |
+|-----------------|--------------------|-------------------------------------------------------------------------------|
+| `world`         | `(update)`         | `update.world` with metadata applied                                          |
+| `tiles`         | `(update)`         | `world`, `decoded`, `updates`, `errors`                                       |
+| `model`         | `(update)`         | `world`, `result` with model changes, side events, command number, timing     |
+| `comms-bubble`  | `(update)`         | `world`, `packet`, `bubble`                                                   |
+| `world-removed` | See below          | World removed from store                                                      |
+| `ack`           | `(ack)`            | `{world, commandNumber}`; latest advancing nonnegative command acknowledgment |
+
+The current implementation emits `world-removed` twice: first with the world update object, then with its raw packet.
+Handle that duplication if subscribing directly. It does not imply two removals.
+
+`model` fires after world/model application but before its side events are dispatched to inventory, panels, and other
+caches. The corresponding acknowledgment is processed afterward too. Do not assume an inventory event embedded in the
+same packet has already run inside a `model` listener.
+
+## Player and interaction updates
+
+| Event            | Callback arguments                   | Cache/state                                              |
+|------------------|--------------------------------------|----------------------------------------------------------|
+| `inventory`      | `(inventory: InventoryState, world)` | `client.inventory.state()` updated                       |
+| `tip-list`       | `(menu: TipList, world)`             | Frozen menu; empty options also emitted                  |
+| `pui`            | `(panel, world)`                     | `client.puiPanels`, keyed by entity                      |
+| `comms`          | `(panel, world)`                     | `client.commsPanels` and active panel                    |
+| `side-event`     | `(event, world)`                     | Remaining model side events; also receives raw tip lists |
+| `tip_warn`       | `(event, world)`                     | Warning retained in `client.warnings`                    |
+| `sfx`            | `(event, world)`                     | Effect retained in `client.effects`                      |
+| `chat`           | `(packet)`                           | Raw chat packet retained in `client.chat`                |
+| `motd`           | `(packet)`                           | Raw MOTD packet retained in `client.motd`                |
+| `outfit`         | `(packet)`                           | Outfit cached by protocol session ID                     |
+| `cpu`            | `(packet)`                           | `client.cpuLoad` set from packet                         |
+| `scanner-result` | `(result, packet)`                   | `lastScannerResult` and history updated                  |
+
+`tip-list` does not carry an authoritative target ID from the server. Its `.entity` is inferred from a pending menu
+request, or `null` for unsolicited menus. [Context menus](MACHINES.md#context-menus-and-access) explains concurrency and
+targeting.
+
+`CommsEvent.messages` contains `{raw, text}` entries; `text` flattens supported rich-text content.
+See [declarations](../src/index.d.ts) for full `InventoryState`, `TipList`, `PuiEvent`, `CommsEvent`, and
+`ScannerResult` shapes.
+
+## Management updates
+
+| Event                   | Callback arguments                | Meaning                                                     |
+|-------------------------|-----------------------------------|-------------------------------------------------------------|
+| `ship-config`           | `(config: ShipConfig              | null, packet)`                                              | Config cache updated or cleared |
+| `captain-subrank`       | `(rank: CaptainSubrank            | null, packet)`                                              | Captain/cheat cache updated or cleared |
+| `player-list`           | `(list: ShipPlayerList            | null, packet)`                                              | Player-list changes merged, or cache cleared |
+| `crew-log`              | `(log: CrewLog                    | null, packet)`                                              | Reset/amend/append applied, or log cleared |
+| `demote`                | `(packet)`                        | Permission-scoped caches cleared before this event          |
+| `starter-recovery`      | `({success, failReason}, packet)` | Recovery response; `failReason` is string or `null`         |
+| `patron-perks-response` | `({failure}, packet)`             | Patron operation response; applied patrons come from config |
+| `session`               | `(packet)`                        | Raw captain/session packet, after dedicated handling        |
+
+Demotion clears ship config, captain subrank, player list, and crew log. It emits `demote`, then the four cache events
+with `null`, then the raw `session` event. Disconnect also clears these caches, but uses the disconnect events rather
+than emitting each cache event.
+
+Rename permission replies remain on `session`; the rename promise handles them internally. It does not expose a
+dedicated commit-success event. Detailed operation contracts are in [management](MANAGEMENT.md).
+
+## Errors
+
+| Event          | Callback arguments              | Use                                                                   |
+|----------------|---------------------------------|-----------------------------------------------------------------------|
+| `error`        | `(error)`                       | Connection/frame errors and forwarded listener exceptions             |
+| `decode-error` | `(entry, error, packet, world)` | A retained processing/decoding error; context arguments may be absent |
+
+`entry` includes `time`, `message`, `packetType`, and `world`. Inspect `client.debug.decodeErrors()` for recent retained
+entries. Some decoders can retain partial state despite reporting an error; an empty/missing decoded component is not
+proof it does not exist on the server.