@mudlet/mudlet-web 0.3.0 → 0.4.0

package/dist-lib/ui/output/linkNavigation.d.ts

@@ -11,7 +11,29 @@
  * the send/prompt/url action, reveals a spoiler, toggles selection, arms
  * visibility); the Menu key or Shift+F10 opens its context menu. Mirrors
  * Mudlet's TTextEdit key handling.
+ *
+ * Being focusable has a mouse-side cost, which `restoreFocusAfterLinkClick`
+ * pays back: a tabIndex of -1 keeps a span out of the Tab order but still lets
+ * a click focus it, and Mudlet's TTextEdit never takes focus off the command
+ * line that way.
+ */
+/**
+ * Give focus back to the command line after a link is clicked with the mouse,
+ * so the player can keep typing — Mudlet's behaviour, where the output never
+ * takes focus at all.
+ *
+ * Call from a *capture*-phase click listener on the output container: a link's
+ * own handler stops propagation, so a bubble-phase listener never sees it. The
+ * hand-back is deferred to a microtask (i.e. after the click has been fully
+ * dispatched) and happens only if a link is still holding focus — a link that
+ * opened a dialog or moved focus deliberately keeps its say. Keyboard
+ * activation (`link.click()` from Enter/Space, which reports `detail === 0`)
+ * leaves focus on the link so Ctrl+]/Ctrl+[ can carry on from there.
  */
