@mudlet/mudlet-web 0.3.0

package/dist-lib/mud/events.d.ts

@@ -0,0 +1,160 @@
+import type { AnsiAwareBuffer } from './text/FormatState';
+import type { MspCommand } from './protocol';
+import type { ScriptLogSource } from './MudSession';
+export type SessionStatus = 'disconnected' | 'connecting' | 'connected';
+/** A pending Mudlet `invokeFileDialog(...)` request. The Lua handler that
+ *  called it is suspended (parked coroutine) until `onPick` fires, so the UI
+ *  must always resolve it eventually — pass the picked VFS path, or '' for
+ *  cancel (Mudlet returns '' when the native dialog is dismissed too). */
+export interface FileDialogRequest {
+    /** What the script asked to pick: a file or a directory. */
+    mode: 'file' | 'folder';
+    /** Dialog title supplied by the script (may be ''). */
+    title: string;
+    /** VFS path to start browsing at; '' means the profile root. */
+    location: string;
+    /** Resolve the dialog. Must be called exactly once. */
+    onPick: (path: string) => void;
+}
+export type MudClientEvents = {
+    'open': [event: Event];
+    'close': [event: CloseEvent];
+    'error': [error: unknown];
+    'client.connect': void;
+    'client.disconnect': void;
+    'client.error': [message: string];
+    /** The WebSocket subprotocol the server selected from our advertised list
+     *  (RFC 6455), or '' if none — only emitted when we advertised any. */
+    'client.subprotocol': [protocol: string];
+    'gmcp.negotiated': void;
+    'msdp.negotiated': void;
+    'mssp.negotiated': void;
+    'msp.negotiated': void;
+    /** Fires when MNES / NEW-ENVIRON (telnet option 39) negotiation starts — the
+     *  server sent IAC DO NEW-ENVIRON and the client agreed (IAC WILL). The
+     *  client then answers the server's SEND request with its environment
+     *  variables. The payload names the active mode — `'MNES'` (restricted core
+     *  set) or `'NEW-ENVIRON'` (extended capability set) — so scripts can hook
+     *  the right `sysProtocolEnabled` name. */
+    'mnes.negotiated': string;
+    /** Fires when NAWS (telnet option 31) negotiation completes — the client
+     *  offered IAC WILL NAWS and the server replied IAC DO NAWS. From then on
+     *  the client reports the main output area's character grid (columns × rows)
+     *  and re-sends it whenever the window resizes. */
+    'naws.negotiated': void;
+    /** Fires when MXP (telnet option 91) starts for the session. The scripting
+     *  engine flips its `mxpActive` flag on this so in-band MXP markup starts
+     *  being parsed, and mirrors Mudlet's `sysProtocolEnabled('MXP')`.
+     *  `viaTelnet` is true when started by a real option-91 handshake (server
+     *  WILL/DO MXP) and false when inferred from in-band `ESC[<n>z` line modes
+     *  on a server that skipped negotiation. Only telnet-negotiated MXP gets the
+     *  `<SUPPORTS>`/`<VERSION>` handshake replies — an in-band-only server's
+     *  inbound MXP channel isn't confirmed, so replying would spam it with
+     *  invalid commands. */
+    'mxp.negotiated': [viaTelnet: boolean];
+    /** Fired for every `!!SOUND` / `!!MUSIC` tag parsed from the in-band text
+     *  stream (or an `IAC SB MSP ... IAC SE` subnegotiation body). The
+     *  scripting engine wires this to the SoundManager. */
+    'msp': [command: MspCommand];
+    /** Fires when a CHARSET (RFC 2066) negotiation completes — either the
+     *  server's REQUEST was ACCEPTED or our advertised REQUEST was ACCEPTED.
+     *  Argument is the IANA charset name as agreed (the wire spelling, e.g.
+     *  "UTF-8"). */
+    'charset.negotiated': [encoding: string];
+    'socket.incoming': [data: string];
+    'socket.outgoing': [data: string];
+    'message': [text?: string | AnsiAwareBuffer, type?: string, timestamp?: number, isPrompt?: boolean];
+    'flushLines': [groups: {
+        text: string;
+        type: string;
+    }[]];
+    'gmcp': [payload: {
+        path: string;
+        value: unknown;
+    }];
+    /** A `Client.GUI` server package-install request, in either wire format:
+     *  the parsed `{url, version}` object, or the legacy raw `<version>\n<url>`
+     *  string. Carried separately from `gmcp` because the legacy form never
+     *  becomes a GMCP table entry — decoding both shapes is the install
+     *  handler's job (parseClientGuiPayload), not this bus's. */
+    'clientGui': [payload: unknown];
+    'msdp': [payload: {
+        path: string;
+        value: unknown;
+    }];
+    'mssp': [payload: {
+        name: string;
+        value: string;
+    }];
+    'gmcp.core.ping': [value: unknown];
+    /** Fires when the server requests GMCP login (Char.Login.Default). The
+     *  argument is the list of supported authentication methods it advertised
+     *  (e.g. `["password-credentials"]`). The UI shows a credentials popup and
+     *  replies via `sendCharLoginCredentials` — or an empty reply (cancel) to
+     *  fall back to the server's text login prompt. */
+    'charLogin.request': [methods: string[]];
+    /** Fires when the server reports a GMCP login outcome (Char.Login.Result).
+     *  `success` is true on a successful authentication; on failure `message`
+     *  carries the server's human-readable reason (e.g. "Invalid credentials"). */
+    'charLogin.result': [result: {
+        success: boolean;
+        message?: string;
+    }];
+    /** Fires when the command input should switch in/out of password masking.
+     *  True only for a genuine password prompt (server enabled ECHO *after* it
+     *  began sending output); a connect-time server-wide ECHO suppresses local
+     *  echo without masking, so it does not raise this with `true`. */
+    'telnet.echo': [maskInput: boolean];
+    /** Mirror of Mudlet's `sysEchoAnomalyDetected`. Fires once per session when
+     *  the server toggles `IAC WILL/WONT ECHO` ≥5 times within 5 s; at that
+     *  point the client sends `IAC DONT ECHO` and refuses any further ECHO
+     *  negotiation for the rest of the connection. */
+    'telnet.echo.anomaly': void;
+    /** Mudlet `sysTelnetEvent(type, option, message)` — fired for telnet
+     *  IAC commands the client doesn't natively recognise (everything other
+     *  than the hardcoded GMCP/MSDP/TTYPE/MCCP/ECHO negotiations). */
+    'telnet.event': [type: number, option: number, message: string];
+    /** Mudlet `raiseProtocolEvent("sysProtocolRejected", name)` — a telnet
+     *  option mudix deliberately refuses. mudix, like Mudlet, operates in line
+     *  mode only, so it rejects SUPPRESS_GO_AHEAD (option 3) and LINEMODE
+     *  (option 34) rather than let the server switch it into character-at-a-
+     *  time / server-driven line editing. The payload is the protocol name
+     *  (`'SUPPRESS_GO_AHEAD'` or `'LINEMODE'`). */
+    'protocol.rejected': [protocol: string];
+    /** Mudlet `sysCharacterModeDetected`. Fires once per connection when the
+     *  server has both asked to suppress go-ahead (IAC WILL SGA) *and* enabled
+     *  server-side echo — the classic character-at-a-time signature that mudix,
+     *  a line-based client, can't drive well. Lets scripts / the UI warn the
+     *  user that input may not behave as expected. */
+    'charmode.detected': void;
+} & Record<string, any>;
+export type MudEvents = MudClientEvents & {
+    'status': [status: SessionStatus];
+    'ping': [duration: number | null];
+    'script.log': [text: string, level: 'error' | 'info', source?: ScriptLogSource];
+    'output.ready': void;
+    'script.deleteline': void;
+    'script.clearwindow': void;
+    'script.appendcmd': [text: string];
+    'script.setcmd': [text: string];
+    'script.clearcmd': void;
+    'script.selectcmd': void;
+    'script.cmdlinesuggestions': [items: string[]];
+    'script.openvfs': [path: string];
+    /** Fired by ScriptingAPI when Lua calls `invokeFileDialog(...)`. The UI
+     *  (ProfileSession) shows the in-app VFS picker and resolves the request
+     *  via `request.onPick`. See {@link FileDialogRequest}. */
+    'script.filedialog': [request: FileDialogRequest];
+    'prompt': void;
+    'script.movecursorup': void;
+    'script.movecursordown': void;
+    /** A Mudlet-format replay started playing. Payload is the recording's
+     *  total duration in milliseconds (sum of chunk offsets, at 1× speed). */
+    'replay.start': [durationMs: number];
+    /** The active replay finished or was aborted. */
+    'replay.over': void;
+    /** Replay recording was toggled on/off (the toolbar Record button state). */
+    'replay.recording': [recording: boolean];
+    /** The replay playback speed divisor changed (1..1024). */
+    'replay.speed': [speed: number];
+};

