dredless 0.7.0 → 1.0.1

package/docs/PLAYER_INVENTORY.md

@@ -0,0 +1,235 @@
+# Player input and inventory
+
+[Documentation index](README.md) · [Machines](MACHINES.md) · [API reference](API_REFERENCE.md)
+
+## Contents
+
+- [Read the player](#read-the-player)
+- [Send input](#send-input)
+- [Persistent input settings](#persistent-input-settings)
+- [Read inventory](#read-inventory)
+- [Move and equip items](#move-and-equip-items)
+- [Blueprints](#blueprints)
+- [Chat and comms](#chat-and-comms)
+
+## Read the player
+
+```ts
+client.player.current(): PlayerSummary | null;
+client.player.entity(): EntityHandle | null;
+client.player.name(): string | null;
+client.player.rank(): CurrentPlayerRank;
+```
+
+`rank()` returns `{shipRank, subrank, isCaptain, patronTier}`. `shipRank` uses names such as `"guest"`, `"crew"`, or
+`"captain"`; it can be `null` before local-player state is known. A WebSocket session ID (`sid`) is not the player's
+entity ID. Management's `refId` is another identifier again.
+
+Player summaries from `client.player.current()` and `world.players.all()` include:
+
+| Field | Meaning |
+| --- | --- |
+| `heldItemId`, `heldItemName` | Held item, or `null` when empty. |
+| `heldItemAngle` | Held tool angle in radians in the current world's coordinate frame; decoded as the server value divided by `200`. |
+| `heldItemBeamDistance` | Beam distance shared by repair tools and handheld pushers, in world units; decoded as the server value divided by `10`. |
+| `itemMode` | Server-reported numeric item mode code. |
+| `buildMultiplier` | Build reach multiplier, decoded as the server value divided by `10`. |
+| `isLocal` | Whether this entity matches the decrypted camera-focus message. False until that identity is known. |
+| `zoomedOut` | Server-requested camera zoom state. This flag alone does not identify which machine the player is operating. |
+| `invisible` | Server invisibility flag; the official client hides the sprite and excludes it from name suggestions for other players. |
+| `cheats` | `{noclip, sandboxBuild}`: noclip/flight and sandbox build mode flags. |
+| `itemEffectActive` | Shared item effect flag. The official renderer uses it for rocket/hover pack exhaust and certain held-item effects. Repair/pusher beams also depend on a positive `heldItemBeamDistance`. |
+| `animation` | `{facing, orientation, walking}`: sprite mirror sign, numeric orientation code, and speed-based limb animation flag. |
+| `appearance` | Base outfit colors, cosmetic styles, and equipped item visual overrides; `null` until the appearance component is available. |
+
+`itemMode`, `heldItemAngle`, and `heldItemBeamDistance` are `null` until available. `buildMultiplier` defaults to `1`, matching the official
+client. `heldItemAngle` replaces `repairTargetAngle`, whose previous scaling
+was incorrect, and `zoomedOut` replaces `piloting`. Helm `occupied` remains inferred from zoom state combined with
+helm updates. `heldItemBeamDistance` replaces `repairTargetDistance`, and `itemEffectActive` replaces `toolEffectActive`.
+Other summary fields include name, ranks, patron status, mute status, and action
+preview; see [PlayerSummary](../src/index.d.ts) for the complete shape.
+
+`appearance` contains packed RGB `bodyColor`, `legsColor`, `skinColor`, and `feetColor`, plus `hair`, `hat`, `face1`,
+and `face2`, each shaped as `{color, styleId}`. Style IDs index the official client's cosmetic catalogs; `0` means no
+style. Outfit fields default to zero when omitted from the initial appearance component, and sparse updates retain
+previous values. The style catalog's image paths and rendering rules are not bundled with these summaries.
+
+`appearance.itemOverrides` contains `back`, `hands`, `feet`, `head1`, and `head2`. Each is `null` or an
+`{itemId, itemName}` entry describing an equipped item visual. These are separate from the base cosmetic
+styles. `back` includes backpacks, rocket packs, and hover packs; it replaces the incorrectly named `body` override.
+The inventory still has separate body and back slots. The replicated appearance component has no confirmed body
+item visual field. The raw appearance component is retained in `appearance.state`.
+
+For handheld pushers, `itemMode & 1` selects the beam direction. Packs can be equipped using
+`client.inventory.equip(source, "back")`; generic player input controls their use.
+
+`animation.facing` is normally `-1` or `1`; `orientation` retains the server's numeric code. `animation.walking`
+selects the official renderer's speed-based limb swing rather than its hovering pose. It can be enabled while the
+player stands still, so it should not be used to detect movement. Raw fields whose meaning is not confirmed remain
+in `player.state`.
+
+Local identity comes from packet `21`, not a player animation flag or the WebSocket session ID. When replaying
+captures, pass camera-focus packets to `WorldStore.apply()` as well as world metadata and model packets. Standalone
+`ModelState` consumers can set the identity with `model.setLocalPlayerEntity(entityId)` and clear it with `null`.
+When attaching after the camera-focus packet has already been received, local identity remains unknown until another
+focus packet arrives or the entity is set explicitly on the world's model.
+
+## Send input
+
+These methods return the client after sending or queueing input, without waiting for action success:
+
+```ts
+client.player.move(vector?: {x?: number; y?: number}, command?: Command): DredlessClient;
+client.player.aim(point?: {x?: number; y?: number; mx?: number; my?: number}, command?: Command): DredlessClient;
+client.player.action(flags?: Command, command?: Command): DredlessClient;
+client.player.useEntity(entity: EntityRef, options?: {invSlot?: number; hold?: boolean},
+                         command?: Command): DredlessClient;
+client.player.useHeldItem(options?: {invSlot?: number; hold?: boolean}, command?: Command): DredlessClient;
+client.player.placeHeldItem(options?: {invSlot?: number; hold?: boolean}, command?: Command): DredlessClient;
+client.player.rotateHeldItem(options?: {invSlot?: number; hold?: boolean}, command?: Command): DredlessClient;
+client.player.selectSlot(invSlot?: number, command?: Command): DredlessClient;
+```
+
+Movement `x`/`y` are input axes; aiming supplies game-coordinate `mx`/`my` (`x`/`y` are accepted by the aim helper).
+`invSlot` defaults to `0` and `hold` to `true` for use/rotate helpers. These calls do not implement pathfinding, range
+checks, or an automatic input loop.
+
+Each send builds a complete command: unspecified command fields are defaulted, not inherited from the previous action.
+Persistent settings below are the exception. If you need movement and aim/action in the same input, supply the other
+fields through `command` instead of assuming separate sends merge.
+
+**Fragment:** send combined input, then later send an explicit stop:
+
+```js
+client.player.move({x: 1, y: 0}, {mx: 10, my: 5});
+// When the application decides movement should stop:
+client.player.move({x: 0, y: 0});
+```
+
+`Command` exposes input flags (`jump`, `drop`, `act1`, `act2`, held/alternate variants), coordinates, inventory slot,
+entity focus, menu selection, view settings, and drag payloads. Use [the declared Command shape](../src/index.d.ts) for
+the full list; signed packet construction is described in [protocol tools](PROTOCOL.md#commands-and-payloads).
+
+## Persistent input settings
+
+```ts
+client.player.inputSettings(): CurrentInputSettings;
+client.player.setInputSettings(settings?: InputSettings, options?: {send?: boolean}): DredlessClient;
+client.player.setView(width: number, height: number, options?: {send?: boolean}): DredlessClient;
+client.player.setScreenSize(width: number, height: number, options?: {send?: boolean}): DredlessClient;
+client.player.setWrenchMode(mode: WrenchMode, options?: {send?: boolean}): DredlessClient;
+client.player.setTurretMode(mode: TurretMode, options?: {send?: boolean}): DredlessClient;
+```
+
+`InputSettings` accepts `wrenchMode`, `turretMode`, `viewWidth`, `viewHeight`, `screenWidth`, and `screenHeight`. View
+sizes must be positive finite numbers; screen sizes must be positive integers. `send` defaults to `true`; `false` only
+updates defaults for later commands.
+
+| Constant     | Values                                             |
+|--------------|----------------------------------------------------|
+| `WrenchMode` | `DropAllItems`, `GrabPrimaryItems`, `GrabAllItems` |
+| `TurretMode` | `ContinuousFire`, `VolleyFire`                     |
+
+The constants' values are lowercase hyphenated names such as `"grab-primary-items"`. Defaults are grab-primary-items and
+continuous-fire. These settings persist across input sends; ordinary movement/action fields do not.
+
+## Read inventory
+
+```ts
+client.inventory.state(): InventoryState;
+client.inventory.hotbarSize(): number;
+client.inventory.allSlots(): InventorySlotHandle[];
+client.inventory.hotbarSlots(): InventorySlotHandle[];
+client.inventory.equipmentSlots(): Record<EquipmentSlot, InventorySlotHandle>;
+client.inventory.slot(ref: InventorySlotRef): InventorySlotHandle;
+client.inventory.findItem(itemId: number, options?: {area?: InventoryArea}): InventorySlotHandle | null;
+client.inventory.findItems(itemId: number, options?: {area?: InventoryArea}): InventorySlotHandle[];
+client.inventory.firstEmpty(options?: {area?: InventoryArea}): InventorySlotHandle | null;
+
+type InventoryArea = "all" | "hotbar" | "equipment";
+type InventorySlotRef = number | EquipmentSlot | InventorySlotHandle | InventorySlotSnapshot;
+```
+
+The normalized state has `hotbarSize`, `slots`, `hotbar`, and an `equipment` object. Hotbar size comes from the protocol
+and is independent of the fixed equipment indexes.
+
+| `EquipmentSlot` key | Value     | Absolute slot |
+|---------------------|-----------|---------------|
+| Head                | `"head"`  | 16            |
+| Face                | `"face"`  | 17            |
+| Body                | `"body"`  | 18            |
+| Back                | `"back"`  | 19            |
+| Hands               | `"hands"` | 20            |
+| Feet                | `"feet"`  | 21            |
+
+A slot handle exposes `index`, `kind`, `equipmentSlot`, `itemId`, `itemName`, `count`, `empty`, `exists()`, and
+`snapshot()`. A slot snapshot is a frozen copy or `null`. Slot handles are live reads; no item is guaranteed to be
+present at index zero.
+
+## Move and equip items
+
+```ts
+client.inventory.move(source: InventorySlotRef, target: InventorySlotRef,
+                      options?: {split?: boolean}, command?: Command): DredlessClient;
+client.inventory.equip(source: InventorySlotRef, equipmentSlot?: EquipmentSlot,
+                       options?: {split?: boolean}, command?: Command): DredlessClient;
+client.inventory.unequip(equipmentSlot: EquipmentSlot, target?: InventorySlotRef,
+                         options?: {split?: boolean}, command?: Command): DredlessClient;
+client.inventory.select(slot: InventorySlotRef, command?: Command): DredlessClient;
+
+slot.moveTo(target: InventorySlotRef, options?: {split?: boolean}, command?: Command): DredlessClient;
+slot.equip(equipmentSlot?: EquipmentSlot, options?: {split?: boolean}, command?: Command): DredlessClient;
+slot.unequip(target?: InventorySlotRef, options?: {split?: boolean}, command?: Command): DredlessClient;
+slot.select(command?: Command): DredlessClient;
+```
+
+These are the ordinary call forms; option-object overloads are in the [declarations](../src/index.d.ts). Omit
+`equipmentSlot` to infer it from the source item schema. Inference throws for an empty slot or an item not classified as
+equipment. Unequip targets default to slot `0`; check that destination before moving items.
+
+All actions send input and return immediately. Observe `inventory` for the resulting state. A server can reject the move
+even when local argument validation succeeds.
+
+**Fragment:** `equipmentItemId` must be an actual equipment item ID your application selected:
+
+```js
+const source = client.inventory.findItem(equipmentItemId, {area: "hotbar"});
+if (!source) throw new Error("Requested item is not in the hotbar");
+source.equip();
+```
+
+## Blueprints
+
+```ts
+interface BlueprintPlacement {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  source: string;
+}
+
+client.player.placeBlueprint(placement: BlueprintPlacement,
+  options?: {invSlot?: number; hold?: boolean; mx?: number; my?: number},
+  command?: Command): DredlessClient;
+```
+
+Supply a real blueprint source string and matching dimensions. `x`/`y` must be finite and width/height positive
+integers; runtime builders also accept protocol aliases `w`/`h`. The helper sends the blueprint placement message and
+uses the selected inventory slot, aiming at the placement coordinates unless overridden. The inventory item, range,
+permissions, and game rules must allow placement. There is no placement-success promise.
+
+`buildBlueprintPlacementMessage()` only builds the message; `client.net.sendBlueprintPlacement()` sends it without the
+player-use step. Blueprint preview state is available as an entity feature; it is not proof a placement completed.
+
+## Chat and comms
+
+```ts
+client.sendChatMessage(message?: string): DredlessClient;
+client.sendCommsMessage(message?: string): DredlessClient;
+commsStation.sendMessage(message?: string): DredlessClient;
+```
+
+Chat uses a chat protocol message. Comms targets the active comms interaction; a station handle's send method does not
+include its ID in that message. Establish the interaction first and observe `comms`/`chat` events. Formatting and
+outbound builders are listed in [protocol tools](PROTOCOL.md).

package/docs/PROTOCOL.md

@@ -0,0 +1,227 @@
+# Protocol tools and debugging
+
+[Documentation index](README.md) · [Client networking](CLIENT.md#send-commands-and-messages) · [API reference](API_REFERENCE.md)
+
+## Contents
+
+- [Import map](#import-map)
+- [Commands and payloads](#commands-and-payloads)
+- [Management builders](#management-builders)
+- [Configuration builders](#configuration-builders)
+- [Generator maze helpers](#generator-maze-helpers)
+- [HTTP and invite tools](#http-and-invite-tools)
+- [Debug domains and state classes](#debug-domains-and-state-classes)
+- [Decoding limitations](#decoding-limitations)
+
+## Import map
+
+Prefer high-level domains when implementing game actions. These tools are for integrations, payload construction, capture analysis, and offline decoding. Check the subpath's declarations for full overloads and constants.
+
+| Import                                                                          | Main exports                                                     | Declaration                                                                                    |
+|---------------------------------------------------------------------------------|------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
+| `dredless/protocol`                                                             | Frame/world decoders and shared outbound builders                | [protocol/index.d.ts](../src/protocol/index.d.ts)                                              |
+| `dredless/protocol/msgpack`                                                     | `encodeMsgpack`, `decodeMsgpack`                                 | [codec/msgpack.d.ts](../src/protocol/codec/msgpack.d.ts)                                       |
+| `dredless/protocol/commands`                                                    | `buildSignedCommandPacket`                                       | [commands.d.ts](../src/protocol/outbound/commands.d.ts)                                        |
+| `dredless/protocol/blueprint`                                                   | Blueprint placement builder/type constant                        | [blueprint.d.ts](../src/protocol/outbound/blueprint.d.ts)                                      |
+| `dredless/protocol/comms`                                                       | Comms builder, rich-text flattening/normalization                | [comms.d.ts](../src/protocol/outbound/comms.d.ts)                                              |
+| `dredless/protocol/inventory`                                                   | Drag/equip builders and slot normalization                       | [inventory.d.ts](../src/protocol/outbound/inventory.d.ts)                                      |
+| `dredless/protocol/ship-management`                                             | Management builders, normalizers, action constants               | [ship-management.d.ts](../src/protocol/outbound/ship-management.d.ts)                          |
+| `dredless/protocol/sign`                                                        | Sign builder/display-mode helpers                                | [sign.d.ts](../src/protocol/outbound/sign.d.ts)                                                |
+| `dredless/protocol/ui-config`                                                   | Binary config/clipboard builders and enums                       | [ui-config.d.ts](../src/protocol/outbound/ui-config.d.ts)                                      |
+| `dredless/game/generator-maze`                                                  | Maze generation/solution helpers                                 | [generator-maze.d.ts](../src/state/generator-maze.d.ts)                                        |
+| `dredless/crypto/chacha`                                                        | `decryptPayload`                                                 | [chacha.d.ts](../src/crypto/chacha.d.ts)                                                       |
+| `dredless/compression/lz4`                                                      | `decompressLz4Frame`                                             | [lz4.d.ts](../src/compression/lz4.d.ts)                                                        |
+| `dredless/model`, `dredless/game/model`                                         | `ModelState`, `decodeModelData`                                  | [model/index.d.ts](../src/state/model/index.d.ts)                                              |
+| `dredless/world`, `dredless/state`                                              | World/model state classes                                        | [world/index.d.ts](../src/state/world/index.d.ts), [state/index.d.ts](../src/state/index.d.ts) |
+| `dredless/network`                                                              | Sessions, connections, discovery, ship/invite reads, disconnects | [network/index.d.ts](../src/network/index.d.ts)                                                |
+| `dredless/servers`, `dredless/ships`, `dredless/connection`, `dredless/session` | Focused network APIs                                             | [package export map](../package.json)                                                          |
+
+Runtime entrypoints re-export many shared builders, but not every low-level decoder or action constant. In particular, `decodeIncomingFrame()` belongs to `dredless/protocol`, not the root namespace. Importing from `node_modules/dredless/src/...` is unnecessary and bypasses the supported export map.
+
+## Commands and payloads
+
+```ts
+encodeMsgpack(value: unknown): Uint8Array;
+decodeMsgpack(bytes: Uint8Array | ArrayBuffer | number[]): unknown;
+decodeIncomingFrame(data: string | Uint8Array | ArrayBuffer | number[]): unknown;
+buildSignedCommandPacket(command: Command, sessionId: number): Uint8Array;
+buildBlueprintPlacementMessage(placement: BlueprintPlacement): BlueprintPlacementMessage;
+buildChatMessage(message?: string): ChatMessage;
+buildCommsMessage(message?: string): CommsMessage;
+buildSignTextMessage(text?: string, mode?: SignDisplayMode): SignTextMessage;
+flattenRichText(value: unknown): string;
+normalizeCommsEvent(event: unknown): CommsEvent;
+```
+
+`decodeIncomingFrame()` parses text as JSON and binary as MessagePack; it does not apply decoded packets to state. A model-bearing packet can still contain encrypted/compressed inner payloads.
+
+`buildSignedCommandPacket()` returns the complete signed binary input frame. Ordinary message builders return decoded objects. UI config builders below return inner byte payloads. Keep these three representations distinct: `sendMessage()`/`sendRaw()` encode objects, while `send()` signs input and `sendUiConfig()` wraps a config payload.
+
+```ts
+buildInventoryDragCommand(source: number, target: number, split?: boolean): InventoryDragCommand;
+buildEquipItemCommand(source: number, slot: EquipmentSlot, split?: boolean): InventoryDragCommand;
+buildUnequipItemCommand(slot: EquipmentSlot, target?: number, split?: boolean): InventoryDragCommand;
+normalizeEquipmentSlot(slot: EquipmentSlot): 16 | 17 | 18 | 19 | 20 | 21;
+equipmentSlotName(slot: number): EquipmentSlot | null;
+normalizeInventoryEvent(event: unknown): InventoryState;
+normalizeSignDisplayMode(mode?: SignDisplayMode): 0 | 1 | 2;
+signDisplayModeName(mode: number): SignDisplayMode | null;
+```
+
+Drag builders produce command fields to pass to input sending, not independent game messages. High-level [inventory methods](PLAYER_INVENTORY.md#move-and-equip-items) also accept slot handles and infer equipment locations.
+
+## Management builders
+
+These return `ShipManagementMessage` objects. They perform local argument validation but no I/O or response waiting:
+
+```ts
+buildShipManagementMessage(act: string, arg?: unknown, extra?: Record<string, unknown> | null): ShipManagementMessage;
+buildShipPrivacyMessage(privacy: ShipPrivacy): ShipManagementMessage;
+buildShipGravityMessage(direction: ShipGravityDirection): ShipManagementMessage;
+buildSetPatronPerksMessage(enabled: boolean): ShipManagementMessage;
+buildPlayerListMessage(): ShipManagementMessage;
+buildInviteResetMessage(): ShipManagementMessage;
+buildSaveShipMessage(): ShipManagementMessage;
+buildShipRenameRequestMessage(): ShipManagementMessage;
+buildShipRenameCommitMessage(name: string, color: string): ShipManagementMessage;
+buildStarterRecoveryMessage(itemId: number): ShipManagementMessage;
+buildSetPlayerRankMessage(refId: number, rank: ShipPlayerRank): ShipManagementMessage;
+buildKickPlayerMessage(refId: number): ShipManagementMessage;
+buildBanPlayerMessage(refId: number): ShipManagementMessage;
+buildUnbanPlayerMessage(refId: number): ShipManagementMessage;
+buildDemoteSelfMessage(): ShipManagementMessage;
+```
+
+`ShipManagementMessage` has `{type: 4, act, arg}` plus optional action-specific fields such as `rank` and `arg2`. The generic builder does not implement the action-specific permission/confirmation flows. Prefer [management methods](MANAGEMENT.md) for save, rename, invite reset, demotion, and recovery.
+
+Normalization helpers:
+
+```ts
+normalizePrivacy(value: ShipPrivacy): 0 | 1;
+normalizePlayerRank(value: ShipPlayerRank): 0 | 1 | 3;
+normalizeGravityDirection(value: ShipGravityDirection): 0 | 1 | 2 | 3;
+normalizeShipConfig(event: unknown): ShipConfig;
+normalizeCaptainSubrank(event: unknown): CaptainSubrank;
+normalizeShipPlayerList(event: unknown, previous?: ShipPlayerList | null,
+                        captain?: CaptainSubrank | null): ShipPlayerList;
+normalizeCrewLog(event: unknown, previous?: CrewLog | null): CrewLog;
+```
+
+Pass the inner session submessage, not the outer `{type: 25, submessage}` packet. Player-list/log normalizers merge with the previous normalized state; omitting it begins a fresh state. [Management](MANAGEMENT.md) describes their reset/amend/remove semantics. Action-name constants, `SHIP_MANAGEMENT_TYPE`, and `CREW_LOG_LENGTH` are exported by the management subpath.
+
+## Configuration builders
+
+All return `Uint8Array` payloads. Their configuration types and operational prerequisites are covered in [machines](MACHINES.md); these low-level functions do not merge cached state or open an interaction.
+
+| Family           | Builder calls                                                                                                                                                                      |
+|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Loader           | `buildLoaderConfigData(entity, config?)`, `buildLoaderFullConfigData(entity, config?)`, `buildLoaderFilterConfigData(entity, mode?)`, `buildLoaderFilterItemsData(entity, slots?)` |
+| Pusher           | `buildPusherConfigData(entity, config?)`, `buildPusherFilterItemsData(entity, slots?)`                                                                                             |
+| Navigation       | `buildNavigationUnitConfigData(entity, config)`, `buildNavigationUnitPasteConfigData(entity, config)`                                                                              |
+| Hatch            | `buildCargoHatchFilterConfigData(entity, mode?)`, `buildCargoHatchFilterItemsData(entity, slots?)`, `buildCargoHatchFullConfigData(entity, config?)`                               |
+| Ejector          | `buildCargoEjectorDirectionData(entity, direction)`, `buildCargoEjectorPasteConfigData(entity, direction)`                                                                         |
+| Generator puzzle | `buildGeneratorMazePuzzleData(entity, solution)`                                                                                                                                   |
+
+Clipboard payload builders:
+
+- `buildLoaderClipboardConfigData(config?)`, `buildLoaderCopyConfigData(config?)`
+- `buildNavigationUnitClipboardConfigData(config)`
+- `buildCargoHatchCopyConfigData(config?)`
+- `buildCargoEjectorCopyConfigData(direction)`, `buildCargoEjectorClipboardDirectionData(direction)`
+- `buildGeneratorClipboardDirectionData(direction)`
+- `buildExpandoClipboardAngleData(degrees)`
+- `buildClipboardConfigData(target, commandName, values?)`
+- `buildClipboardFixedAngleData(target, direction)`
+
+Navigation builder config requires `destination`; hatch full/copy config contains `filterMode` and `filterSlots`. Generic clipboard values are `Iterable<number>`; `target` is a `ClipboardTarget` name or numeric selector. Full exact signatures and target aliases are maintained in [ui-config.d.ts](../src/protocol/outbound/ui-config.d.ts).
+
+**Fragment:** `loader` is a live loader handle and `client` owns it. A complete explicit configuration avoids the current numeric-default enum limitation:
+
+```js
+import {buildLoaderConfigData} from "dredless/protocol/ui-config";
+
+const payload = buildLoaderConfigData(loader.id, {
+  pick: "middle-left", place: "middle-right", priority: "normal", cycle: 5, stack: 16
+});
+client.net.sendUiConfig(payload);
+```
+
+Named-enum validation and the numeric/default mismatch also affect low-level optional-config calls. Supply all required enum fields explicitly as described in [loaders](MACHINES.md#loaders), [pushers](MACHINES.md#pushers), and [hatches](MACHINES.md#hatches-ejectors-and-clipboard-settings).
+
+## Generator maze helpers
+
+```ts
+generateGeneratorMaze(seed: number): GeneratorMaze;
+solveGeneratorMazeSeed(seed: number): string;
+maybeSolveGeneratorMazeSeed(seed: number | null | undefined): string | null;
+```
+
+Generation returns `{seed, width, height, cells, rows, solution}`. Each cell records coordinates, encoded value/hex/digit, wall flags, backtrack direction, and marker. Solving computes the solution string without network activity; the `maybe` form returns `null` for unusable input instead of requiring a known seed. Use a seed actually decoded for the target generator. To send a solution, call the generator handle's `solvePuzzle()`.
+
+## HTTP and invite tools
+
+Session/discovery signatures are in the [Node](NODE_API.md) and [browser](BROWSER_API.md) references. Additional named helpers include:
+
+```ts
+fetchInviteMetadata(invite: string | URL, options?: InviteFetchOptions): Promise<InviteMetadata>;
+parseInviteMetadata(html: string): InviteMetadata;
+createShipSpec(name?: string, color?: string): ShipSpec;
+createInviteShipSpec(code: string): ShipSpec;
+```
+
+`InviteFetchOptions` accepts `fetchImpl` for a custom HTTP implementation. Invite metadata contains name, displayed ship ID, preview image URL, hostname, and invite code. Preview images are not fetched or decoded; consumers can process `previewImageUrl` themselves. The parser expects the invite page's metadata, including an invite URL, and may reject unrelated HTML.
+
+Ship-spec helpers are available from `dredless/ships`; they construct objects without joining. The network subpath also exports discovery/resolution helpers; consult its re-export declarations when building custom connection flows.
+
+## Debug domains and state classes
+
+```ts
+client.debug.packets(): unknown[];
+client.debug.decodeErrors(): unknown[];
+client.debug.worldStore(): WorldStore;
+client.debug.modelTable(worldId: number, tableId: number): Map<number, ModelRecord>;
+client.debug.modelRecord(worldId: number, tableId: number, entityId: number): ModelRecord | null;
+client.debug.entities(scope?: ReadWorldScope): EntityDebugSummary[];
+client.debug.entity(scope: ReadWorldScope, entity: EntityRef): EntityDebugSummary | null;
+client.debug.puiPanels(): PuiEvent[];
+client.debug.commsPanels(): CommsEvent[];
+```
+
+Debug reads expose retained/raw state, sometimes by reference. Do not mutate it while a live client is decoding. Capture history is bounded by [client retention options](CLIENT.md#construction-and-retention).
+
+| Class        | Purpose                                      | Core methods                                                                                                                               |
+|--------------|----------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
+| `WorldStore` | Applies decoded packets into worlds          | `apply(packet)`, `get(id)`, `current()`, `shipWorld()`, `overworld()`, `snapshot(options?)`                                                |
+| `WorldState` | Metadata, tiles, events, model for one world | `readMeta(packet)`, `decodeEncrypted(data)`, `entity(id)`, `entities()`, `table(id)`, `record(table, entity)`, `snapshot(options?)`        |
+| `ModelState` | ECS records and derived summaries            | `apply(bytes)`, `table(id)`, `record(table, entity)`, `entities()`, `machines()`, `transforms()`, `snapshot(options?)`, `tablesSnapshot()` |
+
+World snapshots can include tiles/model tables/blocks; model snapshots use `includeTables` and `includeBlocks`. Full constructors, read methods, and structures are in [world declarations](../src/state/world/index.d.ts) and [model declarations](../src/state/model/index.d.ts). Some direct implementation options are broader than their declared overloads.
+
+Additional state APIs used in offline tooling:
+
+```ts
+worldStore.ids(): number[];
+worldStore.currentShipEntity(): EntityDebugSummary | null;
+worldState.addCommsBubble(packet: unknown): CommsBubbleSummary;
+worldState.applyTile(value: unknown): Tile | null;
+worldState.applyChunk(value: unknown): Tile[] | null;
+worldState.setTile(tile: Tile): Tile;
+worldState.normalizeTile(tile: Tile): Tile;
+worldState.tileDefinition(material: number): TileDefinition | null;
+modelState.itemHolders(): ItemHolderSummary[];
+modelState.fabricators(): FabricatorSummary[];
+modelState.players(): PlayerSummary[];
+modelState.setLocalPlayerEntity(entity: number | null): void;
+modelState.shipControls(): ShipControlSummary[];
+modelState.shipMetadata(): ShipWorldMetadataSummary | null;
+```
+
+Tile/chunk setters update the local decoder state only; they are not server block-edit commands. `WorldStore.get(id)` creates a world when absent; use `.worlds.get(id)` to inspect without creating one. Read aggregate summaries through domains in ordinary live applications.
+
+Binary tools include `decryptPayload(wireBytes, worldId, seed)`, `decompressLz4Frame(bytes)`, and `decodeModelData(bytes)`. The protocol aggregate also exposes inner world/model/chunk decoders. These expect the appropriate layer, seed, and world context; a captured WebSocket frame is not automatically a valid argument to a model decoder.
+
+## Decoding limitations
+
+A decoder can retain partial results while recording unsupported tags or malformed sections. Read `decode-error`, model errors, and the retained raw packet before concluding an entity/component is absent. Website parsers and protocol internals can change independently of this package.
+
+Raw `ModelRecord` keys (`q20`, blobs, table IDs, and section tags) are implementation details. Prefer normalized public summaries for application code. Protocol research belongs in a local capture workflow; avoid encoding application behavior around guessed raw-field semantics when a typed field exists.

package/docs/README.md

@@ -0,0 +1,44 @@
+# Documentation
+
+Dredless separates HTTP account sessions from live game connections. A `Session` authenticates requests; a `DredlessClient` owns a WebSocket and decoded world state. 
+In a browser, `BrowserSession` uses the ambient browser cookie jar.
+
+## Start here
+
+1. [Getting started](GETTING_STARTED.md): read servers, join through an invite, inspect state, and close.
+2. Choose [Node sessions](NODE_API.md) or [browser setup](BROWSER_API.md).
+3. Read [completion and lifecycle](CLIENT.md#completion-and-readiness) before sending actions.
+
+## Choose a task
+
+| I want to…                                                       | Read                                                                                   |
+|------------------------------------------------------------------|----------------------------------------------------------------------------------------|
+| Reuse an account or anonymous identity                           | [Node authentication](NODE_API.md#authentication-and-reuse)                            |
+| Join an active ship or load a saved one                          | [Connection methods](NODE_API.md#join-start-and-invites)                               |
+| Observe an official-client socket                                | [Browser attachment](BROWSER_API.md#attach-to-an-existing-socket)                      |
+| Handle disconnects and retain useful state                       | [Client lifecycle](CLIENT.md)                                                          |
+| Subscribe to model, inventory, or management updates             | [Event catalog](EVENTS.md)                                                             |
+| Find an entity, machine, or nearby ship                          | [World and entity reads](WORLD_STATE.md)                                               |
+| Move, aim, equip, or place a blueprint                           | [Player and inventory](PLAYER_INVENTORY.md)                                            |
+| Use a context menu or set door access                            | [Machines and context menus](MACHINES.md#context-menus-and-access)                     |
+| Configure a loader, pusher, launcher, or navigation unit         | [Machine reference](MACHINES.md)                                                       |
+| Save, rename, reset invites, or manage crew                      | [Ship management](MANAGEMENT.md)                                                       |
+| Read crew logs or apply ship patron perks                        | [Ship management](MANAGEMENT.md#crew-logs), [patron perks](MANAGEMENT.md#patron-perks) |
+| Read account details, change a clan tag, or remove account perks | [Account methods](ACCOUNT.md)                                                          |
+| Decode captures or build protocol messages                       | [Protocol and debugging](PROTOCOL.md)                                                  |
+| Understand an error or missing value                             | [Troubleshooting](TROUBLESHOOTING.md)                                                  |
+
+## Reference conventions
+
+[API_REFERENCE.md](API_REFERENCE.md) indexes the reference pages and defines ID, return-value, and type conventions. Each page includes calling signatures and the behavior needed to use them. The package's [TypeScript declarations](../src/index.d.ts) contain complete state shapes and overloads; the [browser declarations](../src/browser.d.ts) describe browser-specific exports.
+
+Examples marked **fragment** assume a connected `client` or authenticated `session` from the setup guides. They are not standalone programs. Examples that change game/account state describe their prerequisites before the code.
+
+Documentation describes the current checkout. Protocol support and website scraping can change with the upstream game. See [troubleshooting](TROUBLESHOOTING.md) for the specific failure surfaces.
+
+## Contributing to these docs
+
+Put setup in the runtime guides, behavior in the relevant domain page, callbacks in the event catalog, and wire-format details in protocol documentation. 
+Add navigation links for new tasks. Include calling signatures, prerequisites, units/ranges, return/completion meaning, errors, and one contextual example where they affect usage. 
+Keep complete state shapes in the declarations; avoid copying a second exhaustive type catalog into Markdown. 
+Put changes between releases in release notes rather than describing the current API as "now" doing something.

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,91 @@
+# Troubleshooting and limitations
+
+[Documentation index](README.md) · [Client lifecycle](CLIENT.md) · [Events](EVENTS.md)
+
+## Contents
+
+- [Connection and identity](#connection-and-identity)
+- [Missing or stale state](#missing-or-stale-state)
+- [Actions that appear to do nothing](#actions-that-appear-to-do-nothing)
+- [Timeouts and retries](#timeouts-and-retries)
+- [Browser and HTTP problems](#browser-and-http-problems)
+- [Useful diagnostics](#useful-diagnostics)
+
+## Connection and identity
+
+| Symptom                                        | Check                                                                                          |
+|------------------------------------------------|------------------------------------------------------------------------------------------------|
+| `fetch is not available`                       | Run on a Node runtime with built-in global `fetch`, or provide it before calling HTTP APIs     |
+| Import/top-level-await syntax error            | Use `.mjs`/ES modules in Node; use a module script or async wrapper in browser scripts         |
+| A different anonymous account appears each run | Retain/reuse `anonKey`; factories without a key can create a new identity                      |
+| Top-level join ignores your account            | Pass your `session`, or call the method on that session directly                               |
+| Join rejects with `4007` and `never_load=true` | If the ship is saved, use `startShip()` so the server may load it                              |
+| Invite join fails                              | Use the invite code segment and the intended server; check permission/expiry and close details |
+| Connection closes after saving                 | Expected with `Saved` (4015); successful save ends the connection                              |
+| Client stays disconnected                      | There is no automatic reconnect; create a new connection/client                                |
+
+`createSession()` does not perform a registered-provider login. [Node authentication](NODE_API.md#authentication-and-reuse) explains using an existing session cookie; [browser authentication](BROWSER_API.md#execution-context) uses the ambient jar.
+
+## Missing or stale state
+
+- A ready client can still have missing world/components/panels. Check nullable reads, then subscribe to the relevant update and read the cache once.
+- A handler installed after an awaited factory can miss initial events. Use a connection descriptor and attach listeners before awaiting readiness when those first events matter.
+- Attachment cannot recover frames received before it began. Inventing `ready`/`sid` metadata does not reconstruct ECS state.
+- Entity IDs are scoped by world. Do not pass an overworld ship entity ID where an interior machine ID is expected.
+- A nearby ship's presence does not imply its interior is loaded. `includeWorld` only includes already-decoded data.
+- Handles and raw summaries have different lifetimes. Entity handles read live state; ship-read handles hold the summary from that query. Re-query ship reads after updates.
+- Disconnect retains last-known worlds while clearing active management/panel state. Do not treat retained data as current server state.
+- Client/world snapshots are not universally deep-cloned or frozen. Mutating returned objects can affect shared cached data; select and clone fields for history.
+- Unsupported decoding can look like absent state. Inspect `decode-error` before assuming the server has no such component.
+
+## Actions that appear to do nothing
+
+First establish whether the API waits for an effect. A returned client means sent/queued, not successful. `await` on a synchronous setter adds no confirmation.
+
+| Action                                                        | Common cause                                                                                                                                                    |
+|---------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Loader/pusher/hatch configuration throws an enum error        | Numeric decoded/default enums are merged into builders requiring named enums. Supply all enum fields explicitly; see [machine limitations](MACHINES.md#loaders) |
+| Launcher angle/power changes no intended target               | Those commands use the active interaction. A launcher handle alone does not select it                                                                           |
+| Sign setter throws a display-mode error                       | Pass `SignDisplayMode.Always`, `WhenNear`, or `OnHover` explicitly; its numeric default is currently rejected by the named-mode builder                         |
+| Sign/fabricator/comms operation affects the wrong interaction | Their messages also rely on active UI state; `open()` does not await panel readiness                                                                            |
+| Context-menu operation times out                              | Entity must exist in the current world, have a position, be in range, and expose the requested menu                                                             |
+| Menu selection seems successful but effect is absent          | `choose()` resolves when selection is sent, not after the action; use a specialized confirmation method where available                                         |
+| Inventory equip fails                                         | The slot can be empty/non-equipment; infer from a known item or pass a valid explicit equipment slot                                                            |
+| Model state ignores mutations to returned objects             | Cached objects are not configuration commands; call the action methods                                                                                          |
+| Combining separate movement/aim sends loses fields            | Ordinary input fields default on each complete command; combine them in one call's command object                                                               |
+| Rank/kick/ban fails despite local flags                       | Server captain hierarchy and permission checks are authoritative                                                                                                |
+
+Range, permissions, inventory, Safe Zone status, cooldowns, and game rules are not bypassed by Dredless. Check [management completion conditions](MANAGEMENT.md#completion-and-shared-rules) and [machine targeting](MACHINES.md#targeting-and-completion).
+
+## Timeouts and retries
+
+Management waits generally default to 10000 ms; tip operations default to 5000 ms per response. Only documented methods implement these waits. Raw requests and ordinary setters do not acquire a success promise by being awaited.
+
+A timeout stops local waiting, not the server action. Check resulting state before repeating a save, account mutation, recovery, or other consequential request. Messages without request IDs can be mistaken for later retries' responses. Concurrent operations that share an active UI/menu can interfere even when the library does not reject them locally.
+
+Watch `disconnect` separately from `error`; a socket error can precede its eventual close. Catch operation rejections and inspect `DisconnectError.disconnect` when available.
+
+## Browser and HTTP problems
+
+Browser code needs access to the relevant origin/cookies. Loading a CDN script on another origin does not authorize access to Drednot. Workers, extension backgrounds, and popups can have different cookie access from a page/content script.
+
+Use `createSession()` to inspect an existing ambient browser identity; `createAnonSession()` can change it. A blank JavaScript-readable cookie property does not prove the browser lacks an HttpOnly session.
+
+For custom HTTP calls, `session.request()` JSON-stringifies ordinary objects. Send URL-encoded forms as strings with their form content type; native Fetch body types are not all supported by this wrapper. Check status and merge cookies yourself when using the raw helper.
+
+Account methods scrape labeled HTML fields and forms. A login/challenge page, changed markup, missing clan form, or malformed perk list can reject the read. Perk removal cannot confirm success if the subsequent page omits a readable list. These methods have no built-in timeout/cancellation options. See [account limitations](ACCOUNT.md#failures-and-data-lifetime).
+
+## Useful diagnostics
+
+**Fragment:** inspect bounded errors and normalized close details without dumping credential-bearing snapshots:
+
+```js
+client.on("decode-error", (entry) => console.error(entry));
+client.on("error", (error) => console.error(error.message));
+client.on("disconnect", (info) => console.error(info));
+console.log(client.debug.decodeErrors());
+```
+
+For a bug report, include the package version, runtime/entrypoint, operation, relevant error/close code, and whether state was available before the action. A small sanitized capture can help protocol investigations. Session/connection snapshots and HARs can contain authentication cookies; avoid using an entire state dump as an ordinary diagnostic log.
+
+[Protocol tools](PROTOCOL.md) describes frame decoding, world/model layers, and retained histories. The complete [declarations](../src/index.d.ts) are the field reference when inspecting a component not expanded in the prose guides.