+export declare function restoreFocusAfterLinkClick(e: {
+    detail: number;
+    target: EventTarget | null;
+}, commandInput: () => HTMLElement | null | undefined): void;
 /**
  * One representative element per logical link under `root`, in document order.
  * A multicolour link is rendered as several spans (one per colour run) sharing

package/dist-lib/ui/output/outputSearch.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Find-in-output: scans the rendered scrollback for a query and tints every hit.
+ *
+ * This works purely on the rendered DOM rather than on the `AnsiAwareBuffer`
+ * model behind each line. Two reasons:
+ *
+ *  - Highlighting is transient. `buffer.applyFormat()` rewrites segment state,
+ *    so undoing a search highlight would mean snapshotting and restoring every
+ *    touched line's formatting — and a script that recolours a line mid-search
+ *    would lose its change. Wrapping text nodes in `<mark>` leaves the model
+ *    untouched, and unwrapping restores the DOM exactly.
+ *  - Offsets line up by construction. `appendCells` can substitute text on the
+ *    way to the DOM (tab-stop expansion, Mudlet control-character glyphs), so
+ *    `buffer.text` offsets do not always index the rendered line. Searching the
+ *    rendered text means we match what the player can actually see.
+ *
+ * The sticky split-view panel holds `cloneNode` copies of the last N lines, so
+ * it is not scanned — it lives outside the `.output-wrapper` scroller we walk.
+ * Re-populating it after highlighting copies the marks along with the lines.
+ */
+import type { MatchRange, SearchMatcher } from '../search/matcher';
+export declare const HIT_CLASS = "output-search-hit";
+export declare const CURRENT_HIT_CLASS = "output-search-hit--current";
+export interface OutputMatch {
+    /** The `.output-msg` line element containing this hit. */
+    line: HTMLElement;
+    /** Offsets into the line's rendered text — `[start, end)`. */
+    range: MatchRange;
+}
+/**
+ * Every match in the output, in document (i.e. chronological) order.
+ *
+ * Cheap enough to re-run on each keystroke: the per-line cost is one
+ * `textContent` read plus the matcher's scan, and only lines that actually hit
+ * get walked node-by-node later, in {@link applyHighlights}.
+ */
+export declare function scanOutput(container: HTMLElement, matcher: SearchMatcher): OutputMatch[];
+/**
+ * Tint every match, giving `matches[currentIndex]` the "current hit" treatment.
+ *
+ * Callers must {@link clearHighlights} first — marking an already-marked line
+ * would nest marks. Matches whose line has since been evicted from the DOM are
+ * skipped rather than treated as an error; the scrollback trims as new output
+ * arrives and a stale match is normal, not exceptional.
+ */
+export declare function applyHighlights(matches: OutputMatch[], currentIndex: number): void;
+/**
+ * Whether an Escape that reached the document should close the find bar.
+ *
+ * The bar's own input handles Escape directly, but the player usually leaves
+ * focus in the command line while reading results, and there Escape did nothing
+ * — the bar just stayed up. So the bar also listens on the document, in the
+ * BUBBLE phase, and defers to everything with a better claim on the key:
+ *
+ *  - `defaultPrevented` — someone already acted on it. Covers the bar's own
+ *    input, and layers correctly under CommandBar, which preventDefaults
+ *    Escape only while an autocomplete ghost is showing: first Escape dismisses
+ *    the ghost, a second one closes the bar.
+ *  - Modals (`useModalFocus`) stopPropagation on their own node, and
+ *    CaretReviewPanel uses capture + stopImmediatePropagation while focused, so
+ *    neither ever reaches a document bubble listener in the first place.
+ *  - The origin is then required to be inside `.app`, the profile-session shell
+ *    that owns the bar — toolbar, output, command line, docked panels. Floating
+ *    script windows portal to `<body>` instead (`.floating-window-root`), so
+ *    they fall outside it structurally and keep their own Escape.
+ *
+ * Pure apart from reading the event's target, so it is unit-testable.
+ */
+export declare function shouldCloseSearchOnEscape(e: KeyboardEvent): boolean;
+/**
+ * Which way `e` steps through search results — `1` for F3, `-1` for Shift+F3,
+ * or null when it isn't the search-step key at all. Mudlet's binding
+ * (`TConsole::setF3SearchEnabled` wires F3 to slot_searchBufferDown and
+ * Shift+F3 to slot_searchBufferUp).
+ *
+ * Any other modifier disqualifies it, so Ctrl+F3 / Alt+F3 / Cmd+F3 stay
+ * available to the browser and the OS. Pure — reads only `key` and the modifier
+ * flags — and shared by the bar (which steps) and the output area (which opens
+ * the bar when it's closed), so the two can never drift apart.
+ */
+export declare function searchStepDirection(e: KeyboardEvent): -1 | 1 | null;
+/**
+ * The rendered text of a whole matched line, for announcing a hit to a screen
+ * reader. Mudlet's `focusOnSearchResultAndAnnounce` speaks the entire buffer
+ * line rather than the matched fragment, so a listener hears the hit in context.
+ * Excludes the timestamp column, like {@link scanOutput}.
+ */
+export declare function matchLineText(match: OutputMatch): string;
+/**
+ * Park keyboard focus on the current hit so a screen reader's virtual cursor
+ * lands *on* the match in the live output — the reachable half of Mudlet's
+ * `focusOnSearchResultAndAnnounce`, which moves its caret to the found column.
+ *
+ * The mark is made programmatically focusable (`tabIndex = -1`), so it takes
+ * focus without joining the tab order. Scrolling is suppressed: `revealLine`
+ * has already centred the line, and the browser's own focus scroll would
+ * fight it. Returns false when there is no current hit to focus.
+ */
+export declare function focusCurrentHit(container: HTMLElement): boolean;
+/** Unwrap every mark this module added, restoring the pristine rendered line.
+ *  `normalize()` re-merges the text nodes `splitText` created so a subsequent
+ *  scan sees the same node layout it started with. */
+export declare function clearHighlights(container: HTMLElement): void;
+/**
+ * Scroll the output so `line` sits mid-viewport.
+ *
+ * Deliberately not `scrollIntoView` — that walks up and scrolls every scrollable
+ * ancestor, which in a docked layout drags the whole panel around. Measuring
+ * against the wrapper's own rect keeps the movement inside the output.
+ */
+export declare function revealLine(container: HTMLElement, line: HTMLElement): void;
+/**
+ * Index of the match nearest the current viewport — where a fresh search should
+ * start so the first Enter moves from what the player is looking at rather than
+ * from the top of a thousand-line scrollback. Falls back to the last (most
+ * recent) match when nothing is on screen.
+ */
+export declare function indexNearViewport(container: HTMLElement, matches: OutputMatch[]): number;
+/**
+ * Text to prefill the find box with — whatever the player has selected *in the
+ * output*, mirroring the browser's own find.
+ *
+ * Scoped to `container` on purpose. The command line keeps its last command
+ * selected after sending, and `window.getSelection()` can surface that, which
+ * would seed the box with the command the player just ran.
+ */
+export declare function seedFromSelection(container: HTMLElement | null): string;
+/** Locate `target` in a freshly rescanned match list, so incoming MUD output
+ *  does not move the player's place in the results. */
+export declare function findMatchIndex(matches: OutputMatch[], target: OutputMatch | null): number;

