@mudlet/mudlet-web 0.3.0

package/dist-lib/mud/protocol/mnes.d.ts

@@ -0,0 +1,83 @@
+import { CLIENT_NAME, CLIENT_VERSION, TERMINAL_TYPE } from "../../version";
+/** A single MNES variable the client reports back, e.g. `{ name: "CHARSET",
+ *  value: "UTF-8" }`. */
+export interface MnesVar {
+    name: string;
+    value: string;
+}
+/** Result of parsing an `IAC SB NEW-ENVIRON SEND … IAC SE` request body. */
+export interface MnesRequest {
+    /** True when the body is a well-formed SEND command (the only request kind
+     *  a client answers). */
+    isSend: boolean;
+    /** Variable names the server explicitly asked for, in request order. Empty
+     *  means a bare SEND — the server wants every variable we report. */
+    requested: string[];
+}
+/**
+ * Parse an `IAC SB NEW-ENVIRON SEND …` request. `subneg` is the subnegotiation
+ * body with the leading option code (39) still attached (matching how the
+ * telnet option parser hands bodies to the other protocol streams). The byte
+ * after the option code is the command; for a server→client request it's SEND.
+ * After SEND comes an optional list of `VAR <name>` / `USERVAR <name>` entries,
+ * each name running until the next marker (ESC-escaped bytes pass through).
+ * A bare SEND with no entries — or only empty names — means "send everything".
+ */
+export declare function parseMnesRequest(subneg: string): MnesRequest;
+/**
+ * Frame an `IAC SB NEW-ENVIRON IS <marker> <name> VALUE <value> … IAC SE` reply
+ * for the given variables. The returned string is a Latin-1 byte-string ready
+ * for sendBytes (names/values are ASCII; control bytes are escaped per RFC
+ * 1572). `marker` selects how each variable name is tagged: `NEW_ENVIRON_VAR`
+ * (the default — MNES frames every variable as a standard VAR) or
+ * `NEW_ENVIRON_USERVAR` (plain NEW-ENVIRON frames its client-defined variables
+ * as USERVAR, matching Mudlet). The two never mix within one reply because the
+ * client reports a single coherent set per negotiated mode.
+ */
+export declare function encodeMnesIs(vars: ReadonlyArray<MnesVar>, marker?: string): string;
+/** Live client state the NEW-ENVIRON variable set is derived from. Everything
+ *  here is something the server can't know on its own — the negotiated encoding,
+ *  the transport's TLS status, the output window's wrap column. */
+export interface NewEnvironState {
+    /** The active byte→char codec label as reported for the CHARSET variable,
+     *  e.g. "UTF-8" or "LATIN-1". */
+    charset: string;
+    /** Whether the live encoding is UTF-8 (drives the UTF-8 capability flag). */
+    utf8: boolean;
+    /** Whether the link to the game server is TLS-encrypted. True for a direct
+     *  `wss://` connection; false in proxy mode (plaintext upstream telnet). */
+    tls: boolean;
+    /** Output window wrap column, or 0 when the grid hasn't been measured yet. */
+    wrapColumns: number;
+    /** Whether the client is advertising screen-reader use (MTTS SCREEN READER
+     *  bit, NEW-ENVIRON SCREEN_READER var) — `setConfig("advertiseScreenReader", …)`.
+     *  Defaults to false (matching Mudlet's opt-in behaviour). */
+    screenReader?: boolean;
+}
+/** The five core variables MNES standardises (https://tintin.mudhalla.net/protocols/mnes/).
+ *  Plain NEW-ENVIRON reports these too, plus the extended capability set below.
+ *  Client name/version/terminal type come from the shared identity module so
+ *  MNES, TTYPE, GMCP `Core.Hello` and MXP can't drift apart; re-exported here
+ *  because the protocol barrel and `MudClient` already source them from MNES. */
+export { CLIENT_NAME, CLIENT_VERSION, TERMINAL_TYPE };
+/**
+ * Build the variable set the client reports for option 39. The five MNES core
+ * variables (CHARSET, CLIENT_NAME, CLIENT_VERSION, MTTS, TERMINAL_TYPE) are
+ * always present; when `extended` is true the broader NEW-ENVIRON capability
+ * set is appended (mirroring Mudlet's `getNewEnvironDataMap`): terminal
+ * capabilities (ANSI, 256_COLORS, TRUECOLOR, UTF-8), transport/security (TLS),
+ * and layout/accessibility hints (WORD_WRAP, SCREEN_READER). Capabilities mudix
+ * doesn't implement are reported honestly as "0" rather than omitted, so a
+ * server gets a definite answer instead of inferring absence. The caller frames
+ * the result with VAR (MNES) or USERVAR (NEW-ENVIRON) via encodeMnesIs.
+ */
+export declare function buildNewEnvironVars(state: NewEnvironState, extended: boolean): MnesVar[];
+/**
+ * Pick which of the client's `available` MNES variables to report in response
+ * to a parsed request. A bare SEND (no specific names) returns everything;
+ * otherwise the requested names are returned in request order, filtered to the
+ * ones we actually know. If the server asked only for names we don't report,
+ * we fall back to sending everything rather than an empty reply — the server
+ * still learns who we are.
+ */
+export declare function selectMnesVars(request: MnesRequest, available: ReadonlyArray<MnesVar>): MnesVar[];

