@mudlet/mudlet-web 0.4.5 → 1.0.0

package/dist-lib/scripting/ScriptingAPI.d.ts

@@ -2,9 +2,10 @@ import type { MudSession, ScriptLogSource } from '../mud/MudSession';
 import type { AliasEngine } from '../mud/aliases/AliasEngine';
 import type { TriggerEngine } from '../mud/triggers/TriggerEngine';
 import type { TimerEngine } from '../mud/timers/TimerEngine';
-import type { KeyEngine } from '../mud/keybindings/KeyEngine';
+import type { KeyEngine, KeyNode } from '../mud/keybindings/KeyEngine';
 import type { WindowHandle, WindowOpenOptions } from '../ui/windows/types';
-import type { LabelManager, LabelCreateOptions, LabelMouseEvent, LabelWheelEvent } from '../ui/labels/LabelManager';
+import type { LabelManager, LabelCreateOptions, LabelMouseEvent, LabelWheelEvent, LabelLiveRegion } from '../ui/labels/LabelManager';
+import { AddonCommandRegistry } from '../ui/commands/addonCommands';
 import type { CommandLineManager } from '../ui/cmdline/CommandLineManager';
 import type { ScrollBoxManager } from '../ui/scrollbox/ScrollBoxManager';
 import { TextEditManager } from '../ui/textedit/TextEditManager';
