@mudlet/mudlet-web 0.5.0 → 1.0.0

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

@@ -4,6 +4,38 @@ import type { FormatStateSnapshot } from './FormatState';
 /** Longest run of characters one echo or insert may add to a line. Mudlet's
  *  `TBuffer::MAX_CHARACTERS_PER_ECHO`. */
 export declare const MAX_CHARACTERS_PER_ECHO = 1000000;
+/**
+ * Scrollback line limit of a console nothing has sized — `TBuffer::mLinesLimit`
+ * (src/TBuffer.h:386), 10,000 lines with a batch of a tenth of that. Miniconsoles,
+ * user windows and buffers keep it until a script calls setConsoleBufferSize.
+ *
+ * The floor is `TBuffer::setBufferSize`'s (src/TBuffer.cpp:405) — a smaller
+ * buffer is not usable. The ceiling stands in for
+ * `TBuffer::getMaxBufferSize()`, which desktop derives from physical memory; a
+ * browser tab cannot ask about that, so "use the maximum" gets a fixed generous
+ * cap instead.
+ */
+export declare const DEFAULT_CONSOLE_BUFFER_SIZE = 10000;
+/**
+ * The main console's scrollback on a fresh profile — Mudlet's per-profile
+ * `consoleBufferSize` (`Host::mConsoleBufferSize`, Host.h, saved to the profile
+ * XML by XMLexport.cpp), which desktop applies to main over TBuffer's own
+ * default. 100,000 lines with a batch of 20,000 (mudlet-web#341): a tenth of it
+ * dropped scrollback, fired sysBufferShrinkEvent and shifted line numbers ten
+ * times as early as desktop.
+ */
+export declare const MAIN_CONSOLE_BUFFER_SIZE = 100000;
+export declare const MIN_CONSOLE_BUFFER_SIZE = 100;
+export declare const MAX_CONSOLE_BUFFER_SIZE = 1000000;
+/** What a line index outside the buffer reads as, byte for byte Mudlet's
+ *  `badLineError` (TBuffer.cpp) — the QString its `line()` hands back for any
+ *  index below zero or past the end, instead of failing. Scripts compare
+ *  against this literal, so it is API surface, not a diagnostic. */
+export declare const BAD_LINE_ERROR = "ERROR: invalid line number";
+/** Mudlet's batch-deletion size for a given buffer size — 5% of it, never below
+ *  100 lines (mudlet.cpp:2270, and the identical sum in
+ *  dlgProfilePreferences.cpp:3288 when the preference is applied). */
+export declare function consoleBatchDeleteSize(lines: number): number;
 /**
  * Self-contained text output entity — equivalent of Mudlet's TConsole.
  * Owns format state, line history, and cursor position.
@@ -15,7 +47,43 @@ export declare class Console {
     private history;
     private pending;
     private partial;
+    /**
+     * Whether the buffer has a current line at all.
+     *
+     * Mudlet's TBuffer always keeps one — the line being built — as the last
+     * entry of lineBuffer, so a console that has printed nothing still holds a
+     * line and getLineCount() answers 0 rather than -1. Mudlet Web keeps that line in
+     * `partial`, beside `history` instead of in it, which is why getLineNumber()
+     * and moveTo() already treat it as living at index `history.length`; this
+     * flag is what lets the READ side agree with them.
+     *
+     * False in exactly one situation, and it is the one EmptyBufferOps_spec is
+     * about: deleteLine() removing the open line itself, which is what
+     * clearWindow() followed by deleteLine() does. That is the only way to a
+     * buffer of zero lines, and telling it apart from a one-line buffer is
+     * precisely what getLines() answering an empty table exists for.
+     */
+    private hasOpenLine;
     private cursorIdx;
+    /**
+     * Whether writing to the buffer carries the user cursor along with it.
+     *
+     * True only for the main console, whose cursor the trigger engine parks on
+     * each line as it arrives. Every other TConsole in Mudlet — miniconsoles,
+     * user windows, buffers — starts with `mUserCursor` at (0, 0) and keeps it
+     * there however much is echoed, until a script moves it (moveCursor,
+     * moveCursorEnd, …). So `getLineNumber`/`getCurrentLine`/`selectString`/
+     * `copy` on such a window act on line 0 by default (Mudlet/mudlet-web#236).
+     * With this off the cursor starts on line 0 and the paths that would
+     * otherwise send it back to "following the end" put it there instead.
+     */
+    private readonly followsOutput;
+    constructor(options?: {
+        followsOutput?: boolean;
+    });
+    /** Where a reset (clear, a paste) leaves the cursor: following the end on
+     *  the main console, the first line everywhere else — see followsOutput. */
+    private resetCursor;
     private cursorCol;
     private _maxLines;
     private _batchDeleteSize;
