@mudlet/mudlet-web 0.4.5 → 1.0.0

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

@@ -1,9 +1,21 @@
-import type { MudletArea, MudletFont, MudletMap, MudletMapHeader, MudletRoom } from 'mudlet-map-binary-reader';
+import type { MudletArea, MudletColor, MudletFont, MudletLabel, MudletMap, MudletMapHeader, MudletRoom } from 'mudlet-map-binary-reader';
 import { readerExport } from 'mudlet-map-binary-reader';
 import { type ExitWeightFilter, type PathfindResult } from './pathfinding';
+import { type EnvironmentKit } from './environmentKit';
+import { type AreaGraphLink, type AreaGraphNode } from './areaGraph';
 export type { ExitWeightFilter, PathfindResult } from './pathfinding';
 export type MapRendererData = ReturnType<typeof readerExport>;
+/** What an area with no name of its own is called — Mudlet's mUnnamedAreaName,
+ *  which its area-name audit substitutes before checking for duplicates. */
+export declare const UNNAMED_AREA_NAME = "Unnamed Area";
+/** Mudlet's mDefaultAreaName — the name of area -1. */
+export declare const DEFAULT_AREA_NAME = "Default Area";
+/** A stock direction code (1-12) from a number or a direction name. A number
+ *  is read the way desktop's lua_tointeger reads it, truncating toward zero,
+ *  so `4.5` is east (4) — the same rule room ids and coordinates follow. */
 export declare function parseDirection(dir: unknown): number | undefined;
+export declare const BORDER_COLOR_KEY = "room.ui_borderColor";
+export declare const BORDER_THICKNESS_KEY = "room.ui_borderThickness";
 export declare const DEFAULT_FONT: MudletFont;
 export declare function makeRoom(areaId: number): MudletRoom;
 /**
@@ -21,13 +33,59 @@ export declare function makeRoom(areaId: number): MudletRoom;
  * 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.
+ * Room borders and symbol colours have nowhere to live in the binary model, so
+ * applyJsonRoomBorders and applyJsonSymbolColors put them on the store once
+ * the rooms exist.
  */
-export declare function mudletJsonMapToMudletMap(src: unknown): MudletMap | null;
+export declare function mudletJsonMapToMudletMap(src: unknown, droppedRoomWarnings?: string[]): MudletMap | null;
 export declare function makeArea(): MudletArea;
