@mudlet/mudlet-web 0.5.0 → 1.0.0

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

@@ -1,9 +1,10 @@
-import { type OscPaletteOp } from "./ansiEscapes";
 import { HyperlinkPresetRegistry, type HyperlinkConfig, type UnderlineStyle } from "./hyperlinkConfig";
-/** Apply OSC 4/104 palette operations to the global colour tables. Palette
- *  changes affect text parsed *after* this point — which is exactly document
- *  order, since lines are fed to the parser in the order the server sent them. */
-export declare function applyOscPaletteOps(ops: ReadonlyArray<OscPaletteOp>): void;
+/** Obey a Linux-console palette OSC (`ESC]P…` / `ESC]R`, see
+ *  {@link parseOscPalette}) against the global colour tables. Palette changes
+ *  affect text parsed *after* this point — which is exactly document order,
+ *  since lines are fed to the parser in the order the server sent them. Any
+ *  other payload — xterm's OSC 4/104 included — changes nothing. */
+export declare function applyOscPalette(payload: string): void;
 export interface FormatHyperlink {
     onClick?: (ev: MouseEvent) => void;
     onContextMenu?: (ev: MouseEvent) => void;
@@ -36,6 +37,12 @@ export interface FormatHyperlink {
      * for it (`{"style":{"underline":true}}` / a matching pseudo-class state).
      */
     autoUnderline?: boolean;
+    /**
+     * The Lua code a scripted link runs — every entry, for a popup. Read by
+     * the clipboard, which holds its own reference to each function a copied
+     * link calls (see `ScriptingAPI.clipboardLinkCommands`).
+     */
+    luaCommands?: string[];
 }
 export interface IndexedColor {
     space: "indexed";
@@ -77,6 +84,13 @@ export interface FormatStateSnapshot {
     overline?: boolean;
     slowBlink?: boolean;
     rapidBlink?: boolean;
+    /** SGR 8: the text is there and not drawn. */
+    concealed?: boolean;
+    /** SGR 11-19 select one of nine alternate fonts, SGR 10 the primary one.
+     *  Carried for parity with Mudlet's getTextFormat: Mudlet Web has no alternate
+     *  font to switch to, so the number is recorded and nothing renders
+     *  differently — but a script reading it back gets the truth. */
+    alternateFont?: number;
     dim?: DimEffect;
     hyperlink?: FormatHyperlink;
     cssClass?: string;
@@ -100,6 +114,8 @@ export declare class FormatState {
     overline?: boolean;
     slowBlink?: boolean;
     rapidBlink?: boolean;
+    concealed?: boolean;
+    alternateFont?: number;
     dim?: DimEffect;
     hyperlink?: FormatHyperlink;
     private fgNormal?;
@@ -108,6 +124,12 @@ export declare class FormatState {
      *  SGR 0 and SGR 39 leave it. Bold never brightens a default foreground. */
     private fgIsDefault;
     private _foreground?;
+    /** Mudlet's `!mIsDefaultColor` exactly — which is narrower than
+     *  `!fgIsDefault`: TBuffer::decodeSGR clears mIsDefaultColor only for one of
+     *  the sixteen ANSI colours (30–37, 90–97, and `38;5`/`48;5` below 16), not
+     *  for a 256-colour or 24-bit one. It decides one thing here: whether SGR 1
+     *  makes the characters written bold (see {@link toCellSnapshot}). */
+    private ansiColored;
     /** The foreground in force, both variants already resolved. */
     get foreground(): FormatColor | undefined;
     /** Writing the foreground from outside the SGR decoder — `setFgColor`, MXP
@@ -119,6 +141,21 @@ export declare class FormatState {
     constructor(initial?: FormatStateSnapshot);
     private applySnapshot;
     reset(): void;
+    /** The attributes an SGR-decoded character is written with. Mudlet's
+     *  TBuffer gives a cell the Bold flag as `mIsDefaultColor ? mBold : false`:
+     *  on one of the sixteen ANSI colours, SGR 1 only picks the bright twin
+     *  (already resolved into `foreground`) and the character itself is not
+     *  bold. The bold state is still carried — `toSnapshot` keeps it — so a
+     *  colour that arrives later is brightened. */
+    toCellSnapshot(): FormatStateSnapshot;
+    /** The attributes the spaces a `CSI n C` (cursor forward) stands for are
+     *  written with: the current ones, with the foreground set to the
+     *  background so the gap stays transparent — an underline or strike-out in
+     *  force does not show across it (TBuffer's
+     *  `TChar(mBackGroundColor, mBackGroundColor, computeCurrentAttributeFlags())`).
+     *  A default background leaves the foreground default too: the parser has
+     *  no profile colours to resolve it to. */
+    toCursorForwardSnapshot(): FormatStateSnapshot;
     toSnapshot(): FormatStateSnapshot;
     applySgr(params: SgrParam[]): void;
     /**
@@ -156,12 +193,12 @@ export declare class FormatState {
  *
  * The distinction matters for exactly one reason, but it matters a lot: `4:3` is
  * a *curly underline*, one parameter with a sub-parameter, while `4;3` is an
- * underline followed by italics. Flattening both — which mudix did, to make
+ * underline followed by italics. Flattening both — which Mudlet Web did, to make
  * `38:5:1` work alongside `38;5;1` — turned every styled underline into an
  * accidental italic. Extended colours still read either form, since applySgr
  * looks ahead across parameters for the `38;5;n` spelling.
  */
-export declare function parseSgrCodes(sequence: string): SgrParam[];
+export declare function parseSgrCodes(sequence: string): SgrParam[] | null;
 /**
  * A run of text with its visual attributes resolved to concrete CSS colour
  * strings — the shape a canvas/image renderer wants. `color`/`background` are
@@ -185,7 +222,16 @@ export declare class AnsiAwareBuffer {
     private _onRender?;
     private _textCache;
     private _renderContainer;
+    private _lineElement;
+    /** The OSC 8 link still open where a string `initial` ends, which the
+     *  next line of the same stream starts inside (see computeTrailingState). */
+    readonly openHyperlink?: FormatHyperlink;
     constructor(initial?: string | BufferSegment[], state?: FormatStateSnapshot, presets?: HyperlinkPresetRegistry);
+    /** A buffer holding `text` exactly as given — every character, an ESC
+     *  included, stored as text in `state`. The string constructor decodes
+     *  escape sequences instead; this is for text that must not be decoded
+     *  (a script's echo — see Console.echoText). */
+    static literal(text: string, state?: FormatStateSnapshot): AnsiAwareBuffer;
     get deleted(): boolean;
     markAsDeleted(): this;
     /** Per-line prompt flag. Mudlet's TBuffer tracks isPrompt on each line so
@@ -198,10 +244,37 @@ export declare class AnsiAwareBuffer {
      *  buffer is built right as its line is echoed/received, so construction
      *  time is the line's timestamp. */
     timestamp: number;
+    /** True for a line that wrapping split off the end of the one above it.
+     *  Mudlet marks those by giving them a blank timestamp rather than a time,
+     *  which is both what getTimestamp() hands back for them and how a later
+     *  wrapLine() knows to give them the hanging indent rather than the first. */
+    continuation: boolean;
+    /** Columns of indent a wrap put in front of this line, when it starts a
+     *  paragraph — desktop's wrapGapBuffer entry for such a line. Leading
+     *  spaces alone can't tell the indent from text, so a later wrapLine()
+     *  reads this (and that the spaces are still there) to know the line
+     *  already carries its indent and must not be given it again. */
+    wrapIndent: number;
     removeFromDom(): void;
+    /**
+     * `removeFromDom()` for a whole eviction batch at once. A trim takes a run
+     * of lines off the head of a buffer, and their rows normally sit side by
+     * side at the top of the console — those go a block or a Range deletion
+     * at a time rather than one removeChild apiece, which on a 20,000-line
+     * trim was half a second of mutation bookkeeping alone (#443). Rows with
+     * a gap between them (some other element in the way) fall back to the
+     * per-line removal, so nothing that is not one of these lines is touched.
+     */
+    static removeAllFromDom(buffers: readonly AnsiAwareBuffer[]): void;
     onRender(callback: (container: HTMLElement) => void): this;
-    /** @internal */
-    notifyRender(container: HTMLElement): void;
+    /**
+     * @internal
+     * `container` is the element `rerender()` rewrites — the content slot.
+     * `lineElement` is the whole row `removeFromDom()` has to detach; pass it
+     * whenever the row is more than the content slot. Omit it and the content
+     * element doubles as the row.
+     */
+    notifyRender(container: HTMLElement, lineElement?: HTMLElement): void;
     /** Re-renders the buffer into its previously notified container. No-op if not yet rendered. */
     rerender(): void;
     /** Removes all formatting from a range (clears colors, bold, etc.). */
@@ -233,15 +306,24 @@ export declare class AnsiAwareBuffer {
         hyperlink?: FormatHyperlink;
     }[];
     color(range: TextRange, color: number | FormatStateSnapshot): this;
+    /**
+     * Overlays the attributes set in `format` on every segment in `range`,
+     * keeping everything else each character already had — the way
+     * TBuffer::applyBold/applyFgColor/… touch only the one attribute they set.
+     * A coloured selection stays coloured when it is made bold, and a
+     * recoloured one keeps its per-character backgrounds and attributes.
+     */
     applyFormat(range: TextRange, format: FormatStateSnapshot): this;
     /**
      * Overlays a hyperlink on every segment in `range`, preserving each
      * segment's existing colors/attributes. Pass `undefined` to clear any
-     * hyperlinks in the range. Unlike `applyFormat` (which homogenizes
-     * formatting across the range), this is segment-wise — used by Mudlet
-     * `setLink` so coloured selections remain coloured after becoming clickable.
+     * hyperlinks in the range. Used by Mudlet `setLink` so coloured selections
+     * remain coloured after becoming clickable.
      */
     setHyperlink(range: TextRange, hyperlink?: FormatHyperlink): this;
+    /** Split the segments at `range`'s ends and let `edit` change a copy of
+     *  each covered segment's state in place. */
+    private overlaySegments;
     /**
      * Wire deferred URL hyperlinks (recorded by the ANSI parser for OSC 8 links
      * as a bare `url` with no handlers) into live, clickable links. `factory`
@@ -264,7 +346,40 @@ export declare class AnsiAwareBuffer {
      * overlay this reproduces the plain SGR rendering exactly.
      */
     private visualDecls;
-    toHtml(): string;
+    /**
+     * `transparentBackground` is what a fully transparent background stands
+     * for. On screen the console shows through it, but a log document has no
+     * console behind it, so TBuffer::bufferToHtml paints the console's own
+     * colour there instead (#10592) — otherwise it reads as black.
+     */
+    toHtml(opts?: {
+        transparentBackground?: {
+            r: number;
+            g: number;
+            b: number;
+        };
+    }): string;
+    /**
+     * This line as TBuffer::bufferToHtml writes it into an HTML session log:
+     * every run in a span naming BOTH colours outright (text with no colour of
+     * its own takes the console's — Mudlet's TChar always carries one), then
+     * `<br>` and a line feed. The `<br>` is what breaks the lines: the log's
+     * stylesheet sets `white-space: nowrap` on the body, so without it a browser
+     * draws the whole session as one line. Only `<` and `>` are escaped, as
+     * desktop does.
+     */
+    toLogHtml(defaults: {
+        foreground: {
+            r: number;
+            g: number;
+            b: number;
+        };
+        background: {
+            r: number;
+            g: number;
+            b: number;
+        };
+    }): string;
     /**
      * Resolve the buffer's segments to styled runs with concrete CSS colours,
      * for rendering to a canvas (copy-as-image). Mirrors {@link toHtml}'s colour
@@ -275,6 +390,14 @@ export declare class AnsiAwareBuffer {
     toStyledRuns(): OutputStyledRun[];
     toDom(): DocumentFragment;
     private escapeHtml;
+    /**
+     * A colour as the HTML consumers want it written: `rgb(r,g,b)`, decimal and
+     * unspaced, which is what TBuffer::bufferToHtml emits and what anything
+     * reading a Mudlet log back parses. Falls through to {@link colorToHex} for
+     * the forms that are not plain opaque RGB (a named/hex colour stays as it
+     * is, a translucent one keeps its rgba()).
+     */
+    private colorToCss;
     private colorToHex;
     private prepareStyle;
     private appendSegmentAtEnd;
@@ -316,4 +439,4 @@ export { cloneState as cloneFormatState, statesEqual as formatStatesEqual };
  *   - text with no ANSI codes → returns `baseState` unchanged
  * Used to carry SGR state across line breaks the way Mudlet's TBuffer does.
  */
-export declare function computeTrailingState(text: string, baseState?: FormatStateSnapshot): FormatStateSnapshot | undefined;
+export declare function computeTrailingState(text: string, baseState?: FormatStateSnapshot, openHyperlink?: FormatHyperlink): FormatStateSnapshot | undefined;

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

@@ -27,6 +27,34 @@ export interface EscapeScan {
  * for the next line.
  */
 export declare function scanEscape(text: string, start: number): EscapeScan;
+/**
+ * Where the escape sequence `text` leaves unfinished begins, scanning from
+ * `from`, or -1 when every sequence in it is complete. Sequences are walked
+ * from the start rather than from the last ESC, as an ESC inside an OSC or
+ * string payload belongs to that sequence.
+ */
+export declare function unfinishedEscapeStart(text: string, from?: number): number;
+/**
+ * How many spaces a `CSI n C` (CUF, cursor forward) stands for — the one cursor
+ * movement Mudlet emulates (TBuffer::translateToPlainText's 'C' case, added for
+ * games that column-align with it). The parameter has to read whole as a
+ * positive integer (`QByteArray::toInt`): `ESC[C`, `ESC[0C` and anything like
+ * `ESC[1;2C` stand for nothing and return 0.
+ */
+export declare function cursorForwardCount(params: string | undefined): number;
+/** TBuffer::translateToPlainText's `rightMargin`: the column a cursor-forward
+ *  stops at. See {@link cursorForwardSpaces}. */
+export declare const MAX_CURSOR_FORWARD = 1000;
+/**
+ * How many spaces a cursor-forward of `count` (from {@link cursorForwardCount})
+ * actually writes at `column` (the line's length so far) —
+ * TBuffer::translateToPlainText's 'C' case. Like a terminal's, the cursor stops
+ * at the right margin: the count comes from the game, and unbounded, one
+ * sequence (or a run of them) could ask for gigabytes of spaces. The margin is
+ * {@link MAX_CURSOR_FORWARD}, not the window's wrap: games send lines longer
+ * than that, and the spaces have to survive the wrap that splits them.
+ */
+export declare function cursorForwardSpaces(count: number, column: number): number;
 export interface Osc8Link {
     /** The link target. An empty string means "close the current hyperlink". */
     uri: string;
@@ -57,7 +85,7 @@ export type HyperlinkAction = {
     kind: "url";
     url: string;
 };
-/** URI schemes mudix is willing to make clickable from server output. */
+/** URI schemes Mudlet Web is willing to make clickable from server output. */
 export declare const ALLOWED_HYPERLINK_SCHEMES: readonly ["send", "prompt", "http", "https", "ftp"];
 /** Percent-decode a send/prompt command, like Mudlet's `QUrl::fromPercentEncoding`,
  *  so `cast%20fireball` reaches the MUD as `cast fireball`. Malformed escapes are
@@ -70,19 +98,7 @@ export type OscPaletteOp = {
     color: string;
 } | {
     kind: "reset";
-    index: number;
-} | {
-    kind: "reset-all";
 };
-/**
- * Parse an XParseColor spec into a `#rrggbb` string, or null if unrecognised.
- * Handles the two forms MUDs use in practice — `rgb:r/g/b` and `#`-hex — and
- * rejects named colours and other X forms (`rgbi:`, `cmyk:`, …).
- */
-export declare function parseXColorSpec(spec: string): string | null;
-/**
- * Parse an OSC payload as an OSC 4 (set) or OSC 104 (reset) palette command.
- * Returns the ordered list of operations, or null if the payload is neither.
- * Malformed index/spec pairs are skipped rather than aborting the whole list.
- */
-export declare function parseOscColorPalette(payload: string): OscPaletteOp[] | null;
+/** Parse an OSC payload as a Linux-console palette command, or null if it is
+ *  not one (or is a malformed one). */
+export declare function parseOscPalette(payload: string): OscPaletteOp | null;

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

@@ -1,6 +1,8 @@
 import type { FormatColor, FormatStateSnapshot } from './FormatState';
-/** Resolve an MXP color spec — an HTML named color, `#RGB`, `#RRGGBB`, or
- *  `rgb(r,g,b)` — into a {@link FormatColor}, or null when unrecognized.
+/** Resolve an MXP color spec into a {@link FormatColor}, or null when
+ *  unrecognized — what Mudlet's `QColor(name)` accepts (a hex form or a
+ *  colour name, see {@link SVG_COLORS}), then, as this client's own
+ *  additions, `rgb(r,g,b)` and the Mudlet palette names.
  *  Used by the MXP parser for `<COLOR>`/`<FONT>` foreground and background. */
 export declare function mxpColor(spec: string): FormatColor | null;
 export declare function namedColorToAnsi(name: string, bg?: boolean): string;
@@ -41,6 +43,16 @@ export declare function dechoToAnsiFast(str: string): string | null;
  * drift again.
  */
 export declare function cechoToAnsiFast(str: string): string | null;
+/**
+ * The palette {@link cechoToAnsiFast} resolves names against, as a Lua table
+ * constructor (`{["red"]={255,0,0},…}`). Mudlet's cecho reads the live
+ * `color_table` for every tag, so a script that sets `color_table.red` changes
+ * what `<red>` draws. The fast-path wrapper in LuaRuntime compares each tag's
+ * `color_table` entry with this table and hands the call back to the Lua
+ * `xEcho` whenever they disagree — a per-tag lookup, and only overridden
+ * names pay for the slow path.
+ */
+export declare function cechoFastPaletteLua(): string;
 /**
  * Fast-path for `hecho` — see {@link dechoToAnsiFast}. Handles ONLY a plain
  * foreground `#RRGGBB` and the `#r` reset. Falls back to Lua `xEcho` for

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

@@ -0,0 +1,2 @@
+export declare function getExpectColorSpaceId(): boolean;
+export declare function setExpectColorSpaceId(expect: boolean): void;

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

@@ -8,24 +8,31 @@ export declare const colorCodes: {
 /** Built-in 16-color ANSI palette. Index 0–7 dark, 8–15 bright. The Settings
  *  modal uses this as the fallback when a profile hasn't overridden a slot. */
 export declare const DEFAULT_ANSI_PALETTE: readonly string[];
-/** Enable/disable server-driven OSC 4/104 palette redefinition. */
+/** Enable/disable server-driven palette redefinition. */
 export declare function setServerRedefineColorsAllowed(allowed: boolean): void;
 /** Whether the server is currently allowed to redefine palette colors. */
 export declare function isServerRedefineColorsAllowed(): boolean;
+/** Run `listener` after every change to the sixteen ANSI colours. Returns the
+ *  unsubscribe function. */
+export declare function onAnsiPaletteChange(listener: () => void): () => void;
+/** The sixteen ANSI colours in force, `#rrggbb`, dark (0–7) then bright (8–15). */
+export declare function getAnsi16Palette(): string[];
 /** Apply an override palette to the global ANSI table (mutates colorCodes.ansi
  *  in place so FormatState picks it up without plumbing). Pass `undefined` or
  *  a sparse array to restore defaults for unspecified / invalid slots. The
  *  palette layout is `[...dark(8), ...bright(8)]`. */
 export declare function applyAnsiPalette(palette?: readonly (string | undefined)[]): void;
 /**
- * OSC 4 palette redefinition: point colour index `index` (0–255) at `hex`
- * (`#rrggbb`). Indices 0–15 also update the 16-colour ANSI table so subsequent
- * SGR 30–37/40–47/90–107 pick up the change, keeping the two tables coherent.
- * Out-of-range indices and malformed colours are ignored.
+ * The server's `ESC ] P <i> <rrggbb>`: point ANSI colour `index` (0–15) at
+ * `hex` (`#rrggbb`) — SGR 30–37/40–47/90–107, `38;5;0..15` and `color_table`
+ * alike (TBuffer::decodeOSC). Out-of-range indices and malformed colours are
+ * ignored.
  */
-export declare function setPaletteColor(index: number, hex: string): void;
-/** OSC 104 single-index reset: restore one palette entry to its base value (the
- *  user palette for 0–15, the built-in xterm default otherwise). */
-export declare function resetPaletteColor(index: number): void;
-/** OSC 104 with no index: restore the entire palette to its base state. */
+export declare function setAnsiPaletteColor(index: number, hex: string): void;
+/** The server's `ESC ] R`: the sixteen ANSI colours go back to the built-in
+ *  ones — not to the profile's own, which desktop's TBuffer::resetColors
+ *  overwrites with Qt's black/darkRed/… just the same. */
+export declare function resetAnsiPaletteToDefaults(): void;
+/** Restore the entire palette to its base state: the profile's own sixteen
+ *  colours, the built-in 256-colour table above them. */
 export declare function resetAllPaletteColors(): void;

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

@@ -2,7 +2,7 @@
  * The active profile's `controlCharacterHandling` display mode (Mudlet
  * `setConfig`/`getConfig`: `"asis"` / `"oem"` / `"picture"`). Mirrors Mudlet's
  * `Host::mControlCharacter` — a single per-profile value read at paint time by
- * every console/mini-console/text window. mudix renders exactly one active
+ * every console/mini-console/text window. Mudlet Web renders exactly one active
  * connection's output at a time, so a module-level value (kept in sync by
  * `MudSession.setControlCharacterMode`) covers the main output, script
  * windows, and logging/copy paths without threading a parameter through all

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

@@ -46,7 +46,7 @@ export declare class HyperlinkVisibilityController {
  * Whether a link with these settings is written concealed and revealed later.
  *
  * Only the timed reveals are, unlike Mudlet, which also conceals a reveal armed
- * on an expire trigger. mudix drives expire triggers off the rendered element
+ * on an expire trigger. Mudlet Web drives expire triggers off the rendered element
  * (see {@link HyperlinkVisibilityController}), and that path only ever conceals
  * — a link the buffer blanked with nothing to un-blank it would lose its text
  * for good, which is worse than showing it early.

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

@@ -0,0 +1,5 @@
+/**
+ * Where `text` may break: `breaks[p]` is 1 when a line may start at UTF-16
+ * offset `p`. `breaks[0]` is 0 and `breaks[text.length]` is 1, as in Qt.
+ */
+export declare function lineBreakOpportunities(text: string): Uint8Array;

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

@@ -13,7 +13,7 @@
  * tested directly, and so the pipeline glue in `ScriptingEngine` stays readable.
  *
  * **Visible text, not raw.** Mudlet judges `mMudLine`, which is plain characters
- * with the styling held alongside in a `TChar` buffer. mudix keeps styling
+ * with the styling held alongside in a `TChar` buffer. Mudlet Web keeps styling
  * inline as ANSI escapes, so every predicate here takes text that has been put
  * through {@link visibleText} first — otherwise a colour-heavy line would be
  * measured as far longer than the player sees, and its escape punctuation would
@@ -163,7 +163,7 @@ export declare function shouldCommitPendingBeforeJoin(visibleNext: string, nextI
  * and its continuation, restoring the space the game's wrapper swallowed when
  * neither side already carries one.
  *
- * Operates on the **raw** lines (escapes and all): mudix's styling is inline, so
+ * Operates on the **raw** lines (escapes and all): Mudlet Web's styling is inline, so
  * a plain concatenation carries each half's colour across untouched — the
  * `TChar`-buffer splice Mudlet needs has no equivalent here. The space-insertion
  * test looks at the visible text so a trailing colour reset can't hide the space

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

@@ -0,0 +1,79 @@
+/**
+ * Mudlet's text analyser, ported from `TTextEdit::slot_analyseSelection` and
+ * `TTextEdit::convertWhitespaceToVisual` (Mudlet/src/TTextEdit.cpp:2717-3300).
+ *
+ * Desktop puts a context-menu entry on the main display — gated on the
+ * "Enable text analyzer" preference — that reports, for the selected text, how
+ * each character is encoded: its UTF-16 code units, a visible stand-in for
+ * characters that draw as nothing, its UTF-8 bytes, and the `\ddd` escapes Lua
+ * needs to write the same character into a string literal. That last column is
+ * the point of the whole feature: a pattern that will not match usually has a
+ * character in it the player cannot see, and the analyser is how they find out
+ * which one and how to type it.
+ *
+ * This module is the analysis; the table lives in `TextAnalyzerModal`. Both
+ * halves stay pure of Qt's quirks: desktop escapes `<` and `>` because it
+ * builds an HTML tooltip by hand, and pads its counts with spaces so a
+ * `QTableWidget` sorts them correctly. Neither applies here.
+ */
+/** One grapheme cluster of the analysed text, with everything the report shows
+ *  about it. A cluster, not a code point: `é` written as `e` + U+0301 is one
+ *  cell on screen and one row here, carrying both of its code points. */
+export interface AnalysedGrapheme {
+    /** The cluster itself, for rendering as the game drew it. */
+    text: string;
+    /** 1-based index of the cluster's first UTF-16 code unit, so it lines up
+     *  with what a Qt/JS string index would report. */
+    utf16Index: number;
+    /** The cluster's UTF-16 code units, in order. */
+    utf16Units: number[];
+    /** The cluster's Unicode code points (surrogate pairs already joined). */
+    codePoints: number[];
+    /** 1-based index of the cluster's first UTF-8 byte. Mudlet starts this at 1
+     *  "so that it directly maps to string indexing in Lua" (TTextEdit.cpp:2975). */
+    utf8Index: number;
+    /** The cluster's UTF-8 bytes, in order. */
+    utf8Bytes: number[];
+    /** A name in braces for a character that draws as nothing or as whitespace
+     *  ("{zero width space}"), or undefined when the cluster draws as itself. */
+    label?: string;
+}
+/**
+ * The brace-wrapped name for a code point that draws as nothing, or undefined
+ * when it draws as itself. C0 controls other than tab / LF / CR have no name in
+ * Mudlet's table (they are filtered out of its buffer long before this), but
+ * they can reach a browser selection through a script's `echo`, so they are
+ * named here as their Unicode abbreviations rather than left invisible.
+ */
+export declare function codePointLabel(cp: number): string | undefined;
+/** Uppercase hex, zero-padded — the spelling Mudlet uses for code points
+ *  (`U+0200B`) and, at width 2, for UTF-8 bytes (`0x0a`, which it leaves
+ *  lower-case; this pads both the same and lower-cases the byte column at the
+ *  point of display). */
+export declare function hex(value: number, width: number): string;
+/**
+ * How Lua would have to spell one UTF-8 byte inside a string literal —
+ * Mudlet's `byteToLuaCodeOrChar` (TTextEdit.cpp:2919). Printable ASCII is
+ * itself; everything else is the decimal escape `\ddd`, which is what a player
+ * copies into a trigger pattern to match a character they cannot type.
+ */
+export declare function byteToLuaCode(byte: number): string;
+/**
+ * Analyse one line of text into per-grapheme rows.
+ *
+ * Mudlet analyses only the first line of a selection (its menu entry says so:
+ * "only the first line!"), because its buffer is a list of lines and the
+ * selection's second line starts over at column 0. The caller here does the
+ * same trimming, so this takes text that is already one line.
+ */
+export declare function analyseText(text: string): AnalysedGrapheme[];
+/**
+ * The first line of a selection, which is all Mudlet analyses (its menu entry
+ * says so: "only the first line!"). A selection spanning several lines is cut
+ * at the first line break; the modal says so rather than silently analysing a
+ * fragment.
+ */
+export declare function firstLineOf(text: string): {
+    line: string;
+    truncated: boolean;
+};

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

@@ -0,0 +1,11 @@
+/**
+ * Lookup over one of the run-length tables in unicodeTables.generated.ts.
+ *
+ * The Basic Multilingual Plane — where nearly every character a game sends
+ * lives — is expanded into a flat array on first use, so a lookup there is a
+ * single index. The rest stays as runs and is binary-searched.
+ */
+export interface RunLookup {
+    (cp: number): number;
+}
+export declare function runLookup<T extends Uint8Array | Uint16Array>(encoded: string, make: (n: number) => T): RunLookup;

package/dist-lib/mud/text/unicodeTables.generated.d.ts

@@ -0,0 +1,3 @@
+export declare const WIDTH_RUNS: string;
+export declare const LINE_BREAK_RUNS: string;
+export declare const LINE_BREAK_PAIRS: string;

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

@@ -1,29 +1,28 @@
 /**
- * Terminal display-width tables (a wcwidth-style implementation).
- *
- * MUD output is laid out on a monospace grid: every character occupies an
- * integer number of cells (0, 1, or 2). Browsers don't enforce that — a glyph
- * the chosen font lacks falls back to another font with a different advance
- * width, wide CJK/emoji render at their natural width, and combining marks add
- * code-unit length but no visual width. The renderer uses these tables to box
- * each grapheme into a fixed `Nch` cell so columns stay aligned regardless of
- * the font.
- *
- * Ranges follow Markus Kuhn's wcwidth (combining + East Asian Wide/Fullwidth),
- * extended with the Supplementary-plane emoji/symbol blocks. BMP dingbats and
- * miscellaneous symbols (☎ ★ ♠ …) are East Asian *Ambiguous* and kept at width
- * 1, matching the common "narrow" terminal rendering.
- */
-/**
- * Display width of a single Unicode code point, in monospace cells.
- * Returns 0 for combining/zero-width, 2 for wide, 1 otherwise. C0/C1 control
- * characters (which shouldn't reach the renderer) are treated as 0.
+ * Display width of a single Unicode code point, in monospace cells — Mudlet's
+ * graphemeInfo::codepointWidth. Nonprinting characters (C0/C1 controls, soft
+ * hyphen, zero-width spaces, lone surrogates), non-characters and combining
+ * marks are 0; wide and "widened in Unicode 9" (emoji presentation) are 2;
+ * East Asian ambiguous follows {@link setAmbiguousWidthWide}; everything else,
+ * private use and unassigned included, is 1.
  */
 export declare function codePointWidth(cp: number): 0 | 1 | 2;
+/** Set by the profile's `ambiguousWidthWide` preference. Off is the common
+ *  "narrow" terminal rendering and stays the default; on matches a CJK locale's
+ *  terminal, which is what the games drawing box art out of these expect. */
+export declare function setAmbiguousWidthWide(wide: boolean): void;
+export declare function isAmbiguousWidthWide(): boolean;
+/** Whether ambiguous-width characters are drawn wide, given the profile's
+ *  choice (`ambiguousWidthWide`: true/false, or undefined for Mudlet's "auto")
+ *  and the server encoding. "auto" is wide for the CJK encodings only. */
+export declare function effectiveAmbiguousWidthWide(choice: boolean | undefined, encoding: string): boolean;
 /**
- * Display width of a grapheme cluster (base + any combining marks / ZWJ
- * sequence). Width is the widest code point in the cluster, so an emoji ZWJ
- * sequence stays 2 and a base+diacritic stays at the base's width.
+ * Display width of a grapheme cluster (base + any combining marks, variation
+ * selectors, ZWJ sequence): the width of its base character, the way Mudlet
+ * measures every grapheme. So an emoji ZWJ sequence takes its first emoji's 2,
+ * a letter with diacritics its letter's 1, and U+2764 + VS16 the 2 Mudlet
+ * gives the heart itself. A cluster that starts with an unpaired surrogate
+ * measures that surrogate, which is nonprinting.
  */
 export declare function clusterWidth(cluster: string): 0 | 1 | 2;
 /** Total display width of a string, in monospace cells. */
@@ -40,5 +39,11 @@ export interface DisplayCell {
  * their base), falling back to per-code-point iteration where it is missing.
  */
 export declare function segmentCells(text: string): DisplayCell[];
+/**
+ * Where each grapheme of `text` ends, indexed by the UTF-16 offset it starts
+ * at (-1 at offsets inside a grapheme). The same clusters as
+ * {@link segmentCells} without an object per cell, for the wrap's scan.
+ */
+export declare function graphemeEnds(text: string): Int32Array;
 /** Fast check: pure printable ASCII renders at exactly 1 cell with no boxing. */
 export declare function isPlainAscii(text: string): boolean;