package/dist-lib/mud/protocol/msdp.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Frame a Mudlet-style `sendMSDP(variable, ...values)` call as an MSDP
+ * subnegotiation: `IAC SB MSDP MSDP_VAR <variable> [MSDP_VAL <value>]... IAC SE`.
+ * The returned string is a Latin-1 byte-string ready for sendBytes.
+ */
+export declare function encodeMsdp(variable: string, values: string[]): string;
+export interface MsdpEnvelope {
+    /** Top-level MSDP variable name (e.g. "HEALTH", "ROOM"). */
+    path: string;
+    /** Decoded value: a string, an array, or a nested string-keyed object. */
+    value: unknown;
+}
+export interface MsdpStreamOptions {
+    onEnvelope: (payload: MsdpEnvelope) => void;
+}
+/** Mirror of createGmcpStream for MSDP subnegotiations. The handler receives a
+ *  subnegotiation body whose first byte is the MSDP option code (69); each
+ *  top-level variable is emitted as its own envelope. */
+export declare const createMsdpStream: ({ onEnvelope }: MsdpStreamOptions) => (data: string) => void;

package/dist-lib/mud/protocol/msp.d.ts

@@ -0,0 +1,47 @@
+export type MspKind = "sound" | "music";
+/** Parsed `!!SOUND` / `!!MUSIC` command. Numeric fields fall back to undefined
+ *  when the server omits the key — the consumer (SoundManager) substitutes its
+ *  own defaults rather than having parser-level defaults bleed downstream. */
+export interface MspCommand {
+    kind: MspKind;
+    /** Filename or the literal `Off` (case-sensitive per spec) to stop playback. */
+    file: string;
+    /** U= field — explicit URL the file can be downloaded from. */
+    url?: string;
+    /** V= field — volume 0..100 on the MSP scale. */
+    volume?: number;
+    /** L= field — loop count. -1 = forever, otherwise positive integer. */
+    loops?: number;
+    /** P= field — priority 0..100. Only meaningful for `!!SOUND`. */
+    priority?: number;
+    /** C= field — `1` = if same is already playing, keep it (no restart). */
+    continueIfPlaying?: boolean;
+    /** T= field — channel / tag string. */
+    type?: string;
+}
+/**
+ * Stateful MSP parser. Feed each post-telnet-strip chunk through `feed()` and
+ * render the returned `text` instead of the raw input. Parsed commands are
+ * delivered as `commands`. The parser holds back a partial tag (`!!SOUND(...`
+ * with no closing `)` yet) until the next chunk supplies the rest, so tags
+ * split across WebSocket frames still parse correctly.
+ */
+export declare class MspParser {
+    /** Partial tag carried over from the previous chunk, including the
+     *  leading `!!`. Empty when no tag is in progress. */
+    private pending;
+    feed(input: string): {
+        text: string;
+        commands: MspCommand[];
+    };
+    /** Drop any partial-tag buffer. Called on disconnect / reconnect. */
+    reset(): void;
+    /** Parse the body of an `IAC SB MSP ... IAC SE` subnegotiation. The body
+     *  byte[0] is the option code (90); the rest is the raw tag text (often
+     *  `!!SOUND(...)`) per the spec, though some implementations send just the
+     *  body inside the parens. We try both. A subnegotiation is framed as a
+     *  whole unit by the time it reaches us, so we don't share parser state
+     *  with the in-band stream — running `feed()` here would let a malformed
+     *  subneg leak a partial-tag buffer into the next inline chunk. */
+    feedSubneg(subneg: string): MspCommand[];
+}

