dredless 0.6.1 → 0.6.3

package/docs/API_REFERENCE.md

@@ -99,6 +99,29 @@ interface Ship {
 }
 ```
 
+Ship names are returned exactly as provided by the Drednot server. In
+particular, `fetchShips()` and `fetchShipList()` preserve leading and trailing
+spaces; it is up to callers to optionally trim those spaces from `name`.
+
+### `InviteMetadata`
+
+Returned by `fetchInviteMetadata()`.
+
+```ts
+interface InviteMetadata {
+  shipId: string | null;
+  name: string | null;
+  previewImageUrl: string | null;
+  hostname: string;
+  inviteCode: string;
+  color?: string | null;
+}
+```
+
+Invite metadata also preserves leading and trailing spaces in the
+ship name returned by the invite page. The optional `color` field is included
+only when `includeColor: true` is passed and is sampled from the preview image.
+
 ### `ShipList`
 
 Returned by `fetchShipList()`.
@@ -302,6 +325,59 @@ once(type: string, callback: (...args: unknown[]) => void): this;
 
 Events are implementation-defined strings emitted by the client event bus.
 
+### Context menus: `client.tips`
+
+```js
+const door = client.currentShip().machines.doors()[0];
+const menu = await door.openTips();
+console.log(menu.options);
+client.tips.select("Restrict to Crew"); // Also accepts a zero-based option index.
+
+// Open and select in one operation:
+await client.tips.choose(door, "Restrict to Captains");
+
+// Dismiss without selecting an option:
+await door.openTips();
+await client.tips.close();
+
+// Set access and wait for the server's model update:
+await door.setRank("guest");
+await client.currentShip().machines.spawnPoints()[0].setRank("crew");
+```
+
+`client.tips.open(entity, options?)` accepts an entity handle or an entity id in
+the current world and resolves to a frozen `TipList` with
+`{ entity, world, filter, x, y, options }`. Every entity handle also exposes
+`openTips(options?)`. `client.tips.current` is the latest menu, or `null` after
+selection, an empty menu, or disconnect. The `tip-list` event receives
+`(menu, world)` including empty menus; the existing raw `side-event` is preserved.
+The server does not send an entity id in a tip list: `entity` is inferred from
+the API's requested target and is `null` for unsolicited menus. Avoid mixing raw
+context-menu commands with an API operation in progress.
+
+`select(option, command?)` sends the selected index and returns the client.
+`choose(entity, option, options?)` opens a fresh menu and selects by exact text
+or index, resolving to the client once selection is sent. Neither method waits
+for the resulting action to complete.
+
+`close(options?)` sends the captured left-click dismissal input with no focused
+entity or selected option, then resolves to the client after the server sends an
+empty tip list for the menu's world. It skips sending when no menu is open and
+uses the same timeout and overlap rules as `open()`. Optional `command` fields
+can supply click coordinates or inventory/view settings.
+
+Door and spawn-point `setRank(rank, options?)` accept `"guest"`, `"crew"`,
+`"captain"`, or `0`, `1`, `3`. They resolve to the client after the model confirms
+the requested rank, and skip sending when the rank already matches. These are
+access restrictions; they do not change a player's ship rank.
+
+Options are `{ timeout?: number, command?: Command }`. The timeout defaults to
+5000 milliseconds per response (menu and, for `setRank`, rank confirmation).
+Calls reject on timeout, disconnect, unknown options, invalid ranks, or a target
+outside the current world. Only one asynchronous tip operation may run per
+client; overlapping calls reject. The server still enforces permissions and
+interaction range; these helpers do not move the player or grant access.
+
 ## `client.state()` Output
 
 ```ts

package/docs/NODE_API.md