package/dist-lib/mud/keybindings/KeyEngine.d.ts

@@ -0,0 +1,36 @@
+import type { KeyNode } from '../../storage/schema';
+export type { KeyNode };
+type TempFn = () => void;
+/** Mudlet getKeyCode() result — a Qt::Key integer + Qt::KeyboardModifier mask. */
+export interface KeyCodeInfo {
+    keyCode: number;
+    modifiers: number;
+}
+export declare class KeyEngine {
+    private readonly temp;
+    private perm;
+    private nextId;
+    /** Number of live session-scoped temp keys (Mudlet `getProfileStats` temp count). */
+    get tempCount(): number;
+    addTemp(key: string, modifiers: string[], fn: TempFn, qt?: {
+        keyCode: number;
+        modifier: number;
+    }): number;
+    /** Whether a temp key with this id is live — backs exists(id, "key"). */
+    hasTemp(id: number): boolean;
+    /** Whether a live temp key is enabled — backs isActive(id, "key"). */
+    isTempEnabled(id: number): boolean;
+    /** enableKey/disableKey with a numeric id. False when no temp key matches. */
+    setTempEnabled(id: number, enabled: boolean): boolean;
+    /**
+     * Mudlet getKeyCode(idOrName) lookup. A numeric id resolves a temp key; a
+     * string resolves a permanent key by name. Returns the Qt key code + modifier
+     * mask, or null when nothing matches (caller turns that into nil + errMsg).
+     */
+    getKeyCode(idOrName: number | string): KeyCodeInfo | null;
+    killKey(id: number): boolean;
+    processTemp(event: KeyboardEvent): boolean;
+    loadPerm(keybindings: KeyNode[]): void;
+    matchPerm(event: KeyboardEvent): KeyNode | null;
+    destroy(): void;
+}

