@mudlet/mudlet-web 0.3.1 → 0.4.1

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;
@@ -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;
@@ -164,21 +215,68 @@ 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;
@@ -200,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
@@ -245,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

@@ -189,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];
@@ -207,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;

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

@@ -20,7 +20,26 @@ export declare function normalizeCharsetName(raw: string): string | null;
  *  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.) */
+/** What `getServerEncoding()` reports before anything has changed it. UTF-8
+ *  rather than Mudlet's ASCII: the decoder handles ASCII byte-for-byte anyway,
+ *  and a browser stream is far more likely to be UTF-8 than not. */
+export declare const DEFAULT_SERVER_ENCODING = "UTF-8";
 export declare const SUPPORTED_SERVER_ENCODINGS: readonly string[];
+/** The {@link SUPPORTED_SERVER_ENCODINGS} entry a caller's spelling means, or
+ *  null when mudix cannot decode it. Dash/space/case differences are all the
+ *  same encoding — the profile XML, the wire, and Mudlet's own list disagree
+ *  about which to use — so the answer is always the list's own spelling and
+ *  `getServerEncoding()` reports one canonical name whatever was set. */
+export declare function canonicalServerEncoding(raw: string): string | null;
+/**
+ * Whether every character of `text` survives a trip to the game under
+ * `serverEncoding` — Mudlet's TEncodingHelper::canEncode, which is what decides
+ * whether a send gets the "unlikely to understand it" warning.
+ *
+ * Anything mudix cannot judge (an unknown label) is called encodable: the point
+ * is to warn about a loss that will certainly happen, not to guess.
+ */
+export declare function canEncodeForServer(text: string, serverEncoding: string): boolean;
 /**
  * Parse an `IAC SB CHARSET REQUEST ...` subnegotiation body (leading byte is
  * the option code 42, then subcommand byte 1, then optional `[TTABLE]<ver>`
@@ -61,11 +80,14 @@ export declare class SessionCodec {
     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. */
+     *  UTF-8 goes through TextEncoder so multi-byte chars survive; every other
+     *  encoding here is single-byte and goes through the inverted decode table,
+     *  which puts the codepage's own byte on the wire. (A plain `& 0xff`
+     *  truncation used to stand in for that, and was right only for the
+     *  Latin-1 range — every Polish, Cyrillic, or Greek character above it went
+     *  out as a byte meaning something else entirely.) A character the codepage
+     *  has no byte for becomes '?', as Qt's encoder does it — and the send path
+     *  warns before it comes to that. */
     encodeOutgoing(text: string): string;
 }
 export interface CharsetHandlerHooks {

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

@@ -1,4 +1,5 @@
 export declare const TELNET_OPTION_REGEX: RegExp;
+export declare const TELNET_OPTION_REGEX_NO_SB: RegExp;
 export declare const TELNET_GA = "\u00FF\u00F9";
 export declare const TELNET_EOR = "\u00FF\u00EF";
 export declare const TELOPT_EOR = "\u0019";

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

@@ -3,12 +3,28 @@ export interface GmcpEnvelope {
     value: unknown;
 }
 export type TelnetOptionHandler = (data: string) => string;
-export declare const createTelnetOptionParser: (onSubnegotiation: (data: string) => void) => TelnetOptionHandler;
+/** UTF-8-encode into a Latin-1 byte-string, for MudClient.sendBytes (which
+ *  writes `charCodeAt(i) & 0xff` per char). The inverse of fromByteString. */
+export declare const toByteString: (s: string) => string;
+export declare const createTelnetOptionParser: (onSubnegotiation: (data: string) => void, opts?: {
+    /** When true, an inbound IAC GA / IAC EOR is replaced by a newline
+     *  rather than stripped — Mudlet's `mFORCE_GA_OFF` behaviour
+     *  (`cTelnet::processSocketData` pushes `'\n'` in place of the marker
+     *  instead of treating it as a prompt). Doing the substitution here,
+     *  inside the sequence parser, keeps it positional: the newline lands
+     *  exactly where the marker was, and a `\xFF\xF9` byte pair inside a
+     *  subnegotiation payload is never mistaken for one. */
+    promptMarkerAsNewline?: boolean;
+}) => 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. */
+ *  Mudlet's `sendGMCP` semantics — the caller controls the body between IAC SB
+ *  GMCP and IAC SE — except that the body is transcoded to UTF-8 rather than to
+ *  the session's outgoing encoding, so it can't be used to place arbitrary raw
+ *  bytes on the wire. UTF-8 is what the GMCP spec asks for, and it's also what
+ *  keeps a 0xFF byte (which would need IAC-escaping inside a subnegotiation)
+ *  out of the body in the first place. */
 export declare const encodeGmcpRaw: (message: string) => string;
 export interface GmcpStreamOptions {
     onEnvelope: (payload: GmcpEnvelope) => void;

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

@@ -8,4 +8,4 @@ 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";
+export { SessionCodec, CharsetHandler, normalizeCharsetName, pickCharsetFromRequest, SUPPORTED_SERVER_ENCODINGS, DEFAULT_SERVER_ENCODING, canonicalServerEncoding, canEncodeForServer, type CharsetHandlerHooks } from "./charset";