@mudlet/mudlet-web 0.3.0

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

@@ -0,0 +1,256 @@
+import { type OscPaletteOp } from "./ansiEscapes";
+import { HyperlinkPresetRegistry, type HyperlinkConfig } 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;
+export interface FormatHyperlink {
+    onClick?: (ev: MouseEvent) => void;
+    onContextMenu?: (ev: MouseEvent) => void;
+    onMouseEnter?: (ev: MouseEvent) => void;
+    onMouseLeave?: (ev: MouseEvent) => void;
+    title?: string;
+    /**
+     * Raw link target recorded by the low-level ANSI parser for OSC 8 links.
+     * The parser has no access to the scripting API, so it stores the URI here
+     * and the engine later wires the click behaviour via `bindUrlHyperlinks`.
+     * For OSC 8 links this is the *cleaned* command (extension query stripped).
+     */
+    url?: string;
+    /** Parsed Mudlet OSC 8 extension config (styling, states, tooltip, menu,
+     *  spoiler, disabled, visibility, selection), resolved at parse time. */
+    config?: HyperlinkConfig;
+    /** OSC 8 `id=` parameter — groups split runs of one logical link so hover
+     *  can highlight them together. */
+    linkId?: string;
+    /**
+     * Document-style link that should render with an underline cue by default,
+     * the way a web browser underlines anchors. Set on MXP `<send>`/`<a>` links
+     * only. Scripted Mudlet-API links (`echoLink`, `echoPopup`, `setLink`) leave
+     * this unset — they underline only when the script sets the real `underline`
+     * attribute (Mudlet's `useCurrentFormat=false` default), so a
+     * `useCurrentFormat=true` link keeps the current pen with no underline.
+     *
+     * OSC 8 links also leave it unset: Mudlet's `HyperlinkStyling::isUnderlined`
+     * defaults to false, so they underline only when their `config` style asks
+     * for it (`{"style":{"underline":true}}` / a matching pseudo-class state).
+     */
+    autoUnderline?: boolean;
+}
+export interface IndexedColor {
+    space: "indexed";
+    index: number;
+}
+export interface RgbColor {
+    space: "rgb";
+    r: number;
+    g: number;
+    b: number;
+    a?: number;
+}
+export interface HexColor {
+    space: "hex";
+    color: string;
+}
+export type FormatColor = IndexedColor | RgbColor | HexColor;
+export type DimEasing = 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out';
+export interface DimEffect {
+    startOpacity: number;
+    endOpacity: number;
+    duration: number;
+    easing?: DimEasing;
+}
+export interface FormatStateSnapshot {
+    foreground?: FormatColor;
+    background?: FormatColor;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    inverse?: boolean;
+    strikethrough?: boolean;
+    overline?: boolean;
+    slowBlink?: boolean;
+    rapidBlink?: boolean;
+    dim?: DimEffect;
+    hyperlink?: FormatHyperlink;
+    cssClass?: string;
+}
+export type TextRange = [start: number, end: number];
+export interface BufferSegment {
+    text: string;
+    state?: FormatStateSnapshot;
+}
+declare function cloneState(state?: FormatStateSnapshot): FormatStateSnapshot | undefined;
+declare function statesEqual(a?: FormatStateSnapshot, b?: FormatStateSnapshot): boolean;
+export declare class FormatState {
+    static DEFAULT: {};
+    foreground?: FormatColor;
+    background?: FormatColor;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    inverse?: boolean;
+    strikethrough?: boolean;
+    overline?: boolean;
+    slowBlink?: boolean;
+    rapidBlink?: boolean;
+    dim?: DimEffect;
+    hyperlink?: FormatHyperlink;
+    constructor(initial?: FormatStateSnapshot);
+    private applySnapshot;
+    reset(): void;
+    toSnapshot(): FormatStateSnapshot;
+    applySgr(params: number[]): void;
+    setHyperlink(link?: FormatHyperlink): void;
+}
+/**
+ * A run of text with its visual attributes resolved to concrete CSS colour
+ * strings — the shape a canvas/image renderer wants. `color`/`background` are
+ * undefined when the run uses the console default (the renderer fills in its
+ * own default for those).
+ */
+export interface OutputStyledRun {
+    text: string;
+    color?: string;
+    background?: string;
+    bold: boolean;
+    italic: boolean;
+    underline: boolean;
+}
+/**
+ * Buffer of text aware of ANSI formatting codes and hyperlink metadata.
+ */
+export declare class AnsiAwareBuffer {
+    private segments;
+    private _deleted;
+    private _onRender?;
+    private _textCache;
+    private _renderContainer;
+    constructor(initial?: string | BufferSegment[], state?: FormatStateSnapshot, presets?: HyperlinkPresetRegistry);
+    get deleted(): boolean;
+    markAsDeleted(): this;
+    /** Per-line prompt flag. Mudlet's TBuffer tracks isPrompt on each line so
+     *  the matching `isPrompt()` script primitive reflects the prompt status of
+     *  whatever line the cursor is currently on (not just the last). Set by the
+     *  trigger pipeline before triggers run; defaults to false. */
+    isPrompt: boolean;
+    /** Wall-clock time (epoch ms) the line was created. Mudlet stamps every
+     *  buffer line with a QTime; `getTimestamp(lineNumber)` reads it back. A
+     *  buffer is built right as its line is echoed/received, so construction
+     *  time is the line's timestamp. */
+    timestamp: number;
+    removeFromDom(): void;
+    onRender(callback: (container: HTMLElement) => void): this;
+    /** @internal */
+    notifyRender(container: 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.). */
+    clearFormat(range: TextRange): this;
+    clone(): AnsiAwareBuffer;
+    get text(): string;
+    get length(): number;
+    clear(): this;
+    replace(range: [number, number], text: string, state?: FormatStateSnapshot): this;
+    replaceBuffer(range: [number, number], buffer: AnsiAwareBuffer): this;
+    insert(index: number, text: string, state?: FormatStateSnapshot): this;
+    insertBuffer(index: number, buffer: AnsiAwareBuffer): this;
+    prefix(text: string, state?: FormatStateSnapshot): this;
+    suffix(text: string, state?: FormatStateSnapshot): this;
+    private insertInternal;
+    append(text: string, state?: FormatStateSnapshot): this;
+    appendBuffer(buffer: AnsiAwareBuffer): this;
+    prepend(text: string, state?: FormatStateSnapshot): this;
+    prependBuffer(buffer: AnsiAwareBuffer): this;
+    remove(range: [number, number]): this;
+    /** @internal */
+    getSegments(): BufferSegment[];
+    toHyperlinkSegments(): {
+        text: string;
+        hyperlink?: FormatHyperlink;
+    }[];
+    color(range: TextRange, color: number | FormatStateSnapshot): this;
+    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.
+     */
+    setHyperlink(range: TextRange, hyperlink?: FormatHyperlink): this;
+    /**
+     * 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`
+     * turns a URI into a {@link FormatHyperlink} with the right click behaviour
+     * (or `undefined` to drop the link). Segments that already have a handler —
+     * e.g. an MXP `<SEND>` link overlaid on the same range — are left alone.
+     */
+    bindUrlHyperlinks(factory: (url: string, link: FormatHyperlink) => FormatHyperlink | undefined): this;
+    colorWords(words: string | string[], color: number | FormatStateSnapshot, options?: {
+        caseInsensitive?: boolean;
+    }): this;
+    splitLines(): AnsiAwareBuffer[];
+    /** Returns the format state at the end of this buffer, for carrying into the next line. */
+    trailingState(): FormatStateSnapshot | undefined;
+    /**
+     * Build the CSS visual declarations (colour, weight, decorations) for a
+     * segment. When `overlay` is given (an OSC 8 link style for a state), its set
+     * fields win over the segment's own SGR attributes — that's how a link's
+     * configured colour/decoration paints over the underlying run. With no
+     * overlay this reproduces the plain SGR rendering exactly.
+     */
+    private visualDecls;
+    toHtml(): 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
+     * handling, including reverse-video on default colours — there the swap
+     * yields no explicit colour, so we hand back the console default of the
+     * opposite role for the renderer to paint.
+     */
+    toStyledRuns(): OutputStyledRun[];
+    toDom(): DocumentFragment;
+    private escapeHtml;
+    private colorToHex;
+    private prepareStyle;
+    private appendSegmentAtEnd;
+    private createSegmentsFromText;
+    private resolveIndex;
+    private resolveBoundaryIndex;
+    private inferState;
+    private splitSegment;
+    private normalizeSegments;
+    private assertRange;
+    getStateAt(index: number): FormatStateSnapshot | undefined;
+    applyMudletColors(): this;
+    createLink(range: TextRange, options: {
+        onClick?: (ev: MouseEvent) => void;
+        onContextMenu?: (ev: MouseEvent) => void;
+        onMouseEnter?: (ev: MouseEvent) => void;
+        onMouseLeave?: (ev: MouseEvent) => void;
+        title?: string;
+    }): this;
+    createLinksForText(text: string, options: {
+        onClick?: (ev: MouseEvent) => void;
+        onContextMenu?: (ev: MouseEvent) => void;
+        onMouseEnter?: (ev: MouseEvent) => void;
+        onMouseLeave?: (ev: MouseEvent) => void;
+        title?: string;
+    }, searchOptions?: {
+        caseInsensitive?: boolean;
+    }): this;
+    private assertIndex;
+}
+export { cloneState as cloneFormatState, statesEqual as formatStatesEqual };
+/**
+ * Walks ANSI SGR escapes in `text` starting from `baseState` and returns the
+ * SGR state that would apply *after* the last byte of `text`. Unlike
+ * `AnsiAwareBuffer.trailingState()` (which returns the state of the last
+ * non-empty text segment), this reflects the actual end-of-stream state:
+ *   - empty `text` → returns `baseState`, so blank lines preserve carry
+ *   - text ending in `\e[0m` → returns default (undefined), not the pre-reset color
+ *   - 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;

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

@@ -0,0 +1,88 @@
+/** CSI final bytes are 0x40–0x7E (`@`…`~`). */
+export declare function isCsiFinal(c: string): boolean;
+export interface EscapeScan {
+    /**
+     * - `csi`    — `ESC [ <params> <final>` (SGR, cursor moves, erase, …)
+     * - `osc`    — `ESC ] <payload> ST` (OSC 8 hyperlinks, window title, …)
+     * - `string` — DCS/SOS/PM/APC (`ESC P/X/^/_ … ST`); opaque, always ignored
+     * - `esc`    — a short `ESC <intermediates> <final>` escape (charset, RIS, …)
+     * - `incomplete` — the sequence runs off the end of `text`
+     */
+    kind: "csi" | "osc" | "string" | "esc" | "incomplete";
+    /** Index one past the end of the sequence (exclusive). For `incomplete`,
+     *  equals `text.length`. */
+    end: number;
+    /** CSI only: the final byte. */
+    finalByte?: string;
+    /** CSI only: the parameter + intermediate bytes between `ESC [` and the final. */
+    params?: string;
+    /** OSC only: the payload between `ESC ]` and the ST terminator. */
+    oscPayload?: string;
+}
+/**
+ * Scan a single escape sequence beginning at `text[start]` (which must be ESC).
+ * Classifies the sequence and reports where it ends so callers can act on the
+ * ones they understand and skip the rest. When the sequence is cut off by the
+ * end of input the result is `incomplete` — callers either drop it or hold it
+ * for the next line.
+ */
+export declare function scanEscape(text: string, start: number): EscapeScan;
+export interface Osc8Link {
+    /** The link target. An empty string means "close the current hyperlink". */
+    uri: string;
+    /** The optional `id=` parameter, used to group multi-run links. */
+    id?: string;
+}
+/**
+ * Parse an OSC payload (the bytes between `ESC ]` and the terminator) as an
+ * OSC 8 hyperlink. Returns `null` when the payload is some other OSC command
+ * (window title `0;…`, clipboard `52;…`, …) or is malformed — callers then
+ * treat it the same as any other ignored escape.
+ */
+export declare function parseOsc8Payload(payload: string): Osc8Link | null;
+/**
+ * The action a clickable hyperlink performs, derived from its URI scheme. This
+ * mirrors Mudlet's OSC 8 schemes — `send:`/`prompt:` drive the game, while the
+ * web schemes open externally. The URI comes from an untrusted MUD server, so
+ * any other scheme (`javascript:`, `data:`, `file:`, …) is rejected and the
+ * link is dropped rather than made clickable.
+ */
+export type HyperlinkAction = {
+    kind: "send";
+    command: string;
+} | {
+    kind: "prompt";
+    command: string;
+} | {
+    kind: "url";
+    url: string;
+};
+/** URI schemes mudix 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
+ *  left as-is rather than throwing. */
+export declare function decodePercent(s: string): string;
+export declare function classifyHyperlinkUri(uri: string): HyperlinkAction | null;
+export type OscPaletteOp = {
+    kind: "set";
+    index: number;
+    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;

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

@@ -0,0 +1,21 @@
+/**
+ * Renders text onto the monospace grid. Pure-ASCII runs are emitted as plain
+ * text (the font lays them out at exactly 1ch each); every other grapheme is
+ * boxed into a fixed `Nch` inline-block cell so wide/combining/font-fallback
+ * glyphs can't drift the column grid. See `wcwidth.ts` for the width tables.
+ */
+import { type ControlCharacterMode } from "./controlCharacterMode";
+export declare const CELL_CLASS = "ocell";
+/** Append `text` to a DOM node as plain-text runs interleaved with cell spans,
+ *  starting at column `column` (for tab-stop math). Returns the column after
+ *  `text` — pass it into the next segment's call to keep tab stops correct
+ *  across a whole logical line. */
+export declare function appendCells(parent: Node, text: string, column?: number, mode?: ControlCharacterMode): number;
+/** String equivalent of {@link appendCells} for the `toHtml()` path. Unlike
+ *  `appendCells`, this keeps returning a plain string — use {@link columnAfter}
+ *  to carry the running column across segments. */
+export declare function cellsToHtml(text: string, escape: (s: string) => string, column?: number, mode?: ControlCharacterMode): string;
+/** Column after rendering `text` starting at `column` — mirrors `cellsToHtml`'s
+ *  width math without building output, so `toHtml()` can advance its running
+ *  column between segments while `cellsToHtml` keeps returning a plain string. */
+export declare function columnAfter(text: string, column: number, mode?: ControlCharacterMode): number;

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

@@ -0,0 +1,54 @@
+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.
+ *  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;
+/** Converts a named Mudlet color to a FormatStateSnapshot for buffer-level coloring. */
+export declare function namedColorToState(name: string, bg?: boolean): FormatStateSnapshot | null;
+/** cecho: <color_name>text<r>  or  <b:color_name>text for background */
+export declare function parseCecho(text: string): string;
+/** decho: <r,g,b>text  or  <:r,g,b>text for background, <r> to reset */
+export declare function parseDecho(text: string): string;
+/**
+ * Fast-path for `decho`: the ANSI-escape equivalent of `str`, or `null` when the
+ * string uses any decho feature {@link parseDecho} does NOT reproduce exactly as
+ * Mudlet's Lua `xEcho` would. Callers (the native `decho` fast path) fall back to
+ * the Lua `xEcho` on `null`, so output stays identical to Mudlet.
+ *
+ * Handled here (and only here): foreground `<r,g,b>`, background `<:r,g,b>` with
+ * channels in 0..255, and the `<r>` reset. Deferred to Lua: combined `<fg:bg>`,
+ * background alpha `<:r,g,b,a>`, text-style tags (`<b>`/`<i>`/`<u>`/`<s>`/`<o>`),
+ * out-of-range channels, and any other `<...>` token — the conservative guard
+ * from our design discussion, so a decho grammar we don't model degrades to
+ * slow-but-correct rather than wrong.
+ */
+export declare function dechoToAnsiFast(str: string): string | null;
+/**
+ * Fast-path for `cecho` — see {@link dechoToAnsiFast}. Handles ONLY a plain
+ * foreground `<name>` (resolvable in the Mudlet colour table) and the
+ * `<r>`/`<reset>` reset. Everything else falls back to Lua `xEcho`, because
+ * {@link parseCecho}'s grammar and name resolution diverge from Mudlet's:
+ *  - style tags `<b>`/`<i>`/`<u>`/`<s>`/`<o>` (parseCecho would treat `b` as a
+ *    colour name),
+ *  - combined `<fg:bg>` / `<fg,bg>` and `<:bg>` backgrounds, and the `<b:…>`
+ *    form (Mudlet reads `<b:red>` as fg=b, bg=red — not "background red"),
+ *  - unknown names (parseCecho drops the tag; Mudlet leaves it literal).
+ *
+ * The `ansi_NNN` / `ansiXxx` family IS fast-pathed: this palette and the runtime
+ * `color_table` (seeded from {@link ../text/xterm256}) agree, verified by the
+ * full-palette sweep in the parity test — which also fails loudly if they ever
+ * drift again.
+ */
+export declare function cechoToAnsiFast(str: string): string | null;
+/**
+ * Fast-path for `hecho` — see {@link dechoToAnsiFast}. Handles ONLY a plain
+ * foreground `#RRGGBB` and the `#r` reset. Falls back to Lua `xEcho` for
+ * everything {@link parseHecho} can't reproduce as Mudlet does:
+ *  - the `|c…` / `|b` pipe forms and `\#` escapes,
+ *  - `#:…` (not Mudlet syntax) and `#,…` / `#RRGGBB,…` backgrounds/combined,
+ *  - style tags `#b`/`#i`/`#u`/`#s`/`#o`.
+ */
+export declare function hechoToAnsiFast(str: string): string | null;
+/** hecho: #RRGGBBtext  or  #:RRGGBBtext for background, #r to reset */
+export declare function parseHecho(text: string): string;

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

@@ -0,0 +1,31 @@
+export declare const colorCodes: {
+    xterm: string[];
+    ansi: {
+        bright: string[];
+        dark: string[];
+    };
+};
+/** 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. */
+export declare function setServerRedefineColorsAllowed(allowed: boolean): void;
+/** Whether the server is currently allowed to redefine palette colors. */
+export declare function isServerRedefineColorsAllowed(): boolean;
+/** 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.
+ */
+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 resetAllPaletteColors(): void;

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

@@ -0,0 +1,13 @@
+/**
+ * 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
+ * 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
+ * of them.
+ */
+export type ControlCharacterMode = 'asis' | 'oem' | 'picture';
+export declare function getControlCharacterMode(): ControlCharacterMode;
+export declare function setControlCharacterMode(mode: ControlCharacterMode): void;

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

@@ -0,0 +1,31 @@
+/**
+ * Mudlet's `controlCharacterHandling` glyph substitution, ported from
+ * `TTextEdit::replaceControlCharacterWith_Picture` / `_OEMFont`
+ * (Mudlet/src/TTextEdit.cpp). Pure display-time substitution — the raw bytes
+ * received from the MUD are never altered, only what gets painted.
+ */
+import type { ControlCharacterMode } from './controlCharacterMode';
+/** Mudlet's default `mTabStopwidth`. */
+export declare const TAB_STOP_WIDTH = 8;
+/** A control-character cell's rendered replacement. `width` may exceed 2 —
+ *  only tabs in AsIs/Picture mode expand past that, to the next tab stop,
+ *  like a real terminal. `box` mirrors cellRender's span-vs-inline-run split. */
+export interface ControlCellOverride {
+    text: string;
+    width: number;
+    box: boolean;
+}
+/**
+ * Returns the display substitution for one grapheme at `column` under `mode`,
+ * or `null` if `grapheme` isn't a control character (caller should fall back
+ * to normal cell rendering).
+ *
+ * - **asis**: control chars render as Mudlet's default case does — invisible,
+ *   unchanged (handled by the caller's normal zero-width path) — except tab,
+ *   which expands to the next tab stop.
+ * - **picture**: codes 0-31/127 map onto the Unicode Control Pictures block;
+ *   tab still expands to a tab stop, with the picture glyph over the first cell.
+ * - **oem**: codes 0-31/127 map onto CP437-style glyphs; tab does *not* get
+ *   tab-stop spacing here (matches Mudlet — it's just a plain glyph, width 1).
+ */
+export declare function overrideControlCell(grapheme: string, column: number, mode: ControlCharacterMode): ControlCellOverride | null;

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

@@ -0,0 +1,164 @@
+/**
+ * Mudlet OSC 8 hyperlink extension — configuration parsing.
+ *
+ * Mudlet extends the bare OSC 8 sequence (`ESC ] 8 ; params ; URI ST`) with a
+ * rich config carried in the URI's query string:
+ *
+ *   send:attack?config={"style":{"color":"red","bold":true},"tooltip":"…"}
+ *   send:p1?preset=btn&config={"s":{"c":"yellow"}}
+ *   preset:btn?config={"s":{"bg":"#07f","c":"white","b":true}}   (definition only)
+ *
+ * The config is a JSON object whose keys may use a compact shorthand (`s`→`style`,
+ * `c`→`color`, …). Presets are named, reusable config templates: a `preset:NAME`
+ * link registers one (and renders nothing); later links reference it with
+ * `?preset=NAME`, optionally layering an override `config=` on top (deep merge,
+ * override wins).
+ *
+ * This module is the pure, side-effect-free parsing layer (plus a small preset
+ * registry). It turns a URI into a normalised {@link HyperlinkConfig}; the
+ * render/interaction layers consume that. Mirrors Mudlet's
+ * `parseHyperlinkConfig` / `parseJsonHyperlinkConfig` / `expandJsonShorthands`
+ * (src/TBuffer.cpp) and the shorthand table registered in src/TConsole.cpp.
+ */
+import type { FormatColor } from "./FormatState";
+export type UnderlineStyle = "solid" | "wavy" | "dotted" | "dashed";
+/** Visual styling for a link in one state. Mirrors the SGR-style attributes a
+ *  run can carry, expressed as already-resolved colours. */
+export interface LinkStateStyle {
+    foreground?: FormatColor;
+    background?: FormatColor;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    underlineStyle?: UnderlineStyle;
+    overline?: boolean;
+    strikethrough?: boolean;
+    /** `text-decoration-color` — the colour of the underline/overline/strike. */
+    decorationColor?: FormatColor;
+}
+/** CSS-like pseudo-class states a link style can target. */
+export type LinkState = "hover" | "active" | "focus" | "focus-visible" | "visited" | "link" | "any-link" | "selected" | "disabled";
+export declare const LINK_STATES: readonly LinkState[];
+/** The base style plus any per-state overrides. */
+export interface HyperlinkStyling extends LinkStateStyle {
+    states?: Partial<Record<LinkState, LinkStateStyle>>;
+}
+/** One entry in a right-click menu: either a separator or a labelled action. */
+export interface MenuItem {
+    separator?: boolean;
+    label?: string;
+    /** A command URI like `send:strike` / `prompt:cast` / `https://…`. */
+    action?: string;
+}
+/** A menu's header line (shown above the items). */
+export interface LinkTitle {
+    text?: string;
+    style?: LinkStateStyle;
+}
+export type VisibilityAction = "conceal" | "reveal" | "reveal-then-conceal";
+export interface VisibilitySettings {
+    action?: VisibilityAction;
+    /** Delay before the action fires, in milliseconds. */
+    delayMs?: number;
+    deletesEntireLine?: boolean;
+    expireOnInput?: boolean;
+    expireOnPrompt?: boolean;
+    expireOnOutput?: boolean;
+    outputDelayMs?: number;
+}
+export interface SelectionSettings {
+    group?: string;
+    value?: string;
+    /** Clicking toggles the selected state (default true). */
+    toggle?: boolean;
+    selected?: boolean;
+    /** Radio-button behaviour within the group (default true); false = checkbox. */
+    exclusive?: boolean;
+}
+/** The fully-parsed OSC 8 link configuration. Every field is optional — a bare
+ *  `send:look` link parses to an empty config. */
+export interface HyperlinkConfig {
+    style?: HyperlinkStyling;
+    tooltip?: string;
+    menu?: MenuItem[];
+    title?: LinkTitle;
+    spoiler?: boolean;
+    disabled?: boolean;
+    visibility?: VisibilitySettings;
+    selection?: SelectionSettings;
+}
+/** Shorthand key → full property name. Mirrors the table registered in
+ *  Mudlet's TConsole.cpp. Applied recursively to every key in a config object,
+ *  so `{"s":{"c":"red","h":{"u":true}}}` becomes
+ *  `{"style":{"color":"red","hover":{"underline":true}}}`. */
+export declare const HYPERLINK_SHORTHANDS: Readonly<Record<string, string>>;
+type JsonObject = Record<string, unknown>;
+/**
+ * Recursively expand shorthand keys to their full names. When both a shorthand
+ * and its full form are present on the same object (e.g. `s` and `style`), their
+ * object values are deep-merged with the shorthand taking precedence — matching
+ * Mudlet's `expandJsonShorthands`.
+ */
+export declare function expandShorthands(value: unknown): unknown;
+/** Deep-merge two raw JSON objects; `override` wins on scalar/array collisions,
+ *  objects merge recursively. Mirrors Mudlet's `mergeConfigs`. */
+export declare function deepMerge(base: JsonObject, override: JsonObject): JsonObject;
+/**
+ * Normalise an already-shorthand-expanded config object into a
+ * {@link HyperlinkConfig}. Unknown keys are ignored; malformed values are
+ * skipped rather than throwing (a partially-valid config still applies).
+ */
+export declare function normaliseHyperlinkConfig(root: JsonObject): HyperlinkConfig;
+/** Parse a raw config JSON string (shorthand-allowed) into a normalised config,
+ *  or null if the JSON is invalid / not an object. */
+export declare function parseConfigJson(json: string): HyperlinkConfig | null;
+interface ExtractedQuery {
+    /** The URI up to (not including) the first `?`. */
+    base: string;
+    /** The raw `config={…}` JSON body, if present. */
+    configJson?: string;
+    /** The `preset=NAME` value, if present. */
+    presetName?: string;
+    /** Non-reserved query pairs, in original order/encoding (for http links). */
+    userPairs: string[];
+}
+/**
+ * Split a URI into its base and the reserved/user query parts. `config={…}` is
+ * located by brace-matching (its JSON value may contain `&`), mirroring
+ * Mudlet's hand-rolled scan; everything else is `&`-delimited `key=value`.
+ */
+export declare function extractQuery(uri: string): ExtractedQuery;
+/** Session-scoped store of `preset:NAME` definitions. Holds raw config objects
+ *  (shorthand un-expanded, as Mudlet does) so a later `?preset=NAME` can deep-
+ *  merge an override before expansion. */
+export declare class HyperlinkPresetRegistry {
+    private presets;
+    register(name: string, rawConfig: JsonObject): void;
+    get(name: string): JsonObject | undefined;
+    clear(): void;
+}
+export type Osc8UriResult = 
+/** A `preset:NAME` definition was registered; renders nothing. */
+{
+    kind: "preset";
+    name: string;
+}
+/** A normal link. `command` is the cleaned URI (reserved params stripped)
+ *  to hand to scheme classification; `config` is the resolved config. */
+ | {
+    kind: "link";
+    command: string;
+    config: HyperlinkConfig;
+};
+/**
+ * Parse a full OSC 8 URI (the part after the `8;params;` framing) into either a
+ * preset definition or a resolved link. `registry` supplies/receives preset
+ * definitions. Returns null for an empty/whitespace URI.
+ *
+ * - `preset:NAME?config={…}` registers NAME (raw) and returns a `preset` result.
+ * - Otherwise the base command is cleaned: send:/prompt: drop all query params;
+ *   http/https/ftp keep user params but strip `config`/`preset`. The config is
+ *   resolved as `deepMerge(preset, override)` → expand shorthands → normalise.
+ */
+export declare function parseOsc8Uri(uri: string, registry: HyperlinkPresetRegistry): Osc8UriResult | null;
+export {};