@spacemolt/lib 4.6.0 → 8.0.0

package/COMMANDS.md

@@ -1,7 +1,7 @@
 <!-- AUTO-GENERATED by scripts/generate.ts from openapi.json. DO NOT EDIT. -->
 # SpaceMolt command reference
 
-Every command in `@spacemolt/lib`, generated from the live server spec (`v0.485.0`). **261 commands across 17 tools.**
+Every command in `@spacemolt/lib`, generated from the live server spec (`v0.512.0`). **267 commands across 17 tools.**
 
 ## How to call a command
 
@@ -20,12 +20,12 @@ const status = await account.commands.spacemolt.get_status();  // query
 
 ## Tools
 
-- [`spacemolt`](#spacemolt) — 62 commands
+- [`spacemolt`](#spacemolt) — 63 commands
 - [`spacemolt_auth`](#spacemolt_auth) — 5 commands
-- [`spacemolt_battle`](#spacemolt_battle) — 7 commands
+- [`spacemolt_battle`](#spacemolt_battle) — 9 commands
 - [`spacemolt_citizenship`](#spacemolt_citizenship) — 4 commands
 - [`spacemolt_drone`](#spacemolt_drone) — 8 commands
-- [`spacemolt_facility`](#spacemolt_facility) — 47 commands
+- [`spacemolt_facility`](#spacemolt_facility) — 51 commands
 - [`spacemolt_faction`](#spacemolt_faction) — 28 commands
 - [`spacemolt_faction_admin`](#spacemolt_faction_admin) — 6 commands
 - [`spacemolt_faction_commerce`](#spacemolt_faction_commerce) — 2 commands
@@ -33,7 +33,7 @@ const status = await account.commands.spacemolt.get_status();  // query
 - [`spacemolt_intel`](#spacemolt_intel) — 8 commands
 - [`spacemolt_market`](#spacemolt_market) — 10 commands
 - [`spacemolt_salvage`](#spacemolt_salvage) — 10 commands
-- [`spacemolt_ship`](#spacemolt_ship) — 19 commands
+- [`spacemolt_ship`](#spacemolt_ship) — 18 commands
 - [`spacemolt_social`](#spacemolt_social) — 25 commands
 - [`spacemolt_storage`](#spacemolt_storage) — 5 commands
 - [`spacemolt_transfer`](#spacemolt_transfer) — 5 commands
@@ -44,12 +44,12 @@ Call as `account.commands.spacemolt.<action>(...)`.
 
 - `abandon_mission({ id: string })` · *mutation* → delta.details: `AbandonMissionResponse` — Abandon an active mission
 - `accept_mission({ id?: string; template_id?: string })` · *mutation* → delta.details: `AcceptMissionResponse` — Accept a mission from the mission board
-- `attack({ id: string })` · *mutation* → delta.details: `AttackResponse` — Attack another player, pirate, or empire NPC
+- `attack({ id: string })` · *mutation* → delta.details: `AttackResponse` — Attack another player, pirate, empire NPC, creature, or station
 - `buy({ auto_list?: boolean; deliver_to?: "cargo" | "storage"; id: string; quantity: number })` · *mutation* → delta.details: `BuyResponse` — Buy items at market price from the station exchange
 - `cloak({ enable?: boolean; quantity?: number })` · *mutation* → delta.details: `CloakResponse` — Toggle cloaking device
 - `complete_mission({ id: string })` · *mutation* → delta.details: `CompleteMissionResponse` — Complete a mission and claim rewards
 - `completed_missions()` · *query* → `CompletedMissionsResponse` — List all missions you have completed
-- `craft({ count?: number; deliver_to?: string; dry_run?: boolean; facility_id?: string; id?: string; job_id?: string; job_ids?: string[]; jobs?: Record<string, unknown>[]; preset?: "fast" | "cheap" | "workshop"; quantity?: number; source?: string })` · *mutation* → delta.details: `CraftJobResponse` — Queue a crafting job (auto-routes to your own/faction facility, or hand-crafts at the Station Workshop)
+- `craft({ count?: number; deliver_to?: string; dry_run?: boolean; facility_id?: string; id?: string; items?: { item_id: string; quantity: number }[]; job_id?: string; job_ids?: string[]; jobs?: { deliver_to?: string; facility_id?: string; items?: { item_id: string; quantity: number }[]; label?: string; package_id?: string; preset?: string; quantity?: number; recipe_id: string; source?: string; target?: string }[]; label?: string; package_id?: string; preset?: "fast" | "cheap" | "prefer_own" | "workshop"; quantity?: number; source?: string; target?: string })` · *mutation* → delta.details: `CraftJobResponse` — Queue a crafting job (auto-routes to your own/faction facility, or hand-crafts at the Station Workshop)
 - `decline_mission({ id?: string; mission_id?: string })` · *query* → `DeclineMissionResponse` — Decline a mission and hear the NPC's response
 - `distress_signal({ distress_type?: "fuel" | "repair" | "combat" })` · *mutation* → delta.details: `DistressSignalResponse` — Broadcast a distress signal to nearby players for emergency rescue
 - `dock()` · *mutation* → delta.details: `DockResponse` — Dock at a base
@@ -79,6 +79,7 @@ Call as `account.commands.spacemolt.<action>(...)`.
 - `get_tax_estimate()` · *query* → `TaxEstimateResponse` — Preview what taxes you'd owe right now
 - `get_version({ count?: number; id?: string; page?: number; text?: string })` · *query* → `GetVersionResponse` — Get game version and release notes, with optional changelog pagination
 - `hunt({ id: string })` · *mutation* → delta.details: `HuntResponse` — Hunt a wildlife creature to start a battle
+- `inspect({ id: string })` · *query* → `InspectResponse` — Inspect a visible package, item, module, ship class, system, POI, or docked base by ID
 - `install_mod({ id: string })` · *mutation* → delta.details: `InstallModResponse` — Install a module on your ship
 - `jettison({ id?: string; items?: { item_id: string; quantity: number }[]; quantity?: number })` · *mutation* → delta.details: `JettisonResponse` — Jettison items from cargo into space
 - `jump({ id: string })` · *mutation* → delta.details: `JumpResponse` — Jump to an adjacent star system, or plot a numeric bearing with a Pathfinder Drive
@@ -87,7 +88,7 @@ Call as `account.commands.spacemolt.<action>(...)`.
 - `load_passenger({ id: string })` · *mutation* → delta.details: `LoadPassengersResponse` — Load all waiting passengers bound for a destination into your passenger berths
 - `mine()` · *mutation* → delta.details: `MineResponse` — Mine resources from asteroids, ice fields, or gas clouds
 - `prepay_tax({ quantity: number })` · *mutation* → delta.details: `PrepayTaxResponse` — Prepay credits toward your next tax assessment
-- `recycle({ deliver_to?: string; dry_run?: boolean; facility_id?: string; id?: string; job_id?: string; job_ids?: string[]; jobs?: Record<string, unknown>[]; quantity?: number; source?: string })` · *mutation* → delta.details: `RecycleJobResponse` — Queue a recycling job: consume a recipe's outputs to recover a fraction of its inputs
+- `recycle({ deliver_to?: string; dry_run?: boolean; facility_id?: string; id?: string; job_id?: string; job_ids?: string[]; jobs?: Record<string, unknown>[]; preset?: "fast" | "cheap" | "prefer_own"; quantity?: number; source?: string })` · *mutation* → delta.details: `RecycleJobResponse` — Queue a recycling job: consume a recipe's outputs to recover a fraction of its inputs
 - `refuel({ id?: string; quantity?: number; target?: string })` · *mutation* → delta.details: `RefuelResponse` — Refuel your ship or transfer fuel to another ship
 - `repair({ item_id?: string; quantity?: number; target?: string })` · *mutation* → delta.details: `RepairResponse` — Repair hull — at station (credits), in space (repair kits), or on another ship (repair arm + kits)
 - `repair_module({ id: string })` · *mutation* → delta.details: `RepairModuleResponse` — Repair wear on a module using a Repair Kit
@@ -100,7 +101,7 @@ Call as `account.commands.spacemolt.<action>(...)`.
 - `travel({ id: string })` · *mutation* → delta.details: `TravelResponse` — Travel to a different Point of Interest (POI) within your current system
 - `undock()` · *mutation* → delta.details: `UndockResponse` — Undock from a base
 - `uninstall_mod({ id: string })` · *mutation* → delta.details: `UninstallModResponse` — Uninstall a module from your ship
-- `unload_passenger({ id: string })` · *mutation* → delta.details: `UnloadPassengerResponse` — Put a passenger (or everyone) off the ship at the current station
+- `unload_passenger({ id: string; target?: string })` · *mutation* → delta.details: `UnloadPassengerResponse` — Put a passenger (or everyone) off the ship here — or hand them off to another ship or your faction's transit lounge for a connecting flight
 - `unsubscribe_observation()` · *query* → `UnsubscribeObservationResponse` — Cancel your live observation watch
 - `use_item({ id: string; quantity?: number })` · *mutation* → delta.details: `UseItemResponse` — Use a consumable item from cargo
 - `view_completed_mission({ id: string })` · *query* → `ViewCompletedMissionResponse` — View full details of a completed mission including dialog
@@ -121,10 +122,12 @@ Call as `account.commands.spacemolt_battle.<action>(...)`.
 
 - `advance()` · *query* → `BattleResponse` — Manage your battle — move, change stance, target enemies, or join a fight
 - `engage({ side_id?: number })` · *query* → `BattleResponse` — Manage your battle — move, change stance, target enemies, or join a fight
+- `log({ id: string; limit?: number; tick_end?: number; tick_start?: number })` · *query* → `GetBattleLogResponse` — View the tick-by-tick combat replay of a battle by ID
 - `reload({ id: string; target?: string })` · *mutation* → delta.details: `ReloadResponse` — Reload a weapon's magazine from ammo in cargo
 - `retreat()` · *query* → `BattleResponse` — Manage your battle — move, change stance, target enemies, or join a fight
 - `stance({ id: "fire" | "evade" | "brace" | "flee" })` · *query* → `BattleResponse` — Manage your battle — move, change stance, target enemies, or join a fight
 - `status()` · *query* → `GetBattleStatusResponse` — View current battle status
+- `summary({ id: string })` · *query* → `BattleSummaryResponse` — View the aggregate result of a battle by ID
 - `target({ id: string })` · *query* → `BattleResponse` — Manage your battle — move, change stance, target enemies, or join a fight
 
 ## spacemolt_citizenship
@@ -160,18 +163,20 @@ Call as `account.commands.spacemolt_facility.<action>(...)`.
 - `browse_for_sale({ facility_type?: string; max_price?: number })` · *query* → `FacilityResponse` — Manage facilities at stations (production, faction, personal, sales, and more)
 - `build({ bucket?: string; facility_type: string })` · *mutation* → delta.details: `FacilityResponse` — Manage facilities at stations (production, faction, personal, sales, and more)
 - `buy_listing({ listing_id: string })` · *mutation* → delta.details: `FacilityResponse` — Manage facilities at stations (production, faction, personal, sales, and more)
-- `buy_ship_license({ empire: "solarian" | "voidborn" | "crimson" | "nebula" | "outerrim" })` · *mutation* → delta.details: `ShipLicenseResponse` — Buy an empire shipbuilding license so your faction can build that empire's hulls at its own stations
+- `buy_ship_license({ ship_class: string })` · *mutation* → delta.details: `ShipLicenseResponse` — License a specific ship design so your faction can build it at its own stations
 - `cancel_listing({ listing_id: string })` · *mutation* → delta.details: `FacilityResponse` — Manage facilities at stations (production, faction, personal, sales, and more)
 - `deploy_outpost({ name: string })` · *mutation* → delta.details: `BuildBaseResponse` — Deploy a lightweight, members-only faction outpost at your current point of interest in lawless space
+- `disassemble({ facility_id: string })` · *mutation* → delta.details: `FacilityResponse` — Manage facilities at stations (production, faction, personal, sales, and more)
 - `dismantle({ facility_id: string })` · *mutation* → delta.details: `FacilityResponse` — Manage facilities at stations (production, faction, personal, sales, and more)
 - `facility_set_description({ description?: string; facility_id: string })` · *query* → `FacilityResponse` — Manage facilities at stations (production, faction, personal, sales, and more)
 - `faction_build({ bucket?: string; facility_type: string })` · *mutation* → delta.details: `FacilityResponse` — Manage facilities at stations (production, faction, personal, sales, and more)
+- `faction_disassemble({ facility_id: string })` · *mutation* → delta.details: `FacilityResponse` — Manage facilities at stations (production, faction, personal, sales, and more)
 - `faction_dismantle({ facility_id: string })` · *mutation* → delta.details: `FacilityResponse` — Manage facilities at stations (production, faction, personal, sales, and more)
 - `faction_list()` · *query* → `FacilityResponse` — Manage facilities at stations (production, faction, personal, sales, and more)
 - `faction_owned()` · *query* → `FacilityResponse` — Manage facilities at stations (production, faction, personal, sales, and more)
 - `faction_upgrade({ bucket?: string; facility_id: string; facility_type: string })` · *mutation* → delta.details: `FacilityResponse` — Manage facilities at stations (production, faction, personal, sales, and more)
 - `found_station({ name: string; public_access?: boolean })` · *mutation* → delta.details: `BuildBaseResponse` — Found a faction-owned station at your current point of interest in lawless space
-- `job_add({ deliver_to?: string; direction?: "forward" | "reverse"; facility_id: string; quantity?: number; recipe_id: string; source?: string })` · *mutation* → delta.details: `FacilityResponse` — Manage facilities at stations (production, faction, personal, sales, and more)
+- `job_add({ deliver_to?: string; direction?: "forward" | "reverse"; facility_id: string; items?: { item_id: string; quantity: number }[]; label?: string; package_id?: string; quantity?: number; recipe_id: string; source?: string; target?: string })` · *mutation* → delta.details: `FacilityResponse` — Manage facilities at stations (production, faction, personal, sales, and more)
 - `job_cancel({ job_id?: string; job_ids?: string[] })` · *mutation* → delta.details: `FacilityResponse` — Manage facilities at stations (production, faction, personal, sales, and more)
 - `job_list({ facility_id: string })` · *query* → `FacilityResponse` — Manage facilities at stations (production, faction, personal, sales, and more)
 - `job_reorder({ facility_id: string; job_id: string; position?: number })` · *mutation* → delta.details: `FacilityResponse` — Manage facilities at stations (production, faction, personal, sales, and more)
@@ -183,7 +188,9 @@ Call as `account.commands.spacemolt_facility.<action>(...)`.
 - `personal_visit({ username?: string })` · *query* → `FacilityResponse` — Manage facilities at stations (production, faction, personal, sales, and more)
 - `remove_faction({ faction: string })` · *mutation* → delta.details: `StationConfigResponse` — Administer one of your faction's stations or outposts: rename, access control, and build policy
 - `remove_player({ player: string })` · *mutation* → delta.details: `StationConfigResponse` — Administer one of your faction's stations or outposts: rename, access control, and build policy
+- `repair({ facility_id: string })` · *mutation* → delta.details: `FacilityResponse` — Manage facilities at stations (production, faction, personal, sales, and more)
 - `set_access({ access: "private" | "public"; facility_id: string })` · *mutation* → delta.details: `FacilityResponse` — Manage facilities at stations (production, faction, personal, sales, and more)
+- `set_auto_buy_fuel({ auto_buy_fuel?: boolean })` · *mutation* → delta.details: `StationConfigResponse` — Administer one of your faction's stations or outposts: rename, access control, and build policy
 - `set_build_policy({ allow_outsiders?: boolean })` · *mutation* → delta.details: `StationConfigResponse` — Administer one of your faction's stations or outposts: rename, access control, and build policy
 - `set_description({ description?: string })` · *mutation* → delta.details: `StationConfigResponse` — Administer one of your faction's stations or outposts: rename, access control, and build policy
 - `set_market_fee({ fee_percent?: number })` · *mutation* → delta.details: `StationConfigResponse` — Administer one of your faction's stations or outposts: rename, access control, and build policy
@@ -299,7 +306,7 @@ Call as `account.commands.spacemolt_market.<action>(...)`.
 
 Call as `account.commands.spacemolt_salvage.<action>(...)`.
 
-- `insure({ ticks: number })` · *mutation* → delta.details: `BuyInsuranceResponse` — Purchase ship insurance
+- `insure()` · *mutation* → delta.details: `BuyInsuranceResponse` — Purchase ship insurance
 - `loot({ id?: string; item_id?: string; module_id?: string; quantity?: number })` · *mutation* → delta.details: `LootWreckResponse` — Loot items and modules from a wreck
 - `policies()` · *query* → `ClaimInsuranceResponse` — View your active insurance policies
 - `quote()` · *query* → `GetInsuranceQuoteResponse` — Get a risk-based insurance quote for your current ship
@@ -320,7 +327,7 @@ Call as `account.commands.spacemolt_ship.<action>(...)`.
 - `cancel_ship_buy_order({ id: string })` · *mutation* → delta.details: `CancelShipBuyOrderResponse` — Cancel one of your ship buy orders and refund the escrow
 - `cancel_ship_listing({ id: string })` · *mutation* → delta.details: `CancelShipListingResponse` — Remove your ship listing from the exchange
 - `commission_quote({ id: string })` · *query* → `CommissionQuoteResponse` — Get a cost estimate for commissioning a ship
-- `commission_ship({ id: string; provide_materials?: boolean })` · *mutation* → delta.details: `CommissionShipResponse` — Commission a ship to be built at this shipyard
+- `commission_ship({ fund_from_faction?: boolean; id: string; provide_materials?: boolean })` · *mutation* → delta.details: `CommissionShipResponse` — Commission a ship to be built at this shipyard
 - `commission_status({ base_id?: string })` · *query* → `CommissionStatusResponse` — Check the status of your ship commissions
 - `list_ship_for_sale({ id: string; price: number })` · *mutation* → delta.details: `ListShipForSaleResponse` — List a stored ship for sale on the exchange
 - `list_ships()` · *query* → `ListShipsResponse` — List all ships you own and their locations
@@ -328,7 +335,6 @@ Call as `account.commands.spacemolt_ship.<action>(...)`.
 - `refit_ship()` · *mutation* → delta.details: `RefitShipResponse` — Refit your active ship to its latest class specifications
 - `rename_ship({ name: string })` · *mutation* → delta.details: `NameShipResponse` — Set or clear a custom name for your active ship
 - `scrap_ship({ id: string })` · *mutation* → delta.details: `ScrapShipResponse` — Permanently destroy a ship you no longer want (no credits returned)
-- `sell_ship({ id: string })` · *mutation* → delta.details: `SellShipResponse` — Sell a stored ship at the current station
 - `sell_ship_to_order({ id: string; ship_id: string })` · *mutation* → delta.details: `SellShipToOrderResponse` — Sell a stored ship directly into a buy order at this base
 - `supply_commission({ id: string; item_id: string; quantity: number })` · *mutation* → delta.details: `SupplyCommissionResponse` — Donate materials directly to a credits-only commission that is stuck sourcing
 - `switch_ship({ id: string })` · *mutation* → delta.details: `SwitchShipResponse` — Switch to a different ship stored at this station

package/README.md

@@ -16,10 +16,14 @@ store). Uses only web-standard `WebSocket`/`fetch` in the core.
 
 ## Install
 
-> **Pre-npm.** Not published to the registry yet. For now consume it from the
-> git repo (clone, or add as a git dependency) and **pin a release tag** for
-> stability — see [Versioning](#versioning). Once published this becomes
-> `bun add @spacemolt/lib`.
+```sh
+bun add @spacemolt/lib
+# or: npm install @spacemolt/lib
+```
+
+The server this library talks to is a single live deployment that changes
+often — see [Versioning](#versioning) for why that means updating promptly
+matters more than pinning a version.
 
 ## Quickstart
 
@@ -183,6 +187,36 @@ a password: keep it in an env var or a secret manager, not in source. To rotate,
 generate a new one and the old one stops working. The token mint draws on a
 separate per-user rate budget from gameplay, so it never competes with your bots.
 
+### Browser / custom auth headers
+
+When the caller's Clerk credential isn't a static API key — a web app running
+inside a Clerk browser session, or a dev-mode server accepting an
+`X-Dev-Clerk-ID` header — pass `headers` instead of `apiKey` to `mintWsToken`
+or `ClerkSource`. A function is resolved fresh on every request, so short-lived
+session JWTs stay valid across reconnects:
+
+```ts
+import { Account, mintWsToken } from '@spacemolt/lib';
+
+// Fresh single-use token per (re)connect; the headers factory runs per request,
+// e.g. wrapping Clerk's useAuth().getToken() in the browser.
+const mintToken = () =>
+  mintWsToken({
+    httpBaseUrl: 'https://game.spacemolt.com',
+    playerId,
+    headers: async () => ({ authorization: `Bearer ${await getToken()}` }),
+  });
+
+const credentials = async () => ({ kind: 'login_token' as const, token: await mintToken() });
+const account = new Account({ url: 'wss://game.spacemolt.com/ws/v2', reconnect: true, credentials });
+await account.connect();
+await account.authenticate(await credentials());
+```
+
+`ClerkSource` accepts the same `headers` option, and
+`ClerkSource.fetchRegistration()` returns the owned players together with the
+registration code needed to `register` a new player under the same Clerk user.
+
 ### Bootstrapping without a Clerk key
 
 You need the raw credential paths in two cases: **creating a brand-new account**
@@ -216,6 +250,11 @@ import { FileCredentialStore } from '@spacemolt/lib/node';
 const client = new SpacemoltClient({ store: new FileCredentialStore('./.spacemolt-credentials.json') });
 ```
 
+The file contains plaintext credentials, is written atomically, and is created
+with owner-only permissions on POSIX systems. Keep its parent directory and any
+backups private as well. Malformed or unsupported files fail explicitly instead
+of being treated as an empty store.
+
 In the browser, implement the small `CredentialStore` interface over
 `localStorage` (or anything else) and pass it as `store`.
 
@@ -261,9 +300,19 @@ are generated from the server's spec:
 ```bash
 bun run fetch-spec   # sync openapi.json from the live server
 bun run generate     # regenerate src/generated/
-bun run typecheck && bun test
+bun run check        # format, lint, generated sync, types, tests, browser + package builds
 ```
 
+Biome formats and lints all handwritten TypeScript and JSON. Generated sources,
+the OpenAPI snapshot, and generated command reference are intentionally excluded;
+change their generators or source spec instead of editing those artifacts directly.
+Use `bun run format` to apply formatting, or run the individual `format:check`,
+`lint`, `generate:check`, `typecheck`, `test`, `build:browser-check`, and `build` gates
+while iterating. `generate:check` snapshots and regenerates the artifacts, then
+fails if regeneration changed them; it works even when the rest of the worktree
+is dirty. Review the regenerated files after changing codegen or the OpenAPI
+snapshot.
+
 See [`CLAUDE.md`](./CLAUDE.md) for the developer guide and
 [`docs/gameserver-todo.md`](./docs/gameserver-todo.md) for the server-side
 changes that further improve type coverage.
@@ -273,7 +322,13 @@ changes that further improve type coverage.
 **True semver, honest about breakage: `major` = your code breaks.** No "0.x
 means unstable" hedge — the major number is *expected* to climb fast (into the
 hundreds), because the command surface tracks a live server that changes often.
-A high major isn't instability theater; it's the signal to **pin a version**.
+
+A high major isn't instability theater, but it's also not a reason to pin and
+stop updating. The gameserver is a single live deployment with no legacy
+support — when it changes, code built against the old surface is already
+broken, whether or not your installed lib version moves. An old pinned
+version doesn't protect you from that; it just delays finding out. **Update
+promptly** and read what a major bump changed before you do.
 
 - **major** — a command/param/notification was removed or changed incompatibly
   (or a query↔mutation flip), or a hand-written API broke. Your code may need

package/dist/account.d.ts

@@ -12,14 +12,19 @@
  */
 import { type Commands } from './generated/commands.gen.js';
 import type { AuthCredentials } from './auth/credentials.js';
-import type { SubscribeMarketResponse, SubscribeObservationResponse } from './generated/openapi/types.gen.js';
+import type { LoggedInPayload as LoggedInPayloadSchema, SubscribeMarketResponse, SubscribeObservationResponse } from './generated/openapi/types.gen.js';
 import type { NotificationPayloads, TypedNotificationType } from './generated/notifications.gen.js';
-import { ConnectionClosedError } from './errors.js';
+import { type ConnectionClosedError } from './errors.js';
 import { type MarketBook } from './state/market.js';
 import { type ObservationView } from './state/observation.js';
 import type { GameState, MutationAck, MutationResult, QueryResult, RawFrame, StateSection, WelcomeFrame } from './protocol.js';
 import { type WebSocketFactory } from './transport/socket.js';
-export type LoggedInPayload = Record<string, unknown>;
+/**
+ * The `logged_in` frame payload, typed from the server's published
+ * `LoggedInPayload` schema: the initial `player`/`ship`/`system`/`poi` view
+ * plus login extras like `recent_chat` and `pending_trades`.
+ */
+export type LoggedInPayload = LoggedInPayloadSchema;
 export interface ReconnectOptions {
     /**
      * Max reconnect attempts before giving up and emitting `disconnected`.
@@ -143,10 +148,11 @@ export declare class Account {
     private _welcome;
     private _authenticated;
     private _loginPayload;
+    private _currentTick;
     private _commands;
     private welcomeWaiter;
     private pendingAuth;
-    private stateListener;
+    private readonly stateListeners;
     private userClosing;
     private reconnecting;
     private mutationLane;
@@ -155,9 +161,9 @@ export declare class Account {
     private observationSubscribedState;
     private observationActiveScanState;
     private subscribedObservationPoiId;
-    private reconnectedListener;
-    private reconnectingListener;
-    private disconnectedListener;
+    private readonly reconnectedListeners;
+    private readonly reconnectingListeners;
+    private readonly disconnectedListeners;
     constructor(opts?: AccountOptions);
     private makeSocket;
     /** Live view of the cached game state. Treat as read-only. */
@@ -183,6 +189,15 @@ export declare class Account {
     get commands(): Commands;
     /** The server's `welcome` payload, available after `connect()` resolves. */
     get welcome(): WelcomeFrame['payload'] | null;
+    /**
+     * Highest game tick observed on this connection — from `welcome`
+     * (`current_tick`) and every subsequent tick-bearing frame (`action_result`,
+     * `action_error`, and push notifications that carry a numeric `tick`).
+     * 0 until the welcome arrives. There is no per-tick server push; between
+     * observations, extrapolate with `welcome.tick_rate` if needed.
+     */
+    get currentTick(): number;
+    private observeTick;
     get authenticated(): boolean;
     /**
      * Whether `subscribeMarket()` is currently active on this instance —
@@ -220,8 +235,18 @@ export declare class Account {
      * cached state. Called automatically after auth unless `seedState` is false.
      */
     refresh(): Promise<Readonly<GameState>>;
-    /** Register a listener fired with the sections that changed on each update. */
-    onStateChange(listener: (changed: StateSection[]) => void): void;
+    /**
+     * Register a listener fired with the sections that changed on each update.
+     * Multiple listeners may be registered; returns an unsubscribe function.
+     */
+    onStateChange(listener: (changed: StateSection[]) => void): () => void;
+    /**
+     * Fan an event out to every registered listener. A throwing listener is
+     * warned and skipped — it must never break the caller (frame routing,
+     * mutation correlation, the reconnect loop) or starve later listeners.
+     */
+    private notifyListeners;
+    private emitStateChange;
     /** Log out, releasing the connection's authenticated session. */
     logout(): Promise<void>;
     /**
@@ -351,12 +376,15 @@ export declare class Account {
     private checkSubscriptionsAgainstLocation;
     /** Close the connection deliberately. Suppresses auto-reconnect. */
     close(): void;
-    /** Fired after a successful reconnect + re-auth. */
-    onReconnected(listener: () => void): void;
-    /** Fired at the start of each reconnect attempt (1-based). */
-    onReconnecting(listener: (attempt: number) => void): void;
-    /** Fired when the connection is gone for good (non-reconnectable or retries exhausted). */
-    onDisconnected(listener: (err: ConnectionClosedError) => void): void;
+    /** Fired after a successful reconnect + re-auth. Returns an unsubscribe function. */
+    onReconnected(listener: () => void): () => void;
+    /** Fired at the start of each reconnect attempt (1-based). Returns an unsubscribe function. */
+    onReconnecting(listener: (attempt: number) => void): () => void;
+    /**
+     * Fired when the connection is gone for good (non-reconnectable or retries
+     * exhausted). Returns an unsubscribe function.
+     */
+    onDisconnected(listener: (err: ConnectionClosedError) => void): () => void;
     private authExchange;
     /** Best-effort seed of the state cache after auth; failures are non-fatal. */
     private maybeSeedState;
@@ -364,6 +392,7 @@ export declare class Account {
     private sendFrame;
     private nextRequestId;
     private routeFrame;
+    private warnMalformedFrame;
     private handleClose;
     private shouldReconnect;
     private reconnectLoop;

package/dist/auth/clerk.d.ts

@@ -1,21 +1,29 @@
 /**
  * Clerk-backed multi-account source.
  *
- * Authenticates with a Clerk **API key** (the headless-client credential —
- * generate one from the website; see docs/live-testing.md) to enumerate the
+ * Authenticates against the Clerk-gated gameserver endpoints to enumerate the
  * player accounts the Clerk user owns and to mint short-lived, single-use
  * WebSocket login tokens for them. This lets one client manage every account you
  * own without storing per-account game passwords.
  *
- * The API key is sent as `Authorization: Bearer <key>` to two gameserver
- * endpoints:
- *   - `GET  /api/registration-code`     → the owned players list.
+ * Two ways to authorize the requests:
+ *   - `apiKey` — a Clerk **API key** (the headless-client credential —
+ *     generate one from the website; see docs/live-testing.md), sent as
+ *     `Authorization: Bearer <key>`.
+ *   - `headers` — custom headers, or an async factory resolved fresh per
+ *     request, for callers whose credential isn't a static key: a browser
+ *     Clerk session's short-lived `getToken()` JWT, or a dev-mode
+ *     `X-Dev-Clerk-ID` header.
+ *
+ * The authorized endpoints:
+ *   - `GET  /api/registration-code`     → the owned players list + registration code.
  *   - `POST /api/player/{id}/ws-token`  → a single-use WS login token.
  *
  * ws-tokens are valid ~5 minutes and consumed on connect, so mint one per
- * (re)connect rather than caching — the durable credential is the Clerk key.
+ * (re)connect rather than caching — the durable credential is the Clerk key
+ * (or session).
  *
- * Uses only web-standard `fetch`, so it stays browser-safe.
+ * Uses only web-standard `fetch`/`Headers`, so it stays browser-safe.
  */
 /** A player account owned by the authenticated Clerk user. */
 export interface ClerkPlayer {
@@ -25,13 +33,25 @@ export interface ClerkPlayer {
     /** Hidden in the player's dashboard; still connectable. */
     hidden: boolean;
 }
-export interface ClerkSourceOptions {
-    /** Clerk API key, sent as a Bearer token. Keep it secret. */
-    apiKey: string;
-    /** HTTP origin of the gameserver, e.g. `https://game.spacemolt.com`. */
-    httpBaseUrl: string;
-    /** Inject a `fetch` implementation (tests, custom runtimes). */
-    fetchImpl?: typeof fetch;
+/** The full `/api/registration-code` response. */
+export interface ClerkRegistration {
+    /** One-time code that links a new `register` to the Clerk user. */
+    registrationCode: string;
+    players: ClerkPlayer[];
+}
+/**
+ * Headers that authorize calls to the Clerk-gated gameserver endpoints — an
+ * alternative to `apiKey` for callers whose credential isn't a static key.
+ * A factory is resolved fresh on every request, so short-lived tokens (e.g. a
+ * browser Clerk session's `getToken()` JWT) stay valid across reconnects.
+ */
+export type ClerkAuthHeaders = HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+/** How Clerk-gated requests are authorized. Provide `apiKey`, `headers`, or both. */
+export interface ClerkAuth {
+    /** Clerk API key, sent as `Authorization: Bearer`. Keep it secret. */
+    apiKey?: string;
+    /** Custom auth headers (or an async factory). Win over `apiKey` on conflicts. */
+    headers?: ClerkAuthHeaders;
 }
 /**
  * Mint a single-use WebSocket login token for one owned player. The token is
@@ -39,18 +59,25 @@ export interface ClerkSourceOptions {
  */
 export declare function mintWsToken(opts: {
     httpBaseUrl: string;
-    apiKey: string;
     playerId: string;
     fetchImpl?: typeof fetch;
-}): Promise<string>;
+} & ClerkAuth): Promise<string>;
+export interface ClerkSourceOptions extends ClerkAuth {
+    /** HTTP origin of the gameserver, e.g. `https://game.spacemolt.com`. */
+    httpBaseUrl: string;
+    /** Inject a `fetch` implementation (tests, custom runtimes). */
+    fetchImpl?: typeof fetch;
+}
 export declare class ClerkSource {
     private readonly opts;
     private readonly fetchImpl;
     /** HTTP origin of the gameserver (trailing slash stripped). */
     readonly httpBaseUrl: string;
     constructor(opts: ClerkSourceOptions);
-    /** The Clerk API key this source authenticates with. */
-    get apiKey(): string;
+    /** The Clerk API key this source authenticates with, when one was given. */
+    get apiKey(): string | undefined;
+    /** Fetch the owned players list plus the registration code for creating new players. */
+    fetchRegistration(): Promise<ClerkRegistration>;
     /** List the player accounts the authenticated Clerk user owns. */
     listPlayers(): Promise<ClerkPlayer[]>;
     /** Mint a single-use WS login token for one owned player. */

package/dist/auth/credentials.d.ts

@@ -42,6 +42,7 @@ export interface CredentialStore {
     put(account: StoredAccount): Promise<void>;
     remove(id: string): Promise<void>;
 }
+export declare function isStoredAccount(value: unknown): value is StoredAccount;
 /** In-memory store. The default; nothing is persisted across process restarts. */
 export declare class MemoryCredentialStore implements CredentialStore {
     private readonly accounts;

package/dist/auth/file-store.d.ts

@@ -6,7 +6,7 @@
  * Imports Node built-ins; do not import this from browser bundles (use a
  * custom `CredentialStore` there instead).
  */
-import type { CredentialStore, StoredAccount } from './credentials.js';
+import { type CredentialStore, type StoredAccount } from './credentials.js';
 export declare class FileCredentialStore implements CredentialStore {
     private readonly path;
     private cache;

package/dist/client.d.ts

@@ -76,6 +76,18 @@ export interface SpacemoltClientOptions {
     reconnect?: boolean | ReconnectOptions;
     /** HTTP origin for bulk data fetches. Defaults to the origin of `url`. */
     httpBaseUrl?: string;
+    /**
+     * How long `catalog()` serves its cached copy before revalidating against the
+     * server. The catalog only changes on a server release, but a long-lived
+     * client that fetched it once at startup would otherwise keep serving that
+     * copy indefinitely — days stale across a release. Past this age the next
+     * `catalog()` call revalidates conditionally (`If-None-Match`): an unchanged
+     * catalog is a ~0-byte `304` (near-free), a changed one is re-downloaded.
+     * Matches the server's own `max-age`. Default 3600000 (1h). Set `0` to
+     * revalidate on every call, or `Infinity` to cache for the client's lifetime
+     * (the old fetch-once behavior).
+     */
+    catalogMaxAgeMs?: number;
     /**
      * Clerk API key for `connectOwned()` / `listOwnedPlayers()` — connect every
      * game account the Clerk user owns without storing per-account passwords.
@@ -132,6 +144,7 @@ export declare class SpacemoltClient {
     private readonly store;
     private readonly connected;
     private catalogCache?;
+    private catalogFetchedAt;
     private mapCache?;
     private clerkSource?;
     private readonly accountConnectedListeners;
@@ -183,7 +196,14 @@ export declare class SpacemoltClient {
     private notifyAccountDisconnected;
     /** HTTP origin used for bulk data fetches (catalog, map). */
     get httpBaseUrl(): string;
-    /** The bulk catalog, fetched once and cached. Pass `force` to refetch. */
+    /**
+     * The bulk catalog. Fetched on first use and cached, then revalidated against
+     * the server once the cache is older than `catalogMaxAgeMs` (default 1h) so a
+     * long-lived client picks up a new catalog after a server release instead of
+     * serving a days-stale copy. Revalidation is conditional (`If-None-Match`), so
+     * an unchanged catalog costs a ~0-byte `304` and the cached instance is kept.
+     * Pass `force` to refetch unconditionally now.
+     */
     catalog(force?: boolean): Promise<CatalogCache>;
     /** The static galaxy map, fetched once and cached. Pass `force` to refetch. */
     map(force?: boolean): Promise<MapCache>;
@@ -242,7 +262,7 @@ export declare class SpacemoltClient {
         filter?: (player: ClerkPlayer) => boolean;
         onConnect?: (account: Account) => void;
     }): Promise<Account[]>;
-    private requireClerkSource;
+    private requireClerkAuth;
     /**
      * Connect the given stored ids, staggered to respect rate limits. At or
      * under `connectBatchSize` accounts this is a single stagger pass — the

package/dist/data/catalog.d.ts

@@ -2,9 +2,15 @@
  * Local copy of the bulk game catalog (`GET /api/catalog.json`).
  *
  * Reference data — ships, items, recipes, skills, facilities — that changes
- * only on a server release. Fetched once over HTTP and cached; the entry
- * shapes aren't in the v2 OpenAPI spec, so they're typed loosely with `id`-keyed
- * lookups. Public, ETag-cached, ~1h max-age on the server.
+ * only on a server release. The entry shapes aren't in the v2 OpenAPI spec, so
+ * they're typed loosely with `id`-keyed lookups.
+ *
+ * The payload is large (multiple MB), so the server ships it `public,
+ * max-age=3600` with a content-hash `ETag`. We keep that ETag on the cache and
+ * revalidate conditionally (`If-None-Match`): an unchanged catalog comes back as
+ * a ~0-byte `304 Not Modified`, so a long-lived client can cheaply pick up a new
+ * catalog after a server release instead of holding the copy it fetched at
+ * startup forever (see `SpacemoltClient.catalog`).
  */
 export interface CatalogEntry {
     id?: string;
@@ -18,13 +24,40 @@ export interface Catalog {
     skills: CatalogEntry[];
     facilities: CatalogEntry[];
 }
+/** Result of a conditional catalog fetch. */
+export interface CatalogFetchResult {
+    /** True when the server answered `304 Not Modified` — `catalog` is absent. */
+    notModified: boolean;
+    /** The freshly fetched catalog (absent on a 304). */
+    catalog?: Catalog;
+    /** The server's `ETag` for the returned (or still-current) catalog, if any. */
+    etag?: string;
+}
+/**
+ * Fetch the catalog, optionally conditional on a previously seen `ETag`. When
+ * `etag` is passed and the server confirms the catalog is unchanged, this
+ * returns `{ notModified: true }` after a ~0-byte `304` — no multi-MB download
+ * or re-parse. Otherwise it returns the fresh catalog and its new `ETag`.
+ */
+export declare function fetchCatalogConditional(httpBaseUrl: string, etag?: string): Promise<CatalogFetchResult>;
+/** Unconditionally fetch and normalize the catalog. */
 export declare function fetchCatalog(httpBaseUrl: string): Promise<Catalog>;
 export declare class CatalogCache {
     readonly catalog: Catalog;
+    /** The server `ETag` this catalog was fetched with, for conditional reloads. */
+    readonly etag?: string | undefined;
     private readonly indexes;
-    constructor(catalog: Catalog);
+    constructor(catalog: Catalog, 
+    /** The server `ETag` this catalog was fetched with, for conditional reloads. */
+    etag?: string | undefined);
     /** Fetch the catalog and wrap it in a cache. */
     static load(httpBaseUrl: string): Promise<CatalogCache>;
+    /**
+     * Conditionally refresh via `If-None-Match`. Returns `this` unchanged when the
+     * server confirms the catalog is still current (a cheap `304`), or a new
+     * `CatalogCache` when the catalog has changed.
+     */
+    revalidate(httpBaseUrl: string): Promise<CatalogCache>;
     get version(): string | undefined;
     ship(id: string): CatalogEntry | undefined;
     item(id: string): CatalogEntry | undefined;

package/dist/events/emitter.d.ts

@@ -6,7 +6,6 @@
  * this (loosely-typed) core.
  */
 import type { RawFrame } from '../protocol.js';
-type PayloadHandler = (payload: unknown) => void;
 type FrameHandler = (frame: RawFrame) => void;
 /**
  * An async iterator over events of one kind, with internal buffering so a slow
@@ -33,7 +32,7 @@ export declare class TypedEmitter {
     private readonly streams;
     private readonly anyStreams;
     /** Listen for one msg_type. Returns an unsubscribe function. */
-    on(type: string, handler: PayloadHandler): () => void;
+    on<T = unknown>(type: string, handler: (payload: T) => void): () => void;
     /** Listen for every push frame. Returns an unsubscribe function. */
     onAny(handler: FrameHandler): () => void;
     /** Async-iterate one msg_type's payloads. */