package/dist-lib/mud/keybindings/browserReservedKeys.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Some keyboard shortcuts are owned by the browser (or the OS) and are handled
+ * *above* the web page — Ctrl+T opens a new tab, Ctrl+W closes it, F12 opens
+ * devtools. The page never receives the keydown (or can't suppress it), so a MUD
+ * keybinding on one of these can never fire in mudix.
+ *
+ * Real Mudlet runs natively and binds these freely; opened in a browser they
+ * silently do nothing, which is baffling. We scan the loaded keybindings on
+ * profile open (and temp keys as scripts register them) and warn about the ones
+ * the browser intercepts.
+ *
+ * We deliberately do NOT warn about page-level shortcuts the browser owns but a
+ * page can still capture with preventDefault — Ctrl+R (reload), Ctrl+S (save),
+ * Ctrl+P (print), Ctrl+F (find), F5, Ctrl+L, etc. mudix intercepts those, so they
+ * work exactly like they do in Mudlet: while the client has keyboard focus.
+ *
+ * Keys are stored as DOM `KeyboardEvent.code` strings (see {@link KeyNode}), so we
+ * match against codes like `KeyT`, `Digit1`, `F12`.
+ */
+import type { KeyNode } from '../../storage/schema';
+export interface ReservedKeyWarning {
+    node: KeyNode;
+    combo: string;
+    action: string;
+}
+/** Platform accelerator — browser shortcuts use Cmd (meta) on macOS, Ctrl elsewhere. */
+export type Accel = 'ctrl' | 'meta';
+/** Detect the platform accelerator modifier. Falls back to Ctrl off-browser (tests). */
+export declare function detectAccel(): Accel;
+/** Render a keybinding as a display combo like "Ctrl+Shift+I". */
+export declare function formatKeyCombo(node: Pick<KeyNode, 'key' | 'modifiers'>): string;
+/** Explanation appended to each warning line. */
+export declare function reservedKeyNote(action: string): string;
+/**
+ * Classify a single keybinding against the browser-reserved set. Returns the
+ * browser action it collides with, or null when the combo is safe to bind.
+ */
+export declare function classifyReservedKey(node: Pick<KeyNode, 'key' | 'modifiers'>, accel?: Accel): string | null;
+/**
+ * Scan a list of keybindings and return a warning for each one the browser
+ * intercepts. Group nodes and keyless nodes are skipped; the caller is expected
+ * to pass the effectively-enabled bindings (disabled binds never fire, so
+ * warning about them would be noise).
+ */
+export declare function findReservedKeybindings(keys: KeyNode[], accel?: Accel): ReservedKeyWarning[];

package/dist-lib/mud/keybindings/qtKeys.d.ts

@@ -0,0 +1,33 @@
+/** Qt::KeypadModifier — set by Mudlet when a binding came from the numpad. */
+export declare const QT_KEYPAD_MODIFIER = 536870912;
+/**
+ * Translate a Qt::Key integer (or already-translated DOM `KeyboardEvent.code`
+ * string) into a DOM `KeyboardEvent.code`. Mudlet `tempKey` accepts both;
+ * passing a string straight through lets users pre-resolve when they prefer.
+ *
+ * When `modifier` includes Qt::KeypadModifier, digit and symbol codes resolve
+ * to their Numpad* DOM variants — DOM `KeyboardEvent.code` distinguishes
+ * numpad keys from the main keyboard while Qt::Key alone does not.
+ */
+export declare function qtKeyToDomCode(key: string | number, modifier?: number): string;
+/**
+ * Translate a Qt::KeyboardModifier bitmask into an array of modifier names
+ * that match the {ctrl,shift,alt,meta} strings KeyEngine compares against.
+ *
+ * Qt::ShiftModifier   = 0x02000000
+ * Qt::ControlModifier = 0x04000000
+ * Qt::AltModifier     = 0x08000000
+ * Qt::MetaModifier    = 0x10000000
+ * Qt::KeypadModifier  = 0x20000000  (ignored — DOM `code` already encodes "Numpad*")
+ * Qt::GroupSwitchMod. = 0x40000000  (ignored — X11-only)
+ */
+export declare function qtModifiersToList(modifier: number): string[];
+/** Inverse of qtModifiersToList — {ctrl,shift,alt,meta} names → Qt bitmask. */
+export declare function listToQtModifiers(modifiers: string[]): number;
+/**
+ * Inverse of qtKeyToDomCode for the common case — a DOM `KeyboardEvent.code`
+ * back to a Qt::Key integer. Used by getKeyCode() to report a permanent key
+ * binding (stored as a DOM code) in Mudlet's Qt terms. Returns undefined for a
+ * code with no Qt mapping.
+ */
+export declare function domCodeToQtKey(code: string): number | undefined;

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

@@ -0,0 +1,105 @@
+/**
+ * CHARSET (RFC 2066, telnet option 42) negotiation and the session's byte→char
+ * codec. The `SessionCodec` owns the streaming inbound decoder and the outgoing
+ * encoding; the `CharsetHandler` drives the REQUEST/ACCEPTED/REJECTED exchange
+ * against it. Extracted from MudClient so the wire protocol lives alongside the
+ * other per-option modules in `src/mud/protocol/`.
+ */
+/**
+ * Map a wire-format charset name (case-insensitive, with various dash/underscore
+ * spellings) onto an IANA label that `TextDecoder` accepts. Returns null for
+ * encodings we don't support — most legacy MUD codepages aren't reachable from
+ * the browser TextDecoder API and would need a polyfill not worth shipping.
+ *
+ * Coverage is deliberately narrow: UTF-8 (the universal modern answer), the
+ * Latin-N family, the Cyrillic KOI8 variants, and the Windows-125x codepages.
+ * That covers every Polish, Russian, and Western European MUD seen in practice.
+ */
+export declare function normalizeCharsetName(raw: string): string | null;
+/** Wire-format names of every charset mudix can decode, surfaced to Lua scripts
+ *  via `getServerEncodingsList()`. Every entry round-trips through
+ *  {@link normalizeCharsetName}, so any name here is a valid `setServerEncoding`
+ *  argument. ("ASCII" maps to the UTF-8 decoder, which handles it byte-for-byte.) */
+export declare const SUPPORTED_SERVER_ENCODINGS: readonly string[];
+/**
+ * Parse an `IAC SB CHARSET REQUEST ...` subnegotiation body (leading byte is
+ * the option code 42, then subcommand byte 1, then optional `[TTABLE]<ver>`
+ * prefix, then a separator byte, then separator-delimited IANA names). Returns
+ * the best match against {@link CHARSET_PRIORITY} with both the original wire
+ * spelling (echoed back in the ACCEPTED reply per RFC 2066) and the normalized
+ * IANA label suitable for `new TextDecoder(...)`. Returns null if no offered
+ * name is supported.
+ */
+export declare function pickCharsetFromRequest(subneg: string): {
+    original: string;
+    normalized: string;
+} | null;
+/**
+ * The session's byte→char codec. Owns the streaming inbound `TextDecoder`
+ * (holding trailing partial multi-byte chars across WebSocket frames) and the
+ * matching outgoing encoding. Starts at UTF-8 — correct for ASCII and modern
+ * MUDs — and switches when a CHARSET exchange (or an explicit
+ * `setServerEncoding`) agrees on something else.
+ */
+export declare class SessionCodec {
+    private decoder;
+    private currentEncoding;
+    /** The IANA name of the decoder currently applied to the inbound stream. */
+    get encoding(): string;
+    /** Back to the UTF-8 baseline with a fresh decoder (call on connect). */
+    reset(): void;
+    /** Swap the streaming decoder to a new encoding label (an IANA name the
+     *  TextDecoder constructor accepts: 'utf-8', 'iso-8859-2', ...). Any partial
+     *  multi-byte sequence buffered in the previous decoder is discarded —
+     *  fine because CHARSET typically negotiates before any real content
+     *  arrives. Returns false (leaving the current decoder untouched) when the
+     *  browser refuses the label. */
+    trySetEncoding(encoding: string): boolean;
+    /** Converts a Latin-1 byte-string into decoded text under the current
+     *  encoding, buffering any trailing partial multi-byte sequence for the
+     *  next frame. */
+    decode(byteString: string): string;
+    /** Convert a user-typed JS string (UTF-16) into the Latin-1 byte-string the
+     *  socket layer expects, using the currently negotiated outgoing encoding.
+     *  For UTF-8 we run it through TextEncoder so multi-byte chars survive;
+     *  for other encodings we fall back to a per-char `& 0xff` truncation,
+     *  which is lossless for ASCII and acceptable for Latin-1-family inputs.
+     *  TextEncoder has no API for non-UTF-8 outputs, so a full per-encoding
+     *  outbound table isn't worth the bytes given how rare non-UTF-8 MUDs are. */
+    encodeOutgoing(text: string): string;
+}
+export interface CharsetHandlerHooks {
+    sendRaw(data: string): void;
+    /** Fired when an encoding switch takes effect. The argument is the
+     *  wire-spelling name (e.g. "UTF-8") so listeners can surface it. */
+    onNegotiated(displayName: string): void;
+}
+/**
+ * Drives the CHARSET REQUEST/ACCEPTED/REJECTED exchange against a
+ * {@link SessionCodec}. Negotiation methods are gated on `enabled` (the
+ * per-profile CHARSET toggle); `setServerEncoding` is not — it's the explicit
+ * Mudlet API call, honored regardless.
+ */
+export declare class CharsetHandler {
+    private readonly codec;
+    private readonly enabled;
+    private readonly hooks;
+    constructor(codec: SessionCodec, enabled: boolean, hooks: CharsetHandlerHooks);
+    /** Send `IAC SB CHARSET REQUEST ;UTF-8;ISO-8859-2;ISO-8859-1 IAC SE` —
+     *  advertising the encodings we can decode, in preference order. Each name
+     *  is prefixed by the separator (`;`) per RFC 2066 (the separator comes
+     *  before each charset, not between them). The server replies ACCEPTED
+     *  <name> or REJECTED; handleSubneg() processes either. */
+    sendRequest(): void;
+    /** Route an `IAC SB CHARSET ... IAC SE` subnegotiation body (leading byte
+     *  is the option code, 42). Handles REQUEST (server lists charsets, we
+     *  ACCEPT one or REJECT), ACCEPTED (server picked one of ours — switch
+     *  codec), and REJECTED (server didn't like any of ours — stay put).
+     *  TTABLE-* subcommands are silently ignored; almost no MUD uses them. */
+    handleSubneg(subneg: string): void;
+    /** Mudlet `setServerEncoding(name)`. Switch the inbound decoder to `name`
+     *  (any value from getServerEncodingsList()). Returns false — leaving the
+     *  current encoding untouched — when the name isn't one we can decode. */
+    setServerEncoding(name: string): boolean;
+    private setEncoding;
+}

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

@@ -0,0 +1,116 @@
+export declare const TELNET_OPTION_REGEX: RegExp;
+export declare const TELNET_GA = "\u00FF\u00F9";
+export declare const TELNET_EOR = "\u00FF\u00EF";
+export declare const TELOPT_EOR = "\u0019";
+export declare const EOR_WILL = "\u00FF\u00FB\u0019";
+export declare const EOR_DO = "\u00FF\u00FD\u0019";
+export declare const TELOPT_SGA = "\u0003";
+export declare const SGA_WILL = "\u00FF\u00FB\u0003";
+export declare const SGA_DO = "\u00FF\u00FD\u0003";
+export declare const SGA_DONT = "\u00FF\u00FE\u0003";
+export declare const TELOPT_LINEMODE = "\"";
+export declare const LINEMODE_WILL = "\u00FF\u00FB\"";
+export declare const LINEMODE_DO = "\u00FF\u00FD\"";
+export declare const LINEMODE_DONT = "\u00FF\u00FE\"";
+export declare const LINEMODE_WONT = "\u00FF\u00FC\"";
+export declare const GMCP_COMMAND_CODE = 201;
+export declare const GMCP_IAC = "\u00FF";
+export declare const GMCP_SB = "\u00FA";
+export declare const GMCP_SE = "\u00F0";
+export declare const MCCP2_OPTION = 86;
+export declare const MSDP_COMMAND_CODE = 69;
+export declare const OPT_MSDP = "E";
+export declare const MSDP_VAR = "\u0001";
+export declare const MSDP_VAL = "\u0002";
+export declare const MSDP_TABLE_OPEN = "\u0003";
+export declare const MSDP_TABLE_CLOSE = "\u0004";
+export declare const MSDP_ARRAY_OPEN = "\u0005";
+export declare const MSDP_ARRAY_CLOSE = "\u0006";
+export declare const MSDP_WILL = "\u00FF\u00FBE";
+export declare const MSDP_DO = "\u00FF\u00FDE";
+export declare const MSSP_COMMAND_CODE = 70;
+export declare const OPT_MSSP = "F";
+export declare const MSSP_VAR = "\u0001";
+export declare const MSSP_VAL = "\u0002";
+export declare const MSSP_WILL = "\u00FF\u00FBF";
+export declare const MSSP_DO = "\u00FF\u00FDF";
+export declare const GMCP_WILL = "\u00FF\u00FB\u00C9";
+export declare const GMCP_DO = "\u00FF\u00FD\u00C9";
+export declare const ATCP_COMMAND_CODE = 200;
+export declare const OPT_ATCP = "\u00C8";
+export declare const TELNET_102_COMMAND_CODE = 102;
+export declare const OPT_TELNET_102 = "f";
+export declare const TTYPE_COMMAND_CODE = 24;
+export declare const OPT_TTYPE = "\u0018";
+export declare const TTYPE_IS = "\0";
+export declare const TTYPE_SEND = "\u0001";
+export declare const TTYPE_DO = "\u00FF\u00FD\u0018";
+export declare const TTYPE_WILL = "\u00FF\u00FB\u0018";
+export declare const ECHO_WILL = "\u00FF\u00FB\u0001";
+export declare const ECHO_WONT = "\u00FF\u00FC\u0001";
+export declare const ECHO_DO = "\u00FF\u00FD\u0001";
+export declare const ECHO_DONT = "\u00FF\u00FE\u0001";
+export declare const MSP_COMMAND_CODE = 90;
+export declare const OPT_MSP = "Z";
+export declare const MSP_WILL = "\u00FF\u00FBZ";
+export declare const MSP_DO = "\u00FF\u00FDZ";
+export declare const MXP_COMMAND_CODE = 91;
+export declare const OPT_MXP = "[";
+export declare const MXP_WILL = "\u00FF\u00FB[";
+export declare const MXP_DO = "\u00FF\u00FD[";
+export declare const NEW_ENVIRON_COMMAND_CODE = 39;
+export declare const OPT_NEW_ENVIRON = "'";
+export declare const NEW_ENVIRON_IS = "\0";
+export declare const NEW_ENVIRON_SEND = "\u0001";
+export declare const NEW_ENVIRON_INFO = "\u0002";
+export declare const NEW_ENVIRON_VAR = "\0";
+export declare const NEW_ENVIRON_VALUE = "\u0001";
+export declare const NEW_ENVIRON_ESC = "\u0002";
+export declare const NEW_ENVIRON_USERVAR = "\u0003";
+export declare const NEW_ENVIRON_DO = "\u00FF\u00FD'";
+export declare const NEW_ENVIRON_WILL = "\u00FF\u00FB'";
+export declare const NEW_ENVIRON_WONT = "\u00FF\u00FC'";
+export declare const MTTS_ANSI = 1;
+export declare const MTTS_VT100 = 2;
+export declare const MTTS_UTF8 = 4;
+export declare const MTTS_256_COLORS = 8;
+export declare const MTTS_MOUSE_TRACKING = 16;
+export declare const MTTS_OSC_COLOR_PALETTE = 32;
+export declare const MTTS_SCREEN_READER = 64;
+export declare const MTTS_PROXY = 128;
+export declare const MTTS_TRUECOLOR = 256;
+export declare const MTTS_MNES = 512;
+export declare const MTTS_MSLP = 1024;
+export declare const MTTS_SSL = 2048;
+/** Live capabilities that toggle the dynamic MTTS bits. The static bits (ANSI,
+ *  256 colours, OSC colour palette, truecolour) are always on. */
+export interface MttsCapabilities {
+    /** UTF-8 is the active encoding (sets the UTF-8 bit). */
+    utf8?: boolean;
+    /** The game-facing transport is TLS-encrypted (sets the SSL bit). */
+    tls?: boolean;
+    /** MNES is negotiated (sets the MNES bit). */
+    mnes?: boolean;
+    /** A screen reader is being advertised (sets the SCREEN READER bit). */
+    screenReader?: boolean;
+}
+/**
+ * Compose the MTTS bitvector mudix advertises. Mirrors Mudlet's
+ * `getNewEnvironMTTS`: ANSI + 256 COLORS + OSC COLOR PALETTE + TRUECOLOR are
+ * always present (mudix's static terminal capabilities); UTF-8, SSL/TLS, MNES
+ * and SCREEN READER are added from live state. With UTF-8 + TLS this yields
+ * 2349, matching a default Mudlet connection.
+ */
+export declare function computeMtts(caps?: MttsCapabilities): number;
+export declare const NAWS_COMMAND_CODE = 31;
+export declare const OPT_NAWS = "\u001F";
+export declare const NAWS_WILL = "\u00FF\u00FB\u001F";
+export declare const NAWS_DO = "\u00FF\u00FD\u001F";
+export declare const NAWS_DONT = "\u00FF\u00FE\u001F";
+export declare const CHARSET_COMMAND_CODE = 42;
+export declare const OPT_CHARSET = "*";
+export declare const CHARSET_REQUEST = "\u0001";
+export declare const CHARSET_ACCEPTED = "\u0002";
+export declare const CHARSET_REJECTED = "\u0003";
+export declare const CHARSET_WILL = "\u00FF\u00FB*";
+export declare const CHARSET_DO = "\u00FF\u00FD*";

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

@@ -0,0 +1,63 @@
+export declare class EchoHandler {
+    /** Committed (debounced) state exposed to UI / send-echo logic. True
+     *  whenever the server is echoing for us, which means we must suppress our
+     *  own local command echo to avoid showing every line twice. This is *not*
+     *  the same as password masking — see `_passwordStyle` / `passwordMode`. */
+    private _serverEchoing;
+    /** Latest raw on-the-wire state. Used to gate ack dedup and decide whether
+     *  to schedule a commit. */
+    private _rawEchoing;
+    /** Whether the *current* ECHO engagement should mask the input line. A
+     *  server that enables ECHO during the opening negotiation burst — before
+     *  it has printed any output — is doing session-wide remote echo (it will
+     *  echo your name, commands, everything), not requesting a password. The
+     *  classic Diku/ROM password pattern instead toggles `IAC WILL ECHO` on
+     *  *after* the name prompt, right before "Password:". So we only treat an
+     *  ECHO that engages after the server has already sent output as a password
+     *  prompt. Captured at each OFF→ON transition. Mudlet masks on every ECHO;
+     *  doing so here would hide the name on full-server-echo MUDs, which is the
+     *  bug this distinction fixes. */
+    private _passwordStyle;
+    /** Set once the server has emitted any non-telnet output. Distinguishes a
+     *  connect-time (server-wide) ECHO from a later (password) ECHO. */
+    private sawAppData;
+    private stabilityTimer;
+    private passwordSafetyTimer;
+    private connectionStartAt;
+    private toggleCount;
+    private lastToggleAt;
+    private _anomalyDetected;
+    private readonly sendRaw;
+    private readonly onEchoChange;
+    private readonly onAnomalyDetected;
+    constructor(sendRaw: (data: string) => void, onEchoChange: (maskInput: boolean) => void, onAnomalyDetected?: () => void);
+    get serverEchoing(): boolean;
+    /** Whether the command input should be masked (password mode). Only true
+     *  for an ECHO engagement that began after the server started sending
+     *  output — a genuine password prompt — never for connect-time server-wide
+     *  echo. */
+    get passwordMode(): boolean;
+    get anomalyDetected(): boolean;
+    /** Scan the post-MCCP byte stream for true `IAC WILL/WONT ECHO`. Substring
+     *  matching on the raw buffer is unsafe — GMCP/MSDP subnegotiation payloads
+     *  can contain the same byte sequence (e.g. an unescaped IAC followed by
+     *  MSDP_VAR=\x01), which would spuriously flip password mode every prompt
+     *  on data-heavy servers like Legend of Kallisti. Walk the stream as
+     *  telnet: skip SB…SE blocks entirely, honor IAC IAC escapes, and only act
+     *  on top-level IAC WILL/WONT ECHO. */
+    processData(data: string): void;
+    private setEchoing;
+    /** Arm / disarm the Mudlet-style "password mode never ended" safety
+     *  timeout. Called right after a committed state change. */
+    private updatePasswordSafetyTimer;
+    /** Mirror cTelnet::checkEchoAnomalyPattern. Increments a sliding-window
+     *  toggle counter on every raw flip and, when the threshold is crossed,
+     *  trips sticky anomaly state. Returns true when anomaly was tripped on
+     *  this call (the caller should bail out). */
+    private trackToggleAndDetectAnomaly;
+    /** Refuse ECHO for the rest of the session: send `IAC DONT ECHO`, drop any
+     *  pending commit / safety timers, force the UI back to normal, and notify
+     *  the engine so a `sysEchoAnomalyDetected` Lua event can fire. */
+    private tripAnomaly;
+    reset(): void;
+}

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

@@ -0,0 +1,28 @@
+export interface GmcpEnvelope {
+    path: string;
+    value: unknown;
+}
+export type TelnetOptionHandler = (data: string) => string;
+export declare const createTelnetOptionParser: (onSubnegotiation: (data: string) => void) => TelnetOptionHandler;
+export declare const stripTelnetSequences: (data: string, handler: TelnetOptionHandler) => string;
+export declare const encodeGmcp: (path: string, payload: unknown) => string;
+/** Encode a GMCP frame from a single pre-formatted body (e.g. `"Module.Sub args"`).
+ *  Matches Mudlet's `sendGMCP` semantics — the caller controls the exact bytes
+ *  between IAC SB GMCP and IAC SE. */
+export declare const encodeGmcpRaw: (message: string) => string;
+export interface GmcpStreamOptions {
+    onEnvelope: (payload: GmcpEnvelope) => void;
+    /** Called for gmcp_msgs subnegotiations (base64-encoded text with a type field). */
+    onMessage?: (text: string, type: string) => void;
+    /** Called for every `Client.GUI` request, in whichever wire format it
+     *  arrived: the parsed `{url, version}` object, or the legacy raw
+     *  `<version>\n<url>` string. Split out from `onEnvelope` so the install has
+     *  one entry point for both formats, and so the legacy one — which Mudlet
+     *  keeps out of the Lua `gmcp` table — has somewhere to go that isn't the
+     *  table-populating path. The JSON form still emits its envelope as well,
+     *  and does so first, so scripts observe it before the install runs. */
+    onClientGui?: (payload: unknown) => void;
+    /** Text decoder used for gmcp_msgs payloads. Defaults to UTF-8. */
+    textEncoding?: string;
+}
+export declare const createGmcpStream: ({ onEnvelope, onMessage, onClientGui, textEncoding, }: GmcpStreamOptions) => (data: string) => void;

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

@@ -0,0 +1,11 @@
+export * from "./constants";
+export * from "./gmcp";
+export * from "./msdp";
+export * from "./mssp";
+export { MccpHandler } from "./mccp";
+export { EchoHandler } from "./echo";
+export { MspParser, type MspCommand, type MspKind } from "./msp";
+export { MxpParser, splitMxpResultLines, type MxpLink, type MxpLineResult } from "./mxp";
+export { parseMnesRequest, encodeMnesIs, selectMnesVars, buildNewEnvironVars, CLIENT_NAME, CLIENT_VERSION, TERMINAL_TYPE, type MnesVar, type MnesRequest, type NewEnvironState } from "./mnes";
+export { encodeNaws } from "./naws";
+export { SessionCodec, CharsetHandler, normalizeCharsetName, pickCharsetFromRequest, SUPPORTED_SERVER_ENCODINGS, type CharsetHandlerHooks } from "./charset";

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

@@ -0,0 +1,18 @@
+export declare class MccpHandler {
+    private compressing;
+    private inflator;
+    private readonly sendRaw;
+    private _enabled;
+    constructor(sendRaw: (data: string) => void);
+    isActive(): boolean;
+    get enabled(): boolean;
+    set enabled(value: boolean);
+    /**
+     * Process incoming data, handling MCCP negotiation and decompression.
+     * Must be called BEFORE stripTelnetSequences.
+     */
+    processData(data: string): string;
+    reset(): void;
+    private startCompression;
+    private decompress;
+}