@mudlet/mudlet-web 0.3.1 → 0.4.0

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

@@ -8,10 +8,12 @@ import type { LabelManager, LabelCreateOptions, LabelMouseEvent, LabelWheelEvent
 import type { CommandLineManager } from '../ui/cmdline/CommandLineManager';
 import type { ScrollBoxManager } from '../ui/scrollbox/ScrollBoxManager';
 import { TextEditManager } from '../ui/textedit/TextEditManager';
+import type { LogFormat } from '../logging/SessionLogger';
 import { AnsiAwareBuffer, type FormatStateSnapshot, type FormatHyperlink } from '../mud/text/FormatState';
+import { type UnderlineStyle } from '../mud/text/hyperlinkConfig';
 import { StopwatchManager } from './StopwatchManager';
 import { MapStore } from '../map/MapStore';
-import { type EngineHost } from './EngineHost';
+import { type EngineHost, type TempComplexTriggerSpec } from './EngineHost';
 declare class ScriptingWindowsAPI {
     private readonly session;
     constructor(session: MudSession);
@@ -19,6 +21,17 @@ declare class ScriptingWindowsAPI {
     write(id: string, text: string): void;
     clear(id: string): void;
     setTitle(id: string, title?: string): boolean;
+    /** Mudlet getUserWindowTitle / getMapWindowTitle — null when no such window. */
+    getTitle(id: string): string | null;
+    /** Mudlet getScrollBarVisible — the enable/disableScrollBar intent. */
+    scrollBarVisible(id: string): boolean;
+    /** Mudlet getMapWidgetGeometry / getWindowGeometry — null when no such window. */
+    getGeometry(id: string): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
     focus(id: string): void;
     hide(id: string): void;
     show(id: string): boolean;
@@ -71,6 +84,9 @@ declare class ScriptingLabelsAPI {
     htmlRewriter: () => (html: string) => string);
     create(name: string, opts: LabelCreateOptions): boolean;
     has(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;
     /** Read-only state for the geometry/visibility/text getters. */
     get(name: string): Readonly<import("../ui/labels/LabelManager").LabelState> | undefined;
     destroy(name: string): boolean;
@@ -89,6 +105,8 @@ declare class ScriptingLabelsAPI {
     } | 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;
     getSizeHint(name: string): {
@@ -158,6 +176,10 @@ export declare class ScriptingAPI {
     private inTriggerProcessing;
     private echoDeferred;
     private isDeferringEcho;
+    /** Flip echo deferral, mirroring it onto the session so echoCommand knows
+     *  the in-flight console partial belongs to flushDeferredEcho and must not
+     *  be closed out from under it. */
+    private setDeferringEcho;
     private echoOnMatchedLine;
     /** Mudlet `startLogging(state)`. Forwarded to ProfileSession, which owns
      *  the SessionLogger instance (created/torn-down on this hook). */
@@ -173,6 +195,10 @@ export declare class ScriptingAPI {
     private clipboardText;
     private buffers;
     constructor(session: MudSession, aliasEngine: AliasEngine, triggerEngine: TriggerEngine, timerEngine: TimerEngine, keyEngine: KeyEngine, connectionId: string);
+    /** 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. */
+    private syncMediaMuteFromConfig;
     /** Bind the engine backing this API. Called once by ScriptingEngine during
      *  its own construction; pass null on teardown to revert to the inert host,
      *  so anything that outlives the engine (a rendered line's link handler,
@@ -186,7 +212,20 @@ export declare class ScriptingAPI {
      *  during initial load); the default host connects the session directly. */
     private dialConnect;
     disconnect(): void;
+    /**
+     * Mudlet's Lua `send()`, which is C++ `sendRaw` → `Host::send(text,
+     * wantPrint, dontExpandAliases = true)`: the whole text is echoed once under
+     * the showSentText mode, then split on the profile's command separator, and
+     * each part goes to the game **without** passing through the aliases. Item
+     * `command` fields take the alias-expanding path instead —
+     * {@link ScriptingEngine.hostSend}.
+     */
     send(text: string, echo?: boolean): void;
+    /** The tail of `Host::send`: one already-echoed, already-split command onto
+     *  the wire. Same `sysDataSendRequest` veto as {@link send}, no echo. With
+     *  no engine wired yet (early init) the no-op host reports "not denied", so
+     *  this sends straight through. */
+    sendData(text: string): void;
     sendGmcp(message: string): void;
     /** Mudlet `sendMSDP(variable, ...values)`. Frames an MSDP subnegotiation
      *  (`IAC SB MSDP MSDP_VAR <var> [MSDP_VAL <val>]... IAC SE`) and sends it. */
@@ -206,6 +245,17 @@ export declare class ScriptingAPI {
      *  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;
+    /** Deliver any replay chunk that has come due. Only the busted pump calls
+     *  this — see MudSession.pumpReplay. */
+    pumpReplay(): number;
+    /** Commit a line held for a server-wrap continuation whose flush delay has
+     *  elapsed. Same reason as {@link pumpReplay}: the busted runner blocks the
+     *  event loop the timer would have fired on. */
+    pumpServerWrap(): boolean;
+    /** Put back the text of an OSC 8 link written concealed whose reveal delay
+     *  has elapsed. Same reason again: the runner blocks the event loop the
+     *  reveal timer would have fired on. */
+    pumpHyperlinkReveals(): 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
@@ -256,9 +306,9 @@ export declare class ScriptingAPI {
      */
     getProfiles(): Record<string, {
         host: string;
-        port: number;
+        port: string;
         loaded: boolean;
-        connected: boolean;
+        connected?: boolean;
         description: string;
     }>;
     /** Mudlet `getMudletInfo()`. Echoes a short diagnostic block to the main
@@ -318,23 +368,35 @@ export declare class ScriptingAPI {
      * of the two applies before it calls through, and only the type is knowable
      * ahead of the call.
      *
-     * `'readonly'` keys exist for `getConfig` but refuse every write.
+     * `'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' | 'readonly' | null;
+    configKeyKind(key: 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;
-    /** Mudlet `getProfileInformation()`. Returns the profile's free-text
-     *  description, or "" when unset. (mudix is single-profile, so the optional
-     *  profile-name argument is ignored.) */
-    getProfileInformation(): string;
-    /** Mudlet `setProfileInformation(text)`. Stores the profile's free-text
+    /**
+     * 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
+     * up as a folder, and the platforms it runs on mostly have case-insensitive
+     * ones — so `setProfileInformation(name:upper(), …)` has to find the profile
+     * it already has rather than start a second one beside it.
+     */
+    private connectionByName;
+    /** Mudlet `getProfileInformation([profileName])`. The profile's free-text
+     *  description ("" when unset), defaulting to this profile. Returns null for
+     *  a name no profile has. */
+    getProfileInformation(profileName?: string): string | null;
+    /** Mudlet `setProfileInformation([profileName,] text)`. Stores the free-text
      *  description on the connection record (also editable from the connection
-     *  screen). Always succeeds for the active profile. */
-    setProfileInformation(text: string): boolean;
-    /** Mudlet `clearProfileInformation()`. Resets the profile description to
-     *  an empty string. */
-    clearProfileInformation(): boolean;
+     *  screen). False for a name no profile has — deliberately a refusal rather
+     *  than a create, since in Mudlet the write goes through a call that makes
+     *  whatever folder it is handed, and a folder there is a profile. */
+    setProfileInformation(text: string, profileName?: string): boolean;
+    /** Mudlet `clearProfileInformation([profileName])`. Puts the description
+     *  back to what the profile started with: the blurb its game ships with in
+     *  the bundled catalogue, or empty for a profile someone made up. */
+    clearProfileInformation(profileName?: string): boolean;
     /** Mudlet `getProfileIcon()`. Returns the stored icon as a `data:` URI, or
      *  "" when the profile has no custom icon (the connection screen then shows
      *  the auto-generated name tile). */
@@ -356,6 +418,9 @@ export declare class ScriptingAPI {
     installModule(path: string): InstallOutcome;
     uninstallModule(name: string): boolean;
     syncModule(name: string): Promise<void>;
+    /** 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;
     enableModuleSync(name: string): void;
     disableModuleSync(name: string): void;
@@ -386,10 +451,26 @@ export declare class ScriptingAPI {
     /** Hook for ProfileSession to start/stop the per-connection SessionLogger.
      *  Mudlet `startLogging(true|false)` toggles whether new output lines are
      *  recorded; the on/off transition is synchronous. */
-    setLoggingToggler(fn: ((enabled: boolean) => boolean) | null): void;
+    setLoggingToggler(fn: ((enabled: boolean, format: LogFormat) => boolean) | null): void;
     /** Mudlet `startLogging(state)`. Returns true on success, false when
      *  the toggle isn't wired up yet (e.g. before ProfileSession mounts). */
-    startLogging(enabled: boolean): boolean;
+    /**
+     * Mudlet `startLogging(state)` → (ok, message, path, state). The state code
+     * distinguishes a change from a no-op: 1 started, 0 stopped, -1 already on,
+     * -2 already off; the two "already" cases answer nil rather than true, so a
+     * caller can tell "I turned it on" from "it was on".
+     */
+    startLogging(enabled: boolean): {
+        ok: boolean;
+        message: string;
+        path: string | null;
+        state: number;
+    };
+    /** Where the live logger is writing its text log, or null when logging is
+     *  off. Wired by ProfileSession alongside the toggler. */
+    private loggingPathProvider;
+    setLoggingPathProvider(fn: (() => string | null) | null): void;
+    private loggingPath;
     /** Hook for ProfileSession to forward appendLog text to the live logger. */
     setLogAppender(fn: ((text: string) => void) | null): void;
     /** Mudlet `appendLog(text)`. Appends a line to the current session log.
@@ -483,11 +564,19 @@ export declare class ScriptingAPI {
         isActive: boolean;
     }> | null;
     /** Mudlet `findItems(name, type [, exact [, caseSensitive]])`. Numeric ids of
-     *  matching items/groups. Empty when none match or the type is unknown. */
-    findItems(name: string, type: string, exact?: boolean, caseSensitive?: boolean): number[];
+     *  matching items/groups — empty when none match, null when there is no such
+     *  item family (which the Lua wrapper reports as a bad item type). */
+    findItems(name: string, type: string, exact?: boolean, caseSensitive?: boolean): number[] | null;
     /** Mudlet `isAncestorsActive(id, type)`. True when every ancestor group is
      *  enabled; null when no item of that type has the id. */
     isAncestorsActive(id: number, type: string): boolean | null;
+    /** Next id from the profile's single item-id sequence — see
+     *  ItemIdSequence. Backs the Lua runtime's temporary items. */
+    allocateItemId(): number;
+    /** Whether `type` names an item family at all — the tree-walking APIs
+     *  (findItems, ancestors, isAncestorsActive) all refuse an unknown one, and
+     *  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. */
     getProfileStats(): Record<string, unknown>;
@@ -499,6 +588,11 @@ export declare class ScriptingAPI {
      *  empty patterns array creates a trigger group. Returns the new id, or
      *  -1 if `parent` is given but no trigger group of that name exists. */
     permSubstringTrigger(name: string, parent: string, patterns: string[], code: string): number;
+    /** Mudlet `tempComplexRegexTrigger(...)`. See
+     *  ScriptingEngine.createTempComplexTrigger. */
+    tempComplexTrigger(spec: TempComplexTriggerSpec): number;
+    /** Remove a temporary trigger by the id its creator returned. */
+    removeTemporaryTrigger(id: number): boolean;
     /** Mudlet `permBeginOfLineStringTrigger(name, parent, patterns, luaCode)`.
      *  Same shape as permSubstringTrigger but each pattern matches only when it
      *  appears at the start of the line (`String.prototype.startsWith`, like the
@@ -561,6 +655,9 @@ export declare class ScriptingAPI {
     /** Mudlet `getButtonState(name)`. Reads the pressed state of a two-state
      *  button. Returns nil when not found. */
     getButtonState(name: string): boolean | null;
+    /** Which of Mudlet's button refusals applies to `name` — see
+     *  ScriptingEngine.buttonKindByName. */
+    buttonKind(name: string): 'missing' | 'plain' | 'pushdown';
     /** Mudlet `setButtonStyleSheet(name, css)`. Stores a CSS string on the
      *  ButtonNode; the renderer applies it inline. Returns false when not
      *  found. */
@@ -568,16 +665,34 @@ export declare class ScriptingAPI {
     /** 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
-     *  the show/hide hook. Returns true on success, false when not found. */
-    setToolBarVisibility(name: string, show: boolean): boolean;
+     *  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;
-    /** Mudlet `getScript(name [, pos]) → code, count`. Returns the source of the
-     *  pos-th (1-indexed) script named `name` and how many scripts share that
-     *  name. Returns null when none exist (Bridge.lua surfaces "", 0). */
+    /** 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;
+    /** 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
+     *  surfaces as Mudlet's `(-1, "script ... at position ... not found")`. */
     getScript(name: string, pos: number): {
         code: string;
-        count: number;
+        id: number;
     } | null;
+    /** When the `!osc8-docs` banner last went out — see {@link injectOsc8Docs}. */
+    private osc8DocsInjectedAt;
+    /**
+     * Mudlet's `!osc8-docs` easter egg (`TBuffer::appendLine`): text printed
+     * through the echo family that carries the phrase is swallowed whole — not
+     * just the phrase, the whole call — and a banner of worked OSC 8 examples
+     * goes into the MAIN console instead, whichever window the echo named.
+     *
+     * Returns true when the caller must print nothing. That happens even while
+     * the once-a-second debounce is suppressing the banner itself: an echo and
+     * the server response repeating it are two sightings of one phrase, and the
+     * phrase never belongs on screen either way.
+     */
+    private injectOsc8Docs;
     echo(text: string): void;
     echoToWindow(win: string, text: string): void;
     /**
@@ -766,6 +881,17 @@ export declare class ScriptingAPI {
     isAnsiFgColor(ansiColor: number): boolean;
     isAnsiBgColor(ansiColor: number): boolean;
     private matchesAnsiColor;
+    /**
+     * The colour one of `isAnsiFgColor`/`isAnsiBgColor`'s 0..16 codes names.
+     *
+     * This is Mudlet's own numbering (`TLuaInterpreterUI.cpp`), and it is not
+     * the ANSI one: 0 is the profile's default, then the eight colours follow in
+     * *light-first* pairs — 1 light black, 2 black, 3 light red, 4 red, and so
+     * on to 15 light white, 16 white. Anything outside 0..16 names no colour;
+     * the Bridge wrapper already refuses those with Mudlet's message, so this
+     * only has to decline to answer.
+     */
+    private ansiColorCodeToRgb;
     private readSelectionColor;
     /**
      * Resolve the rgb of `channel` for the character at `pos` in `buf`, falling
@@ -774,6 +900,13 @@ export declare class ScriptingAPI {
      * (selection or cursor).
      */
     private readColorAt;
+    /** 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. */
+    private linkColor;
+    /** The profile's own foreground/background — what a cell carrying no colour
+     *  of its own is drawn in, and what `isAnsi*Color(0)` asks about. */
+    private defaultColorRgb;
     /**
      * Mudlet `getTextFormat([windowName]) → table | nil, errMsg`. Reads the full
      * set of display attributes of the character at the current selection's start
@@ -791,6 +924,7 @@ export declare class ScriptingAPI {
         bold: boolean;
         italic: boolean;
         underline: boolean;
+        underlineStyle: UnderlineStyle | 'none';
         strikeout: boolean;
         reverse: boolean;
         overline: boolean;
@@ -834,7 +968,10 @@ export declare class ScriptingAPI {
      * (RGB) segments never match a positive index, matching Mudlet's
      * palette-only semantics.
      */
-    currentLineMatchesColor(wantFg: number, wantBg: number): boolean;
+    currentLineMatchesColor(wantFg: number, wantBg: number, window?: {
+        start: number;
+        length: number;
+    } | null): boolean;
     /**
      * The text of the first run on the current line carrying the wanted ANSI
      * colours, or null when none does. A colour trigger reports that run as
@@ -845,12 +982,32 @@ export declare class ScriptingAPI {
      * may already have recoloured the line, and Mudlet still matches against the
      * colours the server sent.
      */
-    currentLineColorMatch(wantFg: number, wantBg: number): string | null;
+    currentLineColorMatch(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}. -2 marks a segment with
-     *  no palette colour (RGB or default), which never matches a requested
-     *  index. A stack, because a trigger can feedTriggers another line. */
+     *  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. */
     private lineColorSnapshots;
+    /** 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. */
+    private triggerLinePrompts;
+    /** How many lines are being processed at once — more than one whenever a
+     *  trigger calls feedTriggers. See beginLine/endLine. */
+    private triggerLineDepth;
+    /** 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. */
+    private captureShiftHook;
+    setCaptureShiftHook(fn: ((at: number, delta: number) => void) | null): void;
     /**
      * 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
@@ -890,6 +1047,16 @@ export declare class ScriptingAPI {
     enableHorizontalScrollBar(windowName?: string): void;
     disableScrolling(windowName?: string): boolean;
     enableScrolling(windowName?: string): boolean;
+    /** Mudlet `timeStampsEnabled(window)` — whether the console shows its
+     *  timestamp column. Null when no such window exists. */
+    timeStampsEnabled(windowName: string): boolean | null;
+    /** Mudlet `enableTimeStamps(window)` / `disableTimeStamps(window)`. False
+     *  when no such window exists. */
+    setTimeStamps(windowName: string, visible: boolean): boolean;
+    /** Mudlet `scrollingActive([window])` — whether the user can scroll back in
+     *  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). */
     getScroll(windowName?: string): number;
@@ -923,7 +1090,7 @@ export declare class ScriptingAPI {
      * Sets the scrollback cap (and the round-tripped batch-deletion size).
      * Returns false when the named console doesn't exist.
      */
-    setConsoleBufferSize(windowName: string | undefined, linesLimit: number, batchSize?: number): boolean;
+    setConsoleBufferSize(windowName: string | undefined, linesLimit: number, batchSize?: number, useMaximum?: boolean): boolean;
     getColumnNumber(windowName?: string): number;
     /** Mudlet `isPrompt()` — reports the per-line prompt flag at the current
      *  cursor position. Lines pushed via beginLine carry the flag, so
@@ -964,6 +1131,10 @@ export declare class ScriptingAPI {
      * succeeds (persisted on the active profile).
      */
     setWindowWrap(name: string, wrapAt: number): boolean;
+    /** 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. */
+    private applyStoredWrap;
     /**
      * Mudlet `getWindowWrap(name) → cols`. Reports the visual wrap width set by
      * setWindowWrap (0 when unset). For "main" reads the profile's stored
@@ -1043,25 +1214,29 @@ export declare class ScriptingAPI {
      */
     deleteMiniConsole(name: string): boolean;
     /**
-     * MXP `<FRAME>` (Mudlet 4.21). Maps an MXP frame onto a mini-console — the
-     * browser has no OS-level child/floating windows, so internal, external and
-     * floating frames all become overlay mini-consoles. `attrs` keys are
-     * upper-cased (see `MxpFrameCommand`). `ACTION=close` deletes the frame;
-     * anything else opens it (or repositions it if it already exists). Geometry
-     * (`LEFT`/`TOP`/`WIDTH`/`HEIGHT`) accepts pixels, `N%` of the main window, or
-     * `Nc` character cells.
+     * MXP `<FRAME>` (Mudlet 4.21). All the layout thinking lives in
+     * {@link MxpFrameManager}, a port of Mudlet's TMxpFrameManager — edge tiling
+     * with accumulating borders, `<DEST>`-nested sub-frames, `TITLE` tab headers
+     * 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>): void;
+    mxpFrame(name: string, attrs: Record<string, string>, dest?: string): void;
+    /** 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. */
+    mxpResetFrames(): void;
     /**
-     * Write an MXP `<DEST>` redirected line into a frame's mini-console. Returns
-     * false when no mini-console of that name exists (the caller then renders the
-     * text inline in the main window, matching Mudlet). `eof` clears the frame
-     * first — the status-frame "replace contents" idiom.
+     * Write an MXP `<DEST>` redirected line into a frame's console. Returns
+     * false when no such frame exists (the caller then renders the text inline
+     * 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;
-    /** Parse an MXP geometry dimension: `N%` → fraction of `ref`, `Nc` → N
-     *  character cells (approximate), bare number → pixels. null when absent. */
-    private parseMxpDim;
+    /** 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. */
+    private readonly mxpReplacedFrames;
+    private readonly mxpFrames;
     /**
      * Mudlet `createBuffer(name)`. Registers a named off-screen console for
      * formatting and storing rich text — like a miniconsole, but never shown
@@ -1080,6 +1255,13 @@ export declare class ScriptingAPI {
      * but doesn't own the active selection.
      */
     copy(windowName?: string): void;
+    /**
+     * 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;
     /**
      * 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.
@@ -1097,9 +1279,10 @@ export declare class ScriptingAPI {
      * Mudlet `createMapper([parent,] x, y, width, height)`. Creates a positioned
      * mapper widget inside the given parent (defaults to `main`), or repositions
      * it if it already exists. Singleton: Mudlet allows only one in-console
-     * mapper at a time, so we reuse a fixed id (`mapper`) — distinct from the
-     * dockable map widget opened by `openMapWidget` (id `map`). Both render the
-     * same MapStore and stay in sync. Returns true on success.
+     * mapper at a time, so we reuse a fixed id — distinct from the dockable map
+     * widget opened by `openMapWidget`. Both are client-owned ids (see
+     * 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;
     /**
@@ -1193,6 +1376,35 @@ export declare class ScriptingAPI {
     clearCmdLineSuggestions(): void;
     getCmdLineSuggestions(): string[];
     private emitCmdLineSuggestions;
+    private cmdLineBlacklist;
+    addCmdLineBlacklist(word: string): void;
+    removeCmdLineBlacklist(word: string): void;
+    clearCmdLineBlacklist(): void;
+    getCmdLineBlacklist(): string[];
+    private emitCmdLineBlacklist;
+    private saveCommandHistoryFlags;
+    saveCommandHistoryFor(cmdLineName: string): boolean;
+    setSaveCommandHistoryFor(cmdLineName: string, save: boolean): void;
+    /**
+     * The command-line history files an end-of-session save should write, as
+     * `{ name, content }` pairs relative to the profile directory. Empty when
+     * nothing is to be written.
+     *
+     * Mudlet does this from `Host::saveProfile()`, which emits
+     * `signal_saveCommandLinesHistory` and lets every TCommandLine write its own
+     * `command_history_<name>` — newest command first, one per line, capped at
+     * 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
+     * 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.
+     */
+    commandLineHistoryFiles(): {
+        name: string;
+        content: string;
+    }[];
     /**
      * Mudlet `openUrl(url) → bool`. Opens a URL in a new browser tab. Special
      * case: a `file:` prefix (as in `openUrl("file:" .. getMudletHomeDir())`)
@@ -1234,13 +1446,26 @@ 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. */
+    getUserWindowStyleSheet(name: string): string;
+    private readonly userWindowCss;
+    /** 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;
+    noteCmdLineStyleSheet(name: string, css: string): void;
+    private readonly cmdLineCss;
     /**
      * Mudlet `setProfileStyleSheet(stylesheet)`. Installs (or replaces) a
      * profile-wide CSS block. In Mudlet this themes the whole profile's
      * widgets; the browser analogue is a single `<style>` tag in document.head,
      * keyed separately from setAppStyleSheet's blocks so the two don't clobber
-     * each other. Raises sysAppStyleSheetChange (tag "profile") for parity with
-     * the app-level setter. Always returns true.
+     * each other. Always returns true.
+     *
+     * 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
+     * re-apply itself over a change that was never theirs.
      */
     setProfileStyleSheet(css: string): boolean;
     /**
@@ -1304,9 +1529,30 @@ export declare class ScriptingAPI {
     get mouseEvents(): import("../ui/MouseEventRegistry").MouseEventRegistry;
     get sounds(): import("../ui/sound/SoundManager").SoundManager;
     get videos(): import("../ui/video/VideoManager").VideoManager;
-    /** Mudlet `setMapBackgroundColor(r, g, b)`. Persists into the profile
-     *  mapper settings so MapPanel picks it up on its next render pass. */
-    setMapBackgroundColor(r: number, g: number, b: number): boolean;
+    /**
+     * Mudlet `setMapBackgroundColor(r, g, b [, a])`. Persists into the profile
+     * mapper settings so MapPanel picks it up on its next render pass.
+     *
+     * Returns the refusal message for a component outside 0-255 and `null` on
+     * success — Bridge.lua turns the former into Mudlet's `(nil, errMsg)` pair.
+     * The alpha is optional and defaults to opaque; it is stored only when it is
+     * not, so an ordinary colour stays the plain `#rrggbb` the renderer and the
+     * Mapper tab have always written.
+     */
+    setMapBackgroundColor(r: number, g: number, b: number, a?: number): string | null;
+    /** Mudlet `getMapBackgroundColor()` — the four components of the colour
+     *  {@link setMapBackgroundColor} stored, alpha included. */
+    getMapBackgroundColor(): [number, number, number, number];
+    /** Mudlet `setMapRoomExitsColor(r, g, b)`. The exit pen carries no alpha
+     *  either way, so this is the renderer's `lineColor` and nothing else. */
+    setMapRoomExitsColor(r: number, g: number, b: number): string | null;
+    /** Mudlet `getMapRoomExitsColor()` — three components, no alpha. */
+    getMapRoomExitsColor(): [number, number, number];
+    /** Mudlet `setDefaultAreaVisible(visible)`. Mudlet's `TMap::mShowDefaultArea`
+     *  decides whether the unnamed catch-all area rooms land in before they are
+     *  filed anywhere shows up in the area list; here that list is MapPanel's
+     *  area dropdown, which reads the same flag. */
+    setDefaultAreaVisible(visible: boolean): boolean;
     /** Mudlet `setMapRoomSize(size)`. Maps to renderer.settings.roomSize via
      *  the profile mapper field. Returns false for non-positive values. */
     setMapRoomSize(size: number): boolean;
@@ -1351,6 +1597,24 @@ export declare class ScriptingAPI {
      * Returns true on success, false when no connectionId is bound.
      */
     saveWindowLayout(): boolean;
+    /** 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. */
+    private windowLayoutPath;
+    /**
+     * Mirror the snapshot to `windowLayout.dat`.
+     *
+     * The store is still where a layout survives a reload — this file is the
+     * 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
+     * counterpart here.
+     */
+    private writeWindowLayoutFile;
+    /** The snapshot in `windowLayout.dat`, or null when there is no readable,
+     *  parsable file — in which case the caller falls back to the store. */
+    private readWindowLayoutFile;
     /**
      * Mudlet `loadWindowLayout()` — restore the most recently saved snapshot
      * for this connection. Re-applies geometry, dock state, font/colour, and
@@ -1678,6 +1942,11 @@ export declare class ScriptingAPI {
     flushOutput(): void;
     /** @deprecated use echo() */
     print(text: string): void;
+    /** Mudlet `Host::postMessage`. Writes a client message onto the main
+     *  console whatever the profile's error-echo preference — this is the
+     *  client telling the player something about the line in front of them,
+     *  not a script's error. */
+    postSystemMessage(text: string): void;
     printError(text: string, source?: ScriptLogSource): void;
     destroy(): void;
     private getConsole;