@@ -37,6 +38,13 @@ declare class ScriptingWindowsAPI {
     show(id: string): boolean;
     close(id: string): void;
     has(id: string): boolean;
+    /** The window's record, compared by identity to tell it from one a
+     *  handler put in its place under the same name. */
+    record(id: string): object | undefined;
+    /** Whether a mapper has been created this session (see WindowManager.hasMapper). */
+    hasMapper(): boolean;
+    /** The report the last loadJsonMap wrote for log/errors.txt, once (see WindowManager.takeMapReport). */
+    takeMapReport(): string;
     isVisible(id: string): boolean;
     isMiniConsole(id: string): boolean;
     move(id: string, x: number, y: number): void;
@@ -45,6 +53,23 @@ declare class ScriptingWindowsAPI {
      *  Host::openWindow honours the `area` argument on every call, not just
      *  the one that creates the dock widget. 'main' means floating. */
     setDockArea(id: string, area: string): void;
+    /** Whether the window is shown in a dock rather than floating. */
+    isDocked(id: string): boolean;
+    /**
+     * Float a docked user window ahead of a move or resize, as Host::moveWindow
+     * and Host::resizeWindow do (`if (!pD->isFloating()) pD->setFloating(true)`)
+     * before they move or resize the dock widget — which is also why a docked
+     * window's getWindowGeometry reads back what resizeWindow set. Geyser's
+     * UserWindow:move documents the same ("is set to floating state if this
+     * function is used"). setFloating leaves a hidden dock hidden, so this does
+     * too. Miniconsoles have no dock and are left alone.
+     */
+    floatForGeometryChange(id: string): void;
+    /** Commit the window layout synchronously, so the next script line sees the
+     *  sizes a dock change produced (see WindowManager.settleLayout). */
+    settleLayout(): void;
+    /** Queue the sysUserWindowResizeEvent a freshly opened user window is owed. */
+    announceCreatedSize(id: string): void;
     bringToFront(id: string): void;
     sendToBack(id: string): void;
     resize(id: string, width: number, height: number): void;
@@ -68,6 +93,8 @@ declare class ScriptingWindowsAPI {
     printCmdLine(id: string, text: string): boolean;
     appendCmdLine(id: string, text: string): boolean;
     getCmdLineValue(id: string): string;
+    hasCommandLine(id: string): boolean;
+    deleteCommandLine(id: string): boolean;
 }
 declare class ScriptingLabelsAPI {
     private readonly manager;
@@ -88,6 +115,11 @@ declare class ScriptingLabelsAPI {
     htmlRewriter: () => (html: string) => string);
     create(name: string, opts: LabelCreateOptions): boolean;
     has(name: string): boolean;
+    setSvgTint(name: string, color: string): boolean;
+    resetSvgTint(name: string): boolean;
+    setSvgRotation(name: string, degrees: number): boolean;
+    setSvgShear(name: string, shearX: number, shearY: number): boolean;
+    resetSvgTransform(name: string): boolean;
     /** Whether a movie is installed on this label — the movie functions report
      *  "no movie here" separately from "no such label". */
     hasMovie(name: string): boolean;
@@ -107,12 +139,20 @@ declare class ScriptingLabelsAPI {
         b: number;
         a: number;
     } | null;
+    /** Backs the label branch of the global setFont/getFont — see
+     *  {@link ScriptingAPI.setFont}. */
+    setFont(name: string, family: string): boolean;
+    getFont(name: string): string | null;
+    /** The label branch of the global setFontSize/getFontSize. */
+    setFontSize(name: string, size: number): boolean;
+    getFontSize(name: string): number | null;
     setStyleSheet(name: string, css: string): boolean;
     getStyleSheet(name: string): string | undefined;
     /** Pre-rewrite CSS per label, keyed by name — see {@link setStyleSheet}. */
     private readonly authoredCss;
     setLinkStyle(name: string, color: string, visitedColor: string, underline: boolean): boolean;
     resetLinkStyle(name: string): boolean;
+    clearVisitedLinks(name: string): boolean;
     getSizeHint(name: string): {
         width: number;
         height: number;
@@ -125,6 +165,12 @@ declare class ScriptingLabelsAPI {
     setMouseLeaveCallback(name: string, fn: ((e: LabelMouseEvent) => void) | undefined): boolean;
     setWheelCallback(name: string, fn: ((e: LabelWheelEvent) => void) | undefined): boolean;
     setTooltip(name: string, text: string | undefined): boolean;
+    setAccessibleName(name: string, accessibleName: string): boolean;
+    getAccessibleName(name: string): string | undefined;
+    setAccessibleButton(name: string, button: boolean | undefined): boolean;
+    getAccessibleRole(name: string): string | undefined;
+    setLiveRegion(name: string, liveRegion: LabelLiveRegion): boolean;
+    getLiveRegion(name: string): LabelLiveRegion | undefined;
     setClickThrough(name: string, value: boolean): boolean;
     setCursor(name: string, cursor: string | undefined): boolean;
     raise(name: string): boolean;
@@ -157,6 +203,32 @@ export declare class ScriptingAPI {
     private readonly oscLinks;
     readonly windows: ScriptingWindowsAPI;
     readonly labels: ScriptingLabelsAPI;
+    /** Mudlet's addon commands (addCommand and friends). Per profile, like
+     *  every other placement a package makes. */
+    readonly addonCommands: AddonCommandRegistry;
+    /** The package or module whose code the calling frame is, or '' for the
+     *  profile's own; see ScriptingEngine.packageOfCaller. */
+    packageOfCaller(source: string, isMain: boolean, calledFromMain: boolean): string;
+    /** A player clicked a command's button. Mudlet raises `sysCommandClicked`
+     *  with the id as a NUMBER (mudlet.cpp:694-699), which is the id addCommand
+     *  handed the package — that is what makes the id worth returning. */
+    addonCommandClicked(id: number): void;
+    /** The `mapperButton` mode a script set this session — Host::mMapperButtonMode. */
+    mapperButtonMode(): 'default' | 'scripted' | 'disabled';
+    /** Host::interceptMapperButton. Asked by the client's own map button,
+     *  menu entry and shortcut before they toggle the map: true means a script
+     *  has claimed the button and the client must leave the map alone —
+     *  "disabled" swallows the press, "scripted" turns it into
+     *  `sysMapperButtonAction` so a UI package can show its own map window. */
+    interceptMapperButton(): boolean;
+    private readonly mapperButtonListeners;
+    /** Hear `setConfig("mapperButton", …)`, so the button can grey out while
+     *  it is "disabled", as desktop disables its mapper action. */
+    onMapperButtonModeChange(fn: () => void): () => void;
+    /** Values for the `sessionOnly` options in {@link CONFIG_PERSIST_ONLY} —
+     *  held here rather than in the profile's config bag precisely so they are
+     *  gone next session. */
+    private readonly sessionConfig;
     readonly cmdLines: CommandLineManager;
     readonly scrollBoxes: ScrollBoxManager;
     readonly textEdits: TextEditManager;
@@ -184,6 +256,7 @@ export declare class ScriptingAPI {
      *  the in-flight console partial belongs to flushDeferredEcho and must not
      *  be closed out from under it. */
     private setDeferringEcho;
+    private readonly queueCommandEcho;
     private echoOnMatchedLine;
     /** Mudlet `startLogging(state)`. Forwarded to ProfileSession, which owns
      *  the SessionLogger instance (created/torn-down on this hook). */
@@ -191,14 +264,28 @@ export declare class ScriptingAPI {
     /** Mudlet `appendLog(text)`. Forwarded to the active SessionLogger (wired by
      *  ProfileSession, which owns the logger lifecycle). */
     private logAppender;
-    /** Mudlet `closeMudlet()`. mudix maps it to "close the active profile":
+    /** Mudlet `closeMudlet()`. Mudlet Web maps it to "close the active profile":
      *  disconnect, then return to the connection screen. Wired by ProfileSession. */
     private closeProfileCallback;
-    private selection;
+    /** A closeMudlet() is armed and has not run yet (see closeMudlet). */
+    private closeMudletArmed;
+    /** Set by destroy(): an armed closeMudlet() that outlives the profile
+     *  has nothing left to close. */
+    private destroyed;
+    /** One selection per console, keyed by window name ('main' for the main
+     *  console), the way each desktop TConsole keeps its own P_begin/P_end:
+     *  selecting or deselecting in one window leaves every other window's
+     *  selection standing. Each belongs to the line it was made on, as
+     *  desktop's P_begin/P_end name a line: moving the cursor leaves it there,
+     *  and deleting the line drops it. */
+    private readonly selections;
     private clipboard;
     private clipboardText;
     private buffers;
     constructor(session: MudSession, aliasEngine: AliasEngine, triggerEngine: TriggerEngine, timerEngine: TimerEngine, keyEngine: KeyEngine, connectionId: string);
+    /** Push the persisted `accessibleLabels` setting onto the labels, which
+     *  Host::setAccessibleLabels does for every label model it holds. */
+    private syncAccessibleLabelsFromConfig;
     /** Push the persisted `muteMediaAPI` / `muteMediaGame` gates onto the live
      *  sound and video managers. Both setters no-op when already in the wanted
      *  state, so this is cheap to call on every config-bag change. */
@@ -234,21 +321,31 @@ export declare class ScriptingAPI {
     /** Mudlet `sendMSDP(variable, ...values)`. Frames an MSDP subnegotiation
      *  (`IAC SB MSDP MSDP_VAR <var> [MSDP_VAL <val>]... IAC SE`) and sends it. */
     sendMSDP(variable: string, values: string[]): boolean;
-    /** Mudlet `sendSocket(data)`. Sends a literal byte-string over the socket
-     *  with no telnet/encoding processing (each char is one byte). */
-    sendSocket(data: string): boolean;
+    /** Mudlet `sendSocket(data [, parseTelnetCodes])`. Sends a literal
+     *  byte-string over the socket with no telnet/encoding processing (each
+     *  char is one byte). With `parseTelnetCodes` the `<T_IAC>`-style tags are
+     *  decoded first, as feedTelnet's are (TLuaInterpreter::parseTelnetCodes). */
+    sendSocket(data: string, parseTelnetCodes?: boolean): boolean;
     /** Mudlet `feedTelnet(data)`. Injects raw server bytes into the inbound
      *  pipeline as if received from the MUD (telnet stripping → ANSI →
      *  triggers → render). */
     /** Mudlet `feedTelnet(data)` — inject imitation server bytes. Refused while
      *  a socket exists in any state but unconnected, so replayed data can never
      *  interleave with a live stream; the message is returned for the binding to
-     *  shape into Mudlet's `(nil, errMsg)`, and null means it was fed. */
-    feedTelnet(data: string): string | null;
+     *  shape into Mudlet's `(nil, errMsg)`, and null means it was fed.
+     *
+     *  The empty string is not data: it asks which version of the byte-tag
+     *  table this client decodes, and feeds nothing (TLuaInterpreter::feedTelnet
+     *  answers `true, "feedTelnet: using table version N"` for it). */
+    feedTelnet(data: string): string | {
+        version: string;
+    } | null;
     /** Mudlet `loadReplay(fileName)` core. Starts playback of a Mudlet binary
      *  replay (.dat). The LuaRuntime binding reads the bytes from the VFS
-     *  before calling here. Returns null on success or the failure reason. */
-    loadReplay(bytes: Uint8Array): string | null;
+     *  before calling here, and hands over `readAt` so playback reads each
+     *  chunk again from the file as it comes up (see MudSession.loadReplayData).
+     *  Returns null on success or the failure reason. */
+    loadReplay(bytes: Uint8Array, readAt?: (position: number, length: number) => Uint8Array): string | null;
     /** Deliver any replay chunk that has come due. Only the busted pump calls
      *  this — see MudSession.pumpReplay. */
     pumpReplay(): number;
@@ -260,6 +357,13 @@ export declare class ScriptingAPI {
      *  has elapsed. Same reason again: the runner blocks the event loop the
      *  reveal timer would have fired on. */
     pumpHyperlinkReveals(): boolean;
+    /** Report the size of a user window just opened. Same reason again: the
+     *  runner blocks the turn that report was queued for. */
+    pumpCreatedWindowSizes(): boolean;
+    /** Run the map info contributors for a repaint of the map widget that
+     *  updateMap() or centerview() asked for. Same reason again: the runner
+     *  blocks the render that paint would have come with. */
+    pumpMapPaint(): boolean;
     /** Mudlet `receiveMSP(text)`. Parses an MSP payload (`!!SOUND(...)` /
      *  `!!MUSIC(...)` tags) as if the server had sent it and dispatches the
      *  resulting sound/music commands through the normal `msp` event path
@@ -269,6 +373,9 @@ export declare class ScriptingAPI {
      *  merely permitted by the profile's `enableMSP` config. Mudlet gates
      *  receiveMSP on this (ctelnet::isMSPEnabled). */
     isMspNegotiated(): boolean;
+    /** Whether the server has taken GMCP up on this connection — Mudlet's
+     *  `cTelnet::isGMCPEnabled`, which `sendGMCP` is refused without. */
+    isGmcpEnabled(): boolean;
     /** Mudlet `sendATCP(message)`. Frames + sends an ATCP (telnet 200)
      *  subnegotiation; false when the socket isn't open. */
     sendATCP(message: string): boolean;
@@ -286,14 +393,18 @@ export declare class ScriptingAPI {
      *  inbound stream (default "utf-8"). */
     getServerEncoding(): string;
     /** Mudlet `setServerEncoding(name)`. Switch the server stream decoder to
-     *  `name` (one of getServerEncodingsList()); false when unsupported or no
-     *  connection is active. */
-    setServerEncoding(name: string): boolean;
-    /** Mudlet `getServerEncodingsList()`. The encodings mudix can decode. */
+     *  `name` (one of getServerEncodingsList()). Returns true, or the refusal
+     *  cTelnet::setEncoding gives — the only place a script author is shown
+     *  every name they could have asked for, so it lists them all, ASCII first
+     *  as Mudlet does. */
+    setServerEncoding(name: string): true | string;
+    /** Mudlet `getServerEncodingsList()`. The encodings Mudlet Web can decode. */
     getServerEncodingsList(): string[];
-    /** Mudlet `getCharacterName()`. mudix uses one character per profile, so
-     *  this returns the active profile name (same value as getProfileName());
-     *  empty string when unset. */
+    /** Mudlet `getCharacterName()` — `Host::getLogin()`, the character name the
+     *  profile logs in with, *not* the profile name. '' when none is saved; the
+     *  Lua wrapper reports that as Mudlet's `nil, "no character name set"`.
+     *  Read through {@link readStoredLogin}, the same source auto-login and the
+     *  GMCP `Char.Login` reply use, so a branded build's in-memory login counts. */
     getCharacterName(): string;
     /**
      * Mudlet `getProfiles()`. A record keyed by profile name, one entry per
@@ -305,7 +416,8 @@ export declare class ScriptingAPI {
      *  - `connected` — the profile is connected to its game. Own tab: live; other
      *    tabs: their last-announced state (BroadcastChannel presence). Always
      *    false for a profile that isn't loaded.
-     *  - `description` — the connection record's free-text description.
+     *  - `description` — the connection record's free-text description, or the
+ *    blurb its bundled game ships with when it has none.
      * On a duplicate profile name, last-wins (a Lua table can't hold dup keys).
      */
     getProfiles(): Record<string, {
@@ -321,16 +433,58 @@ export declare class ScriptingAPI {
      *  version is our own release (see src/version.ts), not the Mudlet API
      *  level — that's what `getMudletVersion()` reports. */
     getMudletInfo(): void;
-    /** Mudlet `loadProfile(name) → bool`. Opens the named profile and connects
+    /** Mudlet `loadProfile(name)`. Opens the named profile and connects
      *  to it. Each profile lives in its own browser tab (the per-profile lock
      *  keeps it to one tab), so this opens a NEW tab at `?profile=<id>&connect=1`
      *  rather than switching the current one — the calling profile stays open
-     *  alongside, mirroring Mudlet's multi-profile model. Returns false for an
-     *  unknown name, when targeting the profile already open in this tab, or when
-     *  the browser blocks the popup. NOTE: `window.open` needs a user gesture, so
-     *  this works from a key/button/alias but a browser may block it from a
-     *  trigger (no Mudlet equivalent to that limitation). */
-    loadProfile(name: string): boolean;
+     *  alongside, mirroring Mudlet's multi-profile model.
+     *
+     *  Returns null on success, or the message for Mudlet's `nil, message`
+     *  refusal: an unknown name, a profile already open (in this tab or any
+     *  other — the loaded set is the same one getProfiles() reports), or a popup
+     *  the browser blocked. `window.open` needs a user gesture and a browser
+     *  allows one new tab per gesture, so a trigger (no gesture) or the second
+     *  loadProfile in one alias is refused (mudlet-web#453). That can't be
+     *  lifted from a page, so a refusal leaves a link in the main console that
+     *  opens the profile on click — the click is the gesture the call lacked. */
+    loadProfile(name: string): string | null;
+    /** True when profile `id` is open in this tab or any other. */
+    private isProfileLoaded;
+    /** Open profile `id` in a new tab and dial it. False when the browser
+     *  refused the tab. */
+    private openProfileTab;
+    /** The fallback for a loadProfile the browser refused: a line of its own
+     *  in the main console carrying a link that opens the profile. A click on
+     *  it that finds the profile open by then (another link, the user) just
+     *  says so rather than opening a second tab the lock would park. */
+    private echoOpenProfileLink;
+    /** A plain line of client feedback in the main console, on a line of its
+     *  own. */
+    private echoInfoLine;
+    /** Mudlet `closeProfile(name)`. Closes the named open profile — this one,
+     *  or one open in another tab, which is asked to close itself over the
+     *  profiles-presence channel. Closing is what `closeMudlet()` does here:
+     *  disconnect, then return that tab to the connection screen.
+     *
+     *  Returns null on success, or the message for Mudlet's `nil, message`
+     *  refusal when no open profile has that name. Like Mudlet, which closes the
+     *  tab on the next event-loop turn, the close happens after the calling
+     *  script has returned — so a script closing its own profile still finishes
+     *  (closeMudlet defers itself). */
+    closeProfile(name: string): string | null;
+    /** Mudlet `setActiveProfile(name)`: make an open profile the one in front.
+     *  The name is matched as MudletApp::getCanonicalProfileName matches it —
+     *  case-insensitively against the profiles, then against the bundled games
+     *  (a game with no profile is "not loaded").
+     *
+     *  Returns null on success or the refusal message. For this tab's own
+     *  profile it asks for the window's focus and succeeds. Every other profile
+     *  has a tab of its own, and a page can't bring another tab forward —
+     *  browsers only let the user switch tabs — so that is refused rather than
+     *  reported as done (mudlet-web#453): the target tab is asked to flash its
+     *  title instead, and the message says so, so a script can tell the user
+     *  where to look. */
+    setActiveProfile(name: string): string | null;
     /** Mudlet `getCommandSeparator()`. Returns the profile's command separator
      *  (the string that splits one Enter into multiple commands). Defaults to
      *  `;;` when the profile hasn't customised it. */
@@ -339,6 +493,24 @@ export declare class ScriptingAPI {
     private configBag;
     /** Shallow-merge a single key into the persisted config bag. */
     private patchConfigBag;
+    /** Shallow-merge several keys into the config bag in one store write, so
+     *  a watcher sees them change together rather than one at a time. */
+    private patchConfigBagFields;
+    /**
+     * The font the script editor reads code in (Mudlet's editorFont,
+     * editorFontSize and editorFontFollowsDisplay). A profile that never chose
+     * one follows the main console's font; one that did keeps its own, which a
+     * display font moving leaves alone.
+     */
+    editorFontState(): {
+        follows: boolean;
+        family: string;
+        size: number;
+    };
+    /** The negotiator flag each profile protocol toggle drives. MCCP is
+     *  absent on purpose: its handler owns its own switch and isn't part of
+     *  the negotiator flag set. */
+    private static readonly LIVE_PROTOCOL_FLAG;
     private getProtocol;
     private setProtocol;
     private getMapperField;
@@ -363,7 +535,46 @@ export declare class ScriptingAPI {
      *  legacy boolean reading alongside a newer enum — currently `showSentText`.
      *  The no-arg / table forms are handled by the Lua wrapper in Other.lua,
      *  which calls this once per key. */
-    getConfig(key: string, useStringFormat?: boolean): unknown;
+    getConfig(rawKey: string, useStringFormat?: boolean): unknown;
+    /**
+     * An IRC setting as desktop's TIrcClient readers give it. Each lives in a
+     * profile file of its own, as a serialised QString (Host::readProfileData),
+     * so a profile linked from or exported to desktop carries it. A value the
+     * writers would refuse — one a profile saved before they did may still hold
+     * — reads as the default, or for channels is skipped. A profile that kept
+     * its settings in the config bag before they moved to files is read from
+     * there until something writes them again.
+     */
+    private readIrcConfig;
+    /** Store an IRC setting where {@link readIrcConfig} reads it, as desktop's
+     *  writeProfileData writes it. The value has been vetted already. With no
+     *  profile folder to write into it is kept in the config bag instead. */
+    private writeIrcConfig;
+    /**
+     * `getConfig` for the `experiment.*` namespace, or {@link NOT_AN_EXPERIMENT}
+     * when the key is not one. Three shapes: `experiment.list` is the names this
+     * build knows, `<group>.active` is the suffix of whichever experiment in
+     * that group is on (nil when none is), and any other key reads as the
+     * on/off flag — FALSE for a name this build has never heard of, rather than
+     * a refusal, so a script can feature-test one that does not exist here.
+     */
+    private readExperimentConfig;
+    /** The experiments currently switched on, as stored in the profile bag. */
+    private enabledExperiments;
+    /**
+     * `setConfig` for the `experiment.*` namespace: true on success, or the
+     * refusal message. At most one experiment in a group may be on at a time —
+     * a group being the first two dot-segments — so enabling one turns off
+     * whichever of its siblings was on (Host::setExperimentEnabled).
+     */
+    private writeExperimentConfig;
+    /** The bounds a `num` option accepts, for the refusal Bridge.lua writes.
+     *  Null when the key is unbounded or names no option. */
+    configKeyRange(key: string): readonly [number, number] | null;
+    /** The values a string option accepts, for the refusal Bridge.lua writes —
+     *  the list is the only place a script author is told what the option takes,
+     *  so it has to reach the message. Null when the key takes no fixed set. */
+    configKeyValues(key: string): readonly string[] | null;
     /**
      * What kind of value `setConfig(key, …)` takes, or null when the key names
      * no option at all. Mudlet reads each option with a `getVerified*` helper,
@@ -375,10 +586,24 @@ export declare class ScriptingAPI {
      * `'readonly'` keys exist for `getConfig` but refuse every write; `'any'`
      * keys take more than one value type and vet the value themselves.
      */
-    configKeyKind(key: string): 'bool' | 'num' | 'str' | 'any' | 'readonly' | null;
+    configKeyKind(rawKey: string): 'bool' | 'num' | 'str' | 'any' | 'readonly' | null;
     /** Mudlet `setConfig(key, value)`. Returns true when the key is known and
      *  writable, false for unknown or read-only keys. */
-    setConfig(key: string, value: unknown): boolean;
+    /**
+     * The room symbols the named font has no glyph for, as desktop lists them,
+     * or null when it can draw every one the map uses.
+     *
+     * Measured rather than looked up, because a browser will not say what a
+     * font contains: a character with no glyph is drawn as the font's notdef
+     * box, and every such character therefore measures the SAME width. So each
+     * symbol is compared against a codepoint nothing has a glyph for — the last
+     * of Private Use Plane 16 — in the same font at the same size. Equal widths
+     * mean both came out as the box.
+     */
+    private symbolsThisFontCannotDraw;
+    /** Returns true, or a string when the option was taken and the caller
+     *  should be told something about it — see the mapSymbolFont case. */
+    setConfig(rawKey: string, value: unknown): boolean | string;
     /**
      * The connection a profile-name argument refers to, or null when no profile
      * has that name. Matching ignores case, as Mudlet's does: it looks the name
@@ -425,7 +650,17 @@ export declare class ScriptingAPI {
     /** Write every module flagged to sync back out to its own file. Called by
      *  saveProfile — see the note there. */
     saveSyncedModules(): void;
-    reloadModule(name: string): boolean;
+    /** Write the profile out as a Mudlet-format XML save. The XML half of
+     *  `saveProfile([location [, saveName]])` — see ScriptingEngine. */
+    saveProfileXml(location?: string, saveName?: string): {
+        ok: true;
+        path: string;
+    } | {
+        ok: false;
+        err: string;
+        path?: string;
+    };
+    reloadModule(name: string): InstallOutcome;
     enableModuleSync(name: string): void;
     disableModuleSync(name: string): void;
     getModuleSync(name: string): boolean;
@@ -433,17 +668,17 @@ export declare class ScriptingAPI {
     getModulePriority(name: string): number;
     getModules(): string[];
     getModuleInfo(name: string): Record<string, unknown> | null;
-    /** Mudlet `setModuleInfo(name, key, value)`. Stores a custom info field on a
-     *  module (visible via getModuleInfo). Always true. */
-    setModuleInfo(name: string, key: string, value: string): boolean;
+    /** Mudlet `setModuleInfo(name, key, value)`. Stores a custom info field on an
+     *  installed module (visible via getModuleInfo); the refusal, or null. */
+    setModuleInfo(name: string, key: string, value: string): string | null;
     getModulePath(name: string): string | null;
     /** Mudlet `getPackageInfo(name)`. Merged info table — the package manifest's
      *  standard fields overlaid with anything set via setPackageInfo. Empty when
      *  the package isn't installed and nothing was set. */
     getPackageInfo(name: string): Record<string, string>;
-    /** Mudlet `setPackageInfo(name, key, value)`. Stores a custom info field on a
-     *  package (visible via getPackageInfo). Always true. */
-    setPackageInfo(name: string, key: string, value: string): boolean;
+    /** Mudlet `setPackageInfo(name, key, value)`. Stores a custom info field on an
+     *  installed package (visible via getPackageInfo); the refusal, or null. */
+    setPackageInfo(name: string, key: string, value: string): string | null;
     /**
      * Mudlet `setTriggerStayOpen(name, lines)`. Keeps the named trigger's chain
      * open for `lines` more lines of input for the current run only — it adjusts
@@ -483,37 +718,49 @@ export declare class ScriptingAPI {
     /** Hook for ProfileSession to close the active profile (return to the
      *  connection screen). */
     setCloseProfileCallback(fn: (() => void) | null): void;
-    /** Mudlet `closeMudlet()`. mudix maps it to closing the active profile:
-     *  disconnect, then return to the connection screen. */
+    /** Mudlet `closeMudlet()`. Mudlet Web maps it to closing the active profile:
+     *  raise sysExitEvent, disconnect, then return to the connection screen.
+     *  The event comes first because on desktop (TMainConsole::closeEvent) the
+     *  exit handlers run while the profile is still connected, so a goodbye or
+     *  save command they send reaches the game. The engine's teardown does not
+     *  raise it a second time.
+     *
+     *  None of that happens inside the call. Desktop's closeMudlet only arms the
+     *  close (mudlet::armForceClose, a zero-delay single shot), so it returns
+     *  and the rest of the calling script runs — and its sends go out — before
+     *  the exit handlers do. A plain timeout rather than the timer queue, so a
+     *  script pumping events in waitForEvent does not close underneath itself,
+     *  which desktop's armForceClose also waits out. Calls made while a close
+     *  is already armed fold into it. */
     closeMudlet(): void;
     /** Mudlet `resetProfile()` — reload the entire profile as if just opened:
      *  clear every UI surface, recreate the Lua runtime, and re-run all scripts.
      *  The actual work is deferred by the engine (it closes the Lua VM that is
-     *  currently executing this call), so this returns immediately. */
-    resetProfile(): void;
+     *  currently executing this call), so this returns immediately — true once
+     *  the reset is armed, false when it was refused (Host::resetProfile_phase1). */
+    resetProfile(): boolean;
     /** Mudlet `exportAreaImage(areaID, filePath[, zLevel])` — render the area to a
      *  PNG file in the profile VFS. Returns `[true, absolutePath]` on success or
      *  `[false, errorMessage]` (e.g. the mapper isn't open, or the area is
      *  unknown). The 0-indexed array is unpacked into Mudlet's multi-return by
      *  Bridge.lua. */
-    exportAreaImage(areaId: number, filePath: string, zLevel?: number): [boolean, string];
+    exportAreaImage(areaId: number, filePath: string, zLevel?: number | true): [boolean, string, boolean?];
     killByName(kind: 'timer' | 'alias' | 'trigger' | 'key', name: string): boolean;
     installPackage(path: string): InstallOutcome;
-    uninstallPackage(name: string): boolean;
+    /** Lua `uninstallPackage(name)`: the refusal, or null once it is gone. */
+    uninstallPackage(name: string): string | null;
     enableScript(name: string): boolean;
     disableScript(name: string): boolean;
     enableTrigger(nameOrId: string | number): boolean;
     disableTrigger(nameOrId: string | number): boolean;
     enableTimer(name: string): boolean;
     disableTimer(name: string): boolean;
+    private toggleTimer;
     enableAlias(nameOrId: string | number): boolean;
     disableAlias(nameOrId: string | number): boolean;
     /** The saved keybinding carrying this numeric id, or null. Backs
      *  getKeyCode() for a permanent key referenced by the id permKey returned. */
-    keyNodeByNumericId(numericId: number): {
-        key: string;
-        modifiers: string[];
-    } | null;
+    savedKeyNode(idOrName: number | string): KeyNode | null;
     enableKey(nameOrId: string | number): boolean;
     disableKey(nameOrId: string | number): boolean;
     /**
@@ -582,7 +829,7 @@ export declare class ScriptingAPI {
      *  refuse it differently from "nothing matched". */
     isKnownItemType(type: string): boolean;
     /** Mudlet `getProfileStats()`. Per-family total/active counts (+ trigger
-     *  patterns). See ScriptingEngine.getProfileStats for mudix's caveats. */
+     *  patterns). See ScriptingEngine.getProfileStats for Mudlet Web's caveats. */
     getProfileStats(): Record<string, unknown>;
     permScript(name: string, parent: string, code: string): number;
     permRegexTrigger(name: string, parent: string, regexes: string[], code: string): number;
@@ -621,7 +868,7 @@ export declare class ScriptingAPI {
      *  name exists. */
     permAlias(name: string, parent: string, pattern: string, code: string): number;
     /** Mudlet `permTimer(name, parent, seconds, luaCode)`. Creates a
-     *  persistent one-shot timer under the parent group (empty = root).
+     *  persistent repeating timer under the parent group (empty = root).
      *  Returns the new timer id, or -1 when `parent` is non-empty but no
      *  timer group of that name exists. */
     permTimer(name: string, parent: string, delay: number, code: string): number;
@@ -642,39 +889,52 @@ export declare class ScriptingAPI {
      * `source` is the caller's "script:line" captured by the Lua wrapper.
      */
     warnReservedTempKey(key: string, modifiers: string[], source?: string): void;
-    /** Mudlet `tempButton(toolbarName, name, code [, orientation])`. Appends a
-     *  transient button under an existing toolbar group; returns the new id, or
-     *  -1 when the toolbar doesn't exist. `orientation` is Mudlet's int form
-     *  (0=horizontal/1=vertical) — accepted for compat, applied to the
-     *  button row inside the toolbar grid. */
-    tempButton(toolbar: string, name: string, code: string, orientation: number): number;
-    /** Mudlet `tempButtonToolbar(name [, orientation [, location]])`. Creates
-     *  a transient toolbar (ButtonNode group). `location` int: 0=top, 1=bottom,
-     *  2=left, 3=right, 4=floating. Returns the new id or -1 on duplicate
-     *  name. */
+    /** Mudlet `tempButton(toolbarName, name, orientation)`. Appends a
+     *  transient button, with no command or script, under an existing toolbar
+     *  group; returns the new id, or -1 when the toolbar doesn't exist, -2
+     *  when it is a plain button, -3 when the name is already taken (the Lua
+     *  wrapper answers nil and desktop's message for each).
+     *  `orientation` is Mudlet's int form (0=horizontal/1=vertical). */
+    tempButton(toolbar: string, name: string, orientation: number): number;
+    /** Mudlet `tempButtonToolbar(name, location, orientation)` core. Creates
+     *  a transient toolbar (ButtonNode group). `location` is TAction's stored
+     *  int — 0=top, 1=bottom, 2=left, 3=right, 4=floating — which Bridge.lua
+     *  derives from the Lua argument. Returns the new id or -1 on duplicate
+     *  name (the Lua wrapper answers nil and desktop's message then). */
     tempButtonToolbar(name: string, orientation: number, location: number): number;
     /** Mudlet `setButtonState(name, state)`. Sets the pressed state of a
      *  two-state (push-down) button by name. Returns false when not found. */
-    setButtonState(name: string, state: boolean): boolean;
+    setButtonState(name: string | number, state: boolean): boolean;
     /** Mudlet `getButtonState(name)`. Reads the pressed state of a two-state
      *  button. Returns nil when not found. */
-    getButtonState(name: string): boolean | null;
+    getButtonState(name: string | number): boolean | null;
+    /**
+     * The console's own button state, which no-argument `getButtonState()`
+     * reads: 2 when the last clicked button went down, 1 when it came up or
+     * was a plain button. Mudlet's TToolBar/TEasyButtonBar write
+     * `mpConsole->mButtonState` just before running the button, so it holds
+     * the click being handled — ScriptingEngine.executeButton does the same.
+     */
+    clickedButtonState: 1 | 2;
     /** Which of Mudlet's button refusals applies to `name` — see
      *  ScriptingEngine.buttonKindByName. */
-    buttonKind(name: string): 'missing' | 'plain' | 'pushdown';
+    buttonKind(name: string | number): 'missing' | 'plain' | 'pushdown';
     /** Mudlet `setButtonStyleSheet(name, css)`. Stores a CSS string on the
      *  ButtonNode; the renderer applies it inline. Returns false when not
      *  found. */
     setButtonStyleSheet(name: string, css: string): boolean;
     /** Mudlet `showToolBar(name)` / `hideToolBar(name)`. Toggles the toolbar's
      *  effective enabled flag — the existing button bar already gates render
-     *  on `isEffectivelyEnabled`, so flipping the group's `enabled` field is
+     *  on its toolbars being switched on, so flipping the group's `enabled` field is
      *  the show/hide hook. Returns null on success, or why nothing moved. */
     setToolBarVisibility(name: string, show: boolean): string | null;
     setScript(name: string, code: string, pos: number): number;
     /** Removes the script with this numeric id. Backs permScript's rollback
      *  when the new body raises as it is run. True when one was removed. */
     removeScriptById(id: number): boolean;
+    /** Why the body of the script with this numeric id failed when permScript
+     *  or setScript just ran it, or null when it ran cleanly. */
+    scriptLoadError(id: number): string | null;
     /** Mudlet `getScript(name [, pos]) → code, id`. Returns the source of the
      *  pos-th (1-indexed) script named `name` together with that script's own
      *  numeric id. Null when no script sits at that position, which Bridge.lua
@@ -698,6 +958,45 @@ export declare class ScriptingAPI {
      */
     private injectOsc8Docs;
     echo(text: string): void;
+    /**
+     * Write `text` to the main console in the current pen, honouring the
+     * matched line. During trigger processing Mudlet's echo/cecho appends to
+     * the matched line at the output cursor (the line's end); only a `\n`
+     * advances to a fresh line. Mudlet Web seeds the matched line into
+     * mainConsole.history (beginLine) and defers script echoes, so without this
+     * every trigger echo opened a new line — breaking Arkadia's grade/value
+     * triggers, which `replace()`/`prefix()` then append text to the same line,
+     * and the "add a clickable link after the line" pattern `echoLink` and
+     * `echoPopup` are used for. The caller drains.
+     */
+    private echoMain;
+    /** Echo into `con` — through {@link echoMain} when it is the main console,
+     *  so a link or popup echoed from a trigger lands on the matched line.
+     *  `state`, when given, is written instead of the console's pen. */
+    private echoTo;
+    /**
+     * The format a link or popup gets when the caller did not ask for the
+     * current one — Mudlet's `standardLinkFormat`: the link blue, the console's
+     * own background and underline, and nothing else. It replaces the pen
+     * outright rather than layering onto it, so bold, italics, a background,
+     * strikeout or reverse set beforehand do not carry into the link (and a
+     * `cechoLink` with `<b>` inside stays one plain link run, since xEcho
+     * passes no format flag to the echoLink calls it makes).
+     */
+    private standardLinkState;
+    /**
+     * `TConsole::printCommand` on a miniconsole or user window: what Enter on
+     * its own command line (no action bound) prints into it after sending.
+     * Gated as desktop's enterCommand/printCommand gate it — never under
+     * `showSentText` "never", nor while the server echoes (password entry) —
+     * and drawn in that console's command colours, which start as
+     * TConsoleModel's (213,195,0) on black and setCommandForegroundColor /
+     * setCommandBackgroundColor with its name change.
+     */
+    printCommandToWindow(win: string, text: string): void;
+    /** Per-console command echo colours (TConsole::mCommandFgColor/BgColor),
+     *  set by setCommandForegroundColor/BackgroundColor with a window name. */
+    private readonly windowCommandColors;
     echoToWindow(win: string, text: string): void;
     /**
      * Native fast path for the color-echo family (`decho`/`cecho`/`hecho`).
@@ -714,7 +1013,12 @@ export declare class ScriptingAPI {
      *    line via a raw, non-ANSI insert the ANSI path can't reproduce),
      *  - any input the per-kind guard declines ({@link dechoToAnsiFast} /
      *    {@link cechoToAnsiFast} / {@link hechoToAnsiFast}) — style tags,
-     *    combined fg/bg, backgrounds, unknown color names, unmodeled tokens.
+     *    combined fg/bg, backgrounds, unknown color names, unmodeled tokens,
+     *  - an ESC anywhere in the text (Mudlet stores it as text; the ANSI this
+     *    builds would decode it).
+     * The Lua wrapper also keeps a cecho off this path while any of its tags
+     * names a `color_table` entry a script has changed (see LuaRuntime's
+     * installFastColorEcho).
      */
     fastColorEcho(kind: string, win: string, str: string): boolean;
     /**
@@ -726,11 +1030,24 @@ export declare class ScriptingAPI {
      */
     echoLink(text: string, cmd: string, tooltip: string, win?: string, useCurrentFormat?: boolean): void;
     /**
-     * Build a {@link FormatHyperlink} whose right-click handler opens a context
-     * menu listing `cmds` (labelled by `hints`, falling back to the command
-     * text). Shared by `echoPopup`/`insertPopup`/`setPopup` — those three differ
-     * only in whether the styled span is appended, inserted at the cursor, or
-     * applied to the current selection.
+     * Build a {@link FormatHyperlink} for the popup family — shared by
+     * `echoPopup`/`insertPopup`/`setPopup`, which differ only in whether the
+     * styled span is appended, inserted at the cursor, or applied to the
+     * current selection.
+     *
+     * Mudlet keeps links and popups in one link store and decides per click, so
+     * a popup is a link that *also* carries a menu:
+     *  - Left-click runs `cmds[0]`, whatever the entry count. `TTextEdit::
+     *    mousePressEvent` has no popup branch at all — it executes the first
+     *    command of whichever link was hit.
+     *  - Right-click opens the menu only when there is more than one command,
+     *    or the hints list is longer than the commands list (a leading tooltip
+     *    hint marking the rest as menu items). A one-entry popup is therefore
+     *    indistinguishable from `echoLink`, which is what scripts calling
+     *    `cechoPopup(win, text, {code}, {label}, true)` rely on.
+     *  - Right-clicking a link never falls through to the console's own copy
+     *    menu (Mudlet sets `mIsCommandPopup` and returns), but that holds for
+     *    every link, so the renderer swallows it — see FormatBuffer.toDom.
      */
     private buildPopupHyperlink;
     /**
@@ -744,7 +1061,7 @@ export declare class ScriptingAPI {
      *    the commands, each sending to the MUD.
      * Used by ScriptingEngine when rendering MXP-parsed lines.
      */
-    createMxpHyperlink(kind: 'command' | 'url', payload: string, hint?: string, promptCmds?: string[], promptHints?: string[]): FormatHyperlink;
+    createMxpHyperlink(kind: 'command' | 'url' | 'prompt', payload: string, hint?: string, promptCmds?: string[], promptHints?: string[], isLive?: () => boolean): FormatHyperlink;
     /** Execute an OSC 8 link URI — a primary action or a menu item. The scheme
      *  decides the behaviour (send / prompt / open URL); anything else is a
      *  no-op (it was already rejected at parse time). */
@@ -774,10 +1091,21 @@ export declare class ScriptingAPI {
      * backing buffer is available (empty console / sub-window without a buffer).
      */
     insertPopup(text: string, cmds: string[], hints: string[], win?: string, useCurrentFormat?: boolean): void;
+    /**
+     * The shared tail of insertLink/insertPopup — Mudlet routes both through
+     * TConsoleModel::insertLink. When the cursor sits on TBuffer::getEndPos()
+     * (the last character of the last line, or column 0 of an empty one) the
+     * span is appended there instead, which is `appendAtEnd`, and the cursor
+     * stays put. Otherwise it goes in at the cursor — padded out to it when the
+     * cursor is past the end of the line — and, outside the trigger engine,
+     * the cursor moves past it so a following insert lands after the link
+     * rather than in front of it.
+     */
+    private insertLinkSpan;
     /**
      * Mudlet `setPopup([window,] {commands}, {hints})`. Attaches a right-click
      * popup menu to the current selection — preserves the selection's existing
-     * colors/attributes (like `setLink`, unlike the homogenizing color setters).
+     * colors/attributes (like `setLink` and the colour setters).
      * `commands` are Lua code strings run when the matching menu entry is
      * chosen. Returns false when there is no selection (or it belongs to a
      * different window).
@@ -808,8 +1136,8 @@ export declare class ScriptingAPI {
      * the full pen state in one call. r1/g1/b1 is BACKGROUND, r2/g2/b2 is
      * FOREGROUND (a Mudlet quirk — preserved here for parity). `blinkMode` is
      * "none" / "slow" / "fast". Returns false when the named window doesn't
-     * resolve. Mirrors setFgColor & friends: the pen is updated on the resolved
-     * console AND applied to the current selection when one is active on it.
+     * resolve. Unlike setFgColor & friends it touches the pen only — a
+     * selection active on the console keeps its formatting, as in Mudlet.
      */
     setTextFormat(windowName: string | undefined, bg: {
         r: number;
@@ -826,9 +1154,17 @@ export declare class ScriptingAPI {
     selectString(str: string, occurrence: number, windowName?: string): number;
     /**
      * Mudlet `selectSection([window,] from, length) → bool`. `from` is 0-indexed.
-     * Negative `from` is rejected (Mudlet behavior); zero/negative lengths
-     * register a no-op selection but still report success in Mudlet — we match
-     * that, but reject when the resolved buffer doesn't exist.
+     *
+     * A selection that does not fit the line is REFUSED, not trimmed to fit:
+     * TConsole::selectSection rejects a negative start, a start past the end of
+     * the line, and a length that runs off it, and leaves the previous selection
+     * standing in each case. Clamping instead — which Mudlet Web did — turned
+     * "selectSection(5, 1)" on a four-character line into a silent selection of
+     * its last character, so a script checking the return value was told its
+     * out-of-range request had succeeded and then styled the wrong text.
+     *
+     * `from == line length` is allowed: that is an empty selection at the end of
+     * the line, not a start past it.
      */
     selectSection(from: number, length: number, windowName?: string): boolean;
     /**
@@ -839,9 +1175,8 @@ export declare class ScriptingAPI {
      */
     selectCurrentLine(windowName?: string): boolean;
     /**
-     * Mudlet `deselect([windowName])`. With a window name, only clears the
-     * selection if it belongs to that window — selections in other consoles
-     * remain intact. Without an arg, clears unconditionally.
+     * Mudlet `deselect([windowName])`. Clears the named console's selection
+     * (main when omitted); selections in other consoles remain intact.
      */
     deselect(windowName?: string): void;
     /**
@@ -855,11 +1190,11 @@ export declare class ScriptingAPI {
         text: string;
         start: number;
         length: number;
-    } | null;
+    } | string | null;
     /**
      * Mudlet `getFgColor([window])` / `getBgColor([window])`. Reads the fg/bg
      * color at the current selection's start position (Mudlet's P_begin). Each
-     * console tracks its own selection in Mudlet; mudix has a single global
+     * console tracks its own selection in Mudlet; Mudlet Web has a single global
      * selection, so when `window` is given it must match the selection's
      * owning window — otherwise we treat it as "no selection in that window"
      * and return null (Mudlet's "no values" shape, surfaced as nil/nil/nil in
@@ -877,13 +1212,20 @@ export declare class ScriptingAPI {
      * Mudlet `isAnsiFgColor(ansiColor)` / `isAnsiBgColor(ansiColor)`. True when
      * the foreground/background color at the current selection's start equals
      * ANSI/xterm color index `ansiColor` (0..7 normal, 8..15 bright, 16..255 the
-     * xterm-256 palette). mudix stores rendered RGB rather than the original
+     * xterm-256 palette). Mudlet Web stores rendered RGB rather than the original
      * ANSI index, so the comparison is against the palette entry's RGB — exact
      * for the 256 standard slots. Returns false when there's no selection (or it
      * belongs to another window) or `ansiColor` is out of range.
      */
     isAnsiFgColor(ansiColor: number): boolean;
     isAnsiBgColor(ansiColor: number): boolean;
+    /**
+     * Whether the main console's selection (or, with none, the cursor line's
+     * first column) is on a character — what isAnsiFgColor/isAnsiBgColor read.
+     * Desktop answers "current selection invalid in window 'main'" when it is
+     * not, ahead of checking the colour number.
+     */
+    hasReadableSelection(): boolean;
     private matchesAnsiColor;
     /**
      * The colour one of `isAnsiFgColor`/`isAnsiBgColor`'s 0..16 codes names.
@@ -896,6 +1238,18 @@ export declare class ScriptingAPI {
      * only has to decline to answer.
      */
     private ansiColorCodeToRgb;
+    /**
+     * The colour Mudlet's getFgColor/getBgColor read: the one at P_begin, the
+     * start of the selection.
+     *
+     * Mudlet has no "no selection" state — deselect() collapses P_begin and
+     * P_end to (0, 0) rather than unsetting them, so the getters go on reading
+     * the first column of the cursor's line. Mudlet Web models the selection as
+     * absent instead, so that case is spelled out here: with nothing selected
+     * the column is zero, and the answer is "nothing at all" only when there is
+     * no character there to read — an empty console, or a line the selection
+     * outlived.
+     */
     private readSelectionColor;
     /**
      * Resolve the rgb of `channel` for the character at `pos` in `buf`, falling
@@ -904,6 +1258,17 @@ export declare class ScriptingAPI {
      * (selection or cursor).
      */
     private readColorAt;
+    /** The colour the character at `pos` carries on `channel` itself (a
+     *  link's own style first), or undefined for the console's default. */
+    private cellColorAt;
+    /** The background setBackgroundColor gave a miniconsole or user window,
+     *  which its characters with no background of their own are drawn in —
+     *  desktop's TBuffer::updateColors() makes it their format's. */
+    private consoleOwnBackground;
+    /** The alpha of the background the character at `pos` is drawn on, as
+     *  getTextFormat's `backgroundAlpha` reports it: a decho alpha the
+     *  character carries, else its console's own translucent background. */
+    private readBackgroundAlphaAt;
     /** The blue a link gets in `windowName` when the caller did not pass a
      *  format of its own — whichever of Mudlet's two link blues reads better
      *  against that console's background. */
@@ -921,8 +1286,9 @@ export declare class ScriptingAPI {
      *
      * `foreground`/`background` resolve through the same logic as getFgColor /
      * getBgColor (falling back to the profile defaults for unstyled segments).
-     * `overline`, `concealed`, and `alternateFont` have no equivalent in mudix's
-     * FormatState, so they report Mudlet's "off" values (false / 0) for parity.
+     * `alternateFont` is recorded but never rendered — Mudlet Web has no alternate
+     * font to switch to — so a script reads back the number the game asked for
+     * and sees no difference on screen.
      */
     getTextFormat(windowName?: string): {
         bold: boolean;
@@ -937,14 +1303,15 @@ export declare class ScriptingAPI {
         blinking: 'none' | 'slow' | 'fast';
         foreground: [number, number, number];
         background: [number, number, number];
+        backgroundAlpha: number;
     } | null;
     applyFormatToSelection(state: FormatStateSnapshot): void;
     /**
      * Mudlet `setLink([windowName], command, hint)`. Applies a clickable
      * hyperlink to the current selection — preserves existing colors/attributes
-     * on each segment (unlike setFgColor & friends which homogenize). `command`
+     * on each segment (as setFgColor & friends do). `command`
      * is the Lua code run on click; the Bridge.lua wrapper converts function
-     * arguments into a `__mudix_call_link(id)` string before reaching here.
+     * arguments into a `__mudlet_call_link(id)` string before reaching here.
      * Returns false if there is no selection (or it doesn't belong to `win`).
      */
     setLink(cmd: string, tooltip: string, win?: string): boolean;
@@ -964,13 +1331,28 @@ export declare class ScriptingAPI {
      * flushDeferredEcho() is called.
      */
     endLine(): void;
+    /** Where the line the innermost trigger pass is running on is now, or -1
+     *  outside a pass (or once a trigger deleted it). Followed by the line
+     *  itself, as desktop's pass line number is kept up to date across a
+     *  deletion or a wrap above it. */
+    private passLineIndex;
+    /**
+     * Run `fn` with the cursor on the line the trigger pass is processing, and
+     * put the script's cursor back after. A trigger's own highlight paints the
+     * line being processed wherever the scripts before it left the cursor
+     * (TTrigger works on the engine's position, not the user cursor) — after
+     * one deleted a line above, say, which moves the pass line up.
+     */
+    onPassLine(fn: () => void): void;
+    /** The lines a network line is stored as once its triggers are done — see
+     *  Console.wrapAppendedLine. */
+    wrapNetworkLine(buffer: AnsiAwareBuffer): AnsiAwareBuffer[];
     /**
      * Mudlet `tempColorTrigger(fg, bg)` colour-scan helper. Walks the
      * just-appended line buffer (the one beginLine() seeded mainConsole with)
-     * and returns true if any segment carries the requested ANSI palette
-     * indices. `wantFg`/`wantBg` accept -1 as "any colour"; non-indexed
-     * (RGB) segments never match a positive index, matching Mudlet's
-     * palette-only semantics.
+     * and returns true if any segment carries the requested ANSI colours.
+     * `wantFg`/`wantBg` accept -1 as "any colour" and -2 as the console's
+     * default; anything else is compared by the RGB it names, as desktop does.
      */
     currentLineMatchesColor(wantFg: number, wantBg: number, window?: {
         start: number;
@@ -981,22 +1363,66 @@ export declare class ScriptingAPI {
      * colours, or null when none does. A colour trigger reports that run as
      * `matches[1]` — Mudlet matches a contiguous same-coloured run, not the
      * whole line — so adjacent segments sharing the colours are joined.
+     */
+    currentLineColorMatch(wantFg: number, wantBg: number, window?: {
+        start: number;
+        length: number;
+    } | null): string | null;
+    /**
+     * Every run on the current line carrying the wanted ANSI colours, in order,
+     * with its offset in the line — at most `limit` of them. A filter parent
+     * matching a colour hands each run to its children separately, as
+     * TTrigger::match_color_pattern collects them all.
      *
      * Reads the snapshot beginLine took, not the live buffer: an earlier trigger
      * may already have recoloured the line, and Mudlet still matches against the
      * colours the server sent.
      */
-    currentLineColorMatch(wantFg: number, wantBg: number, window?: {
+    currentLineColorRuns(wantFg: number, wantBg: number, window?: {
         start: number;
         length: number;
-    } | null): string | null;
-    /** Per-segment ANSI palette indices (and text) of each line currently being
-     *  processed, as it arrived — see {@link beginLine}. {@link COLOR_DEFAULT}
-     *  marks a segment left on the console's default colour, which is what a
-     *  trigger asking for `-2` matches; {@link COLOR_UNPALETTED} marks an RGB
-     *  colour outside the palette, which matches nothing. A stack, because a
-     *  trigger can feedTriggers another line. */
+    } | null, limit?: number): {
+        text: string;
+        start: number;
+    }[];
+    /** Per-segment colours (as {@link RgbKey}s) and text of each line currently
+     *  being processed, as it arrived — see {@link beginLine}. A segment left
+     *  on the console's default colour holds the default's RGB, as a desktop
+     *  TChar does. A stack, because a trigger can feedTriggers another line. */
     private lineColorSnapshots;
+    /** The live buffer of each line in {@link lineColorSnapshots}, read for
+     *  whatever has been written past the snapshot's end. */
+    private lineColorLive;
+    /** `buffer`'s segments from character `from` on, as colour keys. */
+    private colorKeySegments;
+    /** The console's default foreground/background as {@link RgbKey}s — what
+     *  uncoloured text is drawn in, and what a `-2` pattern asks for. */
+    private triggerDefaultColorKeys;
+    /**
+     * Keep the colour snapshot aligned with a line a trigger has just edited.
+     *
+     * The snapshot is of the colours the SERVER sent, and a trigger that
+     * merely RECOLOURS the line must not disturb it — that is the whole point
+     * of taking one. But inserting or deleting characters moves the runs: the
+     * text after an insert is at a different offset than it was, and a colour
+     * trigger reading stale offsets matches across the seam. In the spec's
+     * words, red "CCCC" with its first two characters deleted has to match as
+     * "CC" and not as "CCDD", which is what taking four red characters from the
+     * shifted line gives.
+     *
+     * Done per character and re-joined rather than by walking segment
+     * boundaries, because an edit lands wherever it lands — mid-run as often as
+     * not — and a line is short enough that the simple version is the one worth
+     * having.
+     */
+    /** The snapshot's colours at a character offset — what a `keepColor`
+     *  replacement inherits. Defaults to the reset pair when the line is
+     *  shorter than the offset. */
+    private snapshotColorAt;
+    /** A pen state's colours as {@link RgbKey}s, unset channels resolved to
+     *  the console's defaults. */
+    private stateColorKeys;
+    private spliceLineColorSnapshot;
     /** Whether each line currently being processed arrived as a prompt — the
      *  fallback isPrompt() reads once a trigger has gagged the line itself. A
      *  stack for the same reason {@link lineColorSnapshots} is one. */
@@ -1004,14 +1430,62 @@ export declare class ScriptingAPI {
     /** How many lines are being processed at once — more than one whenever a
      *  trigger calls feedTriggers. See beginLine/endLine. */
     private triggerLineDepth;
+    /** TriggerUnit::scmMaxProcessingDepth — see {@link feedTriggers}. */
+    private static readonly MAX_TRIGGER_DEPTH;
+    /** Set when a feed chain hits {@link MAX_TRIGGER_DEPTH}, until it unwinds to the outermost pass. */
+    private runawayFeedStopped;
+    /** Main-console lines the trigger pass's own echoes have completed. Mudlet's
+     *  TConsole::echo embeds a trigger echo's newlines in the line being
+     *  processed rather than opening lines, so the line count leaves them out
+     *  until the pass is over. See {@link getLineCount}. */
+    private triggerEchoLines;
+    /** The main console's last line when the outermost trigger pass began.
+     *  The view is not moved on until the pass is over (desktop finalises the
+     *  main console only at depth 0), so getScroll() reports no further than
+     *  this while it runs, however many lines a trigger feeds in meanwhile. */
+    private passStartLastLine;
     /** Per nested line, the line the outer pass was on. See beginLine. */
     private outerTriggerLines;
     /** Told when text is inserted into the line a trigger is matching, so the
      *  runtime can move the capture positions it recorded at match time —
      *  otherwise `selectCaptureGroup` after an `insertText` selects the text
-     *  that has since slid to where the capture used to be. */
+     *  that has since slid to where the capture used to be. `replaced` is the
+     *  length a `replace` took out at `at`, absent for an insert. */
     private captureShiftHook;
-    setCaptureShiftHook(fn: ((at: number, delta: number) => void) | null): void;
+    setCaptureShiftHook(fn: ((at: number, delta: number, replaced?: number) => void) | null): void;
+    /**
+     * What triggers have done to the text of each line being processed, in
+     * the order they did it and each in the columns the line had at the time
+     * (TBuffer::mTriggerPassLineEdits). A stack parallel to
+     * {@link lineColorLive}, as a trigger may feed a line of its own.
+     *
+     * Every trigger matches the line as it ARRIVED, so a later trigger's capture
+     * positions are in the arrived columns; {@link passSpanNow} moves them past
+     * what earlier triggers inserted, deleted or replaced before they are
+     * highlighted, selected or replaced.
+     */
+    private passLineEdits;
+    /**
+     * Record an edit to `buf`'s text against every pass running on that line
+     * (TBuffer::noteTriggerPassLineEdit). A removal followed by an insertion at
+     * the same column is one replacement, so a column inside the removed text
+     * is not pushed past what went in its place (appendTriggerPassLineEdit).
+     */
+    private noteTriggerPassLineEdit;
+    /**
+     * Where a stretch of the innermost pass line, given in the columns the line
+     * arrived with, is now (TBuffer::triggerPassSpanNow). Text replacing part of
+     * the stretch counts as part of it; text put in at either end does not.
+     */
+    passSpanNow(span: {
+        start: number;
+        length: number;
+    }): {
+        start: number;
+        length: number;
+    };
+    /** Whether text triggers earlier in the innermost pass edited its line. */
+    passLineEdited(): boolean;
     /**
      * Flush echo output collected during the just-processed line's trigger run.
      * Called once per line (right after that line is rendered) so a trigger's
@@ -1026,15 +1500,37 @@ export declare class ScriptingAPI {
      */
     flushDeferredEcho(): void;
     /** Raw tail of the last {@link feedTriggers} call that had no trailing
-     *  newline, carried into the next one — see there. */
-    private feedTriggersRemainder;
-    /**
-     * Feed `text` through the trigger pipeline as if it arrived from the MUD.
+     *  newline, held until later data completes it — see feedTriggersText. */
+    private heldFeedText;
+    /** Hand over the held unterminated fed text, for the next batch to lead
+     *  with. The server's next lines complete it as well as a later feed does:
+     *  Mudlet runs both through the one TBuffer. */
+    takeHeldFeedText(): string;
+    /**
+     * Feed bytes through the trigger pipeline as if they arrived from the MUD.
      * Routes complete lines through ScriptingEngine.processFlushBatch (same
      * code path as network-driven flushLines) so trigger ordering, ANSI carry,
      * and deferred-echo placement match exactly.
+     *
+     * `data` is a byte-string (the Lua binding unarmors it — see byteArmor.ts).
+     * `utf8Encoded` says how to read it, and it is the caller's promise rather
+     * than a guess:
+     *
+     *  - true (the default) — the bytes are UTF-8. Mudlet transcodes them into
+     *    the game's encoding before display, so text the encoding cannot carry
+     *    is REFUSED rather than mangled: a script feeding an accented character
+     *    to an ASCII game has made a mistake it needs to hear about, and the
+     *    transcode is lossless otherwise, so refusing costs nothing real.
+     *  - false — the older form, where the caller has already encoded the bytes
+     *    themselves. They pass through untouched, decoded with the game's own
+     *    encoding rather than read as UTF-8 and double-encoded.
+     *
+     * Returns null when the text was fed, or the refusal message; the binding
+     * shapes that into Mudlet's `true` / `(nil, errMsg)`.
      */
-    feedTriggers(text: string): boolean;
+    feedTriggers(data: string, utf8Encoded?: boolean): string | null;
+    /** The feed itself, once {@link feedTriggers} has settled what the bytes say. */
+    private feedTriggersText;
     /**
      * Mudlet `getCurrentLine([window])`. Returns the text on the cursor's
      * current line, or `null` when the named window doesn't exist — the Lua
@@ -1045,6 +1541,11 @@ export declare class ScriptingAPI {
     getLineNumber(windowName?: string): number;
     getLineCount(windowName?: string): number;
     getLastLineNumber(windowName?: string): number;
+    /** Whether a trigger pass is under way (TriggerUnit::processingDepth). */
+    get triggerPassActive(): boolean;
+    /** Whether `con` is the main console mid trigger pass — the one time it has
+     *  no open line past the last complete one. */
+    private inTriggerPass;
     disableScrollBar(windowName?: string): void;
     enableScrollBar(windowName?: string): void;
     disableHorizontalScrollBar(windowName?: string): void;
@@ -1061,26 +1562,42 @@ export declare class ScriptingAPI {
      *  this console. True unless disableScrolling was called on it; the main
      *  window is always scrollable. */
     scrollingActive(windowName?: string): boolean;
-    /** Mudlet getScroll — 0-indexed buffer line at the top of the viewport. In
-     *  tail mode reports the last line (Mudlet's mCursorY behaviour at end). */
+    /** Mudlet getScroll — the buffer line the console is scrolled to, which
+     *  desktop counts as the first line below the scrolled view (its bottom row
+     *  plus one), the same edge scrollTo(window, line) puts a line on.
+     *  Desktop answers `max(min(mCursorY, getLastLineNumber()), 0)`
+     *  (TMainConsole::getWindowScroll), so a console following its output
+     *  reports exactly getLastLineNumber() — the comparison scripts use to ask
+     *  "am I at the bottom?" — and never a line past it. */
     getScroll(windowName?: string): number;
-    /** Mudlet scrollTo. With no line (or a line past end), resume tail mode.
-     *  Negative line counts back from the buffer end. */
+    /** Mudlet scrollTo. With no line (or a line at or past the last one),
+     *  resume tail mode. Negative line counts back from the buffer end. False
+     *  only where desktop does nothing (scrolling disabled); Bridge.lua drops
+     *  the result either way, as desktop's scrollTo returns nothing. */
     scrollTo(windowName: string | undefined, lineNumber: number | undefined): boolean;
-    getLines(from: number, to: number, windowName?: string): string[];
+    /** Whether the console follows its output (desktop's
+     *  `windowFollowsNewLines`), which scrollUp/scrollDown count from: while
+     *  a trigger runs, getScroll still answers the end as it was before the
+     *  packet, but a console at its end scrolls from the end it has now. */
+    windowFollowsNewLines(windowName?: string): boolean;
+    /** Null when the window doesn't exist — the binding answers Mudlet's
+     *  `(nil, errMsg)` then, not an empty table a `if not t` check can't see. */
+    getLines(from: number, to: number, windowName?: string): string[] | null;
     /**
      * Mudlet `getTimestamp([window,] lineNumber)` — the wall-clock time the line
-     * entered the buffer, formatted "HH:MM:SS.mmm" (Mudlet's "hh:mm:ss.zzz").
-     * `lineNumber` is 1-based to match `getLines`; omit it for the current
-     * cursor line. Returns null when the window or line doesn't exist — the Lua
+     * entered the buffer, formatted as Mudlet's "hh:mm:ss.zzz " (13 characters,
+     * trailing space included), or "------------ " for a line wrapping continued. `lineNumber` counts
+     * from 0 as getLineNumber() does, 0 itself refused (see
+     * Console.getLineTimestamp); omit it for the current cursor line. Returns null when the window or line doesn't exist — the Lua
      * binding maps that to Mudlet's `(nil, errMsg)` shape.
      */
     getTimestamp(lineNumber?: number, windowName?: string): string | null;
     /**
-     * Mudlet `wrapLine([window,] lineNumber)`. Re-displays the line at
-     * `lineNumber` (0-indexed, like getLineNumber/getLineCount), re-interpreting
-     * its embedded `\n` and re-wrapping to the current width. Returns false when
-     * the window or line doesn't exist.
+     * Mudlet `wrapLine([window,] lineNumber)`. Re-wraps the buffer from the line
+     * at `lineNumber` (0-indexed, like getLineNumber/getLineCount) to its end,
+     * re-interpreting embedded `\n` and splitting to the current width, as
+     * TBuffer::wrapLine does. Returns false when the window or line doesn't
+     * exist; the Lua binding returns nothing either way, as desktop does.
      */
     wrapLine(lineNumber: number, windowName?: string): boolean;
     /**
@@ -1129,21 +1646,33 @@ export declare class ScriptingAPI {
      */
     getRowCount(windowName?: string): number;
     /**
-     * Mudlet setWindowWrap(name, charsPerLine). Sets the visual wrap width
-     * (in monospace columns) for the named window or "main". 0 clears the
-     * setting. Returns false when the named window does not exist; main always
-     * succeeds (persisted on the active profile).
+     * Mudlet setWindowWrap(name, charsPerLine). Sets the wrap width (in
+     * monospace columns) for the named window, buffer or "main", and re-applies
+     * it to the lines the console stores from then on. 0 clears the setting,
+     * back to the default (100 for main, no wrap for a window); the Lua binding
+     * refuses it as Mudlet does. Returns false when the named window does not
+     * exist; main always succeeds (persisted on the active profile, as Mudlet
+     * keeps it in Host::mWrapAt).
      */
     setWindowWrap(name: string, wrapAt: number): boolean;
+    /** The main console's wrap width: the profile's `outputWrapAt`, which is
+     *  Mudlet's Host::mWrapAt (100 unless changed). 0 means the Settings UI
+     *  turned character wrapping off. */
+    private mainWrapAt;
+    /** `[wrapAt, indent, hangingIndent]` for a console, 0 meaning off. Main
+     *  reads the profile, an on-screen window its WindowManager entry, and a
+     *  createBuffer buffer the Console it lives in. */
+    private wrapSettings;
     /** Tell the console the width to break stored lines at, so what `getLines`
      *  reports matches what the window shows. Called whenever the wrap width or
-     *  either indent moves. */
+     *  either indent moves, and for main when the API is created. */
     private applyStoredWrap;
     /**
-     * Mudlet `getWindowWrap(name) → cols`. Reports the visual wrap width set by
-     * setWindowWrap (0 when unset). For "main" reads the profile's stored
-     * override; for a named window reads the WindowManager hint. Returns -1 when
-     * the named window does not exist (Mudlet's invalid-window sentinel).
+     * Mudlet `getWindowWrap(name) → cols` — TConsole::getWrapAt, the width the
+     * console's buffer wraps at. Main defaults to 100 (Host::mWrapAt) and a
+     * createBuffer buffer to main's width when it was made; a miniconsole or
+     * user window no script has set reports TBuffer's own 99999999. Returns -1
+     * when the named window does not exist (Mudlet's invalid-window sentinel).
      */
     getWindowWrap(name: string): number;
     /**
@@ -1160,7 +1689,7 @@ export declare class ScriptingAPI {
     setWindowWrapHangingIndent(name: string, indent: number): boolean;
     /**
      * Mudlet `setMapWindowTitle(title)`. Sets the dockable map panel's tab
-     * title; an empty string resets it to the default ("Map"). Returns false
+     * title; an empty string resets it to the default ("Map - <profile>"). Returns false
      * when the map widget isn't open.
      */
     setMapWindowTitle(title: string): boolean;
@@ -1172,17 +1701,23 @@ export declare class ScriptingAPI {
      * when the cursor isn't on a valid line yet (empty buffer / sub-window
      * without a backing buffer).
      */
-    insertText(text: string, windowName?: string): void;
+    insertText(text: string, windowName?: string): boolean;
     /**
      * Mudlet `insertLink([window,] text, cmd, hint, [useCurrentFormat])`.
      * Like `insertText` but the inserted span is a clickable link bound to
-     * `cmd`. With `useCurrentFormat=false` (the default) the link inherits
-     * Mudlet's built-in style — blue foreground + underline — layered on top
-     * of the current pen state. If no buffer is available (empty console,
+     * `cmd`. With `useCurrentFormat=false` (the default) the link gets
+     * Mudlet's standard link format — link blue + underline, nothing of the
+     * current pen ({@link standardLinkState}). If no buffer is available (empty console,
      * sub-window without backing buffer) the call degrades to `echoLink` so
      * the text isn't lost.
      */
     insertLink(text: string, cmd: string, tooltip: string, windowName?: string, useCurrentFormat?: boolean): void;
+    /**
+     * The wrapLine() TConsole::insertText and insertLink run after an insert
+     * that broke the line: what the newline left on each side of it is
+     * wrapped to the console's width, from the line the insert began on.
+     */
+    private rewrapInserted;
     /**
      * Mudlet `moveCursorUp([window,] [lines=1,] [keepHorizontal=false]) → bool`.
      * `keepHorizontal=true` preserves the column across the vertical move; the
@@ -1224,7 +1759,9 @@ export declare class ScriptingAPI {
      * and `DOCK` tab groups. This just owns the manager and satisfies its host
      * interface below. `dest` is the `<DEST>` frame open when the tag was parsed.
      */
-    mxpFrame(name: string, attrs: Record<string, string>, dest?: string): void;
+    /** Whether an MXP frame of this name is open for a `<DEST>` to write to. */
+    mxpHasFrame(name: string): boolean;
+    mxpFrame(name: string, attrs: Record<string, string>, dest?: string): boolean;
     /** Tear every MXP frame down. MXP frames are per-connection state in Mudlet
      *  (TMxpFrameManager::resetAllFrames), so a reconnect starts from a clean
      *  main window rather than inheriting the last session's layout. */
@@ -1235,7 +1772,7 @@ export declare class ScriptingAPI {
      * in the main window, matching Mudlet). `eof` clears the frame first — the
      * status-frame "replace contents" idiom.
      */
-    mxpWriteToFrame(name: string, buffer: AnsiAwareBuffer, eof: boolean): boolean;
+    mxpWriteToFrame(name: string, buffer: AnsiAwareBuffer, eof: boolean, eol?: boolean): boolean;
     /** Frames that have been written with `<DEST … EOF>` at least once, i.e. the
      *  server treats them as replace-contents panes. Learned rather than
      *  declared: MXP has no attribute for it. */
@@ -1251,32 +1788,57 @@ export declare class ScriptingAPI {
     createBuffer(name: string): void;
     /** True when `name` is an off-screen buffer created via createBuffer. */
     isBuffer(name: string): boolean;
+    /** showWindow / hideWindow on a buffer: desktop finds it and flips the
+     *  flag windowVisible reads back. False when `name` is no buffer. */
+    setBufferVisible(name: string, visible: boolean): boolean;
+    /** moveWindow on a buffer — kept for getWindowGeometry to report. */
+    moveBuffer(name: string, x: number, y: number): boolean;
+    /** resizeWindow on a buffer — kept for getWindowGeometry to report. */
+    resizeBuffer(name: string, width: number, height: number): boolean;
     /**
      * Mudlet `copy([window])`. Copies the current selection of the resolved
      * console — including all formatting — into the session clipboard, a single
      * rich-text buffer shared with `paste`/`appendBuffer` (Mudlet's host-global
-     * mClipboard). No-op when there's no selection, or when `window` is given
-     * but doesn't own the active selection.
-     */
-    copy(windowName?: string): void;
+     * mClipboard).
+     *
+     * Like Host::copyToClipboard it ALWAYS replaces the clipboard with the named
+     * console's selection (main when omitted) — when that console has none
+     * (after a failed selectString, a deselect(), or a selection that belongs to
+     * another window) the clipboard becomes empty, and a following appendBuffer
+     * appends an empty line. Keeping the previous clipboard instead re-appended
+     * stale text. Only an unknown window leaves the clipboard alone (desktop
+     * raises "window not found" there). TBuffer::copy resets a start outside
+     * the line to column 0, which is reproduced too.
+     */
+    copy(windowName?: string): boolean;
+    /** The Lua code of every scripted link the named console's lines hold, for
+     *  Bridge.lua to let go of the functions a clear takes off the screen. */
+    consoleLinkCommands(win?: string): string[];
+    /** Of the link `commands` given, the ones some console still shows. */
+    linkCommandsShown(commands: string[]): string[];
+    /** The Lua code of every scripted link in the clipboard, for Bridge.lua to
+     *  hold a reference of the clipboard's own to each function a link calls,
+     *  as TBuffer's copied TLinkStore does in desktop. */
+    clipboardLinkCommands(): string[];
     /**
      * Mudlet `cut()`. `copy()` and then delete what was copied, so the clipboard
      * holds exactly the text the line lost (TConsole::cut → TBuffer::cut). Takes
      * no window argument in Mudlet — it always acts on the main console — and is
      * a no-op without a selection there.
      */
-    cut(): void;
+    cut(windowName?: string): boolean;
     /**
      * Mudlet `appendBuffer([window])`. Appends the clipboard's rich text (from
-     * the last `copy()`) as a new line at the end of the named console's buffer.
-     * No-op until something has been copied. Mirrors TConsole::appendBuffer.
+     * the last `copy()`) onto the end of the named console's last line, then
+     * ends that line. No-op until something has been copied. Mirrors
+     * TConsole::appendBuffer.
      */
     appendBuffer(windowName?: string): void;
     /**
      * Mudlet `paste([window])`. Inserts the clipboard at the cursor's current
-     * column when the cursor sits above the last line; otherwise appends it as
-     * a new line at the end (TConsole::paste semantics). No-op without a prior
-     * copy().
+     * column when the cursor sits above the last line; otherwise writes it onto
+     * the end of the last line and ends that line (Host::pasteClipboardInto).
+     * No-op without a prior copy().
      */
     paste(windowName?: string): void;
     /**
@@ -1288,7 +1850,7 @@ export declare class ScriptingAPI {
      * MAPPER_WIDGET_ID) so a script or a MUD cannot name a window over them.
      * Both render the same MapStore and stay in sync. Returns true on success.
      */
-    createMapper(x: number, y: number, width: number, height: number, parent?: string): boolean;
+    createMapper(x: number, y: number, width: number, height: number, parent?: string): true | string;
     /**
      * Mudlet `setWindow(windowName, name[, x, y, show])` — move an element
      * (label, overlay command line, text edit, scroll box, or a miniconsole /
@@ -1301,10 +1863,15 @@ export declare class ScriptingAPI {
     /**
      * Mudlet `getWindowGeometry(name)` → x, y, width, height. Reads back the
      * stored geometry the move/resizeWindow setters write, following the same
-     * routing precedence they use (labels → command lines → text edits →
-     * scroll boxes → user windows/miniconsoles). Null when no widget of any
+     * routing precedence they use (labels → scroll boxes → command lines →
+     * text edits → user windows/miniconsoles). Null when no widget of any
      * kind owns the name; `"main"` is deliberately excluded because
      * moveWindow/resizeWindow don't act on it either.
+     *
+     * The scroll box comes before the other overlays for the reason windowType
+     * puts it there: one name can be a scroll box AND a text edit at once, and
+     * every by-name lookup has to give the same answer as the last one until
+     * the scroll box is deleted.
      */
     getWindowGeometry(name: string): {
         x: number;
@@ -1320,7 +1887,8 @@ export declare class ScriptingAPI {
      * visible. Null when the name belongs to no widget, or is `"main"`.
      */
     windowVisible(name: string): boolean | null;
-    /** A widget's own visible flag, ignoring ancestors. Null when unknown. */
+    /** A widget's own visible flag, ignoring ancestors. Null when unknown. One
+     *  name worn by more than one overlay is the one windowType() names. */
     private ownVisibility;
     /** The name a widget is nested under, or null once the chain reaches a root. */
     private parentOf;
@@ -1330,7 +1898,10 @@ export declare class ScriptingAPI {
      * widget, which Mudlet reports as an error rather than an empty string.
      */
     getLabelText(name: string): string | null;
-    setWindow(windowName: string, name: string, x?: number, y?: number, show?: boolean): boolean;
+    /** A move that would make a parent cycle answers desktop's refusal message
+     *  (TMainConsole::reparentWindow) rather than false, for Bridge.lua to
+     *  return as (nil, message). */
+    setWindow(windowName: string, name: string, x?: number, y?: number, show?: boolean): boolean | string;
     /**
      * Mudlet `replace([win,] with, [keepcolor])`. Default (`keepcolor=false`)
      * applies the resolved console's current pen state (set via
@@ -1347,11 +1918,15 @@ export declare class ScriptingAPI {
      */
     deleteLine(windowName?: string): void;
     appendCmdLine(text: string): void;
-    printCmdLine(text: string): void;
+    /** Mudlet printCmdLine, which leaves the caret at the end with nothing
+     *  selected (TMainConsole's putTextOnCommandLine); `selectAll` is
+     *  sendCmdLine's setCommandLineText, which selects what it put there — the
+     *  form a link PROMPT takes on desktop too. */
+    printCmdLine(text: string, selectAll?: boolean): void;
     clearCmdLine(): void;
     /**
      * Mudlet selectCmdLineText([commandLine]). Selects (highlights) all text in
-     * the command bar so the next keystroke overtypes it. mudix has a single
+     * the command bar so the next keystroke overtypes it. Mudlet Web has a single
      * main command bar; a named overlay command-line arg is accepted for
      * compatibility but only "main"/omitted is acted upon. The actual DOM
      * selection happens in ProfileSession, which owns the input ref.
@@ -1359,34 +1934,78 @@ export declare class ScriptingAPI {
     selectCmdLineText(name?: string): void;
     /**
      * Mudlet setCommandBackgroundColor([windowName], r, g, b, [transparency]).
-     * Recolors the command bar's background. mudix only has the main command
+     * Recolors the command bar's background and the echoed commands
+     * (Host::mCommandBgColor). Mudlet Web only has the main command
      * bar, so a non-"main" windowName is ignored. `a` is Mudlet's 0..255 alpha;
      * the CommandBar reads the `inputBackground` profile field as a CSS color.
      */
     setCommandBackgroundColor(r: number, g: number, b: number, a?: number, name?: string): boolean;
-    /** Mudlet setCommandForegroundColor — recolors the command bar text. */
+    /** Mudlet setCommandForegroundColor — recolors the command bar text and
+     *  the echoed commands (Host::mCommandFgColor). */
     setCommandForegroundColor(r: number, g: number, b: number, a?: number, name?: string): boolean;
     private cmdLineValue;
     private cmdLineProvider;
     /** Registered by ProfileSession while a command bar is mounted; read only
      *  before the first {@link setCmdLineValue} has mirrored anything. */
     setCmdLineProvider(fn: (() => string) | null): void;
-    /** Mirror a command-bar edit (user typing, history recall, submit-clear). */
+    /** Mirror a command-bar edit (user typing, history recall, submit-clear).
+     *  While the game asks for hidden input the bar is the hidden-input box,
+     *  whose text — a password — is no command line's to read. */
     setCmdLineValue(text: string): void;
     getCmdLine(): string;
+    /**
+     * What the main command line holds while the game asks for hidden input
+     * (it has taken the ECHO option), or null when it is not asking. Desktop
+     * lays a separate hidden-input box over the command line for the password:
+     * the command line keeps what was in it — getCmdLine reads that — and what
+     * printCmdLine writes, or the player types, goes into the box, never to be
+     * read back. Mudlet Web draws the box in the command bar itself
+     * (ProfileSession puts the command aside and brings it back), so the
+     * command line is kept here for scripts.
+     */
+    private hiddenInputCommand;
+    beginHiddenInput(command: string): void;
+    endHiddenInput(): void;
     private cmdLineSuggestions;
-    addCmdLineSuggestion(suggestion: string): void;
-    removeCmdLineSuggestion(suggestion: string): void;
-    clearCmdLineSuggestions(): void;
-    getCmdLineSuggestions(): string[];
-    private emitCmdLineSuggestions;
     private cmdLineBlacklist;
-    addCmdLineBlacklist(word: string): void;
-    removeCmdLineBlacklist(word: string): void;
-    clearCmdLineBlacklist(): void;
-    getCmdLineBlacklist(): string[];
+    private completionList;
+    addCmdLineSuggestion(suggestion: string, cmdLine?: string): void;
+    removeCmdLineSuggestion(suggestion: string, cmdLine?: string): void;
+    clearCmdLineSuggestions(cmdLine?: string): void;
+    getCmdLineSuggestions(cmdLine?: string): string[];
+    private emitCmdLineSuggestions;
+    addCmdLineBlacklist(word: string, cmdLine?: string): void;
+    removeCmdLineBlacklist(word: string, cmdLine?: string): void;
+    clearCmdLineBlacklist(cmdLine?: string): void;
+    getCmdLineBlacklist(cmdLine?: string): string[];
     private emitCmdLineBlacklist;
+    /** A deleted command line takes its lists with it; one made later under
+     *  the same name starts empty, as a new TCommandLine does. */
+    forgetCmdLineCompletion(cmdLine: string): void;
+    /** The Tab-completion pool for command line `cmdLine` as it stands now:
+     *  the main console's last 500 lines, then the line's suggestions, less
+     *  its blacklist — what TCommandLine::handleTabCompletion assembles on
+     *  every press. Every command line reads the MAIN console's buffer. */
+    cmdLineCompletionWords(cmdLine?: string): string[];
     private saveCommandHistoryFlags;
+    /** Which file each command line's history is kept in. Assigned on creation
+     *  and never reused, because two command lines sharing one file would
+     *  overwrite each other's history on the next save. */
+    private readonly cmdLineHistoryFiles;
+    private nextHistoryFile;
+    /** Register a command line's history file, returning its name. */
+    noteCommandLineForIni(cmdLineName: string): string;
+    forgetCommandLineForIni(cmdLineName: string): void;
+    /**
+     * The profile's `profile.ini`, in the shape QSettings writes it.
+     *
+     * Mudlet keeps this file open and lets QSettings flush it on the next pass
+     * through the event loop, so what a command line records reaches the disk
+     * without anyone asking for a save. Two things live under [CommandLines]:
+     * which file each one's history goes in, written when it is created, and
+     * whether it saves history at all, written with the end-of-session save.
+     */
+    profileIniContent(): string;
     saveCommandHistoryFor(cmdLineName: string): boolean;
     setSaveCommandHistoryFor(cmdLineName: string, save: boolean): void;
     /**
@@ -1400,7 +2019,7 @@ export declare class ScriptingAPI {
      * the profile-wide save size. Both switches have to be on: the size, and the
      * command line's own flag.
      *
-     * Only the main bar has a history to write. mudix's Geyser command lines
+     * Only the main bar has a history to write. Mudlet Web's Geyser command lines
      * keep none, so unlike Mudlet there are no numbered files beside it — the
      * shape is here rather than a bare `saveMainHistory()` so that one gaining a
      * history is a change in this function alone.
@@ -1436,11 +2055,11 @@ export declare class ScriptingAPI {
     /**
      * Get (or create) a `<style>` tag in `document.head` owned by this profile.
      *
-     * Every tag mudix installs on a script's behalf is stamped with the owning
-     * connection id, both in its element id and in `data-mudix-style-owner`, so
+     * Every tag Mudlet Web installs on a script's behalf is stamped with the owning
+     * connection id, both in its element id and in `data-mudlet-style-owner`, so
      * {@link destroy} can take them all down again. Mudlet's `setAppStyleSheet`
      * is genuinely application-wide (a QApplication stylesheet shared by every
-     * open profile), but a mudix tab hosts one profile at a time: leaving a
+     * open profile), but a Mudlet Web tab hosts one profile at a time: leaving a
      * closed profile's CSS installed silently restyled the *next* profile opened
      * in that tab. So all three setters — app, profile and per-window — are
      * profile-local here, and torn down with the profile.
@@ -1450,14 +2069,28 @@ export declare class ScriptingAPI {
     private removeOwnedStyleTags;
     setAppStyleSheet(css: string, tag?: string): boolean;
     setUserWindowStyleSheet(name: string, css: string): boolean;
-    /** Mudlet `getUserWindowStyleSheet(name)` — the QSS as it was set. */
+    /** Mudlet `getUserWindowStyleSheet(name)` — the QSS as it was set: the
+     *  window's own, or else the profile's, which desktop sets on every dock. */
     getUserWindowStyleSheet(name: string): string;
+    /** A user window was just made (not re-shown): it starts with the profile
+     *  stylesheet, not with whatever an earlier window of its name was given. */
+    noteUserWindowOpened(name: string): void;
+    /** Drop a user window's own stylesheet, and the `<style>` tag carrying it. */
+    private forgetUserWindowStyleSheet;
     private readonly userWindowCss;
+    /** What setProfileStyleSheet was last given. */
+    private profileCss;
     /** Mudlet `getCmdLineStyleSheet([name])`. Same story as above: the command
      *  line's authored QSS, not the CSS the overlay ends up with. "main" is the
      *  default and has no widget of its own to read back from. */
     getCmdLineStyleSheet(name: string): string;
+    /** The stylesheet a sub command line is created with — the profile's command
+     *  line background, in the shape Mudlet's TCommandLine builds. */
+    bornCmdLineStyleSheet(): string;
     noteCmdLineStyleSheet(name: string, css: string): void;
+    /** Whether a command line's stylesheet has been recorded at all — born or
+     *  set — as opposed to recorded as "". */
+    hasCmdLineStyleSheet(name: string): boolean;
     private readonly cmdLineCss;
     /**
      * Mudlet `setProfileStyleSheet(stylesheet)`. Installs (or replaces) a
@@ -1468,7 +2101,7 @@ export declare class ScriptingAPI {
      *
      * Deliberately raises NO sysAppStyleSheetChange: that event announces an
      * *application*-level change, and a profile sheet is not one. Raising it
-     * here (as mudix used to) told every profile-agnostic theme handler to
+     * here (as Mudlet Web used to) told every profile-agnostic theme handler to
      * re-apply itself over a change that was never theirs.
      */
     setProfileStyleSheet(css: string): boolean;
@@ -1487,7 +2120,7 @@ export declare class ScriptingAPI {
      * and return the current mirror synchronously, matching Mudlet's signature.
      */
     getClipboardText(): string;
-    centerView(roomId: number): boolean;
+    centerView(roomId: number, viewId?: number): boolean | string;
     /** Mudlet `createMapView([areaID])` → the new view id, or the refusal
      *  message when the areaID names no area. */
     createMapView(areaId: number): number | string;
@@ -1508,20 +2141,20 @@ export declare class ScriptingAPI {
     /**
      * Mudlet `getMapZoom([areaID])` — the number of map units visible across the
      * viewport's shorter edge. Mudlet keeps this on the area (TArea's
-     * `mLast2DMapZoom`, reached via TRoomDB::get2DMapZoom), so it answers with
-     * no mapper mounted and each area remembers its own; mudix stores it the
-     * same way. Without an areaID the live renderer's current zoom wins when one
+     * `mLast2DMapZoom`, reached via TRoomDB::get2DMapZoom), so each area
+     * remembers its own; Mudlet Web stores it the same way. Desktop still refuses
+     * the call until a mapper exists ("no active mapper"), whichever area is asked. Without an areaID the live renderer's current zoom wins when one
      * is mounted. Undefined for an areaID that doesn't exist — the binding
      * reports that as `(nil, errMsg)`.
      */
-    getMapZoom(areaID?: number): number | undefined;
+    getMapZoom(areaID?: number, viewId?: number): number | undefined | string;
     /**
      * Mudlet `setMapZoom(zoom [, areaID])`. Like Mudlet the zoom must be at
      * least 3.0, and an areaID that doesn't exist is refused. Stored on the area
      * and pushed to the live renderer when one is mounted. Returns the refusal
      * message, or null on success, for the binding to shape.
      */
-    setMapZoom(zoom: number, areaID?: number): string | null;
+    setMapZoom(zoom: number, areaID?: number, viewId?: number): string | null;
     /** The area the 2D view is showing — the player's room's area, falling back
      *  to the default area when there is no player room yet. */
     private currentMapArea;
@@ -1570,7 +2203,7 @@ export declare class ScriptingAPI {
      * this method only deals in already-decoded bytes. Returns true unless the
      * panel reported a parse failure for the given buffer.
      */
-    loadMap(buf?: Uint8Array): boolean;
+    loadMap(buf?: Uint8Array, source?: string): boolean;
     /**
      * Mudlet `saveMap([location])`. Serialises the current MapStore to the
      * Mudlet binary `.dat` format and persists it to the connection's default
@@ -1586,11 +2219,20 @@ export declare class ScriptingAPI {
     loadMapXml(xmlText: string): boolean;
     /** Mudlet `saveJsonMap(path)` backbone — serialises the current MapStore
      *  as JSON. The Lua binding writes the result to the supplied VFS path. */
+    /** The map as Mudlet's JSON, carrying the map-level settings that live in
+     *  the profile rather than in the map store — Mudlet writes them into the
+     *  same file, so a map moved between clients keeps the way it looks. */
     saveJsonMap(): string;
+    /** Desktop's player-room marker settings as saveJsonMap writes them — see
+     *  there. Desktop's Host defaults until a file brings its own. */
+    private jsonPlayerRoom;
+    /** The counterpart of the extras {@link saveJsonMap} writes: an imported
+     *  file's map-level settings, applied after the rooms have loaded. */
+    applyJsonMapSettings(doc: Record<string, unknown>): void;
     /** Mudlet `loadJsonMap(path)` backbone — parse a JSON payload previously
      *  produced by saveJsonMap and reload the map. Returns false when the
      *  JSON is malformed or doesn't match the MudletMap shape. */
-    loadJsonMap(json: string): boolean;
+    loadJsonMap(json: string, source?: string): boolean;
     /** Mudlet `addSupportedTelnetOption(option)`. Forwarded to the session
      *  client so the next IAC WILL/DO from the server can be auto-accepted. */
     addSupportedTelnetOption(option: number): boolean;
@@ -1598,9 +2240,11 @@ export declare class ScriptingAPI {
      * Mudlet `saveWindowLayout()` — capture the current layout (window hints
      * + dock area extents) into a per-connection snapshot in the persisted
      * app store. A later `loadWindowLayout()` re-applies the captured state.
-     * Returns true on success, false when no connectionId is bound.
+     * Returns true on success, false when no connectionId is bound or the
+     * layout file cannot be written — what desktop reports when it cannot open
+     * `windowLayout.dat`.
      */
-    saveWindowLayout(): boolean;
+    saveWindowLayout(): boolean | string;
     /** Where Mudlet keeps the window layout: beside the profiles folder, not
      *  inside one, because the layout is the application's rather than any one
      *  profile's. Null when there is no VFS to write into. */
@@ -1612,7 +2256,7 @@ export declare class ScriptingAPI {
      * Mudlet-shaped copy, so a script (or a person poking at the profile
      * filesystem) finds the layout where Mudlet puts it and can read it. It is
      * JSON rather than Mudlet's `QMainWindow::saveState` blob: nothing outside
-     * mudix reads it, and those bytes describe Qt dock widgets that have no
+     * Mudlet Web reads it, and those bytes describe Qt dock widgets that have no
      * counterpart here.
      */
     private writeWindowLayoutFile;
@@ -1626,6 +2270,9 @@ export declare class ScriptingAPI {
      * but are not currently mounted. Returns false when no snapshot exists.
      */
     loadWindowLayout(): boolean;
+    /** True while {@link loadWindowLayout} is placing windows — the resize
+     *  events it raises run handlers before it returns. */
+    private layoutLoading;
     /**
      * Mudlet `getTime()` — current local time as a record. The Bridge.lua wrapper
      * picks fields off this object for the `{year, month, day, hour, min, sec,
@@ -1641,10 +2288,15 @@ export declare class ScriptingAPI {
         sec: number;
         msec: number;
         wday: number;
+        tzAbbr: string;
+        tzOffset: string;
+        tzOffsetColon: string;
+        tzLong: string;
     };
     /**
-     * Mudlet `getNetworkLatency()` — round-trip time of the most recent
-     * keep-alive ping. Returns the last measured value (in ms) for as long as
+     * Mudlet `getNetworkLatency()` — the most recent round trip measured,
+     * from a command to the game's next GA/EOR prompt marker (as Mudlet
+     * times it). Returns the last measured value (in ms) for as long as
      * the connection is up; -1 when no measurement has been made yet (mirrors
      * Mudlet's "not yet measured" sentinel — better than a fake 0 which would
      * read as "instant" in scripts charting latency).
@@ -1652,10 +2304,14 @@ export declare class ScriptingAPI {
     getNetworkLatency(): number;
     private lastPingMs;
     getMainWindowSize(): [number, number];
+    /** Mudlet `setMainWindowSize(width, height)`. Sizes the main viewport —
+     *  the rectangle {@link getMainWindowSize} reports — since a browser tab
+     *  cannot resize itself. See WindowManager.setMainWindowSize. */
+    setMainWindowSize(width: number, height: number): boolean;
     /**
      * Mudlet `hasFocus([window])` → bool. Reports whether the named console (or
      * the main command bar / output area when omitted) currently holds keyboard
-     * focus. mudix maps "main"/omitted to the command input, and a named window
+     * focus. Mudlet Web maps "main"/omitted to the command input, and a named window
      * to its registered overlay element. Returns false when nothing matches.
      */
     hasFocus(windowName?: string): boolean;
@@ -1672,17 +2328,24 @@ export declare class ScriptingAPI {
      * Mudlet `getMainConsoleWidth()` — pixel width of the main console's text
      * area. Mudlet computes `averageCharWidth * (wrapAt + 1)`; we mirror that
      * with a canvas-measured monospace cell for the profile's output font, and
-     * resolve the wrap column from the profile's `outputWrapAt` override (the
-     * value `setWindowWrap("main", n)` writes), falling back to the live
-     * measured column count when no explicit wrap is set.
+     * the main wrap column (`outputWrapAt`, 100 by default), falling back to
+     * the live measured column count when the Settings turned wrapping off.
      */
     getMainConsoleWidth(): number;
+    /** The server the last connectToServer() pointed the profile at, with the
+     *  dial it asked for — see {@link getConnectionInfo}. */
+    private connectTarget;
     /**
      * Mudlet `getConnectionInfo()` → `host, port, connected`. Mudlet reports the
-     * MUD's telnet host/port; mudix reads them off the active connection config.
-     * For a `mud`-mode connection those are the stored host/port; for a raw
-     * `websocket` connection we parse them out of the endpoint URL (port falls
-     * back to the ws/wss default). `connected` reflects the live session status.
+     * MUD's telnet host/port — cTelnet's own, which `connectToServer` replaces
+     * whether or not it saves them, so a script that moved the profile to
+     * another server is told that server from the call on, through a failed
+     * dial and a `reconnect()` (mudlet-web#339). That target holds until a dial
+     * to somewhere else (the Connect button redialling the profile) overtakes
+     * it. Otherwise Mudlet Web reads the active connection config: for a
+     * `mud`-mode connection the stored host/port, for a raw `websocket` one the
+     * endpoint URL's (port falls back to the ws/wss default). `connected`
+     * reflects the live session status.
      */
     getConnectionInfo(): {
         host: string;
@@ -1690,7 +2353,7 @@ export declare class ScriptingAPI {
         connected: boolean;
     };
     /**
-     * Mudlet `connectToServer(host, port [, save])`. mudix tunnels MUD traffic
+     * Mudlet `connectToServer(host, port [, save])`. Mudlet Web tunnels MUD traffic
      * through a WebSocket proxy, so this builds the same `proxy?host=&port=` URL
      * the connection screen uses and (re)connects the live session. With `save`,
      * the host/port are persisted onto the active connection (switching it to
@@ -1757,17 +2420,36 @@ export declare class ScriptingAPI {
      */
     setFontSize(size: number, win?: string): boolean;
     /**
-     * Mudlet setMiniConsoleFontSize. Strictly targets miniconsoles (created via
-     * createMiniConsole / createConsole) — userwindows and labels are rejected
-     * the same way Mudlet's CONSOLE-only lookup rejects them.
+     * Desktop's `TConsole::raiseFontChangeEvent`: `sysFontChangeEvent(console,
+     * family, size)`, raised whenever a console's font really changes — a new
+     * miniconsole or user window taking its first font, and every setFont /
+     * setFontSize that lands on something different. Layout code listens for
+     * it to reflow. Main's is raised by the engine, which watches the profile
+     * font whatever changed it.
      */
-    setMiniConsoleFontSize(name: string, size: number): boolean;
+    raiseFontChangeEvent(name: string): void;
+    /** Run a font write against a console and raise sysFontChangeEvent if it
+     *  changed what the console is drawn in. Only consoles raise it on desktop
+     *  (not labels, maps or buffers), and a write that lands on the font already
+     *  in use raises nothing — TConsole::setFont compares before it applies. */
+    private withFontChangeEvent;
+    /**
+     * Mudlet setMiniConsoleFontSize. Desktop registers it as another name for
+     * setFontSize, so it reaches every console setFontSize does — main
+     * included, and main when no name is given (mudlet-web#380).
+     */
+    setMiniConsoleFontSize(name: string | undefined, size: number): boolean;
     /**
      * Mudlet getFontSize. Returns the configured font size in pixels for the
      * main window (when no name passed) or for a specific window. Returns null
      * if a named window doesn't exist or has no override.
      */
     getFontSize(win?: string): number | null;
+    /** The point size a user window's style sheet gives its text
+     *  (`TTextEdit { font-size: … }`), which is the font its console is drawn
+     *  in on desktop — and here, once the sheet is scoped onto the window. One
+     *  in pixels is read as points at the CSS 96 dpi. */
+    private userWindowStyleSheetFontSize;
     /**
      * Mudlet setBackgroundColor. With no name (or "main") sets the main window
      * background; otherwise dispatches to the matching label or userwindow/
@@ -1780,6 +2462,16 @@ export declare class ScriptingAPI {
      * fall through here too — their fill color is reported. Returns null when
      * the name doesn't resolve to anything; callers (Lua wrapper) translate that
      * to a 4-tuple of zeros.
+     *
+     * The main window answers from the *preference* when no script has set a
+     * colour, not from nothing. `outputBackgroundColor` is only the override
+     * `setBackgroundColor()` writes; returning null without it meant the Lua
+     * wrapper substituted black, so a package colouring its Geyser UI to match
+     * the user's background — a very common pattern — rendered against black
+     * whatever the user had chosen (issue #71). Desktop reads the
+     * preference-backed model colour for the main window and says why:
+     * "the view's colour is a reference to this one, so read it straight from
+     * the model" (TLuaInterpreterUI.cpp:1217-1243).
      */
     getBackgroundColor(name?: string): {
         r: number;
@@ -1791,25 +2483,42 @@ export declare class ScriptingAPI {
      * Mudlet `setBackgroundImage`. Dispatcher across labels, miniconsoles /
      * userwindows, and the main window — matches Mudlet's overload set:
      *
-     *   setBackgroundImage(labelName, imageLocation)           → label
      *   setBackgroundImage(imageLocation, [mode])              → main console
-     *   setBackgroundImage(windowName, imageLocation, [mode])  → miniconsole / userwindow
+     *   setBackgroundImage(name, imageLocation, [mode])        → label, or
+     *                                                            miniconsole / userwindow
      *
-     * Disambiguation matches Mudlet's C++ semantics — label lookup wins when
-     * the named widget is a label; otherwise the call is treated as a console
-     * form. `mode` arrives already coerced to a number by the GUIUtils.lua
-     * wrapper (string mode like "center" → 2 via `mudlet.BgImageMode`). For
-     * label form `imageLocation` is a VFS path, resolved through the same
-     * rewriter that powers setLabelStyleSheet so package-bundled images work
-     * without scripts knowing about the vfs:// scheme.
-     */
-    setBackgroundImage(a: string, b?: string | number, c?: number): boolean;
+     * Routing follows Host::setBackgroundImage: "main" is the main console, a
+     * label name wins next whatever the argument count (a label takes no mode
+     * and ignores the one it is given), and anything else is a sub-console.
+     * `mode` arrives already coerced to a number by the GUIUtils.lua wrapper
+     * (string mode like "center" → 2 via `mudlet.BgImageMode`). For the label
+     * form `imageLocation` is a VFS path, resolved through the same rewriter
+     * that powers setLabelStyleSheet so package-bundled images work without
+     * scripts knowing about the vfs:// scheme.
+     *
+     * Returns true, or desktop's refusal message — one wording for a name
+     * nothing answers to and for a label image that cannot be loaded, since
+     * TLuaInterpreter::setBackgroundImage only learns that one of them failed.
+     *
+     * `fullWindow` is the trailing boolean of `(main, path, mode, true)`. The
+     * full-window background is the main console's here, but desktop's
+     * TConsole::setWindowBackgroundImage loads the picture for mode 5 ('cover')
+     * up front and refuses one that will not load, which a script (the starter
+     * UI's background picture) relies on to know it is not showing.
+     */
+    setBackgroundImage(a: string, b?: string | number, c?: number, fullWindow?: unknown): true | string;
+    /** Whether a label could load `path` as an image, as far as can be told
+     *  now: a vendored Qt resource, a profile file whose content is an SVG or a
+     *  raster format Qt reads (QPixmap judges by content, not by name), or a
+     *  remote / inline URL — which cannot be judged synchronously and is taken
+     *  on trust. */
+    private labelImageLoads;
     /**
      * Mudlet `resetBackgroundImage([windowName])`. Without a name (or "main")
      * clears the main window background image; otherwise looks up the named
      * label or window and clears its image. Returns true on success.
      */
-    resetBackgroundImage(name?: string): boolean;
+    resetBackgroundImage(name?: string, fullWindow?: boolean): true | string;
     /**
      * Mudlet `setLabelCustomCursor(labelName, cursorPath, [hotX, hotY])`. Points
      * the label's mouse cursor at a custom image. The path is run through the
@@ -1818,7 +2527,16 @@ export declare class ScriptingAPI {
      * value. hotX/hotY are the cursor hotspot in pixels (default 0,0). Returns
      * false when the label doesn't exist.
      */
-    setLabelCustomCursor(name: string, path: string, hotX?: number, hotY?: number): boolean;
+    /** Mudlet `setLabelCustomCursor(name, path [, hotX, hotY])`. True when the
+     *  cursor is set, else the refusal in TMainConsole::setLabelCustomCursor's
+     *  words and order: the empty name, the empty location, then — for a label
+     *  that exists — an image it cannot load; a missing label last. */
+    setLabelCustomCursor(name: string, path: string, hotX?: number, hotY?: number): true | string;
+    /** Whether an image path names something there to load, as far as can be
+     *  told now: a vendored Qt resource, or a profile file that exists. A
+     *  remote or inline URL cannot be judged synchronously and is taken on
+     *  trust. */
+    private canLoadImage;
     /**
      * Mudlet `setMovie(labelName, path)` — decode the animation at `path`,
      * install it on the label, and start playing (Mudlet starts immediately
@@ -1891,10 +2609,18 @@ export declare class ScriptingAPI {
      *  the API is unavailable (Firefox/Safari). */
     getProcessMemoryUsage(): number;
     /** Mudlet `getSubsystemMemoryStats()` → a diagnostic table of heap metrics
-     *  plus per-subsystem counts. Browser-adapted: heap figures come from
-     *  `performance.memory` (Chromium; 0 elsewhere); the Lua GC figure
-     *  (`luaMemoryKb`) is added by the Bridge.lua wrapper via
-     *  `collectgarbage("count")`. Counts are best-effort snapshots. */
+     *  plus per-subsystem counts, under Mudlet's own snake_case key names — the
+     *  table is read by key, so a browser-flavoured spelling would just make
+     *  every existing diagnostic script read nil.
+     *
+     *  Browser-adapted where the C++ figure has no equivalent: the heap sizes
+     *  come from `performance.memory` (Chromium only, and left out entirely
+     *  elsewhere, as Mudlet leaves them out on a platform whose allocator it
+     *  cannot ask); `heap_limit_mb` and `loaded_fonts` are browser-only extras.
+     *  `event_handlers` is absent: Other.lua keeps its handler registry in a
+     *  local upvalue, with no reachable count. The Lua GC figures
+     *  (`lua_heap_kb`/`lua_heap_mb`) are added by the Bridge.lua wrapper.
+     *  Counts are best-effort snapshots. */
     getSubsystemMemoryStats(): Record<string, number>;
     private patchBorders;
     private applyBorders;
@@ -1923,10 +2649,27 @@ export declare class ScriptingAPI {
      *   • `calcFontSize("WindowName")` — measure the named window/miniconsole
      *     using its configured font+size. Use `"main"` for the main output.
      *
+     * The size forms answer the font's average character width, the window
+     * form the width of a "W" — what scripts have long compensated for by hand
+     * — unless `columnWidth` asks for the width a column is drawn in, which is
+     * the average again. All three agree on a monospaced font.
+     *
      * Returns `null` when the size is invalid or the named window doesn't
      * exist; the Lua wrapper turns that into Mudlet's `(nil, errMsg)` shape.
-     */
-    calcFontSize(arg: number | string, fontName?: string): [number, number] | null;
+     *
+     * Whole pixels, like the `QSize` Mudlet builds out of
+     * `QFontMetrics::averageCharWidth()` and `::height()` — and unlike the
+     * fractional cell {@link measureMonospaceCell} hands this client's own
+     * column arithmetic. The rounding is what makes the number multipliable:
+     * every caller of this one is a script scaling it back up into a widget
+     * size (Geyser resolves a `"20c"` constraint as `20 * calcFontSize(...)`,
+     * GUIUtils sizes a `createConsole` the same way), and widget geometry is
+     * whole pixels in Mudlet and here alike. A fractional cell makes that
+     * product land between pixels, where it is truncated — so the size a script
+     * computed and the size `getWindowGeometry` reports back silently disagree,
+     * by an amount that depends on which fonts the machine happens to have.
+     */
+    calcFontSize(arg: number | string, fontName?: string, columnWidth?: boolean): [number, number] | null;
     /**
      * Mudlet `getAvailableFonts()` — set-style table whose keys are font
      * family names usable from scripts. The browser cannot enumerate the
@@ -1942,6 +2685,25 @@ export declare class ScriptingAPI {
      *     call sees the result.
      */
     getAvailableFonts(): Record<string, boolean>;
+    /**
+     * The installed family a requested font name means, or null if none does.
+     *
+     * Mudlet hands the name to QFont, which resolves it three ways before
+     * giving up, and scripts depend on all three: the exact family, the same
+     * family in any casing, and a "Family Style" name whose trailing style word
+     * is a weight/slant request rather than part of the family — "Ubuntu Mono
+     * Bold" is Ubuntu Mono asked for in bold, not a family of that name. The
+     * answer is always spelled the way the font database spells it, because
+     * callers read it straight back (Geyser.Label:setFont stores getFont()'s
+     * reply so what it remembers and what the widget got cannot drift).
+     *
+     * Only weight and slant words are trimmed, never width ones: Qt keeps width
+     * in the family name ("Arial Narrow" is its own family), so trimming those
+     * would resolve a name to a font the caller did not ask for. A trailing word
+     * that is not a style word stops the trim outright, so "Arial Nonsense"
+     * fails rather than quietly becoming Arial.
+     */
+    resolveFontFamily(name: string): string | null;
     /** Flush any buffered partial lines to the main output and all open windows. Called after each event dispatch. */
     flushOutput(): void;
     /** @deprecated use echo() */
@@ -1951,6 +2713,26 @@ export declare class ScriptingAPI {
      *  client telling the player something about the line in front of them,
      *  not a script's error. */
     postSystemMessage(text: string): void;
+    /**
+     * A notice for the player in the main window — not a script fault, so not
+     * printError, which only reaches main when the profile asked for errors
+     * there and would be missed by exactly the person who needs it.
+     *
+     * Written to the buffer as well as emitted, for the reason
+     * warnIfUnencodable gives: a line the player can read has to be a line
+     * getLines() and the cursor APIs can see.
+     */
+    postInfo(text: string): void;
+    /** Mudlet's `Host::postMessage` for the `[ WARN ]` kind, written the same
+     *  way as {@link postInfo}. */
+    postWarning(text: string): void;
+    /** A profile save counts as running until the next pass of the event
+     *  loop; see ScriptingEngine.markProfileSaveInFlight. */
+    markProfileSaveInFlight(): void;
+    /** Mudlet's `Host::postMessage` for the `[ ERROR ]` kind: unlike printError
+     *  this is client news rather than a script's own fault, so it goes on the
+     *  main console whether or not the profile shows script errors there. */
+    postError(text: string): void;
     printError(text: string, source?: ScriptLogSource): void;
     destroy(): void;
     private getConsole;
@@ -1960,12 +2742,56 @@ export declare class ScriptingAPI {
      * all of which back a Console. Used by the read/select methods instead of a
      * bare `windows.has`, which is false for buffers (they have no panel).
      */
+    /** Whether `name` is a console a script can write to (see {@link consoleExists}). */
+    hasConsole(name: string): boolean;
     private consoleExists;
+    /**
+     * The Console a write to `win` goes to, or null when `win` names no console
+     * at all. Mudlet resolves the name and answers a miss with "window not
+     * found" (or, for echo, "console/label does not exist") without creating
+     * anything; going through {@link outputConsole} instead conjured a hidden
+     * console out of the typo, which then showed up as a "userwindow" and
+     * handed its stray text to whatever window was later created under that
+     * name (mudlet-web#280).
+     */
+    private penConsole;
     /** Returns the Console for a window, creating and registering one on demand. */
     private outputConsole;
     private drainWindowConsole;
     private resolveBuffer;
-    private selectionMatches;
+    private selectionKey;
+    /** The named console's own selection (main when omitted), or null. */
+    private selectionOf;
+    /** Whether the named console (main when omitted) has a selection, valid or
+     *  not. */
+    hasSelection(win?: string): boolean;
+    /** Whether the named console's selection covers any text — what setLink
+     *  and setPopup need, since a link on nothing would be one nobody could
+     *  click. */
+    hasSelectedText(win?: string): boolean;
+    /** Whether the named console's cursor is where insertLink / insertPopup
+     *  can put text (see Console.cursorInText). */
+    cursorInText(win?: string): boolean;
+    /** Selections are made on the cursor's line, and stay with that line. */
+    private setSelection;
+    /**
+     * The line a selection was made on, while its console still holds it —
+     * wherever the lines around it have moved it. Once a clear (or the
+     * scrollback limit) has taken that line away, the selection is desktop's
+     * P_begin/P_end again, a line number: whatever line now has that number,
+     * or null when none has, which leaves the selection standing but no longer
+     * valid.
+     */
+    private selectionBuffer;
+    private clearSelection;
+    /**
+     * The columns a selection covers on `buf`, read as TBuffer::applyFgColor
+     * and the other apply* calls read P_begin/P_end: the end is cut at the end
+     * of the line, and a selection starting at or past it covers nothing. A
+     * selection outlives the text it was made on — replace() keeps it, and the
+     * cursor can move to a shorter line — so it can run off the end.
+     */
+    private selectionSpan;
     private applyStateToSelection;
     private drainMain;
 }