package/dist-lib/mud/protocol/mssp.d.ts

@@ -0,0 +1,25 @@
+export interface MsspEnvelope {
+    /** MSSP variable name (e.g. "PLAYERS", "UPTIME", "HOSTNAME"). */
+    name: string;
+    /** The reported value. Always a string — Mudlet treats MSSP values as
+     *  scalars (the multi-value list form, rare in practice, is collapsed to
+     *  the first value). */
+    value: string;
+}
+/**
+ * Parse an MSSP subnegotiation body (the `IAC SB MSSP … IAC SE` payload with
+ * the leading option byte already stripped). The grammar is a flat run of
+ * `MSSP_VAR <name> MSSP_VAL <value>` pairs; names/values are scalar byte runs
+ * terminated by the next control byte. Tolerant of truncation and stray bytes.
+ *
+ * Mirrors Mudlet's TLuaInterpreter::parseMSSP: scalar string values, and a
+ * variable with extra `MSSP_VAL` runs keeps only its first value.
+ */
+export declare function parseMssp(body: string): MsspEnvelope[];
+export interface MsspStreamOptions {
+    onEnvelope: (payload: MsspEnvelope) => void;
+}
+/** Mirror of createMsdpStream for MSSP subnegotiations. The handler receives a
+ *  subnegotiation body whose first byte is the MSSP option code (70); each
+ *  variable is emitted as its own envelope. */
+export declare const createMsspStream: ({ onEnvelope }: MsspStreamOptions) => (data: string) => void;

package/dist-lib/mud/protocol/mxp.d.ts