@@ -38,7 +106,34 @@ export declare class Console {
     setMaxLines(n: number): void;
     get batchDeleteSize(): number;
     setBatchDeleteSize(n: number): void;
+    /** Append `text`, interpreting any ANSI escape sequences in it against the
+     *  current pen — the path for text that came from a server (feedTriggers'
+     *  carried partial) or that Mudlet Web built as ANSI itself (the colour-echo
+     *  fast path). A script's own `echo` goes through {@link echoText}. */
     echo(text: string): void;
+    /**
+     * Append `text` verbatim in the current pen. Mudlet's echo family
+     * (`TConsoleModel::print` → `TBuffer::append`) stores every character it is
+     * given, an ESC byte included — only the network path decodes escape
+     * sequences — so `echo("A\27[31mB")` keeps the sequence as text and the pen
+     * colour unchanged.
+     */
+    echoText(text: string, state?: FormatStateSnapshot): void;
+    /** `state` (literal writes only) replaces the pen for this one write and
+     *  leaves the pen itself untouched — how a link gets Mudlet's standard
+     *  link format without disturbing the format current on the console. */
+    private write;
+    /**
+     * Wrap the line still being built the moment it outgrows the wrap width,
+     * not when its newline arrives. Mudlet's TBuffer::append runs wrapLine() on
+     * the last line after every echo, so a long `echo` without a trailing
+     * newline is already several buffer lines: getLineCount, the cursor moves
+     * and getCurrentLine see them straight away, and the next echo carries on
+     * from the last piece. Every piece but the last is finished and goes to
+     * history; the last stays open as the new partial, marked as a
+     * continuation so its later wrap takes the hanging indent.
+     */
+    private wrapPartial;
     /**
      * Move every newline-terminated line out of the in-flight `partial` and
      * into history, leaving whatever follows the last newline as the new
@@ -55,10 +150,10 @@ export declare class Console {
      * — the renderer for network output drains via the 'message' event
      * pipeline; pending is reserved for script-driven echo flushes.
      */
-    appendLine(buffer: AnsiAwareBuffer): void;
+    appendLine(buffer: AnsiAwareBuffer, moveCursor?: boolean): void;
     /**
-     * Append a pre-formatted buffer as a new complete line — mirrors Mudlet's
-     * TConsole::appendBuffer, the primitive behind the `appendBuffer`/`paste`
+     * Write a pre-formatted buffer onto the end of the last line and end that
+     * 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
@@ -73,10 +168,24 @@ export declare class Console {
      * secret behind it.
      */
     private store;
+    /**
+     * Give the buffer its open line back after deleteLine() removed it while
+     * complete lines remained. Mudlet has no separate open line: its last line
+     * is simply whatever lineBuffer ends with, so once the old last line is
+     * deleted the one above it is the line the next write lands on — an echo
+     * continues it rather than starting a fresh one. Here that line moves back
+     * out of history into `partial`; its row leaves the DOM so the partial
+     * render can show it in its place.
+     */
+    private reopenLastLine;
     private evict;
     /** Drain newly completed lines to hand to the renderer. */
     takeLines(): AnsiAwareBuffer[];
     get currentPartial(): AnsiAwareBuffer;
+    /** The last finished line — the one before the line being built, which is
+     *  where TBuffer's `buffer.size() - 2` points — or undefined when there is
+     *  none yet. */
+    get lastFinishedLine(): AnsiAwareBuffer | undefined;
     /**
      * 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
@@ -89,6 +198,15 @@ export declare class Console {
      * `takeLines()` won't re-emit it.
      */
     completePartialLine(): AnsiAwareBuffer | null;
+    /**
+     * `TConsole::printCommand` outside the trigger engine: when the last line
+     * is still flagged as a prompt (and nothing has been echoed after it), the
+     * command is written onto the end of that line instead of onto a line of
+     * its own, and the line stops being a prompt — so only the first command
+     * after a prompt joins it. Returns the line it was added to, or null when
+     * there is no such prompt line and the caller appends as usual.
+     */
+    appendToPromptLine(buffer: AnsiAwareBuffer): AnsiAwareBuffer | null;
     clear(): void;
     /**
      * Discard only the in-flight partial (and the leading-newline latch),
@@ -110,11 +228,51 @@ export declare class Console {
      * it made `prefix()`/`suffix()` on an unfinished line silent no-ops.
      */
     private get onPartialLine();
+    /**
+     * Whether a script parked the cursor on the open line while it is still
+     * empty — moveCursorEnd(), or moveCursor() onto the line after a trailing
+     * `\n`. Desktop's cursor is on that empty line then: getCurrentLine() reads
+     * '' and insertText() starts the new line. Treating the slot as "the last
+     * complete line" glued the inserted text onto the line above
+     * (mudlet-web#331). Only an explicit index counts — the main console's
+     * following-the-end cursor (-1) still reads the last complete line — and
+     * not mid trigger pass, where there is no open line (see currentBuffer).
+     */
+    private get onEmptyOpenLine();
     getLine(): string;
     getBuffer(): AnsiAwareBuffer | null;
     /** The buffer the cursor is on: the partial when it is following the end,
      *  otherwise the history line it was parked on. */
     private currentBuffer;
+    /** Line `index` in Mudlet's numbering (the open line last), or null when
+     *  the index names no line. */
+    lineBuffer(index: number): AnsiAwareBuffer | null;
+    /** The Lua code of every scripted link or popup this console's lines hold. */
+    linkCommands(): string[];
+    /** Whether `buf` is still one of this console's lines — the open one or a
+     *  complete one — rather than one a clear, a deletion or the scrollback
+     *  limit has taken away. */
+    /** Lines the scrollback limit has trimmed away, as opposed to ones a
+     *  clear or a delete took — see {@link wasTrimmed}. */
+    private readonly trimmed;
+    /** Whether `buf` was one of this console's lines until the scrollback
+     *  limit trimmed it. */
+    wasTrimmed(buf: AnsiAwareBuffer): boolean;
+    holdsLine(buf: AnsiAwareBuffer): boolean;
+    /** The last complete line, whatever the cursor is on — where Mudlet's
+     *  trigger-mode echo writes (`TConsoleModel::echo` inserts at the end of
+     *  line `size() - 1`), which after deleteLine() is the line above. */
+    lastLine(): AnsiAwareBuffer | null;
+    /**
+     * Whether the buffer is between a trigger pass's beginLine and endLine,
+     * when it has no open line past the matched one. Set by ScriptingAPI on
+     * the main console only. See {@link currentBuffer}.
+     */
+    private openLineSuspended;
+    suspendOpenLine(on: boolean): void;
+    /** The text of line `index` in Mudlet's numbering (the open line last), or
+     *  null when there is no such line. */
+    lineText(index: number): string | 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. */
@@ -132,24 +290,30 @@ export declare class Console {
      * 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
+     * inserted segment. The cursor stays at the insertion point, newline or not
+     * (Mudlet's `insertText` never moves `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.
+     *
+     * `split` false keeps every `\n` in the line as a character, the way a
+     * trigger's insertText does on desktop (TConsoleModel::insertText in
+     * trigger mode only inserts); a later wrapLine() splits it there.
      */
-    insertText(text: string, state?: FormatStateSnapshot): boolean;
+    insertText(text: string, state?: FormatStateSnapshot, split?: boolean): 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`.
+     * is preserved across the move, even past the end of a shorter line.
      */
     moveUp(lines?: number, keepHorizontal?: boolean): boolean;
     moveDown(lines?: number, keepHorizontal?: boolean): boolean;
+    /** The line number `buffer` is stored at, or -1 when it is not in the
+     *  buffer (any more). */
+    lineIndexOf(buffer: AnsiAwareBuffer): number;
     /**
      * 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
@@ -157,9 +321,10 @@ export declare class Console {
      */
     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.
+     * Mudlet's `mUserCursor.x()` — the column on the cursor line. Not clamped
+     * to the line's length: TBuffer::moveCursor accepts any column, and each
+     * operation that writes through it decides what past the end means
+     * (insertText pads out to it). Never reports below 0.
      */
     getCursorColumn(): number;
     /**
@@ -176,7 +341,23 @@ export declare class Console {
      *  it can't leak onto an unrelated later echo. */
     markCursorAtEnd(value?: boolean): void;
     getLineNumber(): number;
+    /** How many lines the buffer holds, counting the open one — Mudlet's
+     *  lineBuffer.size(). */
+    private get lineTotal();
+    /** The text of line `index` in Mudlet's numbering, where the open line is
+     *  the last one; null when the index names no line. */
+    private lineAt;
     getLineCount(): number;
+    /** Whether the cursor is somewhere text can be put: on a line the buffer
+     *  holds, at a column that is not negative. A column past the end of the
+     *  line counts — a write there pads up to it. Not after deleteLine() has
+     *  taken the line the cursor was on and left it past the last one, nor mid
+     *  trigger pass once the matched line is gone. */
+    cursorInText(): boolean;
+    /** Mudlet's TBuffer::getLastLineNumber() — the index of the last line, the
+     *  open one included, and 0 for a buffer with no lines at all. Differs from
+     *  getLineCount() + 1 only once deleteLine() has removed the open line. */
+    lastLineNumber(): 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"
@@ -186,55 +367,54 @@ export declare class Console {
      */
     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.
+     * Mudlet `getLines(from, to)` — the lines from the 0-based index `from`
+     * up to, not including, `to`; a reversed range reads downward from `from`
+     * (or the last line, when `from` is past it) to just above `to`.
+     * Only lines the buffer actually holds are returned: an index before line
+     * 0 or past the last line is dropped rather than padded, so the result can
+     * be shorter than asked for, and empty — `getLines(-2, 3)` reads lines 0
+     * to 2, not 0 to 4.
+     *
+     * An empty table is the only way a script can tell an empty buffer from a
+     * one-line one, because getLineCount() answers 0 for both — it reports the
+     * last line's index.
      */
     getLines(from: number, to: number): string[];
+    /** TBuffer::getEndLines(n) — the text of the last `n` lines, oldest first,
+     *  the open line included. Fewer when the buffer holds fewer. */
+    getEndLines(n: 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.
+     * line entered the buffer, or {@link BLANK_TIMESTAMP} for a line wrapping
+     * continued from the one above. `lineNumber` indexes the buffer as
+     * getLineNumber() does, from 0 — Mudlet reads `timeBuffer.at(lineNumber)`
+     * — and the open line after the last complete one counts,
+     * having a time of its own. 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 | typeof BLANK_TIMESTAMP | '' | null;
     /**
      * The wrap this console applies to a line as it is stored — the console's
      * own `setWindowWrap` width, so a line longer than it becomes several
      * buffer lines rather than one long one that only *looks* wrapped.
      *
-     * Off (width 0) unless a script sets one, which is the state nearly every
-     * console is in: the renderer wraps to the panel's real pixel width, and
-     * splitting on a column nobody chose would only fight it. Mudlet always
-     * splits because its buffer IS its layout.
+     * Width 0 is off. A bare Console starts there; ScriptingAPI gives the main
+     * console the profile's `outputWrapAt` (100 unless changed, Mudlet's
+     * Host::mWrapAt) as soon as it exists and again whenever that setting
+     * moves. Miniconsoles and user windows stay off until a script sets a
+     * width, which is what desktop's {@link WINDOW_WRAP_DEFAULT} amounts to.
      */
     setWrapWidth(width: number, indent?: number, hangingIndent?: number): void;
+    /** The stored-line wrap width set by {@link setWrapWidth}; 0 when off. */
+    getWrapWidth(): number;
+    getWrapIndent(): number;
+    getWrapHangingIndent(): number;
+    /** The open line, while it is the untimed one desktop starts after a game
+     *  line — see {@link wrapAppendedLine}. Anything else in `partial` (a new
+     *  buffer, or this one once written to) is timed as usual. */
+    private untimedOpenLine;
     private wrapWidth;
     private wrapIndent;
     private wrapHangingIndent;
@@ -243,5 +423,31 @@ export declare class Console {
      * width set — the usual case — this is the line itself, untouched.
      */
     private toStoredLines;
-    wrapLine(lineNumber: number, wrapAt?: number, indent?: number, hangingIndent?: number): boolean;
+    /**
+     * Break a line that came in through {@link appendLine} to the console's wrap
+     * width once the triggers are done with it, and hand back the lines it is now
+     * stored as (just `buffer` when it needed no breaking, or is no longer in the
+     * buffer). Mudlet's TBuffer::translateToPlainText does the same: the triggers
+     * see the whole line as the server sent it, and only then does wrapLine() cut
+     * it into the buffer lines getLines() and the cursor APIs count.
+     */
+    wrapAppendedLine(buffer: AnsiAwareBuffer, fromGame?: boolean): AnsiAwareBuffer[];
+    /**
+     * Mudlet `wrapLine(lineNumber)` — re-wrap the buffer from `lineNumber`
+     * (0-indexed, matching getLineNumber/getLineCount) to its end at `wrapAt`,
+     * replacing each line with as many buffer lines as it now needs, as
+     * TBuffer::wrapLine does: a real buffer edit that getLineCount and getLines
+     * see, not a repaint. Embedded `\n` become line breaks too. `wrapAt` of 0
+     * (wrapping off) only repaints the line, so pre-wrap rendering shows its
+     * `\n`. Returns false when `lineNumber` names no stored line.
+     */
+    wrapLine(lineNumber: number, wrapAt?: number, indent?: number, hangingIndent?: number, stopAt?: number): boolean;
 }
+/** What getWindowWrap reports for a miniconsole or user window no script has
+ *  set a width on — Mudlet's TBuffer::mWrapAt default. Only the main console
+ *  and createBuffer buffers take the profile's width (TConsole::changeColors). */
+export declare const WINDOW_WRAP_DEFAULT = 99999999;
+/** What getTimestamp() answers for a continued line — Mudlet's
+ *  `smBlankTimeStamp`, trailing space included, the same 13 characters as a
+ *  real stamp ("hh:mm:ss.zzz "). */
+export declare const BLANK_TIMESTAMP = "------------ ";