+/**
+ * A map label as Mudlet Web stores it: the binary-map reader's shape plus the fields
+ * Mudlet's `TMapLabel` carries that the label record in its map file does not —
+ * the font and outline colour (which a v20 file keeps in the area's user data,
+ * see restoreLabelFallbacks / labelFallbackEntries) and the `temporary` flag
+ * (never saved). All optional, so a label read back without them stays valid.
+ */
+export interface MapLabel extends MudletLabel {
+    fontName?: string;
+    fontSize?: number;
+    /** QFont weight and italic flag, carried only so a label read from a
+     *  desktop file writes its `system.labelFont_N` back unchanged. */
+    fontWeight?: number;
+    fontItalic?: boolean;
+    temporary?: boolean;
+    outlineColor?: MudletColor;
+}
+/**
+ * The optional tail of Mudlet's `createMapLabel` — everything after the two
+ * colours. Defaults here are Mudlet's own (TLuaInterpreter::createMapLabel),
+ * not zero values: omitting them has to produce the label Mudlet would.
+ */
+export interface MapLabelOptions {
+    /** Map units per rendered pixel; divides the measured text box. Default 30. */
+    zoom?: number;
+    /** Point size the text is measured at. Default 50. */
+    fontSize?: number;
+    /** Paint above rooms rather than below them. Default true. */
+    showOnTop?: boolean;
+    /** Keep a fixed on-screen size instead of scaling with the map. Default true. */
+    noScaling?: boolean;
+    /** Font family; empty/absent means the default face. */
+    fontName?: string;
+    /** Foreground (and outline) alpha, 0-255. Default 255. */
+    fgAlpha?: number;
+    /** Background alpha, 0-255. Default 50 — Mudlet's labels are mostly see-through. */
+    bgAlpha?: number;
+    /** Excluded from the map save. Default false. */
+    temporary?: boolean;
+    /** Text outline colour. Defaults to the foreground colour, which is Mudlet's
+     *  way of saying "no outline" — it only draws one when the two differ. */
+    outline?: {
+        r: number;
+        g: number;
+        b: number;
+    };
+}
 export interface MapLabelInfo {
     X: number;
     Y: number;
@@ -94,7 +152,7 @@ export interface MapInfoResult {
 /** 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
+ *  into the Lua-side `__mudlet_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 —
@@ -116,7 +174,7 @@ export interface MapEventEntry {
     /** 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
+     *  (the one Mudlet Web mirrors, since the right-clicked room is treated as the
      *  selection) discards these — kept for parity with the registration API. */
     args: unknown[];
 }
@@ -129,6 +187,25 @@ export interface MapMenuEntry {
     /** Label rendered for the submenu. Defaults to name when unspecified. */
     displayName: string;
 }
+/**
+ * One thing wrong with the map, as {@link MapStore.auditExits} found it.
+ *
+ * Desktop's counterpart is a formatted line appended to three lists keyed by
+ * scope (whole map / area / room, `TMap::appendRoomErrorMsg` and friends); the
+ * scope is a field here so a caller can group, filter or link to the room
+ * rather than only print. `severity` matches the `[ WARN ]` / `[ INFO ]`
+ * prefixes Mudlet writes, which its console colours off.
+ */
+export interface MapIssue {
+    /** `warn` for something broken, `info` for something merely surplus. */
+    severity: 'warn' | 'info';
+    /** The room the issue is about, when it is about one. */
+    roomId?: number;
+    /** The area the issue is about, when it is about one. */
+    areaId?: number;
+    /** The sentence to show, without the `[ WARN ]  - ` prefix. */
+    message: string;
+}
 export declare class MapStore {
     private rooms;
     private areas;
@@ -138,10 +215,34 @@ export declare class MapStore {
     private envColors;
     private nextRoomId;
     private nextAreaId;
+    /** Where TRoomDB::createNewAreaID starts looking: just past the last id it
+     *  handed out, so a deleted area's number is not handed straight back. */
+    private areaIdHint;
     /** Installed by `setExitWeightFilter`; consulted per exit in findPath. */
     private exitWeightFilter;
+    /** TMap::mScriptCallbackDepth — how many script callbacks the map is
+     *  inside (the exit weight filter, a map info contributor). Desktop holds
+     *  raw room and area pointers across both, so rooms and areas may not be
+     *  deleted, nor the map replaced, while it is above zero; Mudlet Web keeps
+     *  the same rule so a script behaves the same on both. */
+    private scriptCallbackDepth;
+    /** TMap::mGraphBuildInProgress — the exit weight filter is being asked
+     *  about the map's exits, and a search started from inside it is refused. */
+    private graphBuilding;
     private pendingBinaryHashIndex;
     private pendingBinaryHadSelection;
+    /** Whether the load in flight lifts the v20 `system.*` fallback keys out
+     *  of user data. True for a binary file (and the binary-model JSON that
+     *  toJsonString writes); false while reading Mudlet's own JSON format,
+     *  whose reader leaves user data exactly as the file has it. */
+    private liftFileFallbacks;
+    /** TArea::mLast2DMapZoom — keyed by the area object so it follows an area
+     *  the audit renumbers and goes when the area does. Absent means "never
+     *  set", which reads back as the default zoom. */
+    private areaZooms;
+    /** What the last import's audit found and repaired, for whoever loaded the
+     *  map to report. Read through {@link takeAuditIssues}. */
+    private lastAuditIssues;
     private version;
     private subscribers;
     private notifyPending;
@@ -175,7 +276,7 @@ export declare class MapStore {
     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. */
+     *  uses this so it re-renders without forcing a full MudletMapReader rebuild. */
     subscribeHighlights(cb: () => void): () => void;
     /** Subscribe to selection changes (selectMapRoom / toggleMapRoomSelection /
      *  clearMapSelection and the bulk clears in newEmptyMap / loadFromBinary).
@@ -201,7 +302,7 @@ export declare class MapStore {
      * ids so subsequent {@link createRoomID} / {@link addAreaName} calls don't
      * collide. One notification fires at the end of the batch.
      */
-    loadFromBinary(mudletMap: MudletMap): void;
+    loadFromBinary(mudletMap: MudletMap, audit?: boolean): void;
     /**
      * Header phase of a streamed binary load — everything in a Mudlet map
      * except the rooms (see `MudletMapReader.streamRooms`). Wipes the store and
@@ -226,7 +327,7 @@ export declare class MapStore {
      * resolve the player room, and fire the single notification the whole load
      * is worth.
      */
-    endBinaryLoad(): void;
+    endBinaryLoad(audit?: boolean): 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
@@ -251,12 +352,54 @@ export declare class MapStore {
      */
     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.
+     * The map in Mudlet's OWN `saveJsonMap` schema — the exact shape
+     * {@link mudletJsonMapToMudletMap} reads, and the mirror of it field for
+     * field.
+     *
+     * Not the same thing as {@link toJsonString}, which writes the binary
+     * model. That was what saveJsonMap used to emit, and it round-tripped
+     * through this client perfectly while being unreadable to Mudlet and to
+     * anything reading the file itself — which the corpus does, and which is
+     * the point of a documented interchange format. A map exported here has to
+     * open in Mudlet, and one exported by Mudlet has to open here.
+     */
+    toMudletJsonString(extras?: Record<string, unknown>): string;
+    /**
+     * An area's labels in Mudlet's JSON schema (TArea::writeJsonLabels).
+     *
+     * A TEMPORARY label is left out: it belongs to the session that drew it, not
+     * to the map, and writing it would resurrect it on every later load.
+     */
+    private labelsToJson;
+    /** One room in Mudlet's JSON schema. Fields it has no value for are left
+     *  out rather than written empty, which is what Mudlet does and what keeps
+     *  a hand-read export legible. */
+    private roomToJson;
+    /** One exit in Mudlet's JSON schema. `key` is what the door and weight
+     *  tables are keyed on — the SHORT name for a stock direction, the verbatim
+     *  command for a special exit. */
+    private exitToJson;
+    /**
+     * Save-side variant of {@link toMudletMap}: writes what TMap::serialize
+     * puts into user data for a v20 file, for the fields the format has no
+     * slot for, so the file round-trips back through `loadFromBinary` and
+     * through desktop Mudlet:
+     *
+     * - room `system.fallback_hidden` for rooms in the hidden side-table;
+     * - room `system.fallback_symbol_color` (`QColor::name()`) for a room with
+     *   a symbol colour;
+     * - room `room.ui_borderColor` (`name(HexArgb)`) / `room.ui_borderThickness`
+     *   from the border side-tables — set when there is one, removed when not;
+     * - area `system.fallback_map2DZoom` for every area (the default zoom when
+     *   none was ever set — TArea always has one);
+     * - area `system.labelFont_N` / `system.labelOutlineColor_N` for each
+     *   permanent label.
+     *
+     * Temporary labels are left out, as TMap::serialize leaves them out.
+     * Nothing in the store is mutated: desktop leaves these keys behind in its
+     * in-memory user data after a save, which is not worth copying. Render paths
+     * still call the plain {@link toMudletMap} — none of this is any use to the
+     * renderer.
      */
     toMudletMapForSave(): MudletMap;
     /**
@@ -266,6 +409,59 @@ export declare class MapStore {
      * expected MudletMap shape (no `rooms` / `areas` records).
      */
     loadFromJsonString(json: string): boolean;
+    /** What the last repairing audit found, cleared as it is read — a report is
+     *  owed to the load that caused it, and to no later one. */
+    takeAuditIssues(): MapIssue[];
+    /**
+     * Mudlet's `TMap::audit` — what runs after every map load, and what the
+     * Lua `auditAreas()` asks for: `TRoomDB::auditRooms` followed by
+     * `TRoom::audit` for every room.
+     *
+     * A map file is a document, and a document can say things the mapper API
+     * never could: a room or an area numbered below one, a room filed under an
+     * area that does not exist, an area listing rooms that are elsewhere, an
+     * exit to a room the file does not contain, a door on a direction with no
+     * way out. Every one of them is repaired the way Mudlet repairs it, and what
+     * was done is written into the room's (or area's) user data under the same
+     * `audit.*` keys, so a map that quietly changed shape can still be explained
+     * afterwards. The report is kept for {@link takeAuditIssues}.
+     */
+    auditMap(): MapIssue[];
+    /** Mudlet's mUnnamedAreaName, numbered "_001", "_002"… when it is taken. */
+    private freeUnnamedAreaName;
+    /**
+     * Mudlet's `TRoom::auditExits`, run over every room — the exit half of the
+     * audit alone, with no renumbering, plus a report on area membership.
+     *
+     * Without `repair` nothing is touched and only the report is made; with it,
+     * each room is repaired exactly as {@link auditMap} repairs it.
+     */
+    auditExits(repair?: boolean): MapIssue[];
+    /**
+     * One room's `TRoom::auditExits`. Each normal exit is checked in turn — an
+     * exit to a renumbered room follows it, one to a room that is not there
+     * becomes a stub, one to an id that can never exist becomes a stub too and
+     * sheds what a stub cannot carry — then each special exit, and finally
+     * whatever doors, weights, locks and custom lines are left keyed to no exit
+     * at all are dropped.
+     *
+     * The order matters: an exit that loses its destination BECOMES a stub, and
+     * only then can stub-versus-exit be judged — otherwise the stub just
+     * created would be dropped again by the very exit it replaced.
+     */
+    private auditRoomExits;
+    /**
+     * The area half of the report: a room filed under an area that is not
+     * there, and an area whose room list names a room that is not there. The
+     * repair is {@link auditMap}, which every load runs.
+     */
+    private auditAreaMembership;
+    /**
+     * Every profile's saved player room, ours stamped from the live
+     * playerRoomId so reopening the map restores the position (Mudlet's
+     * mRoomIdHash[mProfileName] round-trip), other profiles' preserved.
+     */
+    private playerRoomHash;
     toMudletMap(): MudletMap;
     /**
      * Mudlet `createRoomID([minimum])` — returns the smallest unused room id
@@ -287,12 +483,40 @@ export declare class MapStore {
         err: string;
     };
     deleteRoom(id: number): boolean;
+    /**
+     * Clear every exit — stock and special — that pointed at a room in `gone`.
+     *
+     * A deleted room does not take its entrances with it: the exits live on the
+     * rooms that lead INTO it, so removing the room alone leaves them pointing
+     * at a number that no longer resolves. Mudlet walks its entrance map for
+     * exactly this (TRoomDB::__removeRoom, then TRoom::removeAllSpecialExitsToRoom
+     * for the named ones), and Mudlet Web left them dangling: getRoomExits went on
+     * reporting a north exit to a room that had been deleted, and the mapper
+     * would happily route a player through it.
+     *
+     * There is no entrance index here, so this is a scan of the remaining rooms.
+     * Deletions are rare and the map is in memory; an index would have to be
+     * kept correct through every exit write to save a walk nobody waits on.
+     */
+    private severExitsTo;
+    /**
+     * TRoomDB::removeRoom resets the player's room to 0 when it removes the
+     * room the player is in (deleteArea goes through it room by room). Keeping
+     * the old id instead put the player silently back "in" whatever unrelated
+     * room was later created with that number (mudlet-web#343).
+     */
+    private forgetPlayerRoomIn;
     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;
+    /** The player room as stored — Mudlet's `mRoomIdHash` entry, which is what
+     *  the Lua getPlayerRoom()/gotoRoom read. Unlike {@link getPlayerRoom} it is
+     *  not checked against the map: after the player's room is deleted it is 0,
+     *  as on desktop, rather than unset. null only when it was never set. */
+    getPlayerRoomId(): 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`
@@ -350,6 +574,22 @@ export declare class MapStore {
     getRoomEnv(id: number): number;
     setRoomEnv(id: number, env: number): boolean;
     getRoomChar(id: number): string;
+    /** Every distinct room symbol on the map — what a font has to be able to
+     *  draw before it is worth choosing. */
+    roomSymbols(): string[];
+    /**
+     * Mudlet's "Show symbol usage…" report (`TMap::roomSymbolsHash`, consumed by
+     * `dlgProfilePreferences::generateMapGlyphDisplay`): every distinct room
+     * symbol with the rooms that carry it, commonest first.
+     *
+     * The room ids come back in full and sorted; desktop's cap of thirty-two
+     * per symbol is a property of its table cell, not of the data, so it is
+     * applied where the table is drawn.
+     */
+    roomSymbolUsage(): {
+        symbol: string;
+        rooms: number[];
+    }[];
     setRoomChar(id: number, char: string): boolean;
     /**
      * Mudlet `lockRoom(roomID, lockIfTrue)` — mark a room as locked so
@@ -376,10 +616,17 @@ export declare class MapStore {
      */
     setRoomWeight(id: number, weight: number): boolean;
     /** Mudlet `getRoomsByPosition(areaID, x, y, z)` — undefined for an unknown
-     *  area, matching {@link getAreaRooms}. */
+     *  area, matching {@link getAreaRooms}. Ids come back ascending, as
+     *  desktop's TArea::getRoomsByPosition sorts them, not in the order the
+     *  rooms joined the area. */
     getRoomsByPosition(areaId: number, x: number, y: number, z: number): number[] | undefined;
     getRoomIDbyHash(hash: string): number | undefined;
-    setRoomIDbyHash(id: number, hash: string): void;
+    /**
+     * Mudlet `setRoomIDbyHash(roomID, hash)`: false for a room that does not
+     * exist (desktop refuses it, as it does the -1 or 0 a failed lookup gives).
+     * An empty hash clears the room's hash rather than binding "" to it.
+     */
+    setRoomIDbyHash(id: number, hash: string): boolean;
     getRoomHashByID(id: number): string | undefined;
     /** Mudlet `getRoomExits(roomID)` — `{ direction = toRoomID }`. Undefined
      *  for an unknown room (Mudlet pushes nothing at all in that case). */
@@ -403,6 +650,13 @@ export declare class MapStore {
     /** 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;
+    /** TMap::scriptCallbackInProgress — inside the exit weight filter or a map
+     *  info contributor, where rooms and areas may not be deleted nor the map
+     *  replaced (see {@link scriptCallbackDepth}). */
+    scriptCallbackInProgress(): boolean;
+    /** TMap::graphBuildInProgress — inside the exit weight filter, where no
+     *  path may be searched for. */
+    graphBuildInProgress(): boolean;
     /** 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}. */
@@ -432,13 +686,41 @@ export declare class MapStore {
     /** Mudlet `removeSpecialExit(exitRoomID, command)` — see {@link addSpecialExit}
      *  for the message/null return shape. */
     removeSpecialExit(from: number, cmd: string): string | null;
+    /**
+     * Drop everything keyed by a special exit's command once the exit itself is
+     * gone: its door, its lock, its weight, its custom line. Mudlet does this
+     * in every path that removes one (TRoom::setSpecialExit(-1, cmd) drops the
+     * custom line; removeAllSpecialExitsToRoom cleans up "related elements
+     * first"), and leaving them behind is not inert — the command name is the
+     * key, so re-adding the same exit later found a door, a lock and a line it
+     * never asked for, and the room stayed unwalkable for reasons nothing showed.
+     */
+    private clearSpecialExitAttributes;
+    /**
+     * The stock-exit twin of {@link clearSpecialExitAttributes}: an exit that
+     * is cleared (setExit to a room below one, or the room it led to deleted)
+     * takes its door, lock, weight and custom line with it, as TRoom::setExit
+     * and TRoomDB::__removeRoom do — otherwise an exit made there again starts
+     * out locked behind a door with a weight nothing shows.
+     */
+    private clearStockExitAttributes;
+    /**
+     * Mudlet's TRoom::hasExitOrSpecialExit(QString): whether `key` still names
+     * an exit of the room — a normal one by its short direction ("n", "up"…),
+     * or a special one by its command. A special exit named like a normal one
+     * shares that exit's weight, so removing the special exit must leave the
+     * weight while the normal exit is still there.
+     */
+    private hasExitOrSpecialExitNamed;
     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
+     * reported — among equally weighted ones the alphabetically LAST, since
+     * desktop walks them in QMap (key) order and keeps a later tie (`<=`); 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).
      */
@@ -502,6 +784,7 @@ export declare class MapStore {
     /**
      * Mudlet `getAllRoomEntrances(roomID)` — every room that has an exit (stock
      * or special) leading into this room, as a sorted, de-duplicated id list.
+     * A room with an exit back into itself lists itself, as on desktop.
      * Returns `undefined` when the room doesn't exist.
      */
     getAllRoomEntrances(id: number): number[] | undefined;
@@ -529,9 +812,8 @@ export declare class MapStore {
      * 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.
+     * table (empty when the room has no custom lines). Points are X/Y only, as
+     * Mudlet stores and reports them — a line lies on its owning room's Z.
      */
     getCustomLines(id: number): Record<string, {
         attributes: {
@@ -546,17 +828,17 @@ export declare class MapStore {
         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.
+     * canonical long name and the short name. Like desktop, every refusal — no
+     * such room, no exit in that direction, no line on it — is a message (the
+     * Lua side's `nil, errMsg`); null means the line was removed.
      */
-    removeCustomLine(id: number, dir: number | string): boolean;
+    removeCustomLine(id: number, dir: number | string): string | null;
     /**
      * Mudlet `addCustomLine(roomID, id_to, direction, style, color, arrow)`.
      * `target` is either a destination room id (line drawn to that room's
@@ -587,12 +869,18 @@ export declare class MapStore {
      * "up"/"down"/"in"/"out"), which is also what a saved map carries — or an
      * arbitrary special-exit command string, used as-is.
      *
+     * Only those twelve exact, lower-case spellings name a stock exit: desktop
+     * compares the command against them verbatim (TLuaInterpreter::setDoor),
+     * so "east", "E" or "4" are special-exit names and are refused unless the
+     * room has a special exit called that — they never touch the stock door.
+     *
      * 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}).
+     * false, so the failure is reported here as the message string. Otherwise
+     * the answer is TRoom::setDoor's: true when the door changed, false when it
+     * already had that status.
      */
-    setDoor(id: number, dir: number | string, val: number): string | null;
+    setDoor(id: number, cmd: string, val: number): string | boolean;
     /**
      * Mudlet `getRoomUserData(id, key)` — returns the stored value, or
      * `undefined` when either the room or the key is missing. The Lua binding
@@ -651,6 +939,22 @@ export declare class MapStore {
     clearMapUserDataItem(key: string): boolean;
     getAllMapUserData(): Record<string, string>;
     /** Replace the entire map-level user-data dict (e.g. after loading a .dat). */
+    /** The areas as a graph with a world layout — see map/areaGraph.ts. It
+     *  reads the map through this source, and keeps its layout in the map's
+     *  user data, so a map replaced under it is noticed on the next read. */
+    private readonly areaGraph;
+    private areaGraphRoom;
+    /** Mudlet getAreaGraph(): the areas, by id in ascending order, and the
+     *  links between them sorted by (from, to). */
+    getAreaGraph(): {
+        areas: AreaGraphNode[];
+        links: AreaGraphLink[];
+    };
+    /** Mudlet setAreaGraphPosition(areaID, x, y): pins the area there. False
+     *  for an area the graph does not have, or a coordinate out of range. */
+    setAreaGraphPosition(areaId: number, x: number, y: number): boolean;
+    /** Mudlet resetAreaGraphLayout([keepPinned]). */
+    resetAreaGraphLayout(keepPinned: boolean): void;
     loadMapUserData(data: Record<string, string> | undefined | null): void;
     /**
      * Mudlet `addAreaName(name)` returns a numeric area ID on success or
@@ -715,8 +1019,9 @@ export declare class MapStore {
      */
     searchAreaUserData(key?: string, value?: string): string[] | number[];
     /**
-     * Per-area 2D-map zoom stored in the map file (area userData under
-     * {@link AREA_ZOOM_KEY}), in Mudlet units. Returns `undefined` when the area
+     * Per-area 2D-map zoom (TArea::mLast2DMapZoom), in Mudlet units — written
+     * to the file under {@link AREA_ZOOM_KEY} and lifted back out of the area's
+     * user data on load, so scripts never see the key. Returns `undefined` when the area
      * is missing or has no usable saved zoom, in which case the caller opens at
      * {@link DEFAULT_MAP_ZOOM}. Mirrors Mudlet's treatment of zoom as map data
      * rather than client config.
@@ -728,8 +1033,8 @@ export declare class MapStore {
      */
     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
+     * Set the per-area zoom; it round-trips with the map file (see
+     * {@link getAreaZoom}). 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
@@ -798,6 +1103,14 @@ export declare class MapStore {
      */
     getAreaExits(areaId: number, fullData?: boolean): number[] | Record<number, Record<string, number>> | undefined;
     getRooms(): Record<number, string>;
+    /**
+     * Every room's id and name in the order the room map is walked — the order
+     * {@link getHiddenRooms} lists them in too. `getRooms()` builds its Lua
+     * table in this order rather than from an object, whose integer keys come
+     * back sorted: what `#` makes of a table with holes depends on the order
+     * its keys went in.
+     */
+    getRoomNamesInOrder(): Array<[number, string]>;
     /**
      * Mudlet `getMapLabels(areaID)` — returns `{ [labelID] = labelText }` for
      * every label in the area, or an empty object if the area has none / is
@@ -818,39 +1131,53 @@ export declare class MapStore {
      * 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. */
+    /** Lowest free label id within an area — Mudlet keys labels by an integer
+     *  that is unique per area, and TArea::createLabelId counts up from 0 to the
+     *  first one not taken, so a deleted label's id is handed out again. */
     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.)
+     * noScaling [, fontName [, foregroundTransparency [, backgroundTransparency
+     * [, temporary [, outlineRed, outlineGreen, outlineBlue]]]]]]]]])`. Adds a
+     * text label to the area and returns its new id, or -1 if the area does not
+     * exist or the text is empty (both are Mudlet's own refusals).
+     *
+     * `fontName`, `temporary` and the outline colour are extra fields on the
+     * stored label (see `MapLabel`); of the three only `temporary` is visible
+     * from Lua, because Mudlet's getMapLabel doesn't publish the other two
+     * either. The label's image is rendered here, as desktop renders it, so a
+     * saved map carries it (see renderLabelPixmap).
      */
-    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;
+    createMapLabel(areaId: number, text: string, x: number, y: number, z: number, fgR: number, fgG: number, fgB: number, bgR: number, bgG: number, bgB: number, opts?: MapLabelOptions): 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;
+     * width, height, zoom, showOnTop [, temporary])`. Adds an image label and
+     * returns its new id, or -1 if the area is missing. `pixmap` is the image
+     * itself as a base64 PNG — desktop reads the file at creation and keeps only
+     * the picture, so getMapLabel's `Pixmap`, the map file and saveJsonMap all
+     * carry image data, never the path (the Lua binding reads the file). Like
+     * TMap::createMapImageLabel, the colours are TMapLabel's untouched opaque
+     * black and the label always scales with the map.
+     */
+    createMapImageLabel(areaId: number, pixmap: string, x: number, y: number, z: number, width: number, height: number, showOnTop?: boolean, temporary?: boolean): number;
+    /**
+     * Replace a label's pixmap, but only while it still holds `expected` — the
+     * swap an image label's asynchronously drawn pixmap makes, which must not
+     * land on a label deleted, recreated or reloaded in the meantime. Returns
+     * whether it replaced anything.
+     */
+    replaceLabelPixmap(areaId: number, labelId: number, expected: string, pixmap: string): boolean;
     /** 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).
+     * Mudlet `auditAreas()` — which is `TMap::audit`, the same audit every map
+     * load runs (see {@link auditMap}): room and area ids below one renumbered,
+     * areas the rooms or the area names call for created, every area's room
+     * list rebuilt from the rooms' own `area`, and every room's exits checked.
+     * Mudlet returns nothing; Mudlet Web also returns a summary of what the area
+     * half found, taken before the repair, so a script can act on it.
      */
     auditAreas(): {
         checkedAreas: number;
@@ -863,11 +1190,24 @@ export declare class MapStore {
     addMapEvent(uniqueName: string, eventName: string, parent?: string | null, displayName?: string | null, ...args: unknown[]): boolean;
     removeMapEvent(uniqueName: string): boolean;
     getMapEvents(): MapEventEntry[];
+    /** The built-in context-menu items hideMapMenuItem() takes, by desktop's
+     *  names (TMap::builtInMenuItemNames). They are API, so never rename one —
+     *  most have no counterpart in this client's menu, but scripts still pass
+     *  them, and desktop accepts every one. */
+    static readonly BUILTIN_MENU_ITEMS: readonly string[];
+    private hiddenMenuItems;
+    /** Hide (or show again) a built-in item. False for a name that is not one. */
+    setMenuItemHidden(name: string, hidden: boolean): boolean;
+    menuItemShown(name: string): boolean;
+    /** The hidden items, sorted as desktop lists them. */
+    getHiddenMenuItems(): string[];
     /** 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;
+    /** True when anything went: the menu itself, or a submenu or event filed
+     *  under it (desktop sweeps those even for a parent never added). */
     removeMapMenu(name: string): boolean;
     getMapMenus(): MapMenuEntry[];
     private roomBorderColors;
@@ -928,7 +1268,7 @@ export declare class MapStore {
      *  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.
+     *  — the callback IDs index into the dying runtime's __mudlet_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. */
@@ -956,6 +1296,16 @@ export declare class MapStore {
      *  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;
+    /**
+     * The sixteen mapper colours as the profile holds them, outliving any map
+     * loaded into this store.
+     *
+     * They outlive the SESSION in Mudlet, being profile data; here they do not
+     * yet — nothing writes them to the profile bag, so reopening a profile
+     * brings back the Qt defaults. Closing that needs a settings field of its
+     * own, which is a change to the stored schema rather than to the map.
+     */
+    private readonly profileEnvColors;
     /**
      * Seed env IDs 257-272 with the profile's 16 mapper colours, mirroring
      * TMap::restore16ColorSet. Mudlet keeps that block permanently present in
@@ -981,12 +1331,31 @@ export declare class MapStore {
      *  falls back to the built-in env palette. Returns true if an entry was
      *  removed. */
     removeCustomEnvColor(envId: number): boolean;
+    /**
+     * The colour desktop draws an environment's rooms in
+     * (RoomAppearance::environmentColor): mEnvColors remaps the id first; 1-16
+     * are the profile's sixteen mapper colours; a custom colour wins over the
+     * xterm cube and grey ramp for 17-255; and anything left — an environment
+     * the map does not define, or one remapped onto nothing — is dark red, the
+     * colour of environment 1, so that no room is drawn invisible.
+     */
+    environmentColor(environmentId: number): [number, number, number];
+    /** Mudlet getMapEnvironmentKit(envID) → the kit, and whether the map names
+     *  it rather than it being guessed from the environment's colour — which is
+     *  read afresh each time, so the guess follows the colour. */
+    getEnvironmentKit(environmentId: number): [EnvironmentKit, boolean];
+    /** Mudlet getMapEnvironmentKits() → the kits the map names, by environment. */
+    getEnvironmentKits(): Map<number, EnvironmentKit>;
+    /** Mudlet setMapEnvironmentKit(envID, kit) — null clears. False when the
+     *  saved kits are not a JSON object, which is then left alone. */
+    setEnvironmentKit(environmentId: number, kit: EnvironmentKit | null): boolean;
     private mapMode;
     private mapModeListener;
     setMapModeListener(fn: ((mode: 'viewing' | 'editing') => void) | null): void;
     getMapMode(): 'viewing' | 'editing';
     setMapMode(mode: 'viewing' | 'editing'): boolean;
     private roomCharColors;
+    private unsetCharColorRooms;
     private hiddenRooms;
     private hiddenVersion;
     setRoomCharColor(id: number, r: number, g: number, b: number, a?: number): boolean;
@@ -1003,6 +1372,9 @@ export declare class MapStore {
      * own semantics).
      */
     unsetRoomCharColor(id: number): boolean;
+    /** Whether unsetRoomCharColor cleared this room's colour (and nothing has
+     *  set one since). */
+    isRoomCharColorUnset(id: number): boolean;
     /**
      * Mudlet `setRoomHidden(roomID, hidden)`. Toggles the hidden flag; the
      * RoomLens installed on the renderer consults {@link isRoomHidden} when
@@ -1028,7 +1400,7 @@ export declare class MapStore {
     /**
      * 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
+     * entire room map); Mudlet Web additionally accepts an areaID to scope the
      * answer, in which case `undefined` distinguishes "no such area" from "no
      * hidden rooms here".
      */
@@ -1041,7 +1413,8 @@ export declare class MapStore {
      * 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. */
+    /** Mudlet unHighlightRoom(roomID). False only for a room that doesn't
+     *  exist; a room with no highlight to remove is still true, as on desktop. */
     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. */