package/dist-lib/ui/search/matcher.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The query compiler shared by every search bar in the app (the script editor's
+ * `ScriptSearch`, the output find bar). Turns a raw query plus the case/regex
+ * toggles into something that hands back match ranges for any string.
+ */
+/** Half-open `[start, end)` character offsets of one match. */
+export type MatchRange = [number, number];
+export interface SearchMatcher {
+    /** False when `useRegex` was set and the pattern failed to compile — the
+     *  caller shows the input as invalid rather than reporting "no results". */
+    valid: boolean;
+    ranges: (s: string) => MatchRange[];
+}
+/** Compile a search bar query into a matcher honouring the case / regex flags. */
+export declare function buildMatcher(pattern: string, matchCase: boolean, useRegex: boolean): SearchMatcher;

package/dist-lib/ui/search/useDebounced.d.ts

@@ -0,0 +1,3 @@
+/** Return `value` delayed by `delay` ms — collapses bursts of keystrokes so an
+ *  expensive scan runs at most once per pause in typing. */
+export declare function useDebounced<T>(value: T, delay: number): T;

package/dist-lib/ui/tts/TtsManager.d.ts

@@ -64,5 +64,8 @@ export declare class TtsManager {
     private advance;
     private beginUtterance;
     private setState;
+    /** Text of the most recent ttsSpeechStarted, so speaking over a running
+     *  utterance can tell a genuinely new one from a repeat. */
+    private lastStarted;
 }
 export {};

package/dist-lib/ui/useCommandHistory.d.ts

