dredless 0.2.0

package/docs/API_REFERENCE.md

@@ -0,0 +1,2481 @@
+# Dredless API Reference
+
+This document describes the public JavaScript API exposed by the package.
+Here, "endpoint" means a public method, constructor, domain method, or exported
+helper function. The actual browser/game wire protocol remains an implementation
+detail unless a helper explicitly builds or decodes protocol payloads.
+
+Use the runtime-specific top-level API references for session, token, and start/join helpers:
+
+- [NODE_API.md](./NODE_API.md): explicit multi-session `Session` / `AnonSession` API for Node.
+- [BROWSER_API.md](./BROWSER_API.md): ambient browser-session API for browser contexts.
+
+This shared reference covers common input/output shapes, `DredlessClient`, world/entity/domain APIs, protocol helpers, and other runtime-neutral APIs.
+
+Subpath imports are available for focused low-level helpers:
+
+```js
+import { DredlessClient } from "dredless/client";
+import { WorldStore, WorldState } from "dredless/world";
+import { generateGeneratorMaze } from "dredless/game/generator-maze";
+import { encodeMsgpack, decodeMsgpack, decodeIncomingFrame } from "dredless/protocol";
+```
+
+## Public Package Exports
+
+`package.json` currently exposes these module specifiers:
+
+```txt
+dredless
+dredless/browser
+dredless/node
+dredless/client
+dredless/network
+dredless/state
+dredless/session
+dredless/servers
+dredless/ships
+dredless/connection
+dredless/world
+dredless/model
+dredless/game/generator-maze
+dredless/game/model
+dredless/protocol
+dredless/protocol/blueprint
+dredless/protocol/comms
+dredless/protocol/commands
+dredless/protocol/inventory
+dredless/protocol/ship-management
+dredless/protocol/sign
+dredless/protocol/ui-config
+dredless/crypto/chacha
+dredless/compression/lz4
+```
+
+The root module defaults to the Node API for types and direct Node imports. Browser bundlers may use the root `browser` condition for JavaScript, but `dredless/browser` is the reliable import for browser IntelliSense.
+
+Both runtime entrypoints re-export world/model classes, protocol builders, config builders, codec helpers, and common type shapes.
+
+## Common Input Types
+
+### `Server`
+
+Returned by `fetchServers()`.
+
+```ts
+interface Server {
+  index: number;
+  domain: string;
+  description: string;
+  playerCount: number;
+  maxPlayerCount: number;
+  ping: number | null;
+}
+```
+
+### `ServerRef`
+
+Accepted anywhere a server is required.
+
+```ts
+type ServerRef = number | Server;
+```
+
+Passing a number selects a server index. Passing a `Server` object uses its
+domain and index directly.
+
+### `Ship`
+
+Returned by ship list reads.
+
+```ts
+interface Ship {
+  id: number | null;
+  hexCode: string | null;
+  name: string;
+  iconUrl: string | null;
+  playerCount: number;
+  owned: boolean;
+  saved: boolean;
+  color: string;
+  time: number | null;
+}
+```
+
+### `ShipList`
+
+Returned by `fetchShipList()`.
+
+```ts
+interface ShipList {
+  playerCount?: number;
+  maxPlayerCount?: number;
+  isMuted?: boolean;
+  ships: Ship[];
+}
+```
+
+### `ShipSpec`, `ShipRef`
+
+Accepted by join/start methods.
+
+```ts
+type ShipSpec =
+  | { type: "join_or_load"; id: number | string }
+  | { type: "new"; name?: string | null; color?: string | null }
+  | { type: "invite"; code: string };
+
+type ShipRef = number | string | Ship | ShipSpec | null;
+```
+
+Useful interpretations:
+
+```txt
+number                 -> ship id
+string                 -> ship id/hex-like selector, depending on server API
+Ship                   -> ship from fetchShips/fetchShipList
+{ type: "new" }        -> create or start a new ship
+{ type: "invite" }     -> join by invite code
+null or undefined      -> default behavior for the method
+```
+
+## Runtime Top-Level APIs
+
+Top-level runtime APIs are split by environment:
+
+- Node explicit session/token/start helpers: [NODE_API.md](./NODE_API.md)
+- Browser ambient session/start helpers: [BROWSER_API.md](./BROWSER_API.md)
+
+`Connection`, `Session`, `AnonSession`, `BrowserSession`, `Dredless`, and `DredlessBrowser` are documented in those runtime-specific files.
+
+## `DredlessClient`
+
+`DredlessClient` owns the websocket, outgoing commands, incoming packets, and
+decoded state domains.
+
+```ts
+class DredlessClient {
+  constructor(connection: Connection, options?: { connect?: boolean });
+  static attachWebSocket(websocket: unknown, options?: AttachWebSocketOptions): DredlessClient;
+
+  connection: Connection | null;
+  session: Session | null;
+  baseUrl: string | null;
+  attachMode: "observe" | "bootstrap" | "readonly" | null;
+  attached: boolean;
+  serverId: number | null;
+  server: Server | null;
+  netPort: number | null;
+  gameToken: string;
+  ws: unknown;
+  sid: number | null;
+  connected: boolean;
+  ready: boolean;
+  packetCount: number;
+  lastPacket: unknown;
+
+  net: ClientNetDomain;
+  debug: ClientDebugDomain;
+  player: PlayerDomain;
+  inventory: InventoryDomain;
+  management: ShipManagementDomain;
+  readyPromise: Promise<this>;
+
+  whenReady(): Promise<this>;
+  close(code?: number, reason?: string): this;
+  disconnect(code?: number, reason?: string): this;
+
+  currentShip(): ShipDomain | null;
+  ship(): ShipDomain | null;
+  overworld(): OverworldDomain | null;
+  world(id: number): WorldDomain | null;
+  shipWorld(options?: { includeTiles?: boolean; includeModel?: boolean }): WorldSnapshot | null;
+  state(options?: { includeTiles?: boolean; includeModel?: boolean }): ClientSnapshot;
+  entities(scope?: number | string): EntitySummary[];
+  entity(entityId: number, scope?: number | string): EntitySnapshot | null;
+  currentPlayerEntity(): EntityHandle | null;
+
+  on(type: string, callback: (...args: unknown[]) => void): this;
+  off(type: string, callback: (...args: unknown[]) => void): this;
+  once(type: string, callback: (...args: unknown[]) => void): this;
+}
+```
+
+### Constructor
+
+```js
+const client = new DredlessClient(connection);
+```
+
+By default the constructor opens the websocket. For tests or offline state
+inspection, pass `{ connect: false }`:
+
+```js
+const client = new DredlessClient(connection, { connect: false });
+```
+
+### `DredlessClient.attachWebSocket(websocket, options?)`
+
+```ts
+type WebSocketAttachMode = "observe" | "bootstrap" | "readonly";
+
+interface AttachWebSocketOptions {
+  mode?: WebSocketAttachMode;
+  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;
+}
+```
+
+Attaches Dredless to an existing websocket without requiring a `Connection`.
+This is intended for observing or integrating with an already-open browser/game websocket.
+
+Modes:
+
+- `"observe"` default: decodes incoming packets and allows explicit writes through normal handle/client methods, but does not send hello, bootstrap, or keepalive automatically.
+- `"bootstrap"`: treats the websocket like a normally owned Dredless socket; sends hello on open and runs bootstrap, keepalive, and queued-message flushing on ready.
+- `"readonly"`: decodes incoming packets only and rejects all write methods. `close()` is a no-op in this mode.
+
+Optional metadata such as `server`, `serverId`, and `netPort` is only used for snapshots/logging; it is not required to attach.
+
+```js
+const client = DredlessClient.attachWebSocket(window.tpgaClient.repsocket.websocket);
+client.on("packet", (packet) => console.log(packet.type));
+```
+
+### Lifecycle endpoints
+
+```ts
+whenReady(): Promise<this>;
+close(code?: number, reason?: string): this;
+disconnect(code?: number, reason?: string): this;
+```
+
+`whenReady()` resolves once the ready packet is received. For normally-owned clients and `attachWebSocket(..., { mode: "bootstrap" })`, bootstrap commands have also been sent.
+
+### World/domain endpoints
+
+```ts
+currentShip(): ShipDomain | null;
+ship(): ShipDomain | null;
+currentPlayerEntity(): EntityHandle | null;
+overworld(): OverworldDomain | null;
+world(id: number): WorldDomain | null;
+shipWorld(options?): WorldSnapshot | null;
+```
+
+Use `currentShip()` for the currently loaded ship world. Use `overworld()` for
+zone-level objects such as nearby ships and overworld entities.
+
+`currentPlayerEntity()` returns the current player entity handle in the loaded
+ship world, or `null` before the player entity is known.
+
+### Compatibility entity endpoints
+
+```ts
+entities(scope?: number | string): EntitySummary[];
+entity(entityId: number, scope?: number | string): EntitySnapshot | null;
+```
+
+Prefer `client.currentShip()?.entities` and `client.overworld()?.entities` for
+new code. These compatibility methods use `"ship"` by default.
+
+Valid common scopes are:
+
+```txt
+"ship"
+"current"
+"overworld"
+number world id
+```
+
+### Events
+
+```ts
+on(type: string, callback: (...args: unknown[]) => void): this;
+off(type: string, callback: (...args: unknown[]) => void): this;
+once(type: string, callback: (...args: unknown[]) => void): this;
+```
+
+Events are implementation-defined strings emitted by the client event bus.
+
+## `client.state()` Output
+
+```ts
+interface ClientSnapshot {
+  baseUrl: string;
+  session: SessionSnapshot;
+  connection: ConnectionSnapshot | null;
+  attachMode: "observe" | "bootstrap" | "readonly" | null;
+  serverId: number | null;
+  server: Server | null;
+  netPort: number | null;
+  sid: number | null;
+  ready: boolean;
+  connected: boolean;
+  currentWorldId: number | null;
+  worlds: WorldSnapshot[];
+  cpuLoad: number | null;
+  inventory: InventoryState | null;
+  puiPanels: PuiEvent[];
+  commsPanels: CommsEvent[];
+  currentCommsPanel: CommsEvent | null;
+  warnings: unknown[];
+  effects: unknown[];
+  chat: unknown[];
+  motd: unknown[];
+  sessionMessages: unknown[];
+  scannerResults: ScannerResult[];
+  lastScannerResult: ScannerResult | null;
+  shipConfig: ShipConfig | null;
+  captainSubrank: CaptainSubrank | null;
+  playerList: ShipPlayerList | null;
+  outfits: { sid: number; outfit: unknown }[];
+  commandAcks: CommandAck[];
+  lastCommandAck: CommandAck | null;
+  decodeErrors: unknown[];
+  packetCount: number;
+  lastPacket: unknown;
+}
+```
+
+## Client Domain APIs
+
+### `client.net`
+
+Low-level outgoing network domain.
+
+```ts
+interface ClientNetDomain {
+  connected: boolean;
+  ready: boolean;
+  sid: number | null;
+  packetCount: number;
+  lastPacket: unknown;
+  send(command?: Command): DredlessClient;
+  sendMessage(message: unknown, options?: { afterReady?: boolean }): DredlessClient;
+  sendRaw(message: unknown, options?: { afterReady?: boolean }): DredlessClient;
+  sendEntityCommand(cmd: string, args?: unknown[]): DredlessClient;
+  sendUiConfig(data: unknown): DredlessClient;
+  sendBlueprintPlacement(placement: BlueprintPlacement): DredlessClient;
+  setOutfit(outfit: unknown): DredlessClient;
+}
+```
+
+`send()` signs and sends a command-like packet. `sendMessage()` sends a decoded
+protocol message. `sendRaw()` sends already-built/raw content. The specialized
+helpers build the corresponding protocol command and return the client for
+chaining.
+
+### `Command`
+
+General command shape for movement, actions, UI focus, and drag operations.
+
+```ts
+interface Command {
+  type?: number;
+  n?: number | null;
+  x?: number;
+  y?: number;
+  mx?: number;
+  my?: number;
+  vx?: number;
+  vy?: number;
+  jump?: boolean;
+  jump_held?: boolean;
+  drop?: boolean;
+  act1?: boolean;
+  act1_held?: boolean;
+  exit?: boolean;
+  act2?: boolean;
+  act_alt?: boolean;
+  act_alt_held?: boolean;
+  wrench_mode?: number;
+  turret_mode?: number;
+  scr_w?: number;
+  scr_h?: number;
+  motion?: number;
+  focus_ent?: number | null;
+  config_ent?: number | null;
+  tip_select?: number | null;
+  inv_slot?: number;
+  blur?: boolean;
+  drag?: DragPayload | null;
+}
+```
+
+### `client.debug`
+
+Read-only debugging and raw-state access.
+
+```ts
+interface ClientDebugDomain {
+  packets(): unknown[];
+  decodeErrors(): unknown[];
+  worldStore(): WorldStore;
+  modelTable(worldId: number, tableId: number): Map<number, ModelRecord>;
+  modelRecord(worldId: number, tableId: number, entityId: number): ModelRecord | null;
+  puiPanels(): PuiEvent[];
+  commsPanels(): CommsEvent[];
+}
+```
+
+### `client.player`
+
+Player input and action domain.
+
+```ts
+interface PlayerDomain {
+  current(): PlayerSummary | null;
+  entity(): EntityHandle | null;
+  name(): string | null;
+  rank(): CurrentPlayerRank;
+  move(vector?: { x?: number; y?: number }, command?: Command): DredlessClient;
+  aim(point?: { x?: number; y?: number; mx?: number; my?: number }, command?: Command): DredlessClient;
+  action(flags?: Command, command?: Command): DredlessClient;
+  useEntity(entity: number | EntityHandle | EntitySummary, options?: { invSlot?: number; hold?: boolean }, command?: Command): DredlessClient;
+  useHeldItem(options?: { invSlot?: number; hold?: boolean }, command?: Command): DredlessClient;
+  placeHeldItem(options?: { invSlot?: number; hold?: boolean }, command?: Command): DredlessClient;
+  placeBlueprint(placement: BlueprintPlacement, options?: { invSlot?: number; hold?: boolean; mx?: number; my?: number }, command?: Command): DredlessClient;
+  rotateHeldItem(options?: { invSlot?: number; hold?: boolean }, command?: Command): DredlessClient;
+  selectSlot(invSlot?: number, command?: Command): DredlessClient;
+  inputSettings(): CurrentInputSettings;
+  setInputSettings(settings?: InputSettings, options?: { send?: boolean }): DredlessClient;
+  setView(width: number, height: number, options?: { send?: boolean }): DredlessClient;
+  setScreenSize(width: number, height: number, options?: { send?: boolean }): DredlessClient;
+  setWrenchMode(mode: WrenchMode, options?: { send?: boolean }): DredlessClient;
+  setTurretMode(mode: TurretMode, options?: { send?: boolean }): DredlessClient;
+}
+```
+
+### Input setting shapes
+
+```ts
+const WrenchMode = { DropAllItems: "drop-all-items", GrabPrimaryItems: "grab-primary-items", GrabAllItems: "grab-all-items" } as const;
+type WrenchMode = typeof WrenchMode[keyof typeof WrenchMode];
+
+const TurretMode = { ContinuousFire: "continuous-fire", VolleyFire: "volley-fire" } as const;
+type TurretMode = typeof TurretMode[keyof typeof TurretMode];
+
+interface InputSettings {
+  wrenchMode?: WrenchMode;
+  turretMode?: TurretMode;
+  viewWidth?: number;
+  viewHeight?: number;
+  screenWidth?: number;
+  screenHeight?: number;
+}
+
+interface CurrentInputSettings {
+  wrenchMode: "drop-all-items" | "grab-primary-items" | "grab-all-items" | null;
+  turretMode: "continuous-fire" | "volley-fire" | null;
+  viewWidth: number | null;
+  viewHeight: number | null;
+  screenWidth: number | null;
+  screenHeight: number | null;
+}
+```
+
+### `client.inventory`
+
+Inventory read and slot movement domain.
+
+```ts
+type InventoryArea = "all" | "hotbar" | "equipment";
+type InventorySlotRef = number | EquipmentSlot | InventorySlotHandle | InventorySlotSnapshot;
+const EquipmentSlot = { Head: "head", Face: "face", Body: "body", Back: "back", Hands: "hands", Feet: "feet" } as const;
+type EquipmentSlot = typeof EquipmentSlot[keyof typeof EquipmentSlot];
+
+interface InventoryDomain {
+  state(): InventoryState | null;
+  hotbarSize(): number;
+  allSlots(): InventorySlotHandle[];
+  slot(ref: InventorySlotRef): InventorySlotHandle;
+  hotbarSlots(): InventorySlotHandle[];
+  equipmentSlots(): { head: InventorySlotHandle; face: InventorySlotHandle; body: InventorySlotHandle; back: InventorySlotHandle; hands: InventorySlotHandle; feet: InventorySlotHandle };
+  findItem(itemId: number, options?: { area?: InventoryArea }): InventorySlotHandle | null;
+  findItems(itemId: number, options?: { area?: InventoryArea }): InventorySlotHandle[];
+  firstEmpty(options?: { area?: InventoryArea }): InventorySlotHandle | null;
+  move(source: InventorySlotRef, target: InventorySlotRef, options?: { split?: boolean }, command?: Command): DredlessClient;
+  equip(source: InventorySlotRef, equipmentSlot?: EquipmentSlot | { split?: boolean }, options?: { split?: boolean } | Command, command?: Command): DredlessClient;
+  unequip(equipmentSlot: EquipmentSlot, target?: InventorySlotRef, options?: { split?: boolean }, command?: Command): DredlessClient;
+  select(slot: InventorySlotRef, command?: Command): DredlessClient;
+}
+```
+
+Slot handles expose live slot reads and convenience actions:
+
+```ts
+interface InventorySlotHandle {
+  index: number;
+  kind: "hotbar" | "equipment" | null;
+  equipmentSlot: "head" | "face" | "body" | "back" | "hands" | "feet" | null;
+  itemId: number | null;
+  itemName: string | null;
+  count: number;
+  empty: boolean;
+  exists(): boolean;
+  snapshot(): InventorySlotSnapshot | null;
+  moveTo(target: InventorySlotRef, options?: { split?: boolean }, command?: Command): DredlessClient;
+  equip(equipmentSlot?: EquipmentSlot | { split?: boolean }, options?: { split?: boolean } | Command, command?: Command): DredlessClient;
+  unequip(target?: InventorySlotRef, options?: { split?: boolean }, command?: Command): DredlessClient;
+  select(command?: Command): DredlessClient;
+}
+```
+
+Inventory state is normalized and does not expose raw `items`, `item_counts`, or `general_slots` arrays. `hotbarSize` is the protocol-provided hotbar slot count from `general_slots`; equipment slots are separate fixed absolute indexes (`16`, `17`, `18`, `19`, `20`, `21`). `equip()` may omit the equipment slot; in that case it infers the target from the item schema and throws if the source slot is empty or the item is not equipment.
+
+```ts
+interface InventorySlotSnapshot {
+  index: number;
+  itemId: number | null;
+  itemName: string | null;
+  count: number;
+  kind: "hotbar" | "equipment";
+  equipmentSlot: "head" | "face" | "body" | "back" | "hands" | "feet" | null;
+  empty: boolean;
+}
+
+interface InventoryState {
+  type: "inventory";
+  filter?: number;
+  hotbarSize: number;
+  slots: InventorySlotSnapshot[];
+  hotbar: InventorySlotSnapshot[];
+  equipment: {
+    head: InventorySlotSnapshot;
+    face: InventorySlotSnapshot;
+    body: InventorySlotSnapshot;
+    back: InventorySlotSnapshot;
+    hands: InventorySlotSnapshot;
+    feet: InventorySlotSnapshot;
+  };
+}
+```
+### `client.management`
+
+Ship-management command and state domain.
+
+```ts
+interface ShipManagementDomain {
+  requestPlayerList(): DredlessClient;
+  resetInvite(): DredlessClient;
+  setPrivacy(privacy: ShipPrivacy): DredlessClient;
+  recoverStarterItem(itemId: number): DredlessClient;
+  setPlayerRank(refId: number, rank: ShipPlayerRank): DredlessClient;
+  kickPlayer(refId: number): DredlessClient;
+  banPlayer(refId: number): DredlessClient;
+  demoteSelf(): DredlessClient;
+  config(): ShipConfig | null;
+  hasCheats(): boolean;
+  playerList(): ShipPlayerList | null;
+}
+```
+
+Input aliases:
+
+```ts
+type ShipPrivacy = 0 | 1 | boolean | "public" | "private";
+type ShipPlayerRank = 0 | 1 | 3 | "guest" | "crew" | "captain";
+type PlayerShipRank = "guest" | "crew" | "crew-invite-pending-deprecated" | "captain" | "banned";
+```
+
+Output shapes:
+
+```ts
+interface ShipConfig {
+  privacy: number | null;
+  privacyName: "public" | "private" | null;
+  inviteKey: string | null;
+  teamId: number | null;
+  patronPerks: unknown[];
+}
+
+interface CaptainSubrank {
+  subrank: number | null;
+  enableCheats: boolean;
+}
+
+interface CurrentPlayerRank {
+  shipRank: PlayerShipRank | null;
+  subrank: number | null;
+  isCaptain: boolean;
+  patronTier: "bronze" | "silver" | "gold" | "plat" | "flux" | null;
+}
+
+interface PlayerListEntry {
+  refId: number | null;
+  discrim: string | null;
+  discrimColor: number | null;
+  teamRank: number | null;
+  captainRank: number | null;
+  isCaptain: boolean;
+  isShipOwner: boolean;
+  canBeManaged: boolean;
+  time: number | null;
+  items: unknown[];
+  aliasDiscrims: unknown[];
+  extraAliasCount: number;
+  onlineCount: number | null;
+}
+
+interface ShipPlayerList {
+  ownerCaptainRank: number | null;
+  shipOwners: PlayerListEntry[];
+  players: PlayerListEntry[];
+  changes: PlayerListEntry[];
+  removedPlayers: number[];
+}
+```
+
+## World Domains
+
+### `WorldDomain`
+
+Available from `client.currentShip()`, `client.overworld()`, and
+`client.world(id)`.
+
+```ts
+interface WorldDomain {
+  id: number | null;
+  entities: EntityCollection;
+  machines: MachineCollection;
+  players: PlayerCollection;
+  blocks: BlockCollection;
+  materials: MaterialCollection;
+  exists(): boolean;
+  snapshot(options?: { includeTiles?: boolean; includeModel?: boolean }): WorldSnapshot | null;
+}
+```
+
+### `ShipDomain`
+
+```ts
+interface ShipDomain extends WorldDomain {
+  metadata: ShipWorldMetadataSummary | null;
+  entity(): EntityHandle | null;
+  overworldEntity: EntityHandle | null;
+}
+```
+
+`entity()` returns the current ship's overworld entity handle, not a ship-world
+placed entity.
+
+### `OverworldDomain`
+
+```ts
+interface OverworldDomain extends WorldDomain {
+  ships(options?: ShipReadOptions): ShipHandle[];
+  shipByHex(hexCode: string, options?: ShipReadOptions): ShipHandle | null;
+  shipByEntity(entity: number | EntityHandle | EntitySummary, options?: ShipReadOptions): ShipHandle | null;
+}
+```
+
+Ship read options:
+
+```ts
+interface ShipReadOptions {
+  includeWorld?: boolean;
+  includeTiles?: boolean;
+  includeModel?: boolean;
+  sort?: "distance" | null;
+}
+```
+
+## Entity API
+
+Entity ids are scoped to their world. Overworld entities and ship-world entities
+do not share one global id pool.
+
+### `EntityCollection`
+
+```ts
+interface EntityCollection {
+  all(): EntityHandle[];
+  snapshots(): EntitySnapshot[];
+  states(): EntitySnapshot[];
+  raw(): EntitySummary[];
+  get(entity: number | EntityHandle | EntitySummary): EntityHandle;
+}
+```
+
+Use:
+
+```js
+const shipEntity = client.currentShip().entities.get(14);
+const overworldEntity = client.overworld().entities.get(2495754);
+```
+
+Costs:
+
+```txt
+all()       -> creates lightweight handles
+raw()       -> returns current summary objects
+snapshots() -> clones and freezes summaries
+states()    -> alias of snapshots()
+get(id)     -> creates one lightweight handle
+```
+
+### `EntityHandle`
+
+```ts
+interface EntityHandle {
+  /** @deprecated Use id. */
+  entity: number;
+  id: number;
+  position: TransformSummary | null;
+  health: HealthSummary | null;
+  contents: EntityContentsSummary | null;
+  exists(): boolean;
+  snapshot(): EntitySnapshot | null;
+  is(type: EntityTypeName): boolean;
+  has(feature: EntityFeatureName): boolean;
+  feature(feature: EntityFeatureName): unknown | null;
+  as(type: EntityTypeName): MachineHandle | null;
+  asLoader(): LoaderHandle | null;
+  asPusher(): PusherHandle | null;
+  asLauncher(): LauncherHandle | null;
+  asNavigationUnit(): NavigationUnitHandle | null;
+  asCommsStation(): CommsStationHandle | null;
+  asSign(): SignHandle | null;
+  asGenerator(): GeneratorHandle | null;
+  asCargoHatch(): CargoHatchHandle | null;
+  asCannon(): CannonHandle | null;
+  asThruster(): ThrusterHandle | null;
+  asHelm(): HelmHandle | null;
+  asDoor(): DoorHandle | null;
+  asSpawnPoint(): SpawnPointHandle | null;
+  asShieldProjector(): ShieldProjectorHandle | null;
+  asFluidTank(): FluidTankHandle | null;
+  asCargoEjector(): CargoEjectorHandle | null;
+  asExpandoBox(): ExpandoBoxHandle | null;
+  use(options?: { invSlot?: number; hold?: boolean }, command?: Command): DredlessClient;
+}
+```
+
+### `EntitySnapshot`
+
+Frozen point-in-time entity read.
+
+```ts
+interface EntitySnapshot extends EntitySummary {
+  id: number;
+  position: TransformSummary | null;
+  rotation: number | null;
+  type: EntitySnapshotType;
+  is(type: EntityTypeName): boolean;
+  has(feature: EntityFeatureName): boolean;
+  feature(feature: EntityFeatureName): unknown | null;
+}
+
+interface EntitySnapshotType {
+  category: EntitySummary["category"] | null;
+  machine: string | null;
+  item: string | null;
+  components: string[];
+}
+```
+
+### `EntitySummary`
+
+Raw normalized entity shape.
+
+```ts
+interface EntitySummary {
+  entity: number;
+  category:
+    | "placed_entity"
+    | "loose_item"
+    | "untyped_holder"
+    | "metadata"
+    | "player"
+    | "ship_control"
+    | "blueprint_preview"
+    | "entity";
+  typeId: number | null;
+  typeName: string | null;
+  markerTypeId: number | null;
+  markerTypeName: string | null;
+  label: string;
+  kind: string[];
+  transform: TransformSummary | null;
+  footprint: {
+    width: number;
+    height: number;
+    source:
+      | "type"
+      | "marker"
+      | "heuristic"
+      | "default"
+      | "crate"
+      | "huge_thruster"
+      | "hover_outline";
+  };
+  contents: EntityContentsSummary | null;
+  occupies: { x: number; y: number }[];
+  tables: { tableId: number; name: string | null; record: ModelRecord }[];
+}
+```
+
+### `EntityContentsSummary`
+
+Feature/component container for an entity.
+
+```ts
+interface EntityContentsSummary {
+  itemHolder?: ItemHolderSummary;
+  expandoBox?: ExpandoBoxSummary;
+  hoverOutline?: HoverOutlineSummary;
+  mapMarker?: MapMarkerSummary;
+  dockingSpring?: DockingSpringSummary;
+  hugeThruster?: HugeThrusterSummary;
+  blueprintPreview?: BlueprintPreviewSummary;
+  itemCrate?: ItemCrateSummary;
+  health?: HealthSummary;
+  bot?: BotSummary;
+  fabricator?: FabricatorSummary;
+  cargoEjector?: CargoEjectorSummary;
+  cannon?: CannonSummary;
+  thruster?: ThrusterSummary;
+  pusher?: PusherSummary;
+  pusherBeam?: PusherBeamSummary;
+  launcher?: LauncherSummary;
+  loader?: LoaderSummary;
+  cargoHatch?: CargoHatchSummary;
+  navigationUnit?: NavigationUnitSummary;
+  commsStation?: CommsStationSummary;
+  fluidTank?: FluidTankSummary;
+  shieldGenerator?: ShieldGeneratorSummary;
+  shieldProjector?: ShieldProjectorSummary;
+  helm?: HelmSummary;
+  player?: PlayerSummary;
+  shipControl?: ShipControlSummary;
+  sign?: SignSummary;
+  spawnPoint?: SpawnPointSummary;
+  door?: DoorSummary;
+  shipSize?: ShipSizeSummary;
+}
+```
+
+Feature lookup accepts the canonical component names above and selected aliases
+such as `outline`, `beam`, `inventory`, `filter`, `filterMode`, `filterSlots`,
+`occupied`, `mapMarker`, and `blueprint`.
+
+## Machine API
+
+### `MachineCollection`
+
+```ts
+interface MachineCollection {
+  state(): MachineSummary;
+  raw(): MachineSummary;
+  loaders(): LoaderHandle[];
+  loader(entity: number | EntityHandle | EntitySummary): LoaderHandle;
+  pushers(): PusherHandle[];
+  pusher(entity: number | EntityHandle | EntitySummary): PusherHandle;
+  launchers(): LauncherHandle[];
+  launcher(entity: number | EntityHandle | EntitySummary): LauncherHandle;
+  navigationUnits(): NavigationUnitHandle[];
+  navigationUnit(entity?: number | EntityHandle | EntitySummary | null): NavigationUnitHandle | null;
+  fabricators(): FabricatorHandle[];
+  fabricator(entity: number | EntityHandle | EntitySummary): FabricatorHandle;
+  commsStations(): CommsStationHandle[];
+  commsStation(entity?: number | EntityHandle | EntitySummary | null): CommsStationHandle | null;
+  signs(): SignHandle[];
+  sign(entity: number | EntityHandle | EntitySummary): SignHandle;
+  generators(): GeneratorHandle[];
+  generator(entity: number | EntityHandle | EntitySummary): GeneratorHandle;
+  cargoHatches(): CargoHatchHandle[];
+  cargoHatch(entity: number | EntityHandle | EntitySummary): CargoHatchHandle;
+  cargoEjectors(): CargoEjectorHandle[];
+  cargoEjector(entity: number | EntityHandle | EntitySummary): CargoEjectorHandle;
+  cannons(): CannonHandle[];
+  cannon(entity: number | EntityHandle | EntitySummary): CannonHandle;
+  thrusters(): ThrusterHandle[];
+  thruster(entity: number | EntityHandle | EntitySummary): ThrusterHandle;
+  helms(): HelmHandle[];
+  helm(entity: number | EntityHandle | EntitySummary): HelmHandle;
+  doors(): DoorHandle[];
+  door(entity: number | EntityHandle | EntitySummary): DoorHandle;
+  spawnPoints(): SpawnPointHandle[];
+  spawnPoint(entity: number | EntityHandle | EntitySummary): SpawnPointHandle;
+  shieldProjectors(): ShieldProjectorHandle[];
+  shieldProjector(entity: number | EntityHandle | EntitySummary): ShieldProjectorHandle;
+  fluidTanks(): FluidTankHandle[];
+  fluidTank(entity: number | EntityHandle | EntitySummary): FluidTankHandle;
+  expandoBoxes(): ExpandoBoxHandle[];
+  expandoBox(entity: number | EntityHandle | EntitySummary): ExpandoBoxHandle;
+}
+```
+
+### `MachineSummary`
+
+Grouped machine/component state.
+
+```ts
+interface MachineSummary {
+  itemHolders: ItemHolderSummary[];
+  health: HealthSummary[];
+  fabricators: FabricatorSummary[];
+  cargoEjectors: CargoEjectorSummary[];
+  cannons: CannonSummary[];
+  thrusters: ThrusterSummary[];
+  pushers: PusherSummary[];
+  pusherBeams: PusherBeamSummary[];
+  launchers: LauncherSummary[];
+  loaders: LoaderSummary[];
+  cargoHatches: CargoHatchSummary[];
+  navigationUnits: NavigationUnitSummary[];
+  commsStations: CommsStationSummary[];
+  fluidTanks: FluidTankSummary[];
+  shieldGenerators: ShieldGeneratorSummary[];
+  shieldProjectors: ShieldProjectorSummary[];
+  helms: HelmSummary[];
+  signs: SignSummary[];
+  spawnPoints: SpawnPointSummary[];
+  doors: DoorSummary[];
+  expandoBoxes: ExpandoBoxSummary[];
+}
+```
+
+### Common machine handle
+
+```ts
+interface MachineHandle extends EntityHandle {
+  open(options?: { invSlot?: number; hold?: boolean }, command?: Command): DredlessClient;
+}
+```
+
+`open()` focuses/uses the entity through the player command path.
+
+### `LoaderHandle`
+
+```ts
+interface LoaderHandle extends MachineHandle {
+  state: LoaderSummary | null;
+  configure(config?: LoaderConfig): DredlessClient;
+  configureFull(config?: LoaderFullConfig): DredlessClient;
+  copy(config?: LoaderFullConfig): DredlessClient;
+  setPickPlace(pick: LoaderPosition, place: LoaderPosition, config?: LoaderConfig): DredlessClient;
+  setPriority(priority: LoaderPriority, config?: LoaderConfig): DredlessClient;
+  setStack(stack: number, config?: LoaderConfig): DredlessClient;
+  setCycle(cycle: number, config?: LoaderConfig): DredlessClient;
+  setRequireOutput(requireOutput: boolean, config?: LoaderConfig): DredlessClient;
+  setWaitForStack(waitForStack: boolean, config?: LoaderConfig): DredlessClient;
+  setFilterMode(filterMode: LoaderFilterMode): DredlessClient;
+  setFilterItems(filterSlots?: Array<number | null | undefined>): DredlessClient;
+  pick: number | undefined;
+  place: number | undefined;
+  priority: number | undefined;
+  stack: number | undefined;
+  cycle: number | undefined;
+  requireOutput: boolean | undefined;
+  waitForStack: boolean | undefined;
+  filterMode: number | undefined;
+  filterSlots: Array<number | null>;
+}
+```
+
+Config inputs:
+
+```ts
+const LoaderPosition = { TopLeft: "top-left", TopMiddle: "top-middle", TopRight: "top-right", MiddleLeft: "middle-left", MiddleRight: "middle-right", BottomLeft: "bottom-left", BottomMiddle: "bottom-middle", BottomRight: "bottom-right" } as const;
+type LoaderPosition = typeof LoaderPosition[keyof typeof LoaderPosition];
+
+const LoaderPriority = { Low: "low", Normal: "normal", High: "high" } as const;
+type LoaderPriority = typeof LoaderPriority[keyof typeof LoaderPriority];
+
+const LoaderFilterMode = { AllowAll: "allow-all", BlockFilter: "block-filter", AllowFilter: "allow-filter", BlockAll: "block-all" } as const;
+type LoaderFilterMode = typeof LoaderFilterMode[keyof typeof LoaderFilterMode];
+
+interface LoaderConfig {
+  pick?: LoaderPosition;
+  place?: LoaderPosition;
+  priority?: LoaderPriority;
+  stack?: number;
+  cycle?: number;
+  requireOutput?: boolean;
+  waitForStack?: boolean;
+}
+
+interface LoaderFullConfig extends LoaderConfig {
+  filterMode?: LoaderFilterMode;
+  filterSlots?: Array<number | null | undefined>;
+}
+```
+
+State output:
+
+```ts
+interface LoaderSummary {
+  entity: number;
+  pick: number | null;
+  pickName: string | null;
+  place: number | null;
+  placeName: string | null;
+  priority: number | null;
+  priorityName: string | null;
+  requireOutput: boolean | null;
+  waitForStack: boolean | null;
+  stack: number | null;
+  cycle: number | null;
+  filterMode: number | null;
+  filterModeName: string | null;
+  filterSlots: (number | null)[] | null;
+  heldItemId: number | null;
+  heldItemName: string | null;
+  heldCount: number | null;
+  active: boolean;
+  progress: number | null;
+  state: ModelRecord;
+  filterState: ModelRecord;
+  filterSlotsState: ModelRecord;
+}
+```
+
+### `PusherHandle`
+
+```ts
+interface PusherHandle extends MachineHandle {
+  state: PusherSummary | null;
+  beam: PusherBeamSummary | null;
+  configure(config?: PusherConfig): DredlessClient;
+  setAngle(angle: number, config?: PusherConfig): DredlessClient;
+  setSpeed(speed: number, config?: PusherConfig): DredlessClient;
+  setLength(length: number, config?: PusherConfig): DredlessClient;
+  setMode(mode: PusherMode, config?: PusherConfig): DredlessClient;
+  setFilteredMode(mode: PusherMode, config?: PusherConfig): DredlessClient;
+  setFilterInventory(filterInventory: boolean, config?: PusherConfig): DredlessClient;
+  setFilterItems(filterSlots?: Array<number | null | undefined>): DredlessClient;
+  angle: number | undefined;
+  speed: number | undefined;
+  length: number | undefined;
+  mode: number | undefined;
+  filteredMode: number | undefined;
+}
+```
+
+Config input:
+
+```ts
+const PusherMode = { Push: "push", Pull: "pull", DoNothing: "do-nothing" } as const;
+type PusherMode = typeof PusherMode[keyof typeof PusherMode];
+
+interface PusherConfig {
+  mode?: PusherMode;
+  filteredMode?: PusherMode;
+  angle?: number;
+  speed?: number;
+  filterInventory?: boolean;
+  length?: number;
+}
+```
+
+State output:
+
+```ts
+interface PusherSummary {
+  entity: number;
+  mode: number;
+  modeName: string | null;
+  filteredMode: number;
+  filteredModeName: string | null;
+  angle: number | null;
+  speed: number;
+  length: number;
+  filterInventory: boolean;
+  filterSlots: (number | null)[] | null;
+  state: ModelRecord;
+  filterSlotsState: ModelRecord;
+}
+
+interface PusherBeamSummary {
+  entity: number;
+  active: boolean;
+  mode: number;
+  modeName: string | null;
+  lengthRaw: number;
+  length: number;
+  state: ModelRecord;
+}
+```
+
+Pusher beams are associated with the same entity as their parent pusher, exposed
+as `pusher.beam`, `entity.feature("beam")`, and `machines.state().pusherBeams`.
+
+### `LauncherHandle`
+
+```ts
+interface LauncherHandle extends MachineHandle {
+  state: LauncherSummary | null;
+  setAngle(angle: number): DredlessClient;
+  setPower(power: number): DredlessClient;
+  angleDegrees: number | undefined;
+  angleRadians: number | undefined;
+  angleRaw: number | null | undefined;
+}
+
+interface LauncherSummary {
+  entity: number;
+  angleRaw: number | null;
+  angleRadians: number | null;
+  angleDegrees: number | null;
+  state: ModelRecord;
+}
+```
+
+Launcher power may not be present until the relevant UI has exposed it.
+
+### `NavigationUnitHandle`
+
+```ts
+interface NavigationUnitHandle extends MachineHandle {
+  state: NavigationUnitSummary | null;
+  configure(config?: NavigationUnitConfig): DredlessClient;
+  copy(config?: NavigationUnitConfig): DredlessClient;
+  paste(config?: NavigationUnitConfig): DredlessClient;
+  setDestination(destination: number, config?: NavigationUnitConfig): DredlessClient;
+  setAutoWarp(config?: NavigationUnitConfig): DredlessClient;
+  startWarp(config?: NavigationUnitConfig): DredlessClient;
+  cancelWarp(config?: NavigationUnitConfig): DredlessClient;
+  destination: number | undefined;
+  autoWarpOnShieldFailure: boolean | undefined;
+  autoWarpOnNoCaptains: boolean | undefined;
+  warp: string | undefined;
+}
+```
+
+Config and state:
+
+```ts
+interface NavigationUnitConfig {
+  destination?: number;
+  page?: number;
+  warp?: boolean | "start" | "idle" | "cancel";
+  autoWarpOnShieldFailure?: boolean;
+  autoWarpOnNoCaptains?: boolean;
+}
+
+interface NavigationUnitSummary {
+  entity: number;
+  destination: number;
+  destinationName: string | null;
+  autoWarpOnShieldFailure: boolean | null;
+  autoWarpOnNoCaptains: boolean | null;
+  state: ModelRecord;
+}
+```
+
+### `FabricatorHandle`
+
+```ts
+interface FabricatorHandle extends MachineHandle {
+  state: FabricatorSummary | null;
+  panel(): PuiEvent | null;
+  add(itemId: number, count?: number, index?: number): DredlessClient;
+  sub(itemId: number, count?: number, index?: number): DredlessClient;
+  clearQueue(): DredlessClient;
+  toggleRepeat(): DredlessClient;
+  lockResource(row: number): DredlessClient;
+  unlockResource(row: number): DredlessClient;
+  eject(row: number): DredlessClient;
+}
+
+const FabricatorType = { Starter: "starter", Munitions: "munitions", Engineering: "engineering", Equipment: "equipment" } as const;
+type FabricatorType = typeof FabricatorType[keyof typeof FabricatorType];
+
+interface FabricatorSummary {
+  entity: number;
+  type: FabricatorType | null;
+  typeIndex: number | null;
+  state: ModelRecord;
+  rows: { itemId: number | null; itemName: string | null; count: number | null }[];
+  progress: number | null;
+  progressRaw: number | null;
+  active: boolean;
+  craftingItemId: number | null;
+  craftingItemName: string | null;
+  craftingCount: number | null;
+}
+```
+
+### `CommsStationHandle`
+
+```ts
+interface CommsStationHandle extends MachineHandle {
+  state: CommsStationSummary | null;
+  panel(): CommsEvent | null;
+  sendMessage(message?: string): DredlessClient;
+}
+
+interface CommsStationSummary {
+  entity: number;
+  typeId: number;
+  typeName: string | null;
+  charges: number | null;
+  maxCharges: number;
+  chargeRatio: number | null;
+  occupied: boolean;
+  state: ModelRecord;
+}
+```
+
+### `SignHandle`
+
+```ts
+interface SignHandle extends MachineHandle {
+  state: SignSummary | null;
+  setText(text?: string, mode?: SignDisplayMode): DredlessClient;
+  text: string | undefined;
+  mode: number | undefined;
+}
+
+const SignDisplayMode = { Always: "always", WhenNear: "when-near", OnHover: "on-hover" } as const;
+type SignDisplayMode = typeof SignDisplayMode[keyof typeof SignDisplayMode];
+
+interface SignSummary {
+  entity: number;
+  text: string;
+  displayMode: number;
+  displayModeName: string | null;
+  state: ModelRecord;
+}
+```
+
+### `GeneratorHandle`
+
+```ts
+interface GeneratorHandle extends MachineHandle {
+  state: ShieldGeneratorSummary | null;
+  solvePuzzle(solution: string | number): DredlessClient;
+}
+
+interface ShieldGeneratorSummary {
+  entity: number;
+  charge: number;
+  maxCharge: number;
+  chargeRatio: number | null;
+  efficiencyPercent: number | null;
+  efficiency: number | null;
+  storedItemId: number | null;
+  storedItemName: string | null;
+  storedItemCount: number | null;
+  hasShieldCore: boolean;
+  boostState: number;
+  boostStateName: string | null;
+  boostTimer: number;
+  boostActive: boolean;
+  puzzleSeed: number | null;
+  puzzleSolution: string | null;
+  state: ModelRecord;
+  itemState: ModelRecord;
+  boostStateRaw: ModelRecord;
+}
+```
+
+### `CargoHatchHandle`
+
+```ts
+interface CargoHatchHandle extends MachineHandle {
+  state: CargoHatchSummary | null;
+  configure(config?: Pick<LoaderFullConfig, "filterMode" | "filterSlots">): DredlessClient;
+  copy(config?: Pick<LoaderFullConfig, "filterMode" | "filterSlots">): DredlessClient;
+  paste(config?: Pick<LoaderFullConfig, "filterMode" | "filterSlots">): DredlessClient;
+  setFilterMode(filterMode: LoaderFilterMode): DredlessClient;
+  setFilterItems(filterSlots?: Array<number | null | undefined>): DredlessClient;
+}
+
+interface CargoHatchSummary {
+  entity: number;
+  typeId: number;
+  typeName: string | null;
+  filterMode: number;
+  filterModeName: string | null;
+  filterSlots: (number | null)[] | null;
+  openFraction: number | null;
+  filterState: ModelRecord;
+  filterSlotsState: ModelRecord;
+}
+```
+
+### Other machine handles
+
+```ts
+interface CannonHandle extends MachineHandle {
+  state: CannonSummary | null;
+}
+
+interface ThrusterHandle extends MachineHandle {
+  state: ThrusterSummary | null;
+}
+
+interface HelmHandle extends MachineHandle {
+  state: HelmSummary | null;
+  occupied: boolean | undefined;
+}
+
+interface DoorHandle extends MachineHandle {
+  state: DoorSummary | null;
+  rank: number | undefined;
+  open: boolean | undefined;
+}
+
+interface SpawnPointHandle extends MachineHandle {
+  state: SpawnPointSummary | null;
+  rank: number | undefined;
+}
+
+interface ShieldProjectorHandle extends MachineHandle {
+  state: ShieldProjectorSummary | null;
+  active: boolean | undefined;
+}
+
+interface FluidTankHandle extends MachineHandle {
+  state: FluidTankSummary | null;
+  amount: number | null | undefined;
+}
+
+interface ExpandoBoxHandle extends MachineHandle {
+  state: ExpandoBoxSummary | null;
+  item: number | null | undefined;
+  count: number | null | undefined;
+}
+
+interface CargoEjectorSummary {
+  entity: number;
+  typeId: number;
+  typeName: string | null;
+  progress: number | null;
+  active: boolean | null;
+}
+
+interface CargoEjectorHandle extends MachineHandle {
+  state: CargoEjectorSummary | null;
+  progress: number | null | undefined;
+  active: boolean | null | undefined;
+  setDirection(direction: FixedAngleDirection): DredlessClient;
+  copy(direction?: FixedAngleDirection): DredlessClient;
+  paste(direction?: FixedAngleDirection): DredlessClient;
+}
+```
+
+Associated summary shapes:
+
+```ts
+interface CannonSummary {
+  entity: number;
+  typeId: number;
+  typeName: string | null;
+  ammoItemId: number | null;
+  ammoName: string | null;
+  ammoCount: number;
+  aim: number | null;
+  recoil: number | null;
+  recoil2: number | null;
+  recoils: [number | null, number | null];
+  charge: number | null;
+  charged: boolean | null;
+  spin: number | null;
+  coolingCellCount: number;
+  state: ModelRecord;
+}
+
+interface ThrusterSummary {
+  entity: number;
+  typeId: number;
+  typeName: string | null;
+  facing: number;
+  facingName:
+    | "bottom"
+    | "top"
+    | "right"
+    | "left"
+    | "bottom-right"
+    | "bottom-left"
+    | "top-right"
+    | "top-left"
+    | null;
+  fuel: number | null;
+  state: ModelRecord;
+}
+
+interface HelmSummary {
+  entity: number;
+  typeId: number;
+  typeName: string | null;
+  occupied: boolean;
+}
+
+interface DoorSummary {
+  entity: number;
+  rank: number;
+  rankName: string | null;
+  open: boolean;
+  rankState: ModelRecord;
+  state: ModelRecord;
+}
+
+interface SpawnPointSummary {
+  entity: number;
+  rank: number;
+  rankName: string | null;
+  state: ModelRecord;
+}
+
+interface ShieldProjectorSummary {
+  entity: number;
+  active: boolean;
+  state: ModelRecord;
+}
+
+interface FluidTankSummary {
+  entity: number;
+  amount: number | null;
+  state: ModelRecord;
+}
+
+interface ExpandoBoxSummary {
+  entity: number;
+  itemId: number | null;
+  itemName: string | null;
+  count: number | null;
+  width: number | null;
+  height: number | null;
+  rawWidth: number | null;
+  rawHeight: number | null;
+  itemState: ModelRecord;
+  sizeState: ModelRecord;
+}
+```
+
+## Ship Reads
+
+### `ShipHandle`
+
+Returned by `client.overworld()?.ships()`.
+
+```ts
+interface ShipHandle {
+  entity: number;
+  name: string | null;
+  hexCode: string | null;
+  distance: number | null;
+  worldId: number | null;
+  hasWorldData: boolean;
+  world(): WorldDomain | null;
+  snapshot(): ShipReadSummary;
+}
+```
+
+### `ShipReadSummary`
+
+```ts
+interface ShipReadSummary {
+  entity: number;
+  name: string | null;
+  hexCode: string | null;
+  color: number | null;
+  colorCss: string | null;
+  position: { x: number | null; y: number | null; rot: number | null } | null;
+  distance: number | null;
+  footprint: EntitySummary["footprint"];
+  label: string;
+  kind: string[];
+  thrust: { x: number | null; y: number | null };
+  shield: ShipShieldSummary | null;
+  warp: ShipWarpSummary | null;
+  worldId: number | null;
+  hasWorldData: boolean;
+  world: WorldSnapshot | null;
+  control: ShipControlSummary;
+  entitySummary: EntitySummary;
+}
+```
+
+### `ShipControlSummary`
+
+```ts
+interface ShipControlSummary {
+  entity: number;
+  name: string | null;
+  hexCode: string | null;
+  shipWorldId: number | null;
+  color: number | null;
+  colorCss: string | null;
+  thrustX: number | null;
+  thrustY: number | null;
+  value52: number | null;
+  value84: number | null;
+  value96: number | null;
+  shield: ShipShieldSummary | null;
+  warp: ShipWarpSummary | null;
+  state: ModelRecord;
+}
+```
+
+### Ship shield and warp summaries
+
+```ts
+interface ShipShieldSummary {
+  maxHp: number | null;
+  baseHp: number | null;
+  activeTankHp: number | null;
+  inactiveTankHp: number | null;
+  tankValues: number[];
+}
+
+interface ShipWarpSummary {
+  active: boolean;
+  ticks: number;
+  elapsedSeconds: number;
+  durationSeconds: number;
+  remainingSeconds: number;
+}
+```
+
+## Player, Blocks, Materials
+
+```ts
+interface PlayerCollection {
+  all(): PlayerSummary[];
+  current(): PlayerSummary | null;
+}
+
+interface BlockCollection {
+  all(): BlockSummary[];
+  at(x: number, y: number): BlockSummary | null;
+}
+
+interface MaterialCollection {
+  all(): MaterialSummary[];
+}
+```
+
+### `PlayerSummary`
+
+```ts
+interface PlayerSummary {
+  entity: number;
+  name: string | null;
+  heldItemId: number | null;
+  heldItemName: string | null;
+  repairTargetDistance: number | null;
+  repairTargetAngle: number | null;
+  shipRank: PlayerShipRank | null;
+  patronTier: "bronze" | "silver" | "gold" | "plat" | "flux" | null;
+  isDeveloper: boolean;
+  isPatron: boolean;
+  piloting: boolean;
+  muted: boolean;
+  actionPreview: PlayerActionPreviewSummary | null;
+  state: ModelRecord;
+}
+```
+
+### `PlayerActionPreviewSummary`
+
+```ts
+interface PlayerActionPreviewSummary {
+  entity: number;
+  active: boolean;
+  x: number | null;
+  y: number | null;
+  width: number | null;
+  height: number | null;
+  progress: number | null;
+  color: number | null;
+  colorCss: string | null;
+  actionName: "place" | "break" | "blueprint" | null;
+  blueprintId: number | null;
+  blueprintItems: BlueprintPreviewSummary[];
+  state: ModelRecord;
+}
+```
+
+### `BlockSummary`
+
+```ts
+interface BlockSummary {
+  x: number;
+  y: number;
+  entities: EntitySummary[];
+}
+```
+
+### `MaterialSummary`
+
+```ts
+interface MaterialSummary {
+  material: number;
+  name: string | null;
+  count: number;
+  solid: boolean | null;
+  hp: number | null;
+}
+```
+
+## World State Classes
+
+These classes are public mostly for inspection, replay, testing, and lower-level
+tooling.
+
+### `WorldStore`
+
+```ts
+class WorldStore {
+  currentWorldId: number | null;
+  worlds: Map<number, WorldState>;
+
+  get(id: number): WorldState;
+  apply(packet: unknown): WorldUpdate | null;
+  snapshot(options?: { includeTiles?: boolean; includeModel?: boolean }): WorldSnapshot[];
+  ids(): number[];
+  overworld(): WorldState | null;
+  shipWorld(): WorldState | null;
+  currentShipEntity(): EntitySummary | null;
+}
+```
+
+### `WorldState`
+
+```ts
+class WorldState {
+  constructor(id: number);
+
+  id: number;
+  seed: number | null;
+  isOverworld: boolean | null;
+  tileset: Tileset | null;
+  blockWidth: number | null;
+  blockHeight: number | null;
+  parentWorld: number | null;
+  parentEntity: number | null;
+  tiles: Map<string, Tile>;
+  chunks: unknown[];
+  events: unknown[];
+  modelPackets: unknown[];
+  commsBubbles: CommsBubbleSummary[];
+  model: ModelState;
+  lastChunkPatch: unknown;
+  lastPacket: unknown;
+  meta: unknown;
+
+  readMeta(packet: unknown): void;
+  addCommsBubble(packet: unknown): CommsBubbleSummary;
+  decodeEncrypted(data: Uint8Array | ArrayBuffer | number[]): unknown;
+  applyTile(value: unknown): Tile | null;
+  applyChunk(value: unknown): Tile[] | null;
+  setTile(tile: Tile): Tile;
+  normalizeTile(tile: Tile): Tile;
+  materials(): MaterialSummary[];
+  snapshot(options?: { includeTiles?: boolean; includeModel?: boolean }): WorldSnapshot;
+  table(id: number): Map<number, ModelRecord>;
+  record(tableId: number, entityId: number): ModelRecord | null;
+  tileDefinition(material: number): TileDefinition | null;
+  entity(entityId: number): EntitySummary | null;
+  entities(): EntitySummary[];
+  blocks(): BlockSummary[];
+}
+```
+
+### `ModelState`
+
+```ts
+class ModelState {
+  generation: number | null;
+  tables: Map<number, Map<number, ModelRecord>>;
+  removedEntities: number[];
+  lastUpdate: unknown;
+  errors: unknown[];
+
+  table(id: number): Map<number, ModelRecord>;
+  record(tableId: number, entityId: number): ModelRecord | null;
+  entity(entityId: number): EntitySummary | null;
+  entities(): EntitySummary[];
+  blocks(): BlockSummary[];
+  apply(bytes: Uint8Array | ArrayBuffer | number[]): unknown;
+  snapshot(options?: { includeTables?: boolean }): ModelSnapshot;
+  tablesSnapshot(): unknown[];
+  transforms(): TransformSummary[];
+  itemHolders(): ItemHolderSummary[];
+  fabricators(): FabricatorSummary[];
+  players(): PlayerSummary[];
+  shipControls(): ShipControlSummary[];
+  shipMetadata(): ShipWorldMetadataSummary | null;
+  machines(): MachineSummary;
+}
+
+type ModelRecord = Record<string, unknown>;
+```
+
+### `WorldSnapshot`
+
+```ts
+interface WorldSnapshot {
+  id: number;
+  is_overworld: boolean | null;
+  overworldZone: OverworldZoneSummary | null;
+  shipMetadata: ShipWorldMetadataSummary | null;
+  tileset: Tileset | null;
+  seed: number | null;
+  block_w: number | null;
+  block_h: number | null;
+  parent_world: number | null;
+  parent_ent: number | null;
+  tileCount: number;
+  chunkCount: number;
+  lastChunkPatch: unknown;
+  lastPacket: unknown;
+  meta: unknown;
+  materials: MaterialSummary[];
+  model: ModelSnapshot;
+  entities: EntitySummary[];
+  blocks: BlockSummary[];
+  transforms: TransformSummary[];
+  machines: MachineSummary;
+  players: PlayerSummary[];
+  shipControls: ShipControlSummary[];
+  commsBubbles: CommsBubbleSummary[];
+  tiles?: Tile[];
+}
+```
+
+### World metadata
+
+```ts
+interface OverworldZoneSummary {
+  id: number;
+  baseId: number;
+  layer: number;
+  key: string;
+  name: string;
+  tiered: boolean;
+  displayName: string;
+}
+
+interface ShipWorldMetadataSummary {
+  name: string | null;
+  color: number | null;
+  colorCss: string | null;
+  width: number | null;
+  height: number | null;
+  lockdownTimerSeconds: number | null;
+  lockdownCountdownSeconds: number | null;
+  onlineShipOwnerCount: number | null;
+  requiredShipOwnerCount: number | null;
+  allShipOwnersOnline: boolean | null;
+  lockdownEngaged: boolean | null;
+  lockdownState: ModelRecord;
+  shipState: ModelRecord;
+}
+
+interface WorldUpdate {
+  type: string;
+  world: WorldState | null;
+  packet?: unknown;
+  bubble?: CommsBubbleSummary;
+  decoded?: unknown;
+  updates?: unknown[];
+  result?: unknown;
+}
+```
+
+### Tiles
+
+```ts
+interface Tile {
+  x: number;
+  y: number;
+  material: number;
+  materialName?: string | null;
+  shape: number;
+  shapeName?: string | null;
+  hp: number;
+  /** @deprecated Use hp. Raw 0-255 HP fraction byte, not absolute integrity. */
+  integrity: number;
+  color: number | null;
+  solid?: boolean | null;
+  maxHp?: number | null;
+  hpRatio?: number | null;
+  hpValue?: number | null;
+}
+
+interface TilePhysics {
+  filter?: {
+    categoryBits: number;
+    maskBits: number;
+    groupIndex: number;
+  };
+  transparent?: boolean;
+  walkway?: boolean;
+  restitution?: number;
+  friction?: number;
+}
+
+interface TileDefinition {
+  name?: string;
+  solid: boolean;
+  destruct_item?: number;
+  blocks_bullets?: boolean;
+  hp?: number;
+  no_build_surface?: boolean;
+  physics?: TilePhysics;
+}
+
+interface Tileset {
+  scale: number;
+  atlas: string;
+  tile_width: number;
+  tiles: TileDefinition[];
+}
+```
+
+### `ModelSnapshot`
+
+```ts
+interface ModelSnapshot {
+  generation: number | null;
+  tableCount: number;
+  entityCount: number;
+  removedEntities: number[];
+  lastUpdate: unknown;
+  errors: unknown[];
+  entities: EntitySummary[];
+  blocks: BlockSummary[];
+  transforms: TransformSummary[];
+  players: PlayerSummary[];
+  shipControls: ShipControlSummary[];
+  machines: MachineSummary;
+  tables: unknown[];
+}
+```
+
+## Additional Entity Component Shapes
+
+```ts
+interface TransformSummary {
+  entity: number;
+  x: number | null;
+  y: number | null;
+  rot: number | null;
+  flags: unknown[];
+}
+
+interface ItemHolderSummary {
+  entity: number;
+  itemId: number | null;
+  itemName: string | null;
+  count: number | null;
+}
+
+interface ItemCrateSummary {
+  entity: number;
+  itemId: number | null;
+  itemName: string | null;
+  count: number | null;
+  width: number | null;
+  height: number | null;
+  itemState: ModelRecord;
+  sizeState: ModelRecord;
+}
+
+interface HoverOutlineSummary {
+  entity: number;
+  width: number | null;
+  height: number | null;
+  rawWidth: number | null;
+  rawHeight: number | null;
+  state: ModelRecord;
+}
+
+interface MapMarkerSummary {
+  entity: number;
+  kind: string;
+  title: string | null;
+  key: string | null;
+  description: string | null;
+  color: number | null;
+  colorCss: string | null;
+  accentColor: number | null;
+  accentColorCss: string | null;
+  width: number | null;
+  height: number | null;
+  labelState: ModelRecord;
+  zoneState: ModelRecord;
+}
+
+interface DockingSpringSummary {
+  entity: number;
+  id: number | null;
+  width: number;
+  height: number;
+  state: ModelRecord;
+}
+
+interface HugeThrusterSummary {
+  entity: number;
+  width: number;
+  height: number;
+  state: ModelRecord;
+}
+
+interface ShipSizeSummary {
+  entity: number;
+  width: number | null;
+  height: number | null;
+  rawWidth: number | null;
+  rawHeight: number | null;
+  state: ModelRecord;
+}
+
+interface HealthSummary {
+  entity: number;
+  hp: number | null;
+  maxHp: number | null;
+  ratio: number | null;
+  state: ModelRecord;
+}
+
+interface BotSummary {
+  entity: number;
+  className: string;
+  identifier: string;
+  typeA: number | null;
+  typeB: number | null;
+}
+```
+
+## Blueprint Shapes
+
+### Placement request
+
+```ts
+interface BlueprintPlacement {
+  x: number;
+  y: number;
+  width?: number;
+  height?: number;
+  w?: number;
+  h?: number;
+  source: string;
+}
+
+interface BlueprintPlacementMessage {
+  type: 9;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  source: string;
+}
+```
+
+### Preview state
+
+```ts
+interface BlueprintPreviewSummary {
+  entity: number;
+  itemId: number;
+  itemName: string | null;
+  bits: number;
+  rawBits: number | null;
+  placementOffsets: number[];
+  placementCount: number;
+  placements: {
+    offset: number;
+    x: number | null;
+    y: number | null;
+    itemId: number;
+    itemName: string | null;
+  }[];
+  x: number | null;
+  y: number | null;
+  rot: number | null;
+  state: ModelRecord;
+}
+```
+
+## PUI And Comms Shapes
+
+```ts
+interface PuiEvent {
+  type: "pui";
+  filter?: number;
+  ent_id?: number;
+  update?: boolean;
+  data?: unknown;
+  world?: number | null;
+}
+
+interface CommsMessage {
+  type: 3;
+  msg: string;
+}
+
+interface NormalizedCommsMessage {
+  raw: unknown;
+  text: string;
+}
+
+interface CommsEvent {
+  type: "comms";
+  filter?: number;
+  ent_id: number | null;
+  entity: number | null;
+  msgs_text: unknown[];
+  rawMessages: unknown[];
+  messages: NormalizedCommsMessage[];
+  update?: boolean;
+  world?: number | null;
+}
+
+interface CommsBubbleSummary {
+  sequence: number;
+  worldId: number;
+  entity: number | null;
+  modelId: number | null;
+  message: string;
+  color: number | null;
+  colorCss: string | null;
+  durationSeconds: number | null;
+  raw: unknown;
+}
+```
+
+## Scanner And Ack Shapes
+
+```ts
+interface CommandAck {
+  world: number;
+  commandNumber: number;
+}
+
+interface ScannerResult {
+  kind: "manifest" | "bom" | "unknown";
+  sid: number | null;
+  shipHex: string | null;
+  shipName: string | null;
+  blocks: Record<string, number> | null;
+  objects: Record<string, number> | null;
+  inventories: Record<string, number> | null;
+  materials: Record<string, number> | null;
+}
+```
+
+## Helper Function Exports
+
+These are public lower-level helpers. Prefer the object/domain methods unless
+you explicitly need protocol payloads or decoded utility functions.
+
+### Msgpack
+
+Module: `dredless/protocol/msgpack` or root.
+
+```ts
+function decodeMsgpack(bytes: Uint8Array | ArrayBuffer | number[]): unknown;
+function encodeMsgpack(value: unknown): Uint8Array;
+```
+
+### Commands
+
+Module: `dredless/protocol/commands` or root.
+
+```ts
+function buildSignedCommandPacket(command: Command, sessionId: number): Uint8Array;
+```
+
+### Inventory helpers
+
+Module: `dredless/protocol/inventory` or root.
+
+```ts
+function normalizeEquipmentSlot(slot: EquipmentSlot): 16 | 17 | 18 | 19 | 20 | 21;
+function equipmentSlotName(slot: number): "head" | "face" | "body" | "back" | "hands" | "feet" | null;
+function buildInventoryDragCommand(source: number, target: number, split?: boolean): InventoryDragCommand;
+function buildEquipItemCommand(source: number, slot: EquipmentSlot, split?: boolean): InventoryDragCommand;
+function buildUnequipItemCommand(slot: EquipmentSlot, target?: number, split?: boolean): InventoryDragCommand;
+function normalizeInventoryEvent(event: unknown): InventoryState;
+```
+
+Inventory drag output remains protocol-shaped:
+
+```ts
+interface InventoryDragCommand {
+  drag: {
+    source: number;
+    target: number;
+    split: boolean;
+  };
+}
+```
+
+`normalizeInventoryEvent()` returns the normalized `InventoryState` shape documented under `client.inventory`.
+
+### Comms helpers
+
+Module: `dredless/protocol/comms` or root.
+
+```ts
+function buildCommsMessage(message?: string): CommsMessage;
+function normalizeCommsEvent(event: unknown): CommsEvent;
+function flattenRichText(value: unknown): string;
+```
+
+### Sign helpers
+
+Module: `dredless/protocol/sign` or root.
+
+```ts
+function buildSignTextMessage(text?: string, mode?: SignDisplayMode): SignTextMessage;
+function normalizeSignDisplayMode(mode?: SignDisplayMode): 0 | 1 | 2;
+function signDisplayModeName(mode: number): SignDisplayMode | null;
+```
+
+Output:
+
+```ts
+interface SignTextMessage {
+  type: 5;
+  cmd: "sign_text";
+  args: [string, 0 | 1 | 2];
+}
+```
+
+### Ship-management helpers
+
+Module: `dredless/protocol/ship-management` or root.
+
+```ts
+function buildShipManagementMessage(act: string, arg?: unknown, extra?: Record<string, unknown> | null): ShipManagementMessage;
+function buildShipPrivacyMessage(privacy: ShipPrivacy): ShipManagementMessage;
+function buildStarterRecoveryMessage(itemId: number): ShipManagementMessage;
+function buildPlayerListMessage(): ShipManagementMessage;
+function buildInviteResetMessage(): ShipManagementMessage;
+function buildSetPlayerRankMessage(refId: number, rank: ShipPlayerRank): ShipManagementMessage;
+function buildKickPlayerMessage(refId: number): ShipManagementMessage;
+function buildBanPlayerMessage(refId: number): ShipManagementMessage;
+function buildDemoteSelfMessage(): ShipManagementMessage;
+function normalizePrivacy(privacy: ShipPrivacy): 0 | 1;
+function normalizePlayerRank(rank: ShipPlayerRank): 0 | 1 | 3;
+function normalizeShipConfig(event: unknown): ShipConfig;
+function normalizeCaptainSubrank(event: unknown): CaptainSubrank;
+function normalizeShipPlayerList(event: unknown, previous?: ShipPlayerList | null, currentCaptainSubrank?: CaptainSubrank | null): ShipPlayerList;
+```
+
+Message output:
+
+```ts
+interface ShipManagementMessage {
+  type: 4;
+  act: string;
+  arg: unknown;
+  rank?: unknown;
+}
+```
+
+### Blueprint helpers
+
+Module: `dredless/protocol/blueprint` or root.
+
+```ts
+function buildBlueprintPlacementMessage(placement: BlueprintPlacement): BlueprintPlacementMessage;
+```
+
+### UI config helpers
+
+Module: `dredless/protocol/ui-config` or root.
+
+```ts
+function buildNavigationUnitConfigData(entity: number, config: NavigationUnitConfig & { destination: number }): Uint8Array;
+function buildNavigationUnitClipboardConfigData(config: NavigationUnitConfig & { destination: number }): Uint8Array;
+function buildNavigationUnitPasteConfigData(entity: number, config: NavigationUnitConfig & { destination: number }): Uint8Array;
+function buildGeneratorMazePuzzleData(entity: number, solution: string | number): Uint8Array;
+function buildCargoHatchFilterConfigData(entity: number, filterMode?: LoaderFilterMode): Uint8Array;
+function buildCargoHatchFilterItemsData(entity: number, filterSlots?: Array<number | null | undefined>): Uint8Array;
+function buildCargoHatchFullConfigData(entity: number, config?: Pick<LoaderFullConfig, "filterMode" | "filterSlots">): Uint8Array;
+function buildCargoHatchCopyConfigData(config?: Pick<LoaderFullConfig, "filterMode" | "filterSlots">): Uint8Array;
+function buildClipboardConfigData(target: ClipboardTarget, commandName: string, values?: Iterable<number>): Uint8Array;
+function buildClipboardFixedAngleData(target: ClipboardTarget, direction: FixedAngleDirection): Uint8Array;
+function buildGeneratorClipboardDirectionData(direction: FixedAngleDirection): Uint8Array;
+function buildCargoEjectorDirectionData(entity: number, direction: FixedAngleDirection): Uint8Array;
+function buildCargoEjectorPasteConfigData(entity: number, direction: FixedAngleDirection): Uint8Array;
+function buildCargoEjectorCopyConfigData(direction: FixedAngleDirection): Uint8Array;
+function buildCargoEjectorClipboardDirectionData(direction: FixedAngleDirection): Uint8Array;
+function buildExpandoClipboardAngleData(angle: number): Uint8Array;
+function buildLoaderClipboardConfigData(config?: LoaderConfig): Uint8Array;
+function buildLoaderConfigData(entity: number, config?: LoaderConfig): Uint8Array;
+function buildLoaderCopyConfigData(config?: LoaderFullConfig): Uint8Array;
+function buildLoaderFilterConfigData(entity: number, filterMode?: LoaderFilterMode): Uint8Array;
+function buildLoaderFilterItemsData(entity: number, filterSlots?: Array<number | null | undefined>): Uint8Array;
+function buildLoaderFullConfigData(entity: number, config?: LoaderFullConfig): Uint8Array;
+function buildPusherConfigData(entity: number, config?: PusherConfig): Uint8Array;
+function buildPusherFilterItemsData(entity: number, filterSlots?: Array<number | null | undefined>): Uint8Array;
+```
+
+Clipboard/config input types:
+
+```ts
+type ClipboardTarget =
+  | number
+  | "loader" | "loader-config" | "loaderConfig"
+  | "hatch" | "cargo-hatch" | "cargoHatch"
+  | "ejector" | "cargo-ejector" | "cargoEjector"
+  | "expando" | "expando-box" | "expandoBox"
+  | "generator" | "shield-generator" | "shieldGenerator"
+  | "navigation" | "navigation-unit" | "navigationUnit"
+  | "nav" | "nav-unit" | "navUnit";
+
+const FixedAngleDirection = { Right: "right", Up: "up", Left: "left", Down: "down" } as const;
+type FixedAngleDirection = typeof FixedAngleDirection[keyof typeof FixedAngleDirection];
+```
+
+### Generator maze helpers
+
+Module: `dredless/game/generator-maze` or root.
+
+```ts
+function generateGeneratorMaze(seed: number): GeneratorMaze;
+function solveGeneratorMazeSeed(seed: number): string;
+function maybeSolveGeneratorMazeSeed(seed: number | null | undefined): string | null;
+```
+
+Output:
+
+```ts
+interface GeneratorMazeCellWalls {
+  up: boolean;
+  down: boolean;
+  left: boolean;
+  right: boolean;
+}
+
+interface GeneratorMazeCell {
+  x: number;
+  y: number;
+  value: number;
+  hex: string;
+  digit: number;
+  walls: GeneratorMazeCellWalls;
+  backtrackDirection: number;
+  marker: number;
+}
+
+interface GeneratorMaze {
+  seed: number;
+  width: number;
+  height: number;
+  cells: GeneratorMazeCell[];
+  rows: GeneratorMazeCell[][];
+  solution: string;
+}
+```
+
+### Crypto, compression, and model decoding
+
+Modules: `dredless/crypto/chacha`, `dredless/compression/lz4`,
+`dredless/model`, and root.
+
+```ts
+function decryptPayload(
+  wireBytes: Uint8Array | ArrayBuffer | number[],
+  worldId: number,
+  seed: number
+): Uint8Array;
+
+function decompressLz4Frame(bytes: Uint8Array | ArrayBuffer | number[]): Uint8Array;
+
+function decodeModelData(bytes: Uint8Array | ArrayBuffer | number[]): unknown;
+```
+
+### Ship spec helpers
+
+Module: `dredless/ships`.
+
+```ts
+function createShipSpec(name?: string, color?: string): ShipSpec;
+function createInviteShipSpec(code: string): ShipSpec;
+```
+
+`createShipSpec()` returns a `{ type: "new", ... }` ship spec. 
+`createInviteShipSpec()` returns a `{ type: "invite", code }` ship spec.
+
+## Public Constants From Subpath Modules
+
+These constants are exported by helper subpaths for consumers that need protocol
+symbols. They are not required for normal object-domain use.
+
+### `dredless/protocol/blueprint`
+
+```ts
+const BLUEPRINT_PLACEMENT_TYPE: 9;
+```
+
+### `dredless/protocol/comms`
+
+```ts
+const COMMS_MESSAGE_TYPE: 3;
+```
+
+### `dredless/protocol/inventory`
+
+```ts
+const EQUIPMENT_SLOT_INDEXES: Readonly<{
+  head: 16;
+  face: 17;
+  body: 18;
+  back: 19;
+  hands: 20;
+  feet: 21;
+}>;
+```
+
+### `dredless/protocol/ship-management`
+
+```ts
+const BAN_ACTION: "ban";
+const DEMOTE_SELF_ACTION: "demote_self";
+const KICK_ACTION: "kick";
+const PLAYER_LIST_ACTION: "player_list";
+const INVITE_RESET_ACTION: "invite_reset";
+const SET_PRIVACY_ACTION: "set_privacy";
+const SET_RANK_ACTION: "set_rank";
+const SHIP_MANAGEMENT_TYPE: 4;
+const STARTER_RECOVERY_ACTION: "starter_recovery";
+```
+
+### `dredless/protocol/sign`
+
+```ts
+const SIGN_TEXT_COMMAND: "sign_text";
+const SIGN_DISPLAY_MODES: Map<0 | 1 | 2, "always" | "when-near" | "on-hover">;
+```
+
+### `dredless/protocol/ui-config`
+
+```ts
+const CLIPBOARD_ACTION: 1;
+const CLIPBOARD_ANGLE_COMMAND: "angle";
+const CLIPBOARD_FIXED_ANGLE_COMMAND: "angle_fixed";
+const CLIPBOARD_TARGET_VALUES: Map<string, number>;
+const FIXED_ANGLE_VALUES: Map<string, 0 | 1 | 2 | 3>;
+const GENERATOR_MAZE_PUZZLE_COMMAND: "maze_puzzle";
+const LOADER_CONFIG_COMMAND: "config_loader";
+const LOADER_FALSE: 0x8e;
+const LOADER_FILTER_CONFIG_COMMAND: "filter_config";
+const LOADER_FILTER_ITEMS_COMMAND: "filter_items";
+const LOADER_TRUE: 0x8d;
+const NAV_UNIT_COMMAND: "config_nav_unit";
+const NAV_UNIT_FALSE: 0x8d;
+const NAV_UNIT_TRUE: 0x8e;
+const PUSHER_CONFIG_COMMAND: "config_pusher";
+const PUSHER_FILTER_ITEMS_COMMAND: "filter_items";
+```
+
+## Usage Patterns
+
+### Read loaders from a live client
+
+Use [NODE_API.md](./NODE_API.md) or [BROWSER_API.md](./BROWSER_API.md) to start a client for the current runtime.
+
+```js
+await client.whenReady();
+
+for (const loader of client.currentShip().machines.loaders()) {
+  console.log(loader.id, loader.pick, loader.place, loader.cycle);
+}
+```
+
+### Read all nearby ships, including detailed loaded worlds when available
+
+```js
+const ships = client.overworld().ships({
+  includeWorld: true,
+  includeModel: true,
+  sort: "distance"
+});
+
+for (const ship of ships) {
+  const snapshot = ship.snapshot();
+  console.log(snapshot.name, snapshot.hexCode, snapshot.hasWorldData);
+}
+```
+
+### Use generic features before narrowing to a machine type
+
+```js
+const entity = client.currentShip().entities.get(14);
+
+if (entity.has("loader")) {
+  const loader = entity.asLoader();
+  loader.setCycle(10);
+}
+
+if (entity.has("outline")) {
+  console.log(entity.feature("outline"));
+}
+```
+
+### Configure a pusher
+
+```js
+const pusher = client.currentShip().machines.pusher(27);
+
+pusher.configure({
+  mode: "push",
+  filteredMode: "pull",
+  angle: 90,
+  speed: 20,
+  length: 30,
+  filterInventory: true
+});
+```
+
+### Configure a navigation unit
+
+```js
+const nav = client.currentShip().machines.navigationUnit();
+
+nav.setDestination(30, {
+  autoWarpOnShieldFailure: true,
+  autoWarpOnNoCaptains: false
+});
+```
+
+## Cost Guidelines
+
+Use handles for normal live code:
+
+```js
+client.currentShip().entities.get(id);
+client.currentShip().machines.loader(id);
+```
+
+Use raw grouped state for display, sorting, and cheap bulk reads:
+
+```js
+client.currentShip().entities.raw();
+client.currentShip().machines.state();
+```
+
+Use snapshots when you need immutable point-in-time data:
+
+```js
+entity.snapshot();
+client.currentShip().entities.snapshots();
+client.state({ includeModel: true });
+```
+
+Use debug and world/model classes when reverse engineering, replaying captures,
+or validating protocol assumptions:
+
+```js
+client.debug.modelRecord(worldId, tableId, entityId);
+client.debug.decodeErrors();
+client.debug.worldStore();
+```