@mudlet/mudlet-web 0.3.0

package/dist-lib/map/MapStore.d.ts

@@ -0,0 +1,1067 @@
+import type { MudletArea, MudletFont, MudletMap, MudletMapHeader, MudletRoom } from 'mudlet-map-binary-reader';
+import { readerExport } from 'mudlet-map-binary-reader';
+import { type ExitWeightFilter, type PathfindResult } from './pathfinding';
+export type { ExitWeightFilter, PathfindResult } from './pathfinding';
+export type MapRendererData = ReturnType<typeof readerExport>;
+export declare function parseDirection(dir: unknown): number | undefined;
+export declare const DEFAULT_FONT: MudletFont;
+export declare function makeRoom(areaId: number): MudletRoom;
+/**
+ * Convert Mudlet's own `saveJsonMap` export into the binary-reader model.
+ *
+ * This is a genuinely different shape from {@link toJsonString}'s output (which
+ * mirrors the binary model): areas are an *array* carrying their rooms nested
+ * inside, there is no top-level `rooms` map, exits are `{exitId, name}` records
+ * rather than direction fields, and a room's symbol is an OBJECT
+ * (`{color24RGB, text}`) rather than a string. Not handling it meant
+ * `loadJsonMap` rejected every map Mudlet actually writes, so packages fell
+ * back to rebuilding the map through the Lua API — and passing that symbol
+ * object straight to setRoomChar is what rendered rooms as "[LuaTable …]".
+ *
+ * Returns null when the payload isn't this format, so the caller can fall
+ * through to the binary-model path.
+ *
+ * Room `border` is the one documented field still unmapped — no map available
+ * to verify it against, and it needs the same post-load side-table treatment as
+ * symbol colours. Everything else in TRoom.cpp's writeJsonRoom is covered.
+ * Symbol colours are applied separately by applyJsonSymbolColors.
+ */
+export declare function mudletJsonMapToMudletMap(src: unknown): MudletMap | null;
+export declare function makeArea(): MudletArea;
+export interface MapLabelInfo {
+    X: number;
+    Y: number;
+    Z: number;
+    Width: number;
+    Height: number;
+    Text: string;
+    Pixmap: string;
+    OnTop: boolean;
+    Scaling: boolean;
+    Temporary: boolean;
+    FgColor: {
+        r: number;
+        g: number;
+        b: number;
+    };
+    BgColor: {
+        r: number;
+        g: number;
+        b: number;
+    };
+}
+export type MapLabelLookup = {
+    ok: false;
+    err: 'noarea' | 'noid';
+} | {
+    ok: true;
+    single: MapLabelInfo;
+} | {
+    ok: true;
+    multi: Record<number, MapLabelInfo>;
+};
+/** Mudlet room highlight: two-color radial gradient with per-color alpha and
+ *  a radius factor. Rendered by MudletHighlightOverlay. Despite the suffix
+ *  naming, Mudlet's gradient puts color2 at the *centre* and color1 at the
+ *  *outer* ring (T2DMap::drawRoom: setColorAt(0, color2), setColorAt(0.85,
+ *  color1)). */
+export interface RoomHighlight {
+    r1: number;
+    g1: number;
+    b1: number;
+    r2: number;
+    g2: number;
+    b2: number;
+    a1: number;
+    a2: number;
+    radius: number;
+}
+/** Mudlet registerMapInfo callback result. Returned by the LuaRuntime
+ *  evaluator after invoking a registered contributor; `null` when the
+ *  callback returned an empty string / nothing, or when the evaluator
+ *  itself failed (the Lua error is reported via showHandlerError, not here). */
+export interface MapInfoResult {
+    label: string;
+    text: string;
+    isBold: boolean;
+    isItalic: boolean;
+    color?: {
+        r: number;
+        g: number;
+        b: number;
+    };
+}
+/** A registered Mudlet `registerMapInfo` contributor.
+ *
+ *  Two kinds exist. Script-registered ones carry a `callbackId` that indexes
+ *  into the Lua-side `__mudix_cb` registry; the LuaRuntime evaluator dispatches
+ *  to it, and they start disabled (Mudlet semantics — caller must
+ *  `enableMapInfo(label)` to show it). Built-in ones (`builtin: true`,
+ *  `callbackId: null`) mirror Mudlet's native "Short"/"Full" contributors —
+ *  they're evaluated directly from MapStore data (see `builtinMapInfo`), don't
+ *  depend on a live Lua runtime, and can't be removed via `killMapInfo`. */
+export interface MapInfoContributor {
+    label: string;
+    callbackId: number | null;
+    enabled: boolean;
+    builtin?: boolean;
+}
+export interface MapEventEntry {
+    /** Stable id used by removeMapEvent and as a parent reference. */
+    uniqueName: string;
+    /** Event name passed to raiseEvent on click. */
+    eventName: string;
+    /** uniqueName of a parent entry that this is nested under, or null for top-level. */
+    parent: string | null;
+    /** Label rendered in the context menu. Defaults to uniqueName when unspecified. */
+    displayName: string;
+    /** Extra arguments captured by addMapEvent. Mudlet's "selection" branch
+     *  (the one mudix mirrors, since the right-clicked room is treated as the
+     *  selection) discards these — kept for parity with the registration API. */
+    args: unknown[];
+}
+export interface MapMenuEntry {
+    /** Stable id used by removeMapMenu and as a parent reference from
+     *  addMapEvent/addMapMenu entries. */
+    name: string;
+    /** name of a parent menu this is nested under, or null for top-level. */
+    parent: string | null;
+    /** Label rendered for the submenu. Defaults to name when unspecified. */
+    displayName: string;
+}
+export declare class MapStore {
+    private rooms;
+    private areas;
+    private areaNames;
+    private hashToRoom;
+    private labels;
+    private envColors;
+    private nextRoomId;
+    private nextAreaId;
+    /** Installed by `setExitWeightFilter`; consulted per exit in findPath. */
+    private exitWeightFilter;
+    private pendingBinaryHashIndex;
+    private pendingBinaryHadSelection;
+    private version;
+    private subscribers;
+    private notifyPending;
+    private highlightSubscribers;
+    private highlightNotifyPending;
+    private selectedRooms;
+    private selectionCenter;
+    private selectionVersion;
+    private selectionSubscribers;
+    private selectionNotifyPending;
+    private mapEvents;
+    private mapMenus;
+    private customEnvColors;
+    /** roomID → the special-exit COMMANDS locked on it. See
+     *  {@link lockedSpecialCommands}. */
+    private specialExitLocks;
+    private roomHighlights;
+    private mapUserData;
+    private playerRoomId;
+    private mRoomIdHash;
+    /** Mudlet's mProfileName — the key into mRoomIdHash for this profile's saved
+     *  player room. Set by ScriptingEngine to the connection name before the map
+     *  loads. Empty string when unknown (then no position is restored/saved). */
+    profileName: string;
+    private mapEventDispatcher;
+    private mapInfoContributors;
+    private builtinMapInfo;
+    private mapInfoEvaluator;
+    constructor();
+    subscribe(cb: () => void): () => void;
+    /** Subscribe to highlight-set changes only (highlightRoom / unHighlightRoom
+     *  and bulk clears via newEmptyMap / loadFromBinary). MudletHighlightOverlay
+     *  uses this so it re-renders without forcing a full MudixMapReader rebuild. */
+    subscribeHighlights(cb: () => void): () => void;
+    /** Subscribe to selection changes (selectMapRoom / toggleMapRoomSelection /
+     *  clearMapSelection and the bulk clears in newEmptyMap / loadFromBinary).
+     *  MapSelectionOverlay rides this so per-click repaints stay off the main
+     *  store-notify channel. */
+    subscribeSelection(cb: () => void): () => void;
+    private notify;
+    private notifyHighlights;
+    private notifySelection;
+    /** Monotonic counter incremented on every mutation. Live readers compare
+     *  the snapshot they cached against this to decide whether to rebuild. */
+    getVersion(): number;
+    isEmpty(): boolean;
+    private initialized;
+    /** True once newEmptyMap() has been called — the store is ready for scripting even with 0 rooms. */
+    isInitialized(): boolean;
+    /** Initialize with a single default area so scripts can start adding rooms immediately. */
+    newEmptyMap(): void;
+    /**
+     * Replace the store's contents with a parsed Mudlet binary map. Loads
+     * rooms, areas, area names, hashes, labels, custom env colors, env color
+     * palette, and map-level user data. Bumps the id cursors past any binary
+     * ids so subsequent {@link createRoomID} / {@link addAreaName} calls don't
+     * collide. One notification fires at the end of the batch.
+     */
+    loadFromBinary(mudletMap: MudletMap): void;
+    /**
+     * Header phase of a streamed binary load — everything in a Mudlet map
+     * except the rooms (see `MudletMapReader.streamRooms`). Wipes the store and
+     * applies areas / names / labels / colours / user data, then leaves it open
+     * for {@link ingestBinaryRooms} batches. Nothing is notified until
+     * {@link endBinaryLoad}, so subscribers never observe a half-loaded map.
+     *
+     * {@link loadFromBinary} is this same three-phase sequence run eagerly over
+     * an already-materialised map.
+     */
+    beginBinaryLoad(header: MudletMapHeader): void;
+    /**
+     * Room phase of a streamed binary load. Call any number of times between
+     * {@link beginBinaryLoad} and {@link endBinaryLoad}; each batch is folded
+     * into the store as it arrives, so the worker never has to hold (nor the
+     * structured clone carry) the whole room graph at once.
+     */
+    ingestBinaryRooms(rooms: Iterable<readonly [number, MudletRoom]>): void;
+    private ingestBinaryRoom;
+    /**
+     * Finalize a streamed binary load: fold in the authoritative hash index,
+     * resolve the player room, and fire the single notification the whole load
+     * is worth.
+     */
+    endBinaryLoad(): void;
+    /**
+     * Mudlet `deleteMap()` — wipe every room, area, label and associated datum,
+     * leaving a fresh empty map with a single default area (so scripts can keep
+     * adding rooms). Returns true.
+     */
+    deleteMap(): boolean;
+    toRendererData(): MapRendererData | null;
+    /**
+     * Mudlet `saveJsonMap(path)` backbone — serialise the entire MapStore as a
+     * JSON string with the same shape as the in-memory `MudletMap` (so a later
+     * `loadJsonMap` can hand it straight to `loadFromBinary`). Pixmaps are
+     * already normalised to base64 by `loadFromBinary`, so the result
+     * round-trips cleanly through `JSON.stringify`.
+     */
+    toJsonString(): string;
+    /**
+     * Save-side variant of {@link toMudletMap}: re-injects the v20-compatible
+     * `system.fallback_hidden` userData key for rooms in the hidden side-table
+     * so the serialised file round-trips back through `loadFromBinary` (and
+     * stays loadable by Mudlet v20 readers). Render paths still call the plain
+     * {@link toMudletMap} — the fallback key is dead weight for the renderer
+     * and we don't want to pay the per-room object spread on every redraw.
+     */
+    toMudletMapForSave(): MudletMap;
+    /**
+     * Mudlet `loadJsonMap(path)` backbone — parse a JSON payload previously
+     * produced by `toJsonString` and replace the store's contents. Returns
+     * true on success, false when the JSON is malformed or doesn't carry the
+     * expected MudletMap shape (no `rooms` / `areas` records).
+     */
+    loadFromJsonString(json: string): boolean;
+    toMudletMap(): MudletMap;
+    /**
+     * Mudlet `createRoomID([minimum])` — returns the smallest unused room id
+     * at or above `minimum` (or above the running cursor if not given). The
+     * id isn't reserved; a follow-up `addRoom(id)` is what actually claims it.
+     */
+    createRoomID(minimum?: number): number;
+    /**
+     * Mudlet `addRoom(roomID [, areaID])`. The room is always created; the
+     * areaID is a placement *request*. An areaID naming an area that doesn't
+     * exist is not created on demand (Mudlet's TLuaInterpreter::addRoom parks
+     * the room in the default area -1 and reports the failed placement as
+     * `(nil, errMsg)` instead), so this returns the message for the binding to
+     * shape and leaves the room in -1.
+     *
+     * Returns false only when the roomID is already taken.
+     */
+    addRoom(id: number, areaId?: number): boolean | {
+        err: string;
+    };
+    deleteRoom(id: number): boolean;
+    roomExists(id: number): boolean;
+    /** Mudlet `getPlayerRoom()` — id of the player's current room, or null
+     *  when unset or the room no longer exists. Strict: no fallback room (Mudlet
+     *  keeps the data-layer value empty until centerview/movement sets it). The
+     *  view's "no known location" fallback lives in {@link getFallbackRoomId}. */
+    getPlayerRoom(): number | null;
+    /** Display-only fallback room for the map view when there is no real player
+     *  position (getPlayerRoom() is null). Mudlet's T2DMap paints the marker on
+     *  getRoomIDList().constFirst() — hash-arbitrary, hence its `randomRoom`
+     *  name. We prefer room 1 (stable and what users expect), then the lowest
+     *  existing id so the marker still lands somewhere on odd maps. null only
+     *  when the map is empty. Never feeds getPlayerRoom — it's purely for
+     *  centering + the marker. */
+    getFallbackRoomId(): number | null;
+    /** Mirror of Mudlet's `mRoomIdHash[host.getName()] = roomId` from centerview.
+     *  centerView validates the id exists before calling this (Mudlet rejects
+     *  unknown ids), so the stored id is normally live; getPlayerRoom still does
+     *  an existence check on read in case the room is deleted afterwards. */
+    setPlayerRoom(id: number): void;
+    getRoomName(id: number): string | undefined;
+    setRoomName(id: number, name: string): boolean;
+    /** Mudlet `getRoomArea(id)` — area id of the room, or -1 if the room is missing. */
+    /** Mudlet `getRoomArea(roomID)` — the area the room belongs to (-1 is the
+     *  default area), or undefined when the room itself doesn't exist. */
+    getRoomArea(id: number): number | undefined;
+    /**
+     * Mudlet `setRoomArea(roomID|{ids}, areaID|areaName)`. Accepts either a
+     * single room ID or an array of room IDs, and either a numeric area ID or
+     * an area-name string.
+     *
+     * The area must already exist — Mudlet does not create one on demand, and
+     * an areaID below 1 is refused outright (resetRoomArea is the documented
+     * way to park a room in the default area -1). Every refusal is a
+     * `(nil, errMsg)` return there, so the message is handed back here and null
+     * means success (see {@link setDoor}).
+     */
+    setRoomArea(id: number | number[], areaIdOrName: number | string): string | null;
+    /** Resolve area-id-or-name → numeric id, or undefined if unknown. */
+    private resolveAreaId;
+    getRoomCoordinates(id: number): [number, number, number] | undefined;
+    /**
+     * Mudlet `searchRoom(roomID | roomName[, caseSensitive[, exactMatch]])` —
+     * by id returns the room's name (or `undefined` for a miss); by name returns
+     * `{ [roomID] = roomName }` for every room whose name matches. Matching is a
+     * case-insensitive substring search by default; `caseSensitive`/`exactMatch`
+     * tighten it. The binding re-keys the wasmoon-stringified ids back to ints.
+     */
+    searchRoom(arg: number | string, caseSensitive?: boolean, exactMatch?: boolean): string | undefined | Record<number, string>;
+    /**
+     * Mudlet `searchRoomUserData([key[, value]])`:
+     *   • no args → sorted list of every user-data key used by any room;
+     *   • key only → sorted list of every distinct value stored under that key;
+     *   • key + value → sorted list of room ids where that key equals value.
+     */
+    searchRoomUserData(key?: string, value?: string): string[] | number[];
+    setRoomCoordinates(id: number, x: number, y: number, z: number): boolean;
+    /**
+     * Mudlet `getRoomEnv(id)` — environment color id, or -1 if the room is
+     * missing. (Rooms without an env override still report their stored value.)
+     */
+    getRoomEnv(id: number): number;
+    setRoomEnv(id: number, env: number): boolean;
+    getRoomChar(id: number): string;
+    setRoomChar(id: number, char: string): boolean;
+    /**
+     * Mudlet `lockRoom(roomID, lockIfTrue)` — mark a room as locked so
+     * pathfinding routes around it (see {@link findPath}). Returns true on
+     * success, false when the room doesn't exist.
+     */
+    lockRoom(id: number, lock: boolean): boolean;
+    /**
+     * Mudlet `roomLocked(roomID)` — true when the room is locked, false when
+     * unlocked or the room doesn't exist (Mudlet returns nil for a missing
+     * room; the Lua binding re-shapes that case).
+     */
+    roomLocked(id: number): boolean;
+    /**
+     * Mudlet `getRoomWeight(roomID)` — the room's pathfinding weight (cost to
+     * enter). Returns `undefined` when the room doesn't exist; the Lua binding
+     * turns that into Mudlet's "no return value" miss.
+     */
+    getRoomWeight(id: number): number | undefined;
+    /**
+     * Mudlet `setRoomWeight(roomID, weight)` — set the room's pathfinding
+     * weight. Mudlet rejects negative weights (0 is allowed). Returns true on
+     * success, false when the room doesn't exist or the weight is invalid.
+     */
+    setRoomWeight(id: number, weight: number): boolean;
+    /** Mudlet `getRoomsByPosition(areaID, x, y, z)` — undefined for an unknown
+     *  area, matching {@link getAreaRooms}. */
+    getRoomsByPosition(areaId: number, x: number, y: number, z: number): number[] | undefined;
+    getRoomIDbyHash(hash: string): number | undefined;
+    setRoomIDbyHash(id: number, hash: string): void;
+    getRoomHashByID(id: number): string | undefined;
+    /** Mudlet `getRoomExits(roomID)` — `{ direction = toRoomID }`. Undefined
+     *  for an unknown room (Mudlet pushes nothing at all in that case). */
+    getRoomExits(id: number): Record<string, number> | undefined;
+    /**
+     * Mudlet `setExit(from, to, dir)` — `dir` is either a 1-12 integer or a
+     * direction name ("north"/"n"/etc.). Returns true on success.
+     */
+    setExit(from: number, to: number, dir: number | string): boolean;
+    /** Mudlet `getExitStubs(roomID)` — the room's stub direction codes, or
+     *  undefined for an unknown room (reported as `(nil, errMsg)` in Lua). */
+    getExitStubs(id: number): number[] | undefined;
+    /**
+     * Mudlet `getExitStubsNames(roomID)` — the room's exit stubs as direction
+     * names ("north"/"northeast"/…, or "other" for the special-exit code 13)
+     * rather than the numeric codes `getExitStubs` returns. Returns `undefined`
+     * when the room doesn't exist so the binding can hand back Mudlet's
+     * `(false, errMsg)`.
+     */
+    getExitStubsNames(id: number): string[] | undefined;
+    /** Mudlet `findPath(from, to)` — see {@link findPath} in `./pathfinding`
+     *  for the algorithm (A* with Mudlet's Euclidean-or-1 heuristic). */
+    findPath(from: number, to: number): PathfindResult | null;
+    /** Mudlet `setExitWeightFilter(fn|nil)` — the callback consulted for every
+     *  candidate exit during pathfinding, or null when none is installed. Set
+     *  by the Lua binding; read only by {@link findPath}. */
+    setExitWeightFilter(filter: ExitWeightFilter | null): void;
+    setExitStub(id: number, dir: number | string, set: boolean): boolean;
+    /**
+     * Mudlet `lockExit(roomID, direction, lockIfTrue)` — toggle a stock-direction
+     * exit lock so pathfinding (see `pathfinding.ts`) routes around it. `dir`
+     * accepts the 1-12 integer code or a direction name ("north"/"n"/etc.).
+     * Returns true on success, false when the room is missing or `dir` doesn't
+     * resolve.
+     */
+    lockExit(id: number, dir: number | string, lock: boolean): boolean;
+    /**
+     * Mudlet `hasExitLock(roomID, direction)` — whether the stock-direction exit
+     * is currently locked. Returns false for an unlocked exit or when the room
+     * doesn't exist (Lua binding maps the latter to `(false, errMsg)`).
+     */
+    hasExitLock(id: number, dir: number | string): boolean;
+    /**
+     * Mudlet `addSpecialExit(exitRoomID, entranceRoomID, command)`. Both rooms
+     * must exist and the command must be non-empty; each failure is a
+     * `(nil, errMsg)` return in Mudlet, so the message is handed back here and
+     * null means success (same shape as {@link setDoor}).
+     */
+    addSpecialExit(from: number, to: number, cmd: string): string | null;
+    /** Mudlet `removeSpecialExit(exitRoomID, command)` — see {@link addSpecialExit}
+     *  for the message/null return shape. */
+    removeSpecialExit(from: number, cmd: string): string | null;
+    getSpecialExitsSwap(id: number): Record<string, number>;
+    /**
+     * Mudlet `getSpecialExits(roomID [, listAllExits])` — special exits keyed by
+     * destination room id: `{ [exitRoomID] = { [command] = "0"|"1" } }`, where
+     * "1" marks a locked exit. When several commands lead to the same room and
+     * `listAllExits` is false (the default), only the lowest-weight command is
+     * reported; pass `true` to list every command. Returns `{}` for a missing
+     * room. The lock flag follows this client's data model (special-exit locks
+     * are tracked by destination room id, see pathfinding.ts).
+     */
+    getSpecialExits(id: number, listAllExits?: boolean): Record<number, Record<string, string>> | undefined;
+    /**
+     * Mudlet `getExitWeights(roomID)` — per-exit weight overrides as
+     * `{ [exit] = weight }`. Stock exits are keyed by their short direction name
+     * ("n"/"ne"/"up"/…), special exits by the verbatim command. Returns `{}`
+     * when the room has no overrides or doesn't exist.
+     */
+    getExitWeights(id: number): Record<string, number>;
+    /**
+     * Mudlet `setExitWeight(roomID, exitCommand, weight)` — override the weight
+     * of a single exit. `exitCommand` is a stock direction (1-12 or a name) or a
+     * special-exit command. A weight of 0 resets the override (pathfinding falls
+     * back to the destination room's weight); negative weights are rejected.
+     * Each refusal is a `(nil, errMsg)` return in Mudlet, so the message is
+     * handed back here and null means success (see {@link setDoor}).
+     */
+    setExitWeight(id: number, exitCommand: number | string, weight: number): string | null;
+    /**
+     * Mudlet `clearSpecialExits(roomID)` — remove every special exit from the
+     * room, along with the locks, doors and custom lines keyed by those
+     * commands (Mudlet's TRoom::clearSpecialExits does the same cleanup).
+     * Returns true on success, false when the room doesn't exist.
+     */
+    clearSpecialExits(id: number): boolean;
+    /**
+     * Mudlet `lockSpecialExit(fromRoomID, toRoomID, command, lockIfTrue)` — lock
+     * or unlock a special exit so pathfinding skips it. Mudlet ignores the
+     * `toRoomID` argument (kept for signature compatibility); the lock is keyed
+     * by the COMMAND (TRoom::mSpecialExitLocks is a `QSet<QString>`), so two
+     * commands leading to the same room lock independently. Returns true on
+     * success or an error string (room missing / no such command) the binding
+     * turns into `(nil, errMsg)`.
+     */
+    lockSpecialExit(fromId: number, command: string, lock: boolean): true | string;
+    /**
+     * Per-command special-exit locks for a room, created on first use. Seeded
+     * from the destination-keyed list a loaded map arrives with, since the
+     * binary reader collapses Mudlet's per-command locks down to the rooms they
+     * lead to (`MudletRoom.mSpecialExitLocks` is `number[]`) — so an imported
+     * map starts out with every command to a locked destination locked, exactly
+     * as it renders today, and diverges only as scripts lock individual
+     * commands.
+     */
+    private lockedSpecialCommands;
+    /** Rebuild a room's destination-keyed `mSpecialExitLocks` from the
+     *  authoritative per-command set. */
+    private syncSpecialExitLockMirror;
+    /**
+     * Mudlet `hasSpecialExitLock(fromRoomID, toRoomID, command)` — whether the
+     * special exit is locked. As with `lockSpecialExit`, the `toRoomID` argument
+     * is ignored and the lock is resolved via the command's destination room.
+     * Returns the boolean lock state, or an error string (room missing / no such
+     * command) the binding turns into `(false, errMsg)`.
+     */
+    hasSpecialExitLock(fromId: number, command: string): boolean | string;
+    /** Whether one special-exit COMMAND is locked. */
+    isSpecialExitLocked(roomId: number, command: string): boolean;
+    /**
+     * Mudlet `getAllRoomEntrances(roomID)` — every room that has an exit (stock
+     * or special) leading into this room, as a sorted, de-duplicated id list.
+     * Returns `undefined` when the room doesn't exist.
+     */
+    getAllRoomEntrances(id: number): number[] | undefined;
+    /**
+     * Mudlet `connectExitStub(fromID, direction)` / `(fromID, toID[, direction])`
+     * — hook up an existing exit stub to another room, wiring the reverse stub
+     * back too. Dispatches the three Mudlet call forms:
+     *   • explicit `(fromID, toID, direction)` — connect the stub in `direction`.
+     *   • direction only — find the nearest in-area room sitting in that
+     *     direction that has a matching reverse stub.
+     *   • toID only — connect when exactly one pair of reverse stubs exists.
+     * A bare numeric second argument is resolved to a direction or a toID by
+     * checking what actually exists (a stub in that direction vs. a room with
+     * that id); genuinely ambiguous cases return an error asking for a string
+     * direction. Returns true on success or an error string.
+     */
+    connectExitStub(fromId: number, arg2: number | string, arg3?: number | string): true | string;
+    /** connectExitStub direction-only form (Mudlet connectExitStubByDirection). */
+    private connectStubByDir;
+    /** connectExitStub toID-only form (Mudlet connectExitStubByToId). */
+    private connectStubByTo;
+    /** connectExitStub explicit form (Mudlet connectExitStubByDirectionAndToId). */
+    private connectStubByDirAndTo;
+    /**
+     * Mudlet `getCustomLines(roomID)` — per-direction custom exit lines drawn
+     * on the map. Returns `undefined` when the room doesn't exist so the Lua
+     * wrapper can hand back `nil`; otherwise a `{ dir = { attributes, points } }`
+     * table (empty when the room has no custom lines). Points carry the room's
+     * Z because Mudlet stores only X/Y per point and uses the owning room's Z
+     * for rendering.
+     */
+    getCustomLines(id: number): Record<string, {
+        attributes: {
+            color: {
+                r: number;
+                g: number;
+                b: number;
+            };
+            style: string;
+            arrow: boolean;
+        };
+        points: Array<{
+            x: number;
+            y: number;
+            z: number;
+        }>;
+    }> | undefined;
+    /**
+     * Mudlet `removeCustomLine(roomID, direction)` — drop the custom exit line
+     * for a direction (stock direction number/name or a special-exit command).
+     * The key form stored varies by map source, so we try the raw command, the
+     * canonical long name and the short name. Returns true when a line was
+     * removed, false when the room or the line doesn't exist.
+     */
+    removeCustomLine(id: number, dir: number | string): boolean;
+    /**
+     * Mudlet `addCustomLine(roomID, id_to, direction, style, color, arrow)`.
+     * `target` is either a destination room id (line drawn to that room's
+     * position, which must be in the same area) or an explicit list of
+     * `[x, y, z]` points. `style` is one of Mudlet's pen-style names
+     * ("solid line", "dot line", "dash line", "dash dot line",
+     * "dash dot dot line"). Returns false when the room/target is invalid, the
+     * areas differ, no points are supplied, or the style name is unknown.
+     */
+    addCustomLine(id: number, target: number | Array<[number, number, number]>, direction: number | string, style: string, color: {
+        r: number;
+        g: number;
+        b: number;
+    }, arrow: boolean): string | null;
+    /**
+     * Whether a room has a stock exit in `dirInt`, or a special exit whose
+     * command is `key`. Mirrors Mudlet's TRoom::hasExitOrSpecialExit, which
+     * addCustomLine consults before drawing — a custom line is a decoration for
+     * an existing exit, not a way to invent one.
+     */
+    private hasExitOrSpecialExit;
+    /** Mudlet `getDoors(roomID)` — `{ exitCmd = doorType }`. Undefined for an
+     *  unknown room, which the Lua binding reports as `(nil, errMsg)`. */
+    getDoors(id: number): Record<string, number> | undefined;
+    /**
+     * Mudlet `setDoor(roomID, exitCmd, status)`. exitCmd is either a stock
+     * direction — spelled exactly as Mudlet keys its door map ("n"/"ne"/…/
+     * "up"/"down"/"in"/"out"), which is also what a saved map carries — or an
+     * arbitrary special-exit command string, used as-is.
+     *
+     * Mudlet refuses a direction the room has no exit *or stub* for, and a
+     * status outside 0-3; both are `(nil, errMsg)` returns rather than a bare
+     * false, so the failure is reported here as the message string and success
+     * as null (same shape as {@link addCustomLine}).
+     */
+    setDoor(id: number, dir: number | string, val: number): string | null;
+    /**
+     * Mudlet `getRoomUserData(id, key)` — returns the stored value, or
+     * `undefined` when either the room or the key is missing. The Lua binding
+     * differentiates the two cases when the script asks for the full-error
+     * shape (`fullErr=true`).
+     */
+    getRoomUserData(id: number, key: string): string | undefined;
+    setRoomUserData(id: number, key: string, value: string): boolean;
+    /**
+     * Mudlet `getRoomUserDataKeys(id)` — returns the user-data keys for the
+     * room (possibly empty) or `undefined` when the room itself does not
+     * exist. The Bridge.lua wrapper converts the JS array to a 1-indexed Lua
+     * table and the `undefined` miss to `nil`.
+     */
+    getRoomUserDataKeys(id: number): string[] | undefined;
+    /**
+     * Mudlet `getAllRoomUserData(roomID)` — every key/value pair stored on the
+     * room as `{ key = value }`. Returns `undefined` when the room itself does
+     * not exist (the Lua binding turns that into Mudlet's `(false, errMsg)`).
+     */
+    getAllRoomUserData(id: number): Record<string, string> | undefined;
+    /**
+     * Mudlet `clearRoomUserData(roomID)` — wipe every user-data entry on the
+     * room. Returns `true` when something was cleared, `false` when it was
+     * already empty, and `undefined` when the room doesn't exist.
+     */
+    clearRoomUserData(id: number): boolean | undefined;
+    /**
+     * Mudlet `clearRoomUserDataItem(roomID, key)` — drop a single user-data
+     * key. Returns `true` when the key existed, `false` when it didn't, and
+     * `undefined` when the room doesn't exist.
+     */
+    clearRoomUserDataItem(id: number, key: string): boolean | undefined;
+    /**
+     * Mudlet `resetRoomArea(roomID)` — move the room back to the default "void"
+     * area (-1). Returns `true` on success, `undefined` when the room doesn't
+     * exist (Lua → `(nil, errMsg)`). Doesn't go through {@link setRoomArea},
+     * which refuses an areaID below 1 — resetRoomArea is Mudlet's documented
+     * way to reach the default area.
+     */
+    resetRoomArea(id: number): boolean | undefined;
+    /**
+     * Mudlet `getMapUserData(key)` — returns the stored value, or `undefined`
+     * when the key has never been set. The Lua binding turns the missing case
+     * into Mudlet's `(false, errMsg)` 2-tuple.
+     */
+    getMapUserData(key: string): string | undefined;
+    setMapUserData(key: string, value: string): void;
+    /**
+     * Mudlet `clearMapUserData()` (no args) wipes the entire map-level user
+     * data dict — used by scripts that want a clean slate when re-importing
+     * data. The single-key form is exposed under `clearMapUserDataItem` to
+     * match Mudlet's split.
+     */
+    clearMapUserData(): boolean;
+    clearMapUserDataItem(key: string): boolean;
+    getAllMapUserData(): Record<string, string>;
+    /** Replace the entire map-level user-data dict (e.g. after loading a .dat). */
+    loadMapUserData(data: Record<string, string> | undefined | null): void;
+    /**
+     * Mudlet `addAreaName(name)` returns a numeric area ID on success or
+     * `(false, errMsg)` when the name is empty or already in use.
+     */
+    addAreaName(rawName: string): number | {
+        ok: false;
+        err: string;
+    };
+    /**
+     * Mudlet `deleteArea(areaID|areaName)` — deletes the area record and the
+     * rooms it contained. The default area cannot be deleted and an areaID
+     * below 1 names it, so every refusal (unknown id/name, empty name, the
+     * default area) is a `(nil, errMsg)` return there: the message is handed
+     * back here and null means success (see {@link setDoor}).
+     */
+    deleteArea(idOrName: number | string): string | null;
+    getAreaTable(): Record<string, number>;
+    /**
+     * Mudlet `getAreaTableSwap()` — the inverse of {@link getAreaTable}: every
+     * area keyed by id → name (`{ [areaID] = name }`). The Lua wrapper re-keys
+     * the wasmoon-stringified ids back to integers.
+     */
+    getAreaTableSwap(): Record<number, string>;
+    /** True when an area with this id exists. */
+    hasArea(id: number): boolean;
+    /** Mudlet's T2DMap::csmDefaultXYZoom / csmMinXYZoom. */
+    static readonly DEFAULT_MAP_ZOOM = 20;
+    static readonly MIN_MAP_ZOOM = 3;
+    /**
+     * Mudlet `getAreaUserData(areaID, key)` — the stored value, or `undefined`
+     * when the key is absent. Area existence is checked by the binding via
+     * {@link hasArea} so it can distinguish the two miss cases.
+     */
+    getAreaUserData(id: number, key: string): string | undefined;
+    /**
+     * Mudlet `setAreaUserData(areaID, key, value)` — store a string value on
+     * the area. Returns `false` when the area doesn't exist.
+     */
+    setAreaUserData(id: number, key: string, value: string): boolean;
+    /**
+     * Mudlet `getAllAreaUserData(areaID)` — every key/value pair on the area.
+     * Returns `undefined` when the area doesn't exist.
+     */
+    getAllAreaUserData(id: number): Record<string, string> | undefined;
+    /**
+     * Mudlet `clearAreaUserData(areaID)` — wipe every entry. Returns `true`
+     * when something was cleared, `false` when already empty, `undefined` when
+     * the area doesn't exist.
+     */
+    clearAreaUserData(id: number): boolean | undefined;
+    /**
+     * Mudlet `clearAreaUserDataItem(areaID, key)` — drop a single key. Returns
+     * `true` when it existed, `false` when it didn't, `undefined` when the area
+     * doesn't exist.
+     */
+    clearAreaUserDataItem(id: number, key: string): boolean | undefined;
+    /**
+     * Mudlet `searchAreaUserData([key[, value]])` — the area-level analogue of
+     * {@link searchRoomUserData}: no args → all keys; key only → all distinct
+     * values for that key; key + value → sorted area ids where key equals value.
+     */
+    searchAreaUserData(key?: string, value?: string): string[] | number[];
+    /**
+     * Per-area 2D-map zoom stored in the map file (area userData under
+     * {@link AREA_ZOOM_KEY}). Returns `undefined` when the area is missing or has
+     * no saved zoom (caller falls back to fitArea). Mirrors Mudlet's treatment of
+     * zoom as map data rather than client config.
+     */
+    getAreaZoom(id: number): number | undefined;
+    /**
+     * Save the per-area zoom into the area's userData so it round-trips with the
+     * map file. Deliberately does NOT call {@link notify} — zoom is a view-only
+     * datum that no renderer reads from the store snapshot, and the camera-move
+     * handler calls this on every wheel tick; notifying would rebuild the whole
+     * scene on each one. The value persists to IndexedDB the next time the map is
+     * serialised (saveMap → toMudletMapForSave). Returns false when the area is
+     * missing or the zoom isn't a positive finite number.
+     */
+    setAreaZoom(id: number, zoom: number): boolean;
+    /**
+     * Mudlet `getGridMode(areaID)` — whether the area is drawn on a fixed grid
+     * (rooms snapped to integer coordinates, no custom exit lines). Returns
+     * `undefined` when the area doesn't exist.
+     */
+    getGridMode(id: number): boolean | undefined;
+    /**
+     * Mudlet `setGridMode(areaID, true/false)` — toggle the area's grid layout.
+     * Returns `false` when the area doesn't exist.
+     */
+    setGridMode(id: number, gridMode: boolean): boolean;
+    /**
+     * Mudlet `getRoomAreaName(areaID|areaName)` — bidirectional. Given an ID
+     * returns the name; given a name returns the ID. Returns undefined when
+     * the input cannot be resolved.
+     */
+    getRoomAreaName(idOrName: number | string): string | number | undefined;
+    /**
+     * Mudlet `setAreaName(areaID|areaName, newName) → true | false, errMsg`.
+     * Rejects empty new names and names that conflict with another area.
+     */
+    setAreaName(idOrName: number | string, newName: string): boolean | {
+        ok: false;
+        err: string;
+    };
+    /** Mudlet `getAreaRooms(areaID)` — the area's room ids, or undefined for an
+     *  unknown area (Mudlet pushes nil, with no message). */
+    getAreaRooms(areaId: number): number[] | undefined;
+    /**
+     * Mudlet `getCollisionLocationsInArea(areaID)` — the (x, y, z) coordinates
+     * in an area occupied by more than one room, which render on top of each
+     * other on the 2D map. Mirrors TArea::getCollisionNodes (TArea.cpp).
+     * Returns null for an unknown area so the Lua wrapper can produce Mudlet's
+     * (nil, errMsg) pair; an area with no overlaps yields an empty list.
+     */
+    getCollisionLocationsInArea(areaId: number): Array<[number, number, number]> | null;
+    /**
+     * Room to center the 2D view on when an area is opened with no player room
+     * in it, mirroring Mudlet's T2DMap::switchArea (T2DMap.cpp). Mudlet does NOT
+     * center on the bounding-box midpoint (which can land on empty space for
+     * sparse / L-shaped areas) — it:
+     *   1. picks a z-level: `preferredZ` if the area has rooms there, otherwise
+     *      the level carrying the most rooms (lowest z wins ties),
+     *   2. takes the geometric centroid (mean x/y) of that level's rooms,
+     *   3. returns the room nearest that centroid.
+     * So the view always lands on an actual room. null when the area has no
+     * rooms (Mudlet falls back to 0,0,0 in that case).
+     */
+    getAreaCenterRoomId(areaId: number, preferredZ?: number): number | null;
+    /**
+     * Mudlet `getAreaExits(areaID[, fullData])` — exits crossing out of the area.
+     * Without full data, a sorted list of the area's rooms that have any exit to
+     * another area. With full data, `{ [fromRoomID] = { [exitName] = toRoomID } }`,
+     * where `exitName` is the long direction name for stock exits or the verbatim
+     * command for special exits. Returns `undefined` when the area is unknown.
+     */
+    getAreaExits(areaId: number, fullData?: boolean): number[] | Record<number, Record<string, number>> | undefined;
+    getRooms(): Record<number, string>;
+    /**
+     * Mudlet `getMapLabels(areaID)` — returns `{ [labelID] = labelText }` for
+     * every label in the area, or an empty object if the area has none / is
+     * unknown. Each `MudletLabel.id` is the QMap key Mudlet uses internally,
+     * which is also what `deleteMapLabel` expects.
+     */
+    getMapLabels(areaId: number): Record<number, string>;
+    /**
+     * Mudlet `getMapLabel(areaID, labelID|labelText)`:
+     *  - by ID (number): single flat properties record, or "noid" sentinel if the
+     *    area has labels but not that ID
+     *  - by text (string): `{[labelID]: properties}` for every label whose text
+     *    matches exactly (possibly empty)
+     *  - if the area has no labels at all: empty `multi: {}` regardless of key form
+     *    (matches Mudlet's early-return)
+     *  - if the area is missing: "noarea" sentinel
+     *
+     * Bridge.lua dispatches the sentinels into Mudlet's `(false, errMsg)` shape.
+     */
+    getMapLabel(areaId: number, key: number | string): MapLabelLookup;
+    /** Next free label id within an area — Mudlet keys labels by an integer that
+     *  is unique per area and starts at 0. */
+    private nextLabelId;
+    /**
+     * Mudlet `createMapLabel(areaID, text, posx, posy, posz, fgRed, fgGreen,
+     * fgBlue, bgRed, bgGreen, bgBlue [, zoom [, fontSize [, showOnTop [,
+     * noScaling]]]])`. Adds a text label to the area and returns its new id, or
+     * -1 if the area does not exist. (`zoom`/`fontSize` are accepted for
+     * signature parity — mudix stores labels but the renderer does not yet draw
+     * them, mirroring how labels loaded from binary maps are kept and queried
+     * but not painted.)
+     */
+    createMapLabel(areaId: number, text: string, x: number, y: number, z: number, fgR: number, fgG: number, fgB: number, bgR: number, bgG: number, bgB: number, fontSize?: number, showOnTop?: boolean, noScaling?: boolean): number;
+    /**
+     * Mudlet `createMapImageLabel(areaID, imagePathFileName, posx, posy, posz,
+     * width, height, zoom [, showOnTop [, noScaling]])`. Adds an image label and
+     * returns its new id, or -1 if the area is missing. The image reference is
+     * stored verbatim in the label's `pixMap` (surfaced as `Pixmap` by
+     * getMapLabel); like text labels it is not yet painted by the renderer.
+     */
+    createMapImageLabel(areaId: number, imagePath: string, x: number, y: number, z: number, width: number, height: number, showOnTop?: boolean, noScaling?: boolean): number;
+    /** Mudlet `deleteMapLabel(areaID, labelID)`. Removes the label; returns
+     *  false when the area or label id does not exist. */
+    deleteMapLabel(areaId: number, labelId: number): boolean;
+    /**
+     * Mudlet `auditAreas()` — sweep the map for area/room consistency problems
+     * and repair what is safe to repair. mudix rebuilds every area's membership
+     * list (`rooms[]`) from the authoritative `room.area` back-pointers, which
+     * drops dangling room ids and re-files rooms that were missing from their
+     * area's list. Rooms whose `area` points at a non-existent area are reported
+     * but left untouched (they may be intentionally parked in the void area -1).
+     * Returns a summary report (Mudlet returns nothing; mudix surfaces the audit
+     * so scripts can act on it).
+     */
+    auditAreas(): {
+        checkedAreas: number;
+        checkedRooms: number;
+        fixedAreas: number;
+        orphanRooms: number[];
+        danglingRefs: number[];
+    };
+    setMapEventDispatcher(fn: ((eventName: string, args: unknown[]) => void) | null): void;
+    addMapEvent(uniqueName: string, eventName: string, parent?: string | null, displayName?: string | null, ...args: unknown[]): boolean;
+    removeMapEvent(uniqueName: string): boolean;
+    getMapEvents(): MapEventEntry[];
+    /** Mudlet `addMapMenu(menuName [, parent [, displayName]])`. Registers a
+     *  submenu in the map's right-click context menu that addMapEvent entries
+     *  can nest under via their `parent`. Re-registering the same name replaces
+     *  the prior entry. */
+    addMapMenu(name: string, parent?: string | null, displayName?: string | null): boolean;
+    removeMapMenu(name: string): boolean;
+    getMapMenus(): MapMenuEntry[];
+    private roomBorderColors;
+    private roomBorderThicknesses;
+    setRoomBorderColor(id: number, r: number, g: number, b: number, a: number): boolean;
+    getRoomBorderColor(id: number): {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    } | null;
+    clearRoomBorderColor(id: number): boolean;
+    setRoomBorderThickness(id: number, thickness: number): boolean;
+    getRoomBorderThickness(id: number): number | null;
+    clearRoomBorderThickness(id: number): boolean;
+    /** Fire the registered event for a context-menu entry. Matches Mudlet's
+     *  T2DMap::slot_userAction selection branch: raiseEvent(eventName,
+     *  uniqueName, roomId). The right-clicked room stands in for Mudlet's
+     *  multi-room selection; the entry's stored extra args are discarded
+     *  (Mudlet does the same in this branch). */
+    dispatchMapEvent(uniqueName: string, roomId: number): void;
+    setMapInfoEvaluator(fn: MapStore['mapInfoEvaluator']): void;
+    /** Add or replace a contributor. Re-registering the same label keeps the
+     *  current enabled state and returns the prior callbackId so the runtime
+     *  can free the leaked Lua-registry slot. Registering over a built-in label
+     *  ("Short"/"Full") overrides it with the script callback — Mudlet's
+     *  registerMapInfo replaces same-named contributors the same way; the native
+     *  evaluator is dropped so the script's version wins. */
+    registerMapInfo(label: string, callbackId: number): {
+        prevCallbackId: number | null;
+    };
+    /** Remove a contributor entirely. Returns the freed callbackId (so the
+     *  runtime can release the Lua-registry slot) or null when the label
+     *  wasn't registered. Built-in contributors can't be removed (Mudlet's
+     *  native "Short"/"Full" are likewise permanent — only enable/disable
+     *  applies); the call is a no-op reporting removed:false. */
+    killMapInfo(label: string): {
+        callbackId: number | null;
+        removed: boolean;
+    };
+    enableMapInfo(label: string): boolean;
+    disableMapInfo(label: string): boolean;
+    /** Snapshot for tests / debug. The panel goes through evaluateMapInfos. */
+    getMapInfoContributors(): MapInfoContributor[];
+    /** Run every enabled contributor and collect their (text, style, color)
+     *  results. Built-in contributors are evaluated natively from MapStore data;
+     *  script ones go through the LuaRuntime evaluator (skipped when it's
+     *  unhooked). Empty when no enabled contributor returned a non-empty text. */
+    evaluateMapInfos(roomId: number | null, selectionSize: number, areaId: number, displayedAreaId: number): MapInfoResult[];
+    /** Drop every script-registered contributor. Called on LuaRuntime teardown
+     *  — the callback IDs index into the dying runtime's __mudix_cb registry.
+     *  Built-in contributors are native (no Lua dependency) so they survive,
+     *  keeping the default "Short"/"Full" overlays available across reconnects
+     *  and script reloads. */
+    clearMapInfoContributors(): void;
+    /** Seed the two built-in contributors. Mudlet registers "Short" then "Full"
+     *  and enables "Full" by default (XMLimport seeds {"Full"} for a profile
+     *  with no saved set); we mirror both the order and the default. */
+    private seedBuiltinMapInfo;
+    /** Mudlet's "Short" contributor: `<room name> / <id> (<area name>)`,
+     *  collapsing to just `<id> (<area name>)` when the room is unnamed or its
+     *  name is exactly its id. Plain (no bold/italic), default colour. */
+    private shortMapInfo;
+    /** Mudlet's "Full" contributor: area name/id + extent, optional room name,
+     *  and the room id + position line whose suffix and styling depend on the
+     *  selection (none → "Current player location"; 1 → "Selected room";
+     *  many → "Center of N selected rooms"). Non-breaking spaces (U+00A0) and
+     *  hyphens (U+2011) match Mudlet so the lines wrap the same way. Selections
+     *  tint the block orange and bold it; with nothing selected the text is
+     *  italic when the room's area isn't the one currently displayed, else bold.
+     *  Mudlet keys the orange shade off the configured info-text lightness — we
+     *  don't surface that, so we use its dark-background variant. */
+    private fullMapInfo;
+    /** Mudlet setCustomEnvColor(envID, r, g, b, a). envID identifies the user
+     *  environment used by setRoomEnv; the renderer reads mCustomEnvColors and
+     *  paints rooms with that env using these RGB values. spec=1 (RGB) is the
+     *  Qt QColor::Rgb spec, matching what the binary reader emits. */
+    setCustomEnvColor(envId: number, r: number, g: number, b: number, a?: number): void;
+    /**
+     * Seed env IDs 257-272 with the profile's 16 mapper colours, mirroring
+     * TMap::restore16ColorSet. Mudlet keeps that block permanently present in
+     * mCustomEnvColors — `setCustomEnvColor(257, …)` is documented as *also*
+     * changing the profile's dark-red, and `getCustomEnvColorTable()[257]`
+     * reads back even on a brand-new map — so it is re-applied whenever the
+     * map is wiped rather than treated as user data.
+     */
+    private restore16ColorSet;
+    getCustomEnvColor(envId: number): {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    } | undefined;
+    getCustomEnvColorTable(): Record<number, {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    }>;
+    /** Mudlet removeCustomEnvColor(envID). Drops the override so the renderer
+     *  falls back to the built-in env palette. Returns true if an entry was
+     *  removed. */
+    removeCustomEnvColor(envId: number): boolean;
+    private mapMode;
+    private mapModeListener;
+    setMapModeListener(fn: ((mode: 'viewing' | 'editing') => void) | null): void;
+    getMapMode(): 'viewing' | 'editing';
+    setMapMode(mode: 'viewing' | 'editing'): boolean;
+    private roomCharColors;
+    private hiddenRooms;
+    private hiddenVersion;
+    setRoomCharColor(id: number, r: number, g: number, b: number, a?: number): boolean;
+    getRoomCharColor(id: number): {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    } | undefined;
+    /**
+     * Mudlet `unsetRoomCharColor(roomID)` — drop the per-room char colour
+     * override so the renderer falls back to the default text colour. Returns
+     * false when the room is missing or had no override to drop (Mudlet's
+     * own semantics).
+     */
+    unsetRoomCharColor(id: number): boolean;
+    /**
+     * Mudlet `setRoomHidden(roomID, hidden)`. Toggles the hidden flag; the
+     * RoomLens installed on the renderer consults {@link isRoomHidden} when
+     * deciding whether to paint a room, so hidden rooms (and exits whose
+     * other endpoint is hidden) disappear from the view. Returns false when
+     * the room doesn't exist; no-ops without a notify when the state is
+     * already the requested one.
+     */
+    setRoomHidden(id: number, hidden: boolean): boolean;
+    /**
+     * Mudlet `getRoomHidden(roomID)`. Returns the hidden flag (false by
+     * default). The Lua binding re-shapes the missing-room case into
+     * Mudlet's (false, errMsg) tuple.
+     */
+    getRoomHidden(id: number): boolean;
+    /** True iff the room exists in the side-table. Used by the RoomLens. */
+    isRoomHidden(id: number): boolean;
+    /** Monotonic counter bumped only when the hidden-rooms set actually
+     *  changes. Surfaced via the RoomLens's getVersion() so the renderer can
+     *  cache lens output, and read by MapPanel to decide when a force-refresh
+     *  is needed after store mutations that left area/level unchanged. */
+    getHiddenVersion(): number;
+    /**
+     * Mudlet `getHiddenRooms()` — the hidden rooms of the whole map. Mudlet
+     * takes no argument at all (TLuaInterpreter::getHiddenRooms walks the
+     * entire room map); mudix additionally accepts an areaID to scope the
+     * answer, in which case `undefined` distinguishes "no such area" from "no
+     * hidden rooms here".
+     */
+    getHiddenRooms(areaId?: number): number[] | undefined;
+    /**
+     * Mudlet highlightRoom(roomID, r1, g1, b1, r2, g2, b2, radius, a1, a2).
+     * Painted by MudletHighlightOverlay as a radial gradient: color1 (with
+     * a1 alpha) at the center, color2 (with a2 alpha) at the outer edge,
+     * with the circle radius = settings.roomSize × `radius`. Returns false
+     * if the room does not exist.
+     */
+    highlightRoom(id: number, r1: number, g1: number, b1: number, r2: number, g2: number, b2: number, radius: number, a1?: number, a2?: number): boolean;
+    /** Mudlet unHighlightRoom(roomID). Returns false when the room had no highlight. */
+    unHighlightRoom(id: number): boolean;
+    /** Snapshot of all active room highlights. MapPanel reads this each store
+     *  notify to reconcile the renderer's overlay shapes against the store. */
+    getRoomHighlights(): Map<number, RoomHighlight>;
+    /** Monotonic counter bumped on every selection mutation. The
+     *  MapSelectionOverlay reads this through its lens-style version channel so
+     *  the renderer's overlay-output cache invalidates only when the set
+     *  actually changes. */
+    getSelectionVersion(): number;
+    /** True when the room is in the current selection — read by
+     *  MapSelectionOverlay when emitting per-room shapes. */
+    isRoomSelected(id: number): boolean;
+    /** The most recently single-clicked room (Mudlet's selection "center"), or
+     *  null when nothing is selected. Used by MapSelectionOverlay to draw a
+     *  distinct marker on the center. */
+    getSelectionCenter(): number | null;
+    /** Size of the current selection — fed to registerMapInfo callbacks as
+     *  Mudlet's `selectionSize` argument. */
+    getMapSelectionSize(): number;
+    /**
+     * Mudlet `getMapSelection()` → `{ rooms = {roomIDs}, center = roomID }`.
+     * `rooms` is a list of selected room ids (sorted for deterministic
+     * Lua-side iteration); `center` is the room marked as the selection's
+     * focal point (Mudlet uses the last-clicked / right-clicked room). Both
+     * are empty / null when nothing is selected.
+     */
+    getMapSelection(): {
+        rooms: number[];
+        center: number | null;
+    };
+    /**
+     * Replace the selection with a single room and mark it as the center.
+     * Mudlet's plain left-click on a room does the same. Returns false when
+     * the room doesn't exist (silently — the caller is usually a UI handler).
+     */
+    selectMapRoom(id: number): boolean;
+    /**
+     * Toggle a room in/out of the selection (Mudlet ctrl-click). Adding a
+     * room makes it the new center; removing the current center promotes the
+     * lowest remaining id as the new center (and nulls the center when the
+     * selection ends up empty).
+     */
+    toggleMapRoomSelection(id: number): boolean;
+    /**
+     * Mudlet `clearMapSelection()` — wipe the selection set and the center.
+     * Returns true when something was cleared, false when the selection was
+     * already empty (so callers don't spin on a no-op notify).
+     */
+    clearMapSelection(): boolean;
+    private updateAreaBounds;
+}