@@ -1,7 +1,9 @@
 /** Reactive MRU command history wrapper around localStorage. History is scoped
  *  to `connectionId` so each profile keeps its own. `saveSize` caps how many
- *  entries are persisted (Mudlet's `commandLineHistorySaveSize`). */
-export declare function useCommandHistory(connectionId: string | null, saveSize?: number): {
+ *  entries are persisted (Mudlet's `commandLineHistorySaveSize`); `persist`
+ *  is Mudlet's per-command-line `setSaveCommandHistory`, which stops the writing
+ *  without touching the history this session already has. */
+export declare function useCommandHistory(connectionId: string | null, saveSize?: number, persist?: boolean): {
     history: string[];
     add: (item: string) => void;
 };

package/dist-lib/ui/useOpenProfiles.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Connection ids currently open in *another* browser tab.
+ *
+ * Every open profile holds an exclusive Web Lock named `mudix:profile:<id>`
+ * (see profileLock.ts), and `navigator.locks.query()` lists held locks across
+ * all same-origin tabs — so the held profile locks are exactly the open set.
+ * The connection screen renders with no profile active, so this tab holds no
+ * profile lock of its own and every hit belongs to someone else; no
+ * self-filtering is needed.
+ *
+ * Polled, because Web Locks has no change event. The refresh is also driven by
+ * focus/visibility so returning to the launcher tab after closing a profile
+ * elsewhere updates immediately instead of waiting out the interval.
+ *
+ * Returns an empty set where the API is unavailable (legacy browser, insecure
+ * context, test env) — the same "can't tell, so don't claim anything" fallback
+ * the lock itself uses.
+ */
+/** The profile ids among a `navigator.locks.query()` held-lock list. Non-profile
+ *  locks (any other feature using Web Locks) and unnamed entries are ignored. */
+export declare function openProfileIds(held: readonly {
+    name?: string;
+}[] | undefined): Set<string>;
+/** Whether two id sets hold the same members — used to skip no-op state updates. */
+export declare const sameIds: (a: ReadonlySet<string>, b: ReadonlySet<string>) => boolean;
+export declare function useOpenProfiles(enabled?: boolean, refreshMs?: number): Set<string>;

package/dist-lib/ui/video/VideoManager.d.ts

@@ -1,4 +1,5 @@
 import type { MediaCaptionInfo } from '../sound/closedCaption';
+import type { MediaOrigin } from '../sound/SoundManager';
 type LoaderFn = (path: string) => Promise<ArrayBuffer | null>;
 export interface PlayVideoOptions {
     name: string;
@@ -11,6 +12,10 @@ export interface PlayVideoOptions {
     height?: string;
     /** Optional closed-caption text (Mudlet's media `caption`). */
     caption?: string;
+    /** Which mute gate governs this playback. Default 'api' — the only way to
+     *  reach a video today is Lua's `playVideoFile`, but GMCP `Client.Media`
+     *  defines a video type, so the gate is parameterised like the sounds'. */
+    origin?: MediaOrigin;
 }
 export declare class VideoManager {
     private loader;
@@ -20,6 +25,14 @@ export declare class VideoManager {
     private active;
     /** Buffers fetched ahead of play via loadVideoFile, keyed by VFS path. */
     private prefetched;
+    /**
+     * Per-origin mute gates, the video half of {@link SoundManager}'s. A muted
+     * origin's videos keep playing (picture and position both advance) with the
+     * element muted, and new ones start muted — nothing is stopped, so unmuting
+     * restores audio mid-clip. `volume` is left alone so `getPlayingVideos`
+     * still reports what the script asked for.
+     */
+    private muted;
     /** Fires when a video ends naturally or is stopped — mirrors Mudlet's
      *  sysMediaFinished. */
     onEnded: ((name: string, path: string) => void) | null;
@@ -28,6 +41,10 @@ export declare class VideoManager {
     onMediaCaption: ((info: MediaCaptionInfo) => void) | null;
     setLoader(fn: LoaderFn | null): void;
     setMountPoint(fn: (() => HTMLElement | null) | null): void;
+    /** Mudlet `muteMediaAPI` / `muteMediaGame`, applied to video playback. See
+     *  {@link muted}; the sound-side twin is `SoundManager.setOriginMuted`. */
+    setOriginMuted(origin: MediaOrigin, muted: boolean): void;
+    isOriginMuted(origin: MediaOrigin): boolean;
     /**
      * Mudlet `loadVideoFile`. Preloads (fetches + caches) a VFS-backed video so
      * the first playVideoFile has no fetch latency. http(s)/data/blob URLs need

package/dist-lib/ui/windows/WindowManager.d.ts

@@ -1,7 +1,7 @@
 import { type OutputRendererControls } from '../output/OutputRenderer';
 import type { Console } from '../../mud/text/Console';
 import type { AnsiAwareBuffer } from '../../mud/text/FormatState';
-import type { DockSide, WindowHandle, WindowOpenOptions, ScriptWindowRenderData } from './types';
+import type { DockSide, MxpTabPage, WindowHandle, WindowOpenOptions, ScriptWindowRenderData } from './types';
 import { MapStore } from '../../map/MapStore';
 import { OverlayLayerOrder } from '../layout/overlayLayerOrder';
 /** Live handle onto a mounted map renderer, registered by MapPanel. Backs the
@@ -103,6 +103,17 @@ export declare class WindowManager {
      *  from openUserWindow panels for windowType() reporting. */
     private mainViewportEl;
     private readonly miniConsoles;
+    /** MXP `<FRAME>` tab strips, keyed by the frame that hosts the strip. Each
+     *  page is another frame's console nested inside this one's viewport, so
+     *  switching tabs just swaps which child is visible. Purely transient — MXP
+     *  frames are torn down on reconnect and never persisted to a layout hint. */
+    private readonly frameTabs;
+    /** Consoles backing an MXP `<FRAME>`. They render with a hairline border,
+     *  the way Mudlet outlines every frame container (TMxpFrameManager's
+     *  `1px solid #444444`), so a server's panes read as separate panes. */
+    private readonly mxpFrameIds;
+    /** See getMxpBorders. */
+    private mxpBorders;
     private consoleRegistry;
     private windowHints;
     private nextZ;
@@ -146,6 +157,9 @@ export declare class WindowManager {
     /** Bridge to ScriptingEngine.downloadMap — the map UI's "download map from
      *  game" action (Mudlet dlgMapper's Download button). */
     onDownloadMap?: () => void;
+    /** Bridge to the Lua speedwalk entry point (Mudlet Host::startSpeedWalk),
+     *  wired by ScriptingEngine. Driven by {@link startSpeedWalk}. */
+    onStartSpeedWalk?: (from: number, to: number) => void;
     /** The MMP map URL from GMCP `Client.Map`, or '' when none announced. */
     get mmpMapLocation(): string;
     /** Record the game-announced map URL (Mudlet TMap::setMmpMapLocation). */
@@ -327,6 +341,20 @@ export declare class WindowManager {
     registerMapCallback(id: string, cb: (roomId: number) => void): void;
     unregisterMapCallback(id: string): void;
     centerView(roomId: number): boolean;
+    /**
+     * Mudlet `T2DMap::initiateSpeedWalk` — start a speedwalk from the player's
+     * current room to `targetRoomId`, the room the user double-clicked on the
+     * map (or the far side of a double-clicked out-of-area exit).
+     *
+     * Like Mudlet, an unknown target room is ignored outright, while an unknown
+     * *player* room is not: it pathfinds from -1 (Mudlet uses the missing
+     * profile entry, 0), finds nothing, and the Lua side reports the mapper's
+     * "cannot find a path" message rather than failing silently.
+     *
+     * Returns false when the gesture didn't start a walk — no such room, or no
+     * scripting runtime attached to walk it.
+     */
+    startSpeedWalk(targetRoomId: number): boolean;
     registerMapControl(id: string, ctrl: MapControl): void;
     unregisterMapControl(id: string): void;
     /** Live zoom of the displayed 2D map, or null when no map panel is mounted.
@@ -342,7 +370,7 @@ export declare class WindowManager {
     private readonly mapViews;
     /** View ids start at 1 — Mudlet treats 0 as "no view". */
     private nextMapViewId;
-    /** The window id backing a map view. */
+    /** The window id backing a map view. Reserved to the client — see types.ts. */
     private static mapViewWindowId;
     /**
      * Mudlet `createMapView([areaID])` — open a secondary map window. Returns
@@ -512,6 +540,38 @@ export declare class WindowManager {
     loadMapXml(xmlText: string): boolean;
     markAsMiniConsole(id: string): void;
     isMiniConsole(id: string): boolean;
+    /** Flag a console as an MXP frame so it renders with a frame border. Also
+     *  hides its scrollbar: Mudlet's frames are `TConsole::SubConsole`s, which
+     *  start with theirs hidden, and no MXP server ever calls enableScrollBar.
+     *  Idempotent — the layout re-places a frame on every reflow. */
+    markAsMxpFrame(id: string): void;
+    /** Install (or replace) an MXP frame's tab strip. An empty `pages` list
+     *  removes it. Pages other than the active one are hidden, which keeps their
+     *  panel mounted — the content pool renders every open window regardless of
+     *  visibility, so a background tab keeps its scrollback. */
+    setFrameTabs(id: string, pages: MxpTabPage[], active: string): void;
+    /** Switch an MXP frame's visible tab. Ignored for an unknown strip or page. */
+    selectFrameTab(id: string, pageId: string): void;
+    getFrameTabs(id: string): {
+        pages: MxpTabPage[];
+        active: string;
+    } | undefined;
+    /** Pixel insets MXP frames have carved out of the main console. Kept apart
+     *  from the profile's setBorder* sizes (Mudlet splits them the same way, as
+     *  Host::mUserBorders vs mMxpBorders) so a server layout never overwrites
+     *  what a script or the settings modal set — OutputArea adds the two. */
+    getMxpBorders(): {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    setMxpBorders(borders: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    }): void;
     getRoomIDbyHash(hash: string): number | undefined;
     setPosition(id: string, x: number, y: number): void;
     /** Mudlet setWindow for miniconsole / mapper panels — re-portal the panel
@@ -527,6 +587,24 @@ export declare class WindowManager {
      *  override and lets the inherited font take over. */
     setFont(id: string, family: string): boolean;
     getFont(id: string): string | null;
+    /** Pin a console's rendered row height, in px. Consoles normally lay rows
+     *  out at the stylesheet's `line-height`, which is roomier than the type
+     *  itself; an MXP frame instead has to match Mudlet's row metric
+     *  (`TTextEdit::mFontHeight` = ascent + descent), because its whole geometry
+     *  contract is "this many rows fit in this box". Undefined restores the
+     *  stylesheet default. */
+    setLineHeight(id: string, px: number | undefined): boolean;
+    /** Pin a console back to the first line. Consoles are scrollbacks and follow
+     *  the tail, which is wrong for a pane the server rewrites wholesale: such a
+     *  redraw arrives over several network flushes, so following the tail makes
+     *  the content visibly slide as the rows land, then snap back on the next
+     *  clear. No-op before the panel mounts. */
+    scrollToTop(id: string): void;
+    /** Consoles pinned to their first row rather than following the tail. See
+     *  scrollToTop; TextPanel reads this live through the renderer's followTail. */
+    private readonly topAnchored;
+    setTopAnchored(id: string, anchored: boolean): void;
+    isTopAnchored(id: string): boolean;
     /** Mudlet setWindowWrap. 0 (or any non-positive value) clears the override. */
     setWrap(id: string, wrapAt: number): boolean;
     getWrap(id: string): number | null;
@@ -544,6 +622,14 @@ export declare class WindowManager {
      *  on a console wrapper. Wheel/keyboard scrolling continues regardless; only
      *  the gutter rendering is affected. Persists across mounts; idempotent. */
     setScrollBarVisible(id: string, visible: boolean): void;
+    /**
+     * Mudlet `getScrollBarVisible([window])`. Reads back the *intent* set by
+     * enable/disableScrollBar rather than whether a gutter is on screen right
+     * now: a console that is hidden still answers for the scroll bar it will
+     * have when shown. Only the main window starts with one — a miniconsole is
+     * created without, as in Mudlet.
+     */
+    scrollBarVisible(id: string): boolean;
     /** Mudlet enable/disableHorizontalScrollBar — toggle a horizontal scrollbar
      *  on a console wrapper. mudix wraps long lines by default so this is rarely
      *  needed; included for parity. */
@@ -552,6 +638,26 @@ export declare class WindowManager {
      *  bottom (wheel/touch/keys cannot scroll back). Mudlet forbids this on the
      *  main window; we follow that policy. Returns false on 'main', true otherwise. */
     setScrollingEnabled(id: string, enabled: boolean): boolean;
+    /**
+     * Mudlet `timeStampsEnabled(window)` — whether the console is showing its
+     * timestamp column. Null when the window has no renderer registered, which
+     * is how the Lua wrapper tells a missing window from one that simply has
+     * timestamps off. Pre-mount, a queued preference wins over the default.
+     */
+    timeStampsEnabled(id: string): boolean | null;
+    /**
+     * Mudlet `enable/disableTimeStamps(window)`. The renderer owns the column,
+     * but a script can ask for it before the panel has mounted — openUserWindow
+     * followed immediately by enableTimeStamps — so the preference is queued and
+     * applied by registerTextPanel. False when the window doesn't exist at all.
+     */
+    setTimeStamps(id: string, visible: boolean): boolean;
+    /** Timestamp preference asked for before the panel mounted. */
+    private readonly pendingTimestamps;
+    /** Mudlet `scrollingActive(window)` — whether scrollback is currently
+     *  allowed. Always true for `'main'`, which setScrollingEnabled refuses to
+     *  change, and true for any console nobody has called disableScrolling on. */
+    isScrollingEnabled(id: string): boolean;
     /** Buffer-line index of the topmost visible line in `id`'s wrapper. In tail
      *  mode returns the last line number (matching Mudlet's mCursorY behaviour at
      *  the end of the buffer). Returns 0 if the element is unmounted or empty.
@@ -560,6 +666,26 @@ export declare class WindowManager {
      *  is `position: relative` — child offsetTop is relative to *that*, not to the
      *  scroll-container `.output-wrapper`, so the rectangles are the unambiguous
      *  way to relate child position to the scroll viewport. */
+    /** Whether `id`'s wrapper is mounted with laid-out lines, i.e. whether
+     *  {@link getScrollLine}'s measurement means anything. A console whose panel
+     *  isn't on screen yet measures as 0, which is indistinguishable from being
+     *  genuinely scrolled to the top. */
+    canMeasureScroll(id: string): boolean;
+    /**
+     * Where `scrollTo` last parked each console, as a buffer line index; absent
+     * means tail mode (or that only the user has scrolled it).
+     *
+     * Mudlet's getScroll/scrollTo are buffer-index operations. mudix measured
+     * the DOM instead, which is fine for a console the player is looking at but
+     * answers nothing useful for one whose panel has not been laid out yet — and
+     * a script that scrolls and reads back in the same breath never gives React
+     * a chance to commit in between. So the scripted position is remembered here
+     * and the measurement is the fallback, not the source of truth.
+     */
+    private readonly scriptScrollLine;
+    /** Called when the *user* scrolls a console, so a script's remembered
+     *  position stops overriding what they can see. */
+    noteUserScroll(id: string): void;
     getScrollLine(id: string): number;
     /** Scroll `id`'s wrapper so `line` (0-indexed) sits at the top. `undefined`
      *  resumes tail mode (scroll-to-bottom); negative values count from the end
@@ -594,6 +720,14 @@ export declare class WindowManager {
      *  translates it through cmdLineQssToScopedCss at render time. Returns
      *  false when the window doesn't exist. */
     setCmdLineStyleSheet(id: string, qss: string): boolean;
+    /**
+     * Mudlet setCommandForegroundColor / setCommandBackgroundColor for a named
+     * window. Mudlet styles a per-window command line through QSS, so the colour
+     * is patched into the same `cmdLineStyleSheet` a script could have set by
+     * hand rather than kept as a parallel piece of state. False when the window
+     * doesn't exist.
+     */
+    setCmdLineColor(id: string, property: 'color' | 'background-color', r: number, g: number, b: number, a: number): boolean;
     /** Bind the Lua callback fired when the user presses Enter in this
      *  window's command line. Pass null to clear. Returns false when the
      *  window doesn't exist. */
@@ -670,6 +804,19 @@ export declare class WindowManager {
      * behaviour). Returns false when the named window doesn't exist.
      */
     setTitle(id: string, title?: string): boolean;
+    /** Mudlet `getUserWindowTitle(name)` — the header text, whether it was set
+     *  or generated. Null when there is no such window. */
+    getTitle(id: string): string | null;
+    /**
+     * The title a window carries when nobody has set one. Mudlet builds it from
+     * the profile and the window's own name ("<profile> - <window>"), which is
+     * what a player sees on a freshly opened user window; mudix used to fall
+     * back to the bare id, so resetting a title lost the profile half of it.
+     * The profile name is injected by ScriptingAPI — the manager has no other
+     * reason to know it.
+     */
+    profileName: string;
+    defaultTitle(id: string): string;
     focus(id: string): void;
     has(id: string): boolean;
     getElement(id: string): HTMLElement | null;

package/dist-lib/ui/windows/panels/MapPanel.d.ts

@@ -1,8 +1,11 @@
 import type { WindowManager } from '../WindowManager';
+import type { ProfileVFS } from '../../../scripting/vfs/ProfileVFS';
 interface MapPanelProps {
     id: string;
     manager: WindowManager;
     connectionId: string;
+    /** Lets "Load map…" read a .dat/.xml the profile already holds. */
+    vfs?: ProfileVFS | null;
 }
-export declare function MapPanel({ id, manager, connectionId }: MapPanelProps): import("react/jsx-runtime").JSX.Element;
+export declare function MapPanel({ id, manager, connectionId, vfs }: MapPanelProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist-lib/ui/windows/panels/PackageExportModal.d.ts

@@ -0,0 +1,18 @@
+import type { ProfileVFS } from '../../../scripting/vfs/ProfileVFS';
+import './PackageExportModal.css';
+export type ExportCategory = 'triggers' | 'aliases' | 'scripts' | 'timers' | 'keys' | 'buttons';
+interface Props {
+    connectionId: string;
+    vfs: ProfileVFS | null;
+    /** Pre-check this item (and its subtree), as Mudlet does when the exporter is
+     *  opened from a right-click in the editor tree. */
+    preselect?: {
+        category: ExportCategory;
+        id: string;
+    } | null;
+    onClose: () => void;
+    /** Reported back for the editor's log pane. */
+    onExported?: (message: string) => void;
+}
+export declare function PackageExportModal({ connectionId, vfs, preselect, onClose, onExported }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist-lib/ui/windows/panels/TextPanel.d.ts

@@ -13,6 +13,8 @@ interface TextPanelProps {
     scrollBoxes?: ScrollBoxManager;
     fontSize?: number;
     fontFamily?: string;
+    /** Rendered row height in px (MXP frames). See WindowManager.setLineHeight. */
+    lineHeight?: number;
     wrapAt?: number;
     wrapIndent?: number;
     wrapHangingIndent?: number;
@@ -31,5 +33,5 @@ interface TextPanelProps {
     cmdLineValue?: string;
     cmdLineValueSeq?: number;
 }
-export declare function TextPanel({ id, title, manager, labels, cmdLines, scrollBoxes, fontSize, fontFamily, wrapAt, wrapIndent, wrapHangingIndent, backgroundColor, backgroundImage, cmdLineEnabled, cmdLineStyleSheet, cmdLineValue, cmdLineValueSeq }: TextPanelProps): import("react/jsx-runtime").JSX.Element;
+export declare function TextPanel({ id, title, manager, labels, cmdLines, scrollBoxes, fontSize, fontFamily, lineHeight, wrapAt, wrapIndent, wrapHangingIndent, backgroundColor, backgroundImage, cmdLineEnabled, cmdLineStyleSheet, cmdLineValue, cmdLineValueSeq }: TextPanelProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist-lib/ui/windows/types.d.ts

@@ -11,6 +11,27 @@ export interface DragState {
     /** true = insert before target in cross-axis; false = after. */
     splitBefore?: boolean;
 }
+/** One page of an MXP `<FRAME>` tab strip. `id` is the frame whose console the
+ *  tab shows — the host frame itself for the first page, a `DOCK`ed child
+ *  otherwise. See MxpFrameManager. */
+export interface MxpTabPage {
+    id: string;
+    title: string;
+}
+/** The dockable map widget — the toolbar's Map button and Lua openMapWidget. */
+export declare const MAP_WIDGET_ID = "sys:map";
+/** The embedded mapper created by Lua createMapper / Geyser.Mapper. */
+export declare const MAPPER_WIDGET_ID = "sys:mapper";
+/** Window id backing secondary map views (Lua createMapView). */
+export declare function mapViewWindowId(viewId: number): string;
+export declare const MAP_VIEW_ID_RE: RegExp;
+/**
+ * Saved window hints predate the prefix, so a profile stored the map widget's
+ * geometry under the bare `map`. Rename it on load, or every existing profile
+ * loses its Map position, size and dock side. Bare `mapper`/`mapViewN` need no
+ * migration: neither is ever restored from a hint.
+ */
+export declare function migrateClientWindowHints(hints: Record<string, WindowOpenOptions>): Record<string, WindowOpenOptions>;
 export interface WindowOpenOptions {
     title?: string;
     kind?: 'text' | 'html' | 'map';
@@ -46,6 +67,10 @@ export interface WindowOpenOptions {
     fontSize?: number;
     /** Output font family override (Mudlet setFont). */
     fontFamily?: string;
+    /** Rendered row height in px, overriding the stylesheet's line-height. Set
+     *  for MXP frames so a box of N rows really holds N rows. See
+     *  WindowManager.setLineHeight. */
+    lineHeight?: number;
     /** Character-column wrap width (Mudlet setWindowWrap). 0/undefined disables. */
     wrapAt?: number;
     /** Indent (in characters) of newline-started lines (Mudlet setWindowWrapIndent). */
@@ -102,6 +127,8 @@ export interface ScriptWindowRenderData {
     splitFlex?: number;
     fontSize?: number;
     fontFamily?: string;
+    /** See WindowOpenOptions.lineHeight. */
+    lineHeight?: number;
     wrapAt?: number;
     wrapIndent?: number;
     wrapHangingIndent?: number;
@@ -142,4 +169,12 @@ export interface ScriptWindowRenderData {
      *  still trigger React's seed effect (otherwise printCmdLine('x') after a
      *  user types 'x' would do nothing). */
     cmdLineValueSeq?: number;
+    /** MXP `<FRAME TITLE=…>` tab strip rendered as this window's chrome. Absent
+     *  for every other window; set only by MxpFrameManager. */
+    frameTabs?: {
+        pages: MxpTabPage[];
+        active: string;
+    };
+    /** True for a console backing an MXP `<FRAME>` — draws the frame border. */
+    isMxpFrame?: boolean;
 }

package/dist-lib/utils/describeThrown.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Render a caught value for a user-facing error line.
+ *
+ * `String(err)` is the usual shorthand, but it collapses every non-`Error`
+ * object to the literal text "[object Object]" — which is exactly what the
+ * script error log showed for errors that never went through Lua's own
+ * `error()`. Those come from a JS exception escaping the wasm boundary: the
+ * metamethod trampolines wasmoon installs for JS objects (`__index`,
+ * `__newindex`, `__tostring`) don't wrap the call, so a throw inside a getter
+ * unwinds straight past Lua into whoever called `resume`. Nothing rewrites it
+ * into a Lua error string on the way, so the value arrives raw — and a raw
+ * plain object rendered with `String` says nothing at all.
+ *
+ * Errors keep rendering as their bare `message` (unchanged); everything else is
+ * described by what it actually is.
+ *
+ * Pass `label` (the entity or event the failure is attributed to) to also
+ * record the live value in devtools when it is opaque — such a value carries no
+ * stack of its own, so the object itself is the only handle on where it came
+ * from.
+ */
+export declare function describeThrown(err: unknown, label?: string): string;

package/dist-lib/utils/fontLoader.d.ts

@@ -34,6 +34,11 @@ export interface LocalFontEntry {
 }
 export declare function isLocalFontApiSupported(): boolean;
 export declare function queryLocalFonts(): Promise<LocalFontEntry[]>;
+/** The family consoles actually render in when the profile sets none — the
+ *  bundled face App.css applies (picked to match Mudlet's default look). Mudlet
+ *  always reports a concrete family from getFont, never an empty string, and
+ *  UI_spec checks that what comes back is a real name. */
+export declare const DEFAULT_OUTPUT_FONT_FAMILY = "Bitstream Vera Sans Mono";
 export declare function getUniversalDefaultFonts(): readonly string[];
 export declare function getCachedLocalFonts(): string[];
 export declare function setLocalFontsCache(families: Iterable<string>): void;