@@ -0,0 +1,188 @@
+import type { BufferSegment, FormatStateSnapshot } from "../text/FormatState";
+import { HyperlinkPresetRegistry } from "../text/hyperlinkConfig";
+import type { MspCommand } from "./msp";
+/** A clickable region the parser found, expressed as offsets into `plain`. The
+ *  engine builds the actual `FormatHyperlink` (with session/URL behaviour). */
+export interface MxpLink {
+    /** Start offset into the line's plain text (inclusive). */
+    start: number;
+    /** End offset into the line's plain text (exclusive). */
+    end: number;
+    /** `url` → open in a browser tab; `command` → send to the MUD. */
+    kind: "command" | "url";
+    /** The single command or URL fired on left-click. */
+    payload: string;
+    /** Tooltip / title text. */
+    hint?: string;
+    /** Present when the SEND carried a `cmd1|cmd2|…` list — the engine renders a
+     *  right-click popup of `cmds` labelled by `hints`. */
+    prompts?: {
+        cmds: string[];
+        hints: string[];
+    };
+}
+/** A `<FRAME>` window-lifecycle command the parser surfaces to the session.
+ *  The parser is session-free, so it only reports the request; the consumer
+ *  (ScriptingEngine) maps it onto a mini-console via the window manager. */
+export interface MxpFrameCommand {
+    /** Frame name (the window id). */
+    name: string;
+    /** Upper-cased attribute keys → raw string values. Flag attributes
+     *  (`INTERNAL`/`EXTERNAL`/`FLOATING`) are present with value `"true"`.
+     *  `ACTION` is `open` (default) / `close` / `redirect`; geometry lives in
+     *  `LEFT`/`TOP`/`WIDTH`/`HEIGHT`. */
+    attrs: Record<string, string>;
+}
+/** Text the parser redirected into a named frame via `<DEST>…</DEST>`. */
+export interface MxpRedirect {
+    /** Target frame name (matches an `MxpFrameCommand.name`). */
+    frame: string;
+    /** Styled segments of the redirected text. */
+    segments: BufferSegment[];
+    /** Plain text of the redirected run. */
+    plain: string;
+    /** `EOL` attr (or the network line ended mid-DEST): the write is a complete
+     *  line. */
+    eol: boolean;
+    /** `EOF` attr: clear the frame before writing (status-frame replace). */
+    eof: boolean;
+}
+/** The result of parsing one raw MXP line. */
+export interface MxpLineResult {
+    /** Styled segments, ready for `new AnsiAwareBuffer(segments)`. */
+    segments: BufferSegment[];
+    /** MXP-stripped, ANSI-stripped, entity-decoded text — for trigger matching. */
+    plain: string;
+    /** End-of-line SGR/format pen, carried into the next line (replaces
+     *  `computeTrailingState` while MXP is active). */
+    trailingSnapshot?: FormatStateSnapshot;
+    /** Clickable regions discovered on this line. */
+    links: MxpLink[];
+    /** `<FRAME>` commands seen on this line (window create/close). Omitted when none. */
+    frames?: MxpFrameCommand[];
+    /** Text redirected into frames via `<DEST>` on this line. Omitted when none. */
+    redirects?: MxpRedirect[];
+    /** `<SOUND>`/`<MUSIC>` audio triggers seen on this line, shaped as
+     *  {@link MspCommand} so the consumer can route them through the same
+     *  SoundManager path as MSP. Omitted when none. */
+    sounds?: MspCommand[];
+}
+export declare class MxpParser {
+    private readonly opts;
+    private elements;
+    private entities;
+    private lineMode;
+    private lockedMode;
+    private tempSecure;
+    private stack;
+    /** Active MXP `<COLOR>`/`<FONT>` fg/bg overrides, innermost last. While
+     *  non-empty, the top entry's colours are painted over whatever the ANSI
+     *  pen holds — matching Mudlet, where an open MXP colour element overrides
+     *  embedded ANSI SGR (TBuffer.cpp: `if (hasFgColor()) c.mFgColor = ...`).
+     *  Stays in sync with the colour tags on `stack` (pushed in openColor,
+     *  popped in finalizeTag). */
+    private mxpColorStack;
+    /** Partial tag/entity held from the end of the previous line. */
+    private pendingTag;
+    /** Active `<DEST>` target frame (persists across lines until `</DEST>`), or
+     *  null when output flows to the main window. While set, appended text and
+     *  flushed runs route to `destOut`/`destPlain` instead of `out`/`plain`. */
+    private destName;
+    private destEol;
+    private destEof;
+    /** OSC 8 preset definitions seen this session (shared with the ANSI path
+     *  when the engine supplies a registry). */
+    private presets;
+    private fmt;
+    private out;
+    private run;
+    private plain;
+    private links;
+    /** `<FRAME>` commands and `<DEST>` redirects accumulated this line. */
+    private frames;
+    private redirects;
+    /** `<SOUND>`/`<MUSIC>` commands accumulated this line. */
+    private sounds;
+    /** Redirected-text scratch — the current `<DEST>` run's segments/plain. */
+    private destOut;
+    private destPlain;
+    constructor(opts: {
+        send: (raw: string) => void;
+        presets?: HyperlinkPresetRegistry;
+        /** Fired whenever a server-defined custom element is used, with the
+         *  tag's attributes resolved the way Mudlet resolves them (see
+         *  {@link elementEventAttrs}). Backs the Lua `mxp` table. */
+        onElementEvent?: (name: string, attrs: Record<string, string>) => void;
+    });
+    /**
+     * Lock the parser to secure line mode (or release the lock). Mudlet does
+     * this whenever the MXP processor is forced on without an option-91
+     * handshake (ctelnet.cpp: MXP_MODE_CODE_LOCK_SECURE): such servers are
+     * IRE-style and never send mode switches, they just use secure tags — and
+     * without the lock every definition tag would be ignored as unsafe.
+     */
+    lockSecureMode(locked: boolean): void;
+    /** Clear all cross-line state. Called on (re)connect so a new session starts
+     *  with no leftover definitions, open tags, or modes. */
+    reset(): void;
+    /** Parse one raw line (post telnet-strip, post UTF-8 decode), which may carry
+     *  ANSI SGR, MXP tags, `ESC[#z` modes, and entities. `baseSnapshot` is the
+     *  carried pen from the previous line. */
+    parseLine(rawLine: string, baseSnapshot?: FormatStateSnapshot): MxpLineResult;
+    private effectiveMode;
+    private resetTransientMode;
+    private appendText;
+    private flushRun;
+    private parseFragment;
+    private applyLineMode;
+    private closeAllTags;
+    private handleTag;
+    private openAllowed;
+    private handleOpenTag;
+    /** `<FRAME name [action] [internal|external|floating] [left|top|width|height]
+     *  [scrolling] [title]>` — record a window create/close request for the
+     *  consumer. NAME is the first positional or the NAME attribute; valueless
+     *  flags (INTERNAL/EXTERNAL/FLOATING) become `"true"`. */
+    private handleFrameTag;
+    /** `<DEST name [eol] [eof]>` — start redirecting enclosed text into `name`.
+     *  NAME is the NAME attribute or the first non-flag positional. Persists
+     *  until `</DEST>` (or end of line). A nameless DEST is ignored so its text
+     *  renders inline, matching Mudlet (setMxpDestination fails → not handled). */
+    private handleDestTag;
+    /** `<SOUND fname [V=vol] [L=loops] [P=priority] [T=type] [U=url]>` and
+     *  `<MUSIC fname [V=vol] [L=loops] [C=continue] [T=type] [U=url]>` — MXP's
+     *  audio triggers (https://www.zuggsoft.com/zmud/mxp.htm#Sound). They carry
+     *  the same fields as MSP's `!!SOUND`/`!!MUSIC`, so surface them as an
+     *  {@link MspCommand} and let the consumer route them through the same
+     *  SoundManager path. FNAME is the FNAME attribute or the first positional;
+     *  the literal `Off` (also `off`) stops playback. A fileless tag is ignored. */
+    private handleSoundTag;
+    /** Finalize the current `<DEST>` run into a redirect and stop redirecting. */
+    private closeDest;
+    private openFormat;
+    private openColor;
+    private openLink;
+    private openVar;
+    private handleCloseTag;
+    private finalizeTag;
+    private handleDefinition;
+    private defineElement;
+    private defineEntity;
+    private expandElement;
+    private substituteTemplate;
+    private decodeEntity;
+}
+/** Split a parsed MXP line into one entry per *visual* line. MXP `<BR>` tags
+ *  become embedded `\n`s in the parser's plain text and segments — Discworld
+ *  sends a whole room (description, exits, contents, prompt) as a single network
+ *  line delimited by `<BR>` — but a render path that emits one line per result
+ *  would collapse them all together. So we split the segments at every `\n`,
+ *  re-slicing each segment's text and remapping each link's `plain`-offset range
+ *  into the subline it falls on. The `\n` separators are dropped (each subline
+ *  renders on its own). The fast path (no embedded newline) returns the result
+ *  untouched, sharing the original arrays. */
+export declare function splitMxpResultLines(r: MxpLineResult): {
+    plain: string;
+    segments: BufferSegment[];
+    links: MxpLink[];
+}[];