@@ -44,6 +44,7 @@ interface DredlessNamespace {
   fetchServers: typeof fetchServers;
   fetchShips: typeof fetchShips;
   fetchShipList: typeof fetchShipList;
+  fetchInviteMetadata: typeof fetchInviteMetadata;
   joinShip: typeof joinShip;
   startShip: typeof startShip;
   startNewShip: typeof startNewShip;
@@ -133,6 +134,9 @@ function fetchShips(session: Session, server: ServerRef): Promise<Ship[]>;
 
 Authenticated convenience wrapper around `session.fetchShips(server)`.
 
+Ship names in the returned objects are canonical Drednot server data. Leading
+and trailing spaces are preserved exactly; callers should not trim them.
+
 ### `Dredless.fetchShipList(session, server)`
 
 ```ts
@@ -141,6 +145,22 @@ function fetchShipList(session: Session, server: ServerRef): Promise<ShipList>;
 
 Authenticated convenience wrapper around `session.fetchShipList(server)`.
 
+Ship names in the returned objects are canonical Drednot server data. Leading
+and trailing spaces are preserved exactly; callers should not trim them.
+
+### `Dredless.fetchInviteMetadata(invite, options?)`
+
+```ts
+function fetchInviteMetadata(
+  invite: string | URL,
+  options?: { includeColor?: boolean }
+): Promise<InviteMetadata>;
+```
+
+Fetches and parses an invite page. The returned ship name preserves leading
+and trailing spaces exactly as returned by Drednot. Set `includeColor: true`
+to sample the preview image’s top-left pixel; otherwise no image is fetched.
+
 ### `Dredless.joinShip(server, ship?, session?)`
 
 ```ts
@@ -371,4 +391,3 @@ interface ConnectionSnapshot {
   session: SessionSnapshot;
 }
 ```
-

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "dredless",
-    "version": "0.6.1",
+    "version": "0.6.3",
     "description": "A fully-featured and from-scratch headless drednot.io client implementation written in pure js.",
     "license": "MIT",
     "homepage": "https://github.com/certainhuman/dredless#readme",
@@ -152,6 +152,7 @@
         }
     },
     "dependencies": {
+        "sharp": "^0.35.4",
         "ws": "^8.18.0"
     },
     "files": [

package/src/browser.d.ts

@@ -82,6 +82,9 @@ export {
 } from "./index.js";
 
 export type {
+    TipDomain,
+    TipList,
+    TipOptions,
     Server,
     Ship,
     ShipList,

package/src/client/core.js

@@ -1,6 +1,7 @@
 import {INITIAL_OUTFIT_MESSAGE, JOIN_USER_AGENT, KEEPALIVE_INTERVAL_MS, KEEPALIVE_MESSAGE} from "../constants.js";
 import {getWebSocket, isNode} from "../runtime.js";
 import {EventBus} from "../events.js";
+import {TipDomain} from "./domains/tips.js";
 import {cookieHeader} from "../network/cookies.js";
 import {fetchServers} from "../network/servers.js";
 import {Connection} from "../network/connection.js";
@@ -143,6 +144,7 @@ export class DredlessClient extends EventBus {
         this.debug = new ClientDebugDomain(this);
         this.player = new PlayerDomain(this);
         this.inventory = new InventoryDomain(this);
+        this.tips = new TipDomain(this);
         this.management = new ShipManagementDomain(this);
         this.cpuLoad = null;
         this.inventoryState = normalizeInventoryEvent({type: "inventory", general_slots: 5});
@@ -1042,6 +1044,7 @@ export class DredlessClient extends EventBus {
 
     #handleSideEvent(event, world) {
         if (!event || typeof event !== "object") return;
+        if (event.type === "tip_list") this.tips.receive(event, world);
         if (event.type === "inventory") {
             this.inventoryState = normalizeInventoryEvent(event);
             this.emit("inventory", this.inventoryState, world);

package/src/client/domains/index.js

@@ -835,6 +835,10 @@ export class EntityHandle {
     use(options = {}, command = {}) {
         return this.client.player.useEntity(this.id, options, command);
     }
+
+    openTips(options = {}) {
+        return this.client.tips.open(this, options);
+    }
 }
 
 export class MachineHandle extends EntityHandle {
@@ -1228,6 +1232,10 @@ export class HelmHandle extends MachineHandle {
 }
 
 export class DoorHandle extends MachineHandle {
+    setRank(rank, options = {}) {
+        return this.client.tips.setRank(this, rank, options);
+    }
+
     get state() {
         return summaryForEntity(this.client, this.scope, this.id)?.contents?.door || null;
     }
@@ -1242,6 +1250,10 @@ export class DoorHandle extends MachineHandle {
 }
 
 export class SpawnPointHandle extends MachineHandle {
+    setRank(rank, options = {}) {
+        return this.client.tips.setRank(this, rank, options);
+    }
+
     get state() {
         return summaryForEntity(this.client, this.scope, this.id)?.contents?.spawnPoint || null;
     }

package/src/client/domains/tips.js

@@ -0,0 +1,153 @@
+import {normalizePlayerRank} from "../../protocol/outbound/ship-management.js";
+
+function timeoutValue(options) {
+  const timeout = options.timeout ?? 5000;
+  if (!Number.isFinite(timeout) || timeout <= 0) throw new RangeError("timeout must be positive milliseconds");
+  return timeout;
+}
+
+function waitFor(client, eventType, read, timeout, label, send = null) {
+  return new Promise((resolve, reject) => {
+    const cleanup = () => {
+      clearTimeout(timer);
+      client.off(eventType, check);
+      client.off("close", closed);
+    };
+    const check = (...args) => {
+      const value = read(...args);
+      if (value) { cleanup(); resolve(value); }
+    };
+    const closed = () => { cleanup(); reject(new Error(`Disconnected while waiting for ${label}`)); };
+    const timer = setTimeout(() => { cleanup(); reject(new Error(`Timed out waiting for ${label}`)); }, timeout);
+    client.on(eventType, check);
+    client.on("close", closed);
+    if (send) {
+      try { send(); } catch (error) { cleanup(); reject(error); return; }
+    }
+    check();
+  });
+}
+
+export class TipDomain {
+  #busy = false;
+  #target = null;
+  #current = null;
+
+  constructor(client) {
+    this.client = client;
+    client.on("close", () => { this.#current = null; this.#target = null; });
+  }
+
+  get current() {
+    return this.#current;
+  }
+
+  receive(event, world) {
+    const options = Array.isArray(event.options) ? event.options.map(String) : [];
+    const entity = this.#target?.world === world?.id ? this.#target.entity : null;
+    const menu = Object.freeze({entity, world: world?.id ?? null, filter: event.filter ?? null,
+      x: event.x ?? 0, y: event.y ?? 0, options: Object.freeze(options)});
+    this.#current = options.length ? menu : null;
+    this.client.emit("tip-list", menu, world);
+  }
+
+  async #exclusive(action) {
+    if (this.#busy) throw new Error("A tip menu operation is already in progress");
+    this.#busy = true;
+    try {
+      return await action();
+    } catch (error) {
+      this.#current = null;
+      this.#target = null;
+      throw error;
+    } finally { this.#busy = false; }
+  }
+
+  async #open(entity, options) {
+    if (!this.client.ready || !this.client.connected) throw new Error("Client must be connected and ready to open tips");
+    const timeout = timeoutValue(options);
+    const handle = typeof entity === "number" ? this.client.currentShip()?.entities.get(entity) : entity;
+    if (!handle || handle.client !== this.client || !handle.exists()) throw new Error("Tip target must be an existing entity on this client");
+    const world = this.client.worlds.currentWorldId;
+    const scopeWorld = handle.scope === "ship" ? this.client.worlds.shipWorld()
+      : handle.scope === "current" ? this.client.worlds.worlds.get(world)
+        : handle.scope === "overworld" ? this.client.worlds.overworld()
+          : this.client.worlds.worlds.get(Number(handle.scope));
+    if (scopeWorld?.id !== world) {
+      throw new Error("Tip target must be in the current world");
+    }
+    const position = handle.position;
+    if (!position) throw new Error("Tip target has no position");
+    this.#current = null;
+    this.#target = {entity: handle.id, world, command: {...options.command,
+      focus_ent: handle.id, mx: position.x, my: position.y}};
+    // Subscribe before sending: attached sockets can deliver a reply synchronously.
+    return waitFor(this.client, "tip-list", () => {
+      return this.#current?.entity === handle.id && this.#current.world === world ? this.#current : null;
+    }, timeout, "tip menu", () => {
+      this.client.send({...this.#target.command, act1: false, act2: true, tip_select: null});
+    });
+  }
+
+  open(entity, options = {}) {
+    return this.#exclusive(() => this.#open(entity, options));
+  }
+
+  close(options = {}) {
+    return this.#exclusive(async () => {
+      const timeout = timeoutValue(options);
+      const menu = this.#current;
+      if (!menu) return this.client;
+      if (!this.client.connected || !this.client.ready) throw new Error("Client must be connected and ready to close tips");
+      if (menu.world !== this.client.worlds.currentWorldId) throw new Error("Tip menu belongs to another world");
+      await waitFor(this.client, "tip-list", (update) => update?.world === menu.world
+        && update.options.length === 0, timeout, "tip menu dismissal", () => {
+        // The official client dismisses with a normal left click outside an entity.
+        this.client.send({...options.command, focus_ent: null, config_ent: null,
+          act1: true, act1_held: true, act2: false, tip_select: null});
+      });
+      this.#target = null;
+      return this.client;
+    });
+  }
+
+  select(option, command = {}) {
+    if (this.#busy) throw new Error("A tip menu operation is already in progress");
+    return this.#select(option, command);
+  }
+
+  #select(option, command = {}) {
+    if (!this.client.connected || !this.client.ready) throw new Error("Client must be connected and ready to select tips");
+    const menu = this.#current;
+    if (!menu || menu.entity == null || !this.#target) throw new Error("Open an entity's tip menu before selecting an option");
+    if (menu.world !== this.client.worlds.currentWorldId) throw new Error("Tip menu belongs to another world");
+    const index = typeof option === "string" ? menu.options.indexOf(option) : option;
+    if (!Number.isInteger(index) || index < 0 || index >= menu.options.length) throw new RangeError("Tip option is not in the current menu");
+    this.client.send({...this.#target.command, ...command, focus_ent: menu.entity,
+      act1: false, act2: false, tip_select: index});
+    this.#current = null;
+    this.#target = null;
+    return this.client;
+  }
+
+  choose(entity, option, options = {}) {
+    return this.#exclusive(async () => {
+      await this.#open(entity, options);
+      return this.#select(option);
+    });
+  }
+
+  setRank(handle, rank, options = {}) {
+    return this.#exclusive(async () => {
+      const value = normalizePlayerRank(rank);
+      const timeout = timeoutValue(options);
+      if (!handle.exists()) throw new Error("Rank target no longer exists");
+      if (handle.rank === value) return this.client;
+      const text = {0: "Restrict to Guests", 1: "Restrict to Crew", 3: "Restrict to Captains"}[value];
+      await this.#open(handle, options);
+      await waitFor(this.client, "model", () => handle.rank === value, timeout, "access rank update",
+        () => this.#select(text));
+      return this.client;
+    });
+  }
+}

package/src/client/index.d.ts

@@ -1,2 +1,2 @@
 export {DredlessClient, WrenchMode, TurretMode} from "../index.js";
-export type {DredlessClientOptions, ClientSnapshot} from "../index.js";
+export type {DredlessClientOptions, ClientSnapshot, TipDomain, TipList, TipOptions} from "../index.js";

package/src/index.d.ts

@@ -26,12 +26,16 @@ export interface ShipList {
 export interface InviteMetadata {
     shipId: string | null;
     name: string | null;
-    color: string | null;
+    /** CSS RGB color sampled from the preview image's top-left pixel, when available. */
+    color?: string | null;
     previewImageUrl: string | null;
     hostname: string;
     inviteCode: string;
 }
-export interface InviteFetchOptions { fetchImpl?: typeof fetch; }
+export interface InviteFetchOptions {
+    fetchImpl?: typeof fetch;
+    includeColor?: boolean;
+}
 export function fetchInviteMetadata(invite: string | URL, options?: InviteFetchOptions): Promise<InviteMetadata>;
 export function parseInviteMetadata(html: string): InviteMetadata;
 
@@ -475,6 +479,7 @@ export class DredlessClient {
     debug: ClientDebugDomain;
     player: PlayerDomain;
     inventory: InventoryDomain;
+    tips: TipDomain;
     management: ShipManagementDomain;
     readyPromise: Promise<this>;
 
@@ -508,13 +513,41 @@ export class DredlessClient {
 
     entity(entityId: number, scope?: number | string): EntitySnapshot | null;
 
+    on(type: "tip-list", callback: (menu: TipList, world: WorldState) => void): this;
     on(type: string, callback: (...args: unknown[]) => void): this;
 
+    off(type: "tip-list", callback: (menu: TipList, world: WorldState) => void): this;
     off(type: string, callback: (...args: unknown[]) => void): this;
 
+    once(type: "tip-list", callback: (menu: TipList, world: WorldState) => void): this;
     once(type: string, callback: (...args: unknown[]) => void): this;
 }
 
+export interface TipList {
+    /** Target inferred from tips.open(); null for unsolicited menus. */
+    readonly entity: number | null;
+    readonly world: number | null;
+    readonly filter: number | null;
+    readonly x: number;
+    readonly y: number;
+    readonly options: readonly string[];
+}
+
+export interface TipOptions {
+    /** Milliseconds to wait per server response; default 5000. */
+    timeout?: number;
+    command?: Command;
+}
+
+export interface TipDomain {
+    readonly current: TipList | null;
+    open(entity: number | EntityHandle, options?: TipOptions): Promise<TipList>;
+    /** Dismiss the menu and wait for the server's empty tip list. */
+    close(options?: TipOptions): Promise<DredlessClient>;
+    select(option: number | string, command?: Command): DredlessClient;
+    choose(entity: number | EntityHandle, option: number | string, options?: TipOptions): Promise<DredlessClient>;
+}
+
 export interface ClientNetDomain {
     connected: boolean;
     ready: boolean;
@@ -948,6 +981,7 @@ export interface EntityHandle {
     asExpandoBox(): ExpandoBoxHandle | null;
 
     use(options?: { invSlot?: number; hold?: boolean }, command?: Command): DredlessClient;
+    openTips(options?: TipOptions): Promise<TipList>;
 }
 
 export interface MachineHandle extends EntityHandle {
@@ -1133,11 +1167,13 @@ export interface DoorHandle extends EntityHandle {
     state: DoorSummary | null;
     rank: number | undefined;
     open: boolean | undefined;
+    setRank(rank: ShipPlayerRank, options?: TipOptions): Promise<DredlessClient>;
 }
 
 export interface SpawnPointHandle extends MachineHandle {
     state: SpawnPointSummary | null;
     rank: number | undefined;
+    setRank(rank: ShipPlayerRank, options?: TipOptions): Promise<DredlessClient>;
 }
 
 export interface ShieldProjectorHandle extends MachineHandle {

package/src/network/invites.d.ts

@@ -1,11 +1,15 @@
 export interface InviteMetadata {
     shipId: string | null;
     name: string | null;
-    color: string | null;
+    /** CSS RGB color sampled from the preview image's top-left pixel, when available. */
+    color?: string | null;
     previewImageUrl: string | null;
     hostname: string;
     inviteCode: string;
 }
-export interface InviteFetchOptions { fetchImpl?: typeof fetch; }
+export interface InviteFetchOptions {
+    fetchImpl?: typeof fetch;
+    includeColor?: boolean;
+}
 export function fetchInviteMetadata(invite: string | URL, options?: InviteFetchOptions): Promise<InviteMetadata>;
 export function parseInviteMetadata(html: string): InviteMetadata;

package/src/network/invites.js

@@ -1,10 +1,48 @@
-import {getFetch} from "../runtime.js";
+import {getFetch, isBrowser} from "../runtime.js";
 
-export async function fetchInviteMetadata(invite, {fetchImpl = null} = {}) {
+export async function fetchInviteMetadata(invite, {fetchImpl = null, includeColor = false} = {}) {
     const url = normalizeInviteUrl(invite);
-    const response = await (fetchImpl || getFetch())(url.href, {headers: {accept: "text/html"}});
+    const fetcher = fetchImpl || getFetch();
+    const response = await fetcher(url.href, {headers: {accept: "text/html"}});
     if (!response.ok) throw new Error(`Invite metadata request failed: ${response.status} ${response.statusText}`);
-    return parseInviteMetadata(await response.text());
+    const metadata = parseInviteMetadata(await response.text());
+    if (!includeColor || !metadata.previewImageUrl) return metadata;
+    return Object.freeze({...metadata, color: await fetchTopLeftColor(metadata.previewImageUrl, fetcher)});
+}
+
+async function fetchTopLeftColor(imageUrl, fetcher) {
+    try {
+        let response = await fetcher(imageUrl, {headers: {range: "bytes=0-1023"}});
+        if (!response.ok) return null;
+        const buffer = await response.arrayBuffer();
+        try {
+            return await decodeImageColor(buffer);
+        } catch (error) {
+            if (response.status !== 206) throw error;
+            response = await fetcher(imageUrl);
+            if (!response.ok) return null;
+            return await decodeImageColor(await response.arrayBuffer());
+        }
+    } catch {
+        return null;
+    }
+}
+
+async function decodeImageColor(buffer) {
+        if (isBrowser()) {
+            const bitmap = await createImageBitmap(new Blob([buffer]));
+            const canvas = typeof OffscreenCanvas === "function" ? new OffscreenCanvas(1, 1) : document.createElement("canvas");
+            canvas.width = canvas.height = 1;
+            const context = canvas.getContext("2d");
+            context.drawImage(bitmap, 0, 0, 1, 1);
+            const [red, green, blue] = context.getImageData(0, 0, 1, 1).data;
+            bitmap.close();
+            return `rgb(${red},${green},${blue})`;
+        }
+        const sharpModule = await import("sharp");
+        const sharp = sharpModule.default || sharpModule;
+        const {data} = await sharp(buffer).extract({left: 0, top: 0, width: 1, height: 1}).raw().toBuffer({resolveWithObject: true});
+        return `rgb(${data[0]},${data[1]},${data[2]})`;
 }
 
 export function parseInviteMetadata(html) {
@@ -15,7 +53,6 @@ export function parseInviteMetadata(html) {
     return Object.freeze({
         shipId: parsedTitle.shipId,
         name: parsedTitle.name,
-        color: metaContent(html, "theme-color") || metaContent(html, "color") || null,
         previewImageUrl: preview ? new URL(preview, url).href : null,
         hostname: url.hostname,
         inviteCode: url.pathname.split("/").filter(Boolean).at(-1)
@@ -29,7 +66,7 @@ function normalizeInviteUrl(invite) {
 }
 
 function parseInviteTitle(title) {
-    const match = title.match(/^Invite:\s?(.*?)\s*\{([^{}]+)}(?:\s*-\s*drednot\.io)?\s*$/i);
+    const match = title.match(/^Invite:\s?(.+?) \{([^{}]+)}(?:\s*-\s*drednot\.io)?\s*$/i);
     return match ? {name: decodeHtml(match[1]), shipId: decodeHtml(match[2])} : {name: null, shipId: null};
 }