@mudlet/mudlet-web 0.3.0 → 0.4.0

package/dist-lib/mud/connection/MudClient.d.ts

@@ -3,7 +3,7 @@ import { AnsiAwareBuffer } from "../text/FormatState";
 import { type ChunkProcessor } from "../triggers/ChunkProcessor";
 import type { MudClientEvents } from "../events";
 export type { MudClientEvents } from "../events";
-export { SUPPORTED_SERVER_ENCODINGS } from "../protocol";
+export { SUPPORTED_SERVER_ENCODINGS, DEFAULT_SERVER_ENCODING, canonicalServerEncoding, canEncodeForServer } from "../protocol";
 export interface MudClientOptions {
     url: string;
     mccpEnabled?: boolean;
@@ -67,9 +67,9 @@ export interface MudClientOptions {
     /** Whether the link to the *game server* is TLS-encrypted, reported as the
      *  NEW-ENVIRON `TLS` capability. Defaults to whether `url` is `wss://` — the
      *  correct answer for a direct websocket-mode connection. In proxy (`mud`)
-     *  mode the caller passes `false` explicitly, because a `wss://` proxy URL
-     *  only secures the browser↔proxy hop while the proxy↔MUD telnet socket is
-     *  plaintext (see connectionSecureTransport). */
+     *  mode the caller passes the answer explicitly, because a `wss://` proxy URL
+     *  only secures the browser↔proxy hop: the proxy↔MUD leg is plaintext telnet
+     *  unless the profile enabled TLS (see connectionSecureTransport). */
     secureTransport?: boolean;
     /** Whether to advertise screen-reader use, reported as the MTTS SCREEN
      *  READER bit and the NEW-ENVIRON `SCREEN_READER` capability
@@ -88,6 +88,51 @@ export interface MudClientOptions {
      *  of each GA-terminated data block — the IRE-server bug Mudlet patches in
      *  `cTelnet::gotPrompt`. See LineAssembler. */
     fixUnnecessaryLinebreaks?: boolean;
+    /** Mudlet's `Host::mUndoServerWrap` — rejoin the lines the game wrapped
+     *  itself, so triggers and rendering see whole logical lines. Default false.
+     *  See LineAssembler and mud/text/serverWrap.ts. */
+    undoServerWrap?: boolean;
+    /** The column that game wraps at (`Host::mUndoServerWrapWidth`, default 80).
+     *  Only consulted while {@link undoServerWrap} is on. */
+    undoServerWrapWidth?: number;
+    /** Mudlet's `setConfig("inputLineStrictUnixEndings", …)` (host flag
+     *  `mUSE_UNIX_EOL`). Default false. When true a submitted command is
+     *  terminated with a bare `\n` instead of the telnet-standard `\r\n`
+     *  (`cTelnet::sendData` appends the CR only when the flag is off) — some
+     *  Unix-y servers treat the CR as part of the command. */
+    inputLineStrictUnixEndings?: boolean;
+    /** Mudlet's `setConfig("specialForceGAOff", …)` (host flag `mFORCE_GA_OFF`).
+     *  Default false. When true an inbound IAC GA / IAC EOR is *not* treated as
+     *  a prompt marker: the session never latches into GA-driven mode and the
+     *  marker becomes a plain newline in the data stream, exactly as
+     *  `cTelnet::processSocketData` does in its `else` branch. For servers whose
+     *  GA placement is wrong often enough that prompt detection does more harm
+     *  than good. Read once per connect (Mudlet snapshots it in `connectIt`), so
+     *  a mid-session change applies on the next dial. */
+    specialForceGAOff?: boolean;
+    /** Mudlet's `setConfig("promptForVersionInTTYPE", …)` (host flag
+     *  `mPromptedForVersionInTTYPE`). Default false. Latches once the KaVir
+     *  auto-detect has had its say for this profile, so a user who then turns
+     *  `versionInTTYPE` back off isn't overridden on the next connect. */
+    promptForVersionInTTYPE?: boolean;
+    /** Mudlet's `setConfig("promptForMXPProcessorOn", …)` (host flag
+     *  `mPromptedForMXPProcessorOn`). Default false. Latches once the in-band
+     *  MXP auto-detect has fired for this profile; together with
+     *  `specialForceMXPProcessorOn` it decides whether an `ESC[<n>z` from a
+     *  server that never negotiated option 91 may still start MXP. */
+    promptForMXPProcessorOn?: boolean;
+    /** Mudlet's `setConfig("specialForceMXPProcessorOn", …)` (host flag
+     *  `mForceMXPProcessorOn`). Default false. Only consulted here for the
+     *  in-band-detection gate above — the parser-side effect lives in
+     *  ScriptingEngine, which owns the MXP processor. */
+    specialForceMXPProcessorOn?: boolean;
+    /** Mudlet's `setConfig("versionInTTYPE", …)` (host flag `mVersionInTTYPE`).
+     *  Default false. When true the first TTYPE cycle value carries our version
+     *  after the client name (`MUDLET-WEB 1.2.3`). Off by default because the
+     *  period is not a legal TTYPE character per RFC 1091 — but servers running
+     *  KaVir's protocol snippet parse a version out of it and fall back to 16
+     *  colours without one, so it's opt-in rather than absent. */
+    versionInTTYPE?: boolean;
     /** WebSocket subprotocols to advertise in the opening handshake's
      *  `Sec-WebSocket-Protocol` header (RFC 6455), in preference order — the
      *  server selects at most one. Mutually-exclusive stream *modes*, not layers:
@@ -117,6 +162,8 @@ export declare const MUD_TELNET_SUBPROTOCOL = "telnet.mudstandards.org";
  * GMCP/MSDP/MSSP subnegotiation streams.
  */
 export declare class MudClient {
+    /** The live WebSocket, or null when there is none — before the first
+     *  connect, and from the moment disconnect() lets go of one. */
     private socket;
     private readonly eventBus;
     private readonly chunkProcessor;
@@ -130,8 +177,12 @@ export declare class MudClient {
     private readonly negotiator;
     /** Latches once `sysCharacterModeDetected` has fired for this connection so
      *  the warning isn't repeated. Reset on each connect(). See
-     *  {@link maybeDetectCharacterMode}. */
+     *  {@link checkCharacterModePattern}. */
     private charModeDetected;
+    /** Pending character-at-a-time verdict, armed by a submitted game command
+     *  while ECHO+SGA are active and cancelled if the server releases ECHO
+     *  first. Null when nothing is in flight. */
+    private charModeTimer;
     /** Byte↔char codec for the session (inbound streaming decoder + outgoing
      *  encoding). Swapped between encodings by the CHARSET handler. */
     private readonly codec;
@@ -149,6 +200,14 @@ export declare class MudClient {
      *  handshake this session, so a server that re-offers GMCP doesn't make us
      *  announce ourselves twice. Reset on each connect(). */
     private gmcpHelloSent;
+    /** Set when this dial asked the proxy for TLS (`&tls=1` in the URL), so the
+     *  client knows to expect a `tls.established` control frame and to police
+     *  the deadline below. */
+    private readonly tlsRequested;
+    /** True once the proxy confirmed the handshake, or once any game bytes have
+     *  arrived (which can only happen through a working tunnel). */
+    private tlsResolved;
+    private tlsDeadline;
     commandEcho: boolean;
     /** Gates the in-band `!!SOUND(...)` / `!!MUSIC(...)` tag parsing — the tag
      *  bytes are legitimate text on non-MSP MUDs. */
@@ -156,26 +215,78 @@ export declare class MudClient {
     private readonly mspParser;
     /** WebSocket subprotocols advertised on connect (see MudClientOptions). */
     private readonly subprotocols;
-    constructor({ url, mccpEnabled, commandEcho, chunkProcessor, promptTimeoutMs, gmcpEnabled, mttsEnabled, msdpEnabled, msspEnabled, charsetEnabled, mspEnabled, mxpEnabled, mnesEnabled, newEnvironEnabled, secureTransport, screenReaderAdvertised, nawsEnabled, fixUnnecessaryLinebreaks, subprotocols, }: MudClientOptions, eventBus: EventBus<MudClientEvents>);
-    /** Mudlet-parity character-at-a-time detection (cTelnet::
-     *  checkCharacterModePattern). When the server has both asked to suppress
-     *  go-ahead (IAC WILL SGA — which we refuse) *and* enabled server-side echo,
-     *  it's driving a character-at-a-time session that mudix, a line-based
-     *  client, can't handle well. Raise `sysCharacterModeDetected` once so the
-     *  UI / scripts can warn the user. Checked on both trigger edges: an SGA
-     *  request arriving while echo is already on, and echo committing while SGA
-     *  was already requested. */
-    private maybeDetectCharacterMode;
+    /** Mudlet `mUSE_UNIX_EOL` — terminate submitted commands with a bare `\n`.
+     *  Read on every send, so a change applies to the next command (Mudlet reads
+     *  the host flag in `sendData` too). */
+    private strictUnixEndings;
+    /** Mudlet `mFORCE_GA_OFF` — see MudClientOptions.specialForceGAOff. A live
+     *  session keeps parsing with the value it connected with (Mudlet snapshots
+     *  the host flag into cTelnet at `connectIt`), which here falls out of
+     *  MudSession building a fresh client per connect. An unconnected one takes
+     *  the change straight away — see {@link setForceGaOff}. */
+    private forceGaOff;
+    /** Handed to the telnet sequence parser and mutated in place, so the parser
+     *  reads the current setting rather than the one it was built with. */
+    private readonly telnetParserOpts;
+    constructor({ url, mccpEnabled, commandEcho, chunkProcessor, promptTimeoutMs, gmcpEnabled, mttsEnabled, msdpEnabled, msspEnabled, charsetEnabled, mspEnabled, mxpEnabled, mnesEnabled, newEnvironEnabled, secureTransport, screenReaderAdvertised, nawsEnabled, fixUnnecessaryLinebreaks, undoServerWrap, undoServerWrapWidth, inputLineStrictUnixEndings, specialForceGAOff, versionInTTYPE, promptForVersionInTTYPE, promptForMXPProcessorOn, specialForceMXPProcessorOn, subprotocols, }: MudClientOptions, eventBus: EventBus<MudClientEvents>);
+    /** Mudlet-parity character-at-a-time detection (cTelnet::sendData's
+     *  `armCharacterModeDetection`). ECHO+SGA on its own is *not* the signature:
+     *  an ordinary line-mode server masking a password negotiates exactly the
+     *  same pair. The two are told apart by behaviour, so detection is armed
+     *  only by a submitted game command and only decides {@link
+     *  CHARACTER_MODE_DETECT_MS} later — a password mask sends WONT ECHO right
+     *  after the masked line and cancels it first.
+     *
+     *  Re-armed on every game command so the window always measures from the
+     *  most recent submission. */
+    private armCharacterModeDetection;
+    private cancelCharacterModeDetection;
+    /** The armed window elapsed with ECHO+SGA still active — a full input line
+     *  was submitted without the server releasing echo, which a password prompt
+     *  never does. Raise `sysCharacterModeDetected` once per connection so the
+     *  UI / scripts can warn the user.
+     *
+     *  Accepted limitation (same as Mudlet's): this can't tell genuine
+     *  character-at-a-time from the rarer cases of a buggy password prompt that
+     *  never sends WONT ECHO, or a line-mode server using persistent
+     *  server-side echo. We stay in line mode regardless and the message is
+     *  only advisory. */
+    private checkCharacterModePattern;
     setMccpEnabled(enabled: boolean): void;
     isMccpEnabled(): boolean;
     /** Mudlet `setConfig("fixUnnecessaryLinebreaks", …)`. Takes effect on the
      *  next GA-driven block; never retroactive. */
     setFixUnnecessaryLinebreaks(enabled: boolean): void;
+    /**
+     * Mudlet `setConfig("specialForceGAOff", …)`. Only an UNCONNECTED client
+     * takes the change: a live session has to keep parsing telnet the way it
+     * connected, or a GA mid-stream would suddenly mean something else. Mudlet
+     * draws the same line — `cacheHostSettings()` is re-run from setConfig only
+     * while the socket is unconnected, and otherwise at the next connect.
+     */
+    setForceGaOff(enabled: boolean): void;
+    /** Mudlet `setConfig("undoServerWrap", …)`. Live: the next server line is
+     *  judged under the new setting. */
+    setUndoServerWrap(enabled: boolean): void;
+    /** Mudlet `setConfig("undoServerWrapWidth", …)`. */
+    setUndoServerWrapWidth(width: number): void;
+    /** Commit a line held for a wrap continuation whose flush delay has passed.
+     *  See {@link LineAssembler.pumpServerWrapDue}. */
+    pumpServerWrapDue(now?: number): boolean;
+    /** Mudlet `setConfig("inputLineStrictUnixEndings", …)`. Live: `cTelnet::
+     *  sendData` reads the host flag per send, so the next command submitted
+     *  uses the new terminator. */
+    setInputLineStrictUnixEndings(enabled: boolean): void;
     /** Mudlet `addSupportedTelnetOption(option)`. See TelnetNegotiator. */
     addSupportedTelnetOption(option: number): boolean;
     setPromptTimeoutMs(ms: number): void;
     getPromptTimeoutMs(): number;
     connect(): void;
+    /** Stop policing the TLS deadline — the handshake is accounted for. */
+    private resolveTls;
+    /** Decode one proxy control frame. Anything unrecognised is ignored so a
+     *  newer proxy can add message types without breaking older clients. */
+    private handleControlFrame;
     disconnect(): void;
     /** Whether MSP is live on this connection (negotiated, not merely allowed
      *  by the profile config) — gates Mudlet's receiveMSP. */
@@ -187,7 +298,11 @@ export declare class MudClient {
     isSocketOpen(): boolean;
     isPasswordMode(): boolean;
     shouldEchoCommand(): boolean;
-    send(message: string): void;
+    /** `isGameCommand` mirrors `cTelnet::sendData`'s third argument: only a real
+     *  game command (typed or from a script's `send()`) may arm
+     *  character-at-a-time detection. Credentials and internal protocol replies
+     *  route through here too and must not. */
+    send(message: string, isGameCommand?: boolean): void;
     private sendRaw;
     /** Encodes a Latin-1 byte-string to raw bytes and sends it as a binary
      *  WebSocket frame. The proxy worker expects binary, not base64. Every
@@ -232,9 +347,11 @@ export declare class MudClient {
      *  (the zMUD generic out-of-band channel) and sends it raw. Returns false
      *  when the socket isn't open. */
     sendTelnetChannel102(msg: string): boolean;
-    /** Frame a raw `IAC SB <opt> <payload> IAC SE` subnegotiation and send it
-     *  with no encoding conversion (each char → one byte), like the other
-     *  telnet negotiations. Shared by sendATCP / sendTelnetChannel102. */
+    /** Frame an `IAC SB <opt> <payload> IAC SE` subnegotiation and send it.
+     *  `payload` must already be a Latin-1 byte-string (each char → one byte)
+     *  with any IAC handled — the framing is all this does, since ATCP and
+     *  channel 102 need different byte treatments. Shared by sendATCP /
+     *  sendTelnetChannel102. */
     private sendSubnegotiation;
     /** Mudlet `getServerEncoding()`. The IANA name of the decoder currently
      *  applied to the inbound stream — 'utf-8' until CHARSET negotiation (or an

package/dist-lib/mud/connection/TelnetNegotiator.d.ts

@@ -18,6 +18,25 @@ export interface TelnetNegotiatorFlags {
      *  key. Default false; some MUDs adjust their output (e.g. suppress ASCII
      *  art, add extra room-description detail) when this is set. */
     screenReaderAdvertised: boolean;
+    /** Whether the first TTYPE cycle value carries our version after the client
+     *  name — Mudlet's `versionInTTYPE` config key (`mVersionInTTYPE`). Default
+     *  false: RFC 1091 doesn't permit the period, so Mudlet stopped sending it
+     *  in 2024. Servers running KaVir's protocol snippet want it anyway (without
+     *  a version they assume 1.0 and cap colour support at 16), which is what
+     *  the KaVir auto-detect below turns it on for. */
+    versionInTTYPE: boolean;
+    /** Whether this profile has already been through the KaVir auto-detect —
+     *  Mudlet's `promptForVersionInTTYPE` config key (`mPromptedForVersionInTTYPE`).
+     *  When true the detector below is disabled, so a user who turned
+     *  `versionInTTYPE` back off is not overridden on every reconnect. */
+    versionInTTYPEPrompted: boolean;
+    /** Whether an in-band `ESC[<n>z` may still auto-start MXP on a server that
+     *  never negotiated telnet option 91. Mudlet gates its equivalent scan on
+     *  `mForceMXPProcessorOn || !mPromptedForMXPProcessorOn`
+     *  (`cTelnet::gotRest`): once the auto-detect has fired for a profile, only
+     *  the forced-on state keeps it live — so a user who then turns
+     *  `specialForceMXPProcessorOn` off is not re-overridden every connect. */
+    mxpInBandDetectionEnabled: boolean;
 }
 export interface TelnetNegotiatorHooks {
     sendRaw(data: string): void;
@@ -30,6 +49,10 @@ export interface TelnetNegotiatorHooks {
     /** Current inbound encoding (IANA label) — drives the MTTS UTF-8 bit and
      *  the MNES/NEW-ENVIRON CHARSET variable. */
     getEncoding(): string;
+    /** The server's option-negotiation order matched KaVir's protocol snippet —
+     *  it wants a version in our TTYPE reply. Fired at most once per connection;
+     *  the owner turns `versionInTTYPE` on and redials. */
+    onKaVirProtocolDetected(): void;
 }
 /**
  * Telnet option negotiation for a MUD session. Owns the WILL/WONT/DO/DONT
@@ -76,6 +99,15 @@ export declare class TelnetNegotiator {
      *  telnet handshake, so the in-band signal is the reliable trigger. Reset on
      *  each connect(). */
     private mxpStarted;
+    /** Rolling window of the last {@link KAVIR_NEGOTIATION_ORDER}`.length`
+     *  options the server sent us a WILL/DO for, oldest first — Mudlet's
+     *  `mNegotiationOrder`. Compared against the KaVir fingerprint after each
+     *  push. Reset on each connect(). */
+    private negotiationOrder;
+    /** Latches once the KaVir fingerprint has matched this connection, so the
+     *  detector fires the hook at most once even though a server may keep
+     *  re-offering options. */
+    private kaVirDetected;
     /** True once we've sent IAC WILL NAWS this session (proactively on connect,
      *  or in response to a server-initiated IAC DO NAWS), so we don't re-offer. */
     private nawsWillSent;
@@ -141,6 +173,13 @@ export declare class TelnetNegotiator {
      *  supported-options registry answers every occurrence; anything left is
      *  surfaced as a `telnet.event`. */
     private handleNegotiationCommand;
+    /** Mudlet `cTelnet::trackKaVirNegotiation`. Records the option of each
+     *  inbound WILL/DO in a rolling window and fires the hook the first time the
+     *  window equals the KaVir fingerprint. Recording happens before the
+     *  per-frame response dedupe, so the order seen here is the order the server
+     *  actually sent — the same thing Mudlet feeds its own tracker from
+     *  `processTelnetCommand`. */
+    private trackKaVirNegotiation;
     private respondToKnownOption;
     /** Raise `telnet.event` for an SB of an option we neither handle natively
      *  nor auto-negotiate (type 5 in Mudlet's sysTelnetEvent mapping). */

package/dist-lib/mud/connection/telnetByteTags.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Mudlet's `<XX>` byte placeholders for `feedTelnet(data)` —
+ * `TLuaInterpreter::decodeBytes`.
+ *
+ * Lua strings are text, and the bytes a telnet stream is made of mostly are not:
+ * `\xff\xf9` typed into a script is awkward to read and easy to get wrong, and a
+ * profile that saves scripts as XML has to survive round-tripping them. So
+ * Mudlet lets the data name its control bytes instead — `<T_IAC><T_GA>` for a
+ * prompt marker, `<ESC>` for the start of an ANSI sequence — and decodes them
+ * here before the bytes reach the parser.
+ *
+ * Anything that isn't a known tag is passed through unchanged, so ordinary text
+ * containing `<` survives; `<<` and `>>` are the escapes for a literal one.
+ */
+/**
+ * Version of the tag table, as Mudlet's `decodeBytes` reports it: feeding the
+ * empty string yields this number as text rather than nothing, so a script can
+ * ask which tags it can count on.
+ */
+export declare const TELNET_BYTE_TAG_TABLE_VERSION = 1;
+/**
+ * Decode Mudlet's `<XX>` byte placeholders into the bytes they name, as
+ * `feedTelnet` does before handing data to the telnet parser.
+ *
+ * The result is a byte-string (each code unit ≤ 0xFF), which is what the inbound
+ * pipeline takes — the same shape a decoded WebSocket frame arrives in.
+ *
+ * - `<<` yields a literal `<`, `>>` a literal `>`.
+ * - An unknown `<…>` is left exactly as written, so prose and markup pass
+ *   through: `<b>bold</b>` is text, not a failed decode.
+ * - An unclosed `<` is likewise just a `<`.
+ * - The empty string yields the tag table's version number as text, which is how
+ *   a script asks what this build understands.
+ */
+export declare function decodeTelnetByteTags(input: string): string;

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

@@ -2,6 +2,55 @@ import type { AnsiAwareBuffer } from './text/FormatState';
 import type { MspCommand } from './protocol';
 import type { ScriptLogSource } from './MudSession';
 export type SessionStatus = 'disconnected' | 'connecting' | 'connected';
+/** The peer certificate as reported by the proxy. Mirrors the four fields
+ *  Mudlet shows (issuer / issued-to / expiry / serial) plus a little extra for
+ *  diagnostics. All strings, already formatted for display. */
+export interface TlsCertInfo {
+    subject: string;
+    subjectOrg: string;
+    issuer: string;
+    issuerOrg: string;
+    validFrom: string;
+    validTo: string;
+    serial: string;
+    fingerprint: string;
+    altNames: string;
+}
+export interface TlsEstablished {
+    /** Negotiated protocol, e.g. `TLSv1.3`. Empty when the proxy can't report it. */
+    protocol: string;
+    /** Negotiated cipher suite name. Empty when the proxy can't report it. */
+    cipher: string;
+    cert: TlsCertInfo | null;
+    /** False when the proxy runtime cannot inspect certificates at all. */
+    certInspection: boolean;
+    /** Certificate faults tolerated because of the profile's ignore-flags. */
+    acceptedDespite: string[];
+    /** Cert-tolerance options this proxy was asked for but cannot honour. */
+    unsupportedOptions: string[];
+}
+/** What the UI knows about the current connection's TLS state. */
+export type TlsStatus = {
+    kind: 'established';
+    info: TlsEstablished;
+} | {
+    kind: 'error';
+    info: TlsError;
+}
+/** TLS was asked for but nothing came back — see the `tls.timeout` event. */
+ | {
+    kind: 'timeout';
+    host: string;
+    port: number;
+};
+export interface TlsError {
+    /** Primary blocking fault, e.g. `CERT_HAS_EXPIRED`. */
+    code: string;
+    message: string;
+    codes: string[];
+    cert: TlsCertInfo | null;
+    certInspection: boolean;
+}
 /** 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
@@ -26,6 +75,24 @@ export type MudClientEvents = {
     /** 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];
+    /** The proxy completed a TLS handshake with the game and the link is
+     *  carrying decrypted traffic. `cert` is null when the proxy cannot inspect
+     *  certificates (the Cloudflare Worker runtime can't), in which case
+     *  `certInspection` is false. `acceptedDespite` lists any certificate faults
+     *  the profile's ignore-flags waved through — non-empty means encrypted but
+     *  not authenticated. */
+    'tls.established': [info: TlsEstablished];
+    /** The proxy refused the game's certificate, or the TLS handshake failed.
+     *  The connection is closing; `codes` carries every blocking fault. */
+    'tls.error': [info: TlsError];
+    /** TLS was requested but the link produced no evidence of a handshake before
+     *  the deadline. Distinct from `tls.error` because the cause is ambiguous:
+     *  a proxy too old to understand `&tls=1`, or a Cloudflare-Worker-backed
+     *  proxy where a rejected certificate hangs silently instead of reporting. */
+    'tls.timeout': [info: {
+        host: string;
+        port: number;
+    }];
     'gmcp.negotiated': void;
     'msdp.negotiated': void;
     'mssp.negotiated': void;
@@ -122,11 +189,21 @@ export type MudClientEvents = {
      *  (`'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. */
+     *  server has both asked to suppress go-ahead (IAC WILL SGA) *and* kept
+     *  server-side echo on across a submitted game command — the
+     *  character-at-a-time signature that mudix, a line-based client, can't
+     *  drive well. The three-second delay is what separates it from an ordinary
+     *  password mask, which negotiates the same pair but releases echo as soon
+     *  as the masked line is in. Lets scripts / the UI warn the user that input
+     *  may not behave as expected. */
     'charmode.detected': void;
+    /** The server's telnet option-negotiation order matched KaVir's protocol
+     *  snippet (Mudlet `cTelnet::trackKaVirNegotiation`). Such servers read a
+     *  decimal version out of our TTYPE client-name reply and fall back to 16
+     *  colours without one, so the owner switches `versionInTTYPE` on and
+     *  redials. Fires at most once per connection, and never once the profile's
+     *  `promptForVersionInTTYPE` latch is set. */
+    'kavir.detected': void;
 } & Record<string, any>;
 export type MudEvents = MudClientEvents & {
     'status': [status: SessionStatus];
@@ -140,6 +217,11 @@ export type MudEvents = MudClientEvents & {
     'script.clearcmd': void;
     'script.selectcmd': void;
     'script.cmdlinesuggestions': [items: string[]];
+    /** Words Tab completion must never offer, whatever list they came from. */
+    'script.cmdlineblacklist': [items: string[]];
+    /** Whether the main command bar's history is persisted at all
+     *  (setSaveCommandHistory); the size cap stays a separate setting. */
+    'script.savecommandhistory': [save: boolean];
     'script.openvfs': [path: string];
     /** Fired by ScriptingAPI when Lua calls `invokeFileDialog(...)`. The UI
      *  (ProfileSession) shows the in-app VFS picker and resolves the request

package/dist-lib/mud/games/bundledGames.d.ts

@@ -0,0 +1,29 @@
+/** One entry of Mudlet's bundled-game catalogue (its C++ `GameDetail`). */
+export interface BundledGame {
+    name: string;
+    hostUrl: string;
+    port: number;
+    tlsEnabled: boolean;
+    /** Small HTML fragment of website/forum/Discord links. */
+    websiteInfo: string;
+    /** Qt resource path of the game's icon, kept as the upstream identifier. */
+    icon: string;
+    /** Filename of the copy vendored in ./icons/, when one was available.
+     *  Resolve it with `gameIconUrl()` rather than building a path by hand —
+     *  the bundler only emits assets it can see referenced. */
+    iconFile?: string;
+    description: string;
+    /** The game's own loader installs its full interface, so the generic
+     *  starter UI is not preinstalled for it. */
+    providesOwnUi?: boolean;
+    /** Other hostnames the game answers on. */
+    alternateHostUrls?: string[];
+}
+export declare const BUNDLED_GAMES: readonly BundledGame[];
+/** The bundled game called `name`, matched the way Mudlet matches it
+ *  (TGameDetails::findGame — exact, case-sensitive). */
+export declare function findBundledGame(name: string): BundledGame | null;
+/** Whether the game reachable at `hostUrl` installs its own full interface,
+ *  in which case the generic starter UI is not preinstalled (Mudlet's
+ *  TGameDetails::gameProvidesOwnUi). */
+export declare function gameProvidesOwnUi(hostUrl: string): boolean;

package/dist-lib/mud/games/gameIcons.d.ts

@@ -0,0 +1,5 @@
+import { type BundledGame } from './bundledGames';
+/** URL of a bundled game's logo, or null when it has none vendored. Accepts the
+ *  entry or its exact name, so a caller holding only a profile name (which is
+ *  the game's name for a profile made from the catalogue) can ask too. */
+export declare function gameIconUrl(game: BundledGame | string | undefined): string | null;

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

@@ -1,3 +1,4 @@
+import { ItemIdSequence } from '../ItemIdSequence';
 import type { KeyNode } from '../../storage/schema';
 export type { KeyNode };
 type TempFn = () => void;
@@ -9,8 +10,11 @@ export interface KeyCodeInfo {
 export declare class KeyEngine {
     private readonly temp;
     private perm;
-    private nextId;
-    /** Number of live session-scoped temp keys (Mudlet `getProfileStats` temp count). */
+    /** Shared with every other engine in the profile — see ItemIdSequence. */
+    private idSeq;
+    setIdSequence(seq: ItemIdSequence): void;
+    /** Number of live session-scoped temp keys (Mudlet `getProfileStats` temp
+     *  count). Killed-but-unreaped keys are not live and don't count. */
     get tempCount(): number;
     addTemp(key: string, modifiers: string[], fn: TempFn, qt?: {
         keyCode: number;
@@ -29,6 +33,9 @@ export declare class KeyEngine {
      */
     getKeyCode(idOrName: number | string): KeyCodeInfo | null;
     killKey(id: number): boolean;
+    /** Free every key killed since the last call. Runs once per processed line
+     *  batch, mirroring the deferred cleanup Mudlet's TKeyUnit does. */
+    reapKilled(): void;
     processTemp(event: KeyboardEvent): boolean;
     loadPerm(keybindings: KeyNode[]): void;
     matchPerm(event: KeyboardEvent): KeyNode | null;

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

@@ -25,7 +25,11 @@ export interface ReservedKeyWarning {
 }
 /** 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). */
+/** Detect the platform accelerator modifier, from `navigator.platform` on every
+ *  call. Note that a `navigator` exists under vitest's node environment too, and
+ *  reports the real host — so this is not a Ctrl fallback in tests, and a test
+ *  that hard-codes one accelerator will pass on CI and fail on a Mac. Callers
+ *  that need a fixed platform should pass `accel` explicitly. */
 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;

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

@@ -0,0 +1,17 @@
+/**
+ * Whether a keydown belongs to the focused text widget rather than to the
+ * keybinding engine.
+ *
+ * The MUD command line is a `<textarea class="command-input">` (an `<input>`
+ * of the same class in password mode) and holds focus for essentially the
+ * whole session. So the usual "don't hijack keys while the user is typing"
+ * guard — `tagName === 'TEXTAREA'` — cannot be applied to it: it is true
+ * almost always, and it silently disables every keybinding in the profile.
+ * Typing a command is the app's resting state, not a text-entry mode that
+ * should own every hotkey.
+ *
+ * Real text entry elsewhere — the Lua script editor (CodeMirror, so
+ * `contentEditable`), a modal's form field, the script tree's filter box —
+ * does keep the event to itself.
+ */
+export declare function isTextEntryTarget(target: EventTarget | null): boolean;

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

@@ -1,5 +1,7 @@
 /** Qt::KeypadModifier — set by Mudlet when a binding came from the numpad. */
 export declare const QT_KEYPAD_MODIFIER = 536870912;
+/** Qt::Key_unknown — what Mudlet stores for a key item with nothing bound to it. */
+export declare const QT_KEY_UNKNOWN = 33554431;
 /**
  * Translate a Qt::Key integer (or already-translated DOM `KeyboardEvent.code`
  * string) into a DOM `KeyboardEvent.code`. Mudlet `tempKey` accepts both;

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

@@ -0,0 +1,68 @@
+/**
+ * GMCP `Char.Login` flow decisions.
+ *
+ * The server sends `Char.Login.Default` to ask for credentials and then waits,
+ * withholding its text login prompt until the client answers. Answering is
+ * therefore mandatory — every path here ends in either a credentials reply or a
+ * popup that will produce one. `Char.Login.Result` reports the outcome, and a
+ * server that rejects an attempt commonly re-sends `Char.Login.Default` to ask
+ * again, so these rules run repeatedly within one connection.
+ *
+ * Mirrors Mudlet's `GMCPAuthenticator` (GMCPAuthenticator.cpp). Kept free of
+ * React and session plumbing so the rules can be tested directly; the caller
+ * supplies the per-connection state.
+ */
+/** What to do about a `Char.Login.Default` request. */
+export type CharLoginAction = 
+/** Reply with the empty `{}` form — "no credentials, use your next method". */
+{
+    kind: 'decline';
+}
+/** Send stored credentials without troubling the player. */
+ | {
+    kind: 'autofill';
+    account: string;
+    password: string;
+}
+/** Raise the credentials popup. */
+ | {
+    kind: 'prompt';
+};
+export interface CharLoginRequestState {
+    /** The `type` list from `Char.Login.Default`; empty when the server sent none. */
+    methods: string[];
+    /** The player chose "Use text login" earlier this connection. */
+    declined: boolean;
+    /** Credentials have already been sent once this connection (stored or typed). */
+    attempted: boolean;
+    /** Stored/in-memory credentials, if any. */
+    account?: string;
+    password?: string;
+}
+/**
+ * Decide how to answer a `Char.Login.Default`.
+ *
+ * The one automatic attempt per connection is the load-bearing rule: it makes a
+ * saved login silent when it works, and guarantees that a *wrong* saved login
+ * turns into a visible popup instead of a silent send-reject-send loop against
+ * the server's repeated asks.
+ */
+export declare function decideCharLoginRequest(state: CharLoginRequestState): CharLoginAction;
+/**
+ * The console line for a rejected login, in Mudlet's wording
+ * (`GMCPAuthenticator::handleAuthResult`). Servers doing GMCP login usually send
+ * no text of their own, so this is often the only trace of the failure.
+ */
+/**
+ * The console line for credentials the game never answered at all: it closed the
+ * connection instead of sending `Char.Login.Result`.
+ *
+ * Measured against Achaea (2026-08-02): a rejected `Char.Login.Credentials` gets
+ * no result, no text, no close reason — the socket simply ends. The same wrong
+ * password typed into its *text* login prints "Password incorrect. For recovery,
+ * see …" before dropping, so the silence is specific to the GMCP path. Mudlet
+ * only reports `Char.Login.Result`, so it is equally silent here; without this
+ * line a mistyped password is indistinguishable from a network failure.
+ */
+export declare const CHAR_LOGIN_SILENT_DROP_MESSAGE: string;
+export declare function charLoginFailureMessage(message?: string): string;