package/dist-lib/mud/protocol/naws.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Frame an `IAC SB NAWS <width> <height> IAC SE` subnegotiation (telnet option
+ * 31, RFC 1073) reporting the client window size as character columns × rows.
+ * Both dimensions are 16-bit big-endian, clamped to [0, 65535], with IAC bytes
+ * escaped. The returned string is a Latin-1 byte-string ready for sendRaw.
+ */
+export declare function encodeNaws(cols: number, rows: number): string;

package/dist-lib/mud/replay/ReplayPlayer.d.ts

@@ -0,0 +1,31 @@
+import { type ReplayChunk } from './replayFormat';
+export interface ReplayPlayerCallbacks {
+    /** Current playback speed divisor (1 = real time). Read at each chunk's
+     *  schedule time, so mid-replay speed changes affect subsequent chunks —
+     *  matching Mudlet's `offset / mReplaySpeed` singleShot scheduling. */
+    speed: () => number;
+    /** Deliver one chunk's bytes (as a Latin-1 byte-string) to the inbound
+     *  telnet pipeline. */
+    feed: (data: string) => void;
+    /** Fired once, after the last chunk has been delivered. Not fired on abort. */
+    onDone: () => void;
+}
+/**
+ * Plays parsed replay chunks back on their recorded timeline: each chunk is
+ * scheduled `offsetMs / speed` after the previous one and fed into the telnet
+ * parsing pipeline, so triggers, GMCP handlers, and rendering all behave as
+ * they did live.
+ */
+export declare class ReplayPlayer {
+    private readonly chunks;
+    private readonly callbacks;
+    private timer;
+    private index;
+    private finished;
+    constructor(chunks: ReplayChunk[], callbacks: ReplayPlayerCallbacks);
+    start(): void;
+    /** Stop playback and drop any pending chunk. Idempotent; onDone is not
+     *  fired for an aborted replay. */
+    abort(): void;
+    private scheduleNext;
+}

package/dist-lib/mud/replay/ReplayRecorder.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Accumulates the inbound telnet stream into Mudlet replay chunks. Fed with
+ * the post-MCCP Latin-1 byte-strings the client emits as `socket.incoming` —
+ * the same tap point Mudlet records at, so the file captures IAC sequences,
+ * GMCP subnegotiations, prompts, and ANSI verbatim. Chunks are buffered in
+ * memory (MUD output is small) and serialized once on stop().
+ */
+export declare class ReplayRecorder {
+    private chunks;
+    private lastChunkTime;
+    constructor();
+    /** Record one inbound data block. The chunk's offset is the time elapsed
+     *  since the previous block (or since recording started, for the first). */
+    feed(data: string): void;
+    get chunkCount(): number;
+    /** Serialize everything recorded so far to Mudlet's .dat format. */
+    encode(): Uint8Array;
+}

package/dist-lib/mud/replay/replayFormat.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Mudlet binary replay (".dat") format — the files written by Mudlet's
+ * "record replay" toolbar button and consumed by its `loadReplay()`.
+ *
+ * The on-disk layout is a bare sequence of chunk records with no header:
+ *
+ *     int32 BE  offsetMs   milliseconds elapsed since the previous chunk
+ *     int32 BE  length     payload byte count (1..REPLAY_MAX_CHUNK)
+ *     bytes     payload    the network data verbatim — post-MCCP-decompression,
+ *                          pre-telnet-parsing, IAC sequences and all
+ *
+ * Qt's QDataStream defaults to big-endian, and Mudlet only ever streams
+ * qint32s + raw bytes, so this is the complete format. One historical quirk:
+ * Mudlet PR #4400 accidentally widened the offset to a qint64 for some
+ * releases (the "modified format"); Mudlet's loader trial-parses the original
+ * layout first and falls back, and parseReplay mirrors that so both vintages
+ * load. We always *write* the original format — what current Mudlet records.
+ */
+export interface ReplayChunk {
+    /** Milliseconds since the previous chunk (recording start for the first). */
+    offsetMs: number;
+    /** Raw telnet bytes as received post-MCCP. */
+    data: Uint8Array;
+}
+/** Mudlet's replay read buffer size (cTelnet BUFFER_SIZE). A record whose
+ *  length field exceeds this is treated as corrupt by Mudlet's loader, so the
+ *  encoder splits bigger payloads into continuation records (offset 0). */
+export declare const REPLAY_MAX_CHUNK = 100000;
+/** Latin-1 byte-string (charCode === byte) → bytes, the inverse of
+ *  {@link replayBytesToLatin1}. The telnet pipeline traffics in these strings. */
+export declare function replayLatin1ToBytes(data: string): Uint8Array;
+/** Bytes → Latin-1 byte-string, chunked to respect String.fromCharCode's
+ *  argument limit on large payloads (same trick as MudClient's frame decode). */
+export declare function replayBytesToLatin1(bytes: Uint8Array): string;
+/** Serialize chunks to the original (current-Mudlet) replay format. Payloads
+ *  larger than {@link REPLAY_MAX_CHUNK} are split into continuation records
+ *  with a 0ms offset so Mudlet itself can read the file back. Empty payloads
+ *  are dropped — Mudlet's loader treats a 0-length record as corruption. */
+export declare function encodeReplay(chunks: ReplayChunk[]): Uint8Array;
+/** Parse a replay file, auto-detecting the original (4-byte offset) vs the
+ *  modified (8-byte offset, PR #4400 era) layout the way Mudlet's
+ *  testReadReplayFile does: trial-parse original first, fall back to modified.
+ *  Returns null when the data is readable as neither — "seems to be corrupt". */
+export declare function parseReplay(bytes: Uint8Array): ReplayChunk[] | null;
+/** Total recorded duration in milliseconds (sum of chunk offsets). */
+export declare function replayDurationMs(chunks: ReplayChunk[]): number;
+/** Mudlet-style replay file name for a recording finished at `date`:
+ *  `yyyy-MM-dd#HH-mm-ss.dat`, e.g. `2026-07-08#14-03-59.dat`. */
+export declare function replayFileName(date: Date): string;

package/dist-lib/mud/text/Console.d.ts

@@ -0,0 +1,183 @@
+import { FormatState } from './FormatState';
+import { AnsiAwareBuffer } from './FormatState';
+import type { FormatStateSnapshot } from './FormatState';
+/**
+ * Self-contained text output entity — equivalent of Mudlet's TConsole.
+ * Owns format state, line history, and cursor position.
+ * The renderer is a pure consumer: it receives lines via takeLines() and
+ * calls buf.notifyRender() so that rerender()/removeFromDom() can reach the DOM.
+ */
+export declare class Console {
+    readonly format: FormatState;
+    private history;
+    private pending;
+    private partial;
+    private cursorIdx;
+    private cursorCol;
+    private _maxLines;
+    private _batchDeleteSize;
+    /** Mudlet `sysBufferShrinkEvent(name, linesRemoved)` hook. Fired by
+     *  `evict()` whenever the scrollback cap drops one or more lines from the
+     *  head of `history`. Set by the owning session (ScriptingAPI for "main",
+     *  WindowManager for named user windows). */
+    onBufferShrink: ((linesRemoved: number) => void) | undefined;
+    private consumeLeadingNewline;
+    setFgColor(r: number, g: number, b: number): void;
+    setBgColor(r: number, g: number, b: number, a?: number): void;
+    setBold(v: boolean): void;
+    setItalic(v: boolean): void;
+    setUnderline(v: boolean): void;
+    setStrikethrough(v: boolean): void;
+    setOverline(v: boolean): void;
+    setReverse(v: boolean): void;
+    resetFormat(): void;
+    get maxLines(): number;
+    setMaxLines(n: number): void;
+    get batchDeleteSize(): number;
+    setBatchDeleteSize(n: number): void;
+    echo(text: string): void;
+    /**
+     * Append a pre-built complete line buffer to history. Used by the network
+     * trigger pipeline: the line has already been parsed and is being added as
+     * a single canonical entry, not via partial accumulation. The cursor is
+     * placed on the new line at column 0 so triggers see Mudlet's "cursor on
+     * the matching line at trigger fire" state. Does NOT enqueue into pending
+     * — the renderer for network output drains via the 'message' event
+     * pipeline; pending is reserved for script-driven echo flushes.
+     */
+    appendLine(buffer: AnsiAwareBuffer): void;
+    /**
+     * Append a pre-formatted buffer as a new complete line — mirrors Mudlet's
+     * TConsole::appendBuffer, the primitive behind the `appendBuffer`/`paste`
+     * clipboard functions. Unlike `appendLine` (network pipeline) this also
+     * enqueues into `pending` so the line reaches the renderer through the
+     * normal drain path; the cursor resets to the end so a following
+     * `selectCurrentLine` sees the pasted line.
+     */
+    appendBuffer(buffer: AnsiAwareBuffer): void;
+    private evict;
+    /** Drain newly completed lines to hand to the renderer. */
+    takeLines(): AnsiAwareBuffer[];
+    get currentPartial(): AnsiAwareBuffer;
+    /**
+     * Promote the in-flight partial (an echo without a trailing newline, e.g.
+     * a trigger's `cecho("\n text")`) into a finished history line and return
+     * it, leaving a fresh empty partial behind. Returns null when nothing is
+     * pending. Unlike `clear()`, the existing history is preserved so
+     * line-number / selectString lookups for later lines in the same flush
+     * batch stay valid — this is what lets a per-line trigger-echo flush place
+     * the echoed line right after the line it was echoed on. The line is NOT
+     * enqueued into `pending` (the caller emits it explicitly), so a following
+     * `takeLines()` won't re-emit it.
+     */
+    completePartialLine(): AnsiAwareBuffer | null;
+    clear(): void;
+    /**
+     * Discard only the in-flight partial (and the leading-newline latch),
+     * leaving history/cursor untouched. `feedTriggers` uses this to drop a
+     * stray partial left by a prior direct `echo()` without wiping accumulated
+     * history — multiple `feedTriggers` calls must accumulate lines (Mudlet
+     * appends fed text to the buffer), which a full `clear()` would destroy.
+     */
+    clearPartial(): void;
+    private get cursor();
+    private get followingEnd();
+    getLine(): string;
+    getBuffer(): AnsiAwareBuffer | null;
+    /** Per-line prompt flag on the current cursor line. Mirrors Mudlet's TBuffer
+     *  behaviour: `isPrompt()` follows the cursor, so moveCursor + isPrompt can
+     *  inspect any historical line's prompt status, not just the most recent. */
+    cursorOnPrompt(): boolean;
+    deleteLine(): void;
+    /**
+     * Insert `text` at the cursor (Mudlet `insertText`). Embedded `\n` split the
+     * current line into multiple history lines (Mudlet issue #8945): the text up
+     * to the first `\n` is inserted at the cursor column, each subsequent `\n`
+     * starts a new line, and the remainder of the original line trails the last
+     * inserted segment. For a single-line insert the cursor stays at the
+     * insertion point (Mudlet's `insertText` does not advance `mUserCursor` — the
+     * bundled GUIUtils `xEcho`/`cinsertText` loop advances it explicitly with its
+     * own `moveCursor` after each segment; advancing here too would double-count
+     * and push later color segments past their intended column). Returns false
+     * when there's no current line to insert into (caller falls back to an echo).
+     * Mid-buffer multi-line inserts update the buffer model fully; the
+     * incremental renderer redraws the affected line(s) lazily.
+     */
+    insertText(text: string, state?: FormatStateSnapshot): boolean;
+    /**
+     * Move the cursor up `lines` rows. When `keepHorizontal` is false (the
+     * default, matching Mudlet) the column resets to 0; when true the column
+     * is preserved across the move and lazily clamps to the destination
+     * line's length on read via `getCursorColumn`.
+     */
+    moveUp(lines?: number, keepHorizontal?: boolean): boolean;
+    moveDown(lines?: number, keepHorizontal?: boolean): boolean;
+    /**
+     * Seek the cursor to absolute line `line` (0-indexed). When `col` is
+     * supplied, also set the column; otherwise the column is reset to 0 (the
+     * Mudlet `moveCursor(x=0, y)` default).
+     */
+    moveTo(line: number, col?: number): boolean;
+    /**
+     * Mudlet's `mUserCursor.x()` — the column on the cursor line. Lazily
+     * clamped to the current line's length so a stale `cursorCol` from a
+     * `keepHorizontal` move never reports past the end of a shorter line.
+     */
+    getCursorColumn(): number;
+    setCursorColumn(col: number): boolean;
+    /** Mark cursor as positioned at the end of existing rendered content, so the
+     *  next leading `\n` is treated as cursor advance rather than a blank line.
+     *  Pass `false` to clear the latch (e.g. when leaving trigger processing) so
+     *  it can't leak onto an unrelated later echo. */
+    markCursorAtEnd(value?: boolean): void;
+    getLineNumber(): number;
+    getLineCount(): number;
+    /**
+     * Mudlet `moveCursorEnd` — park the cursor on the empty line past the last
+     * complete one, which is where Mudlet's buffer always keeps its "current"
+     * entry (so `getLineNumber() == getLineCount()` right after). That slot is
+     * one past `history`, which {@link moveTo} deliberately refuses, so it is
+     * set here rather than routed through it.
+     */
+    moveToEnd(): void;
+    /**
+     * Mudlet `getLines(from, to)` — the lines starting at the 0-based index
+     * `from`, `abs(to - from)` of them (TConsole::getLines). Note that `to` is
+     * exclusive and that neither bound is clamped by Mudlet; out-of-range
+     * indices simply yield fewer lines here.
+     */
+    getLines(from: number, to: number): string[];
+    /**
+     * Mudlet `getTimestamp(lineNumber)` — the wall-clock time (epoch ms) the
+     * line entered the buffer. `lineNumber` is 1-based to match `getLines`
+     * (Mudlet's timeBuffer reserves index 0); omit it to read the current
+     * cursor line. Returns null when the line is out of range or the buffer
+     * is empty. Formatting into Mudlet's "hh:mm:ss.zzz" string happens one
+     * layer up, in ScriptingAPI.
+     */
+    getLineTimestamp(lineNumber?: number): number | null;
+    /**
+     * Mudlet `wrapLine(lineNumber)` — re-display the line at `lineNumber`
+     * (0-indexed, matching getLineNumber/getLineCount), re-interpreting its
+     * embedded `\n` characters and re-wrapping to the current width. mudix
+     * renders each line buffer with CSS `white-space: pre-wrap`, and the
+     * rendered DOM node holds the very same buffer object as history (set via
+     * `notifyRender`), so re-rendering that buffer in place is what makes any
+     * `\n` show as line breaks — the documented use case after a `deleteLine()`
+     * + `echo()` sequence left un-displayed newlines in the buffer. Returns
+     * false when `lineNumber` is out of range.
+     */
+    /**
+     * Mudlet `wrapLine(lineNumber)` — re-wrap one stored line to the console's
+     * current wrap width, replacing it with as many buffer lines as it now
+     * needs. That is a real buffer edit in Mudlet (TBuffer::wrapLine splits the
+     * line in place), not a repaint: getLineCount and getLines see the split
+     * afterwards.
+     *
+     * `wrapAt` of 0 (wrapping disabled) leaves the line alone and just
+     * repaints. `indent` prefixes the first resulting line and `hangingIndent`
+     * every continuation, matching setWindowWrapIndent /
+     * setWindowWrapHangingIndent.
+     */
+    wrapLine(lineNumber: number, wrapAt?: number, indent?: number, hangingIndent?: number): boolean;
+}