@mudlet/mudlet-web 0.3.0

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

@@ -0,0 +1,268 @@
+import { EventBus } from "../../core/EventBus";
+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 interface MudClientOptions {
+    url: string;
+    mccpEnabled?: boolean;
+    commandEcho?: boolean;
+    chunkProcessor?: ChunkProcessor;
+    /** Milliseconds to hold a partial trailing line (text after the last `\n`)
+     *  before flushing it as a prompt. Mirrors Mudlet's "Network packet timeout"
+     *  preference; defaults to 300ms. Once a server has sent IAC GA or IAC EOR
+     *  at least once, the client latches into "GA-driver" mode and the partial
+     *  tail is flushed by the prompt marker instead of this timer — so the value
+     *  only matters as an idle safety net (e.g. a line split across frames whose
+     *  remainder never arrives). */
+    promptTimeoutMs?: number;
+    /** Whether to accept GMCP (telnet option 201) negotiation. Default true.
+     *  When false, the client silently ignores IAC WILL/DO GMCP so the server
+     *  never sees a positive ack and no GMCP envelopes flow. */
+    gmcpEnabled?: boolean;
+    /** Whether to accept TERMINAL-TYPE / MTTS (telnet option 24) negotiation.
+     *  Default true. When false, IAC DO TTYPE is ignored so the server falls
+     *  back to its non-MTTS code path. */
+    mttsEnabled?: boolean;
+    /** Whether to accept MSDP (telnet option 69) negotiation. Default false.
+     *  When false, IAC WILL/DO MSDP is ignored and no MSDP envelopes flow. */
+    msdpEnabled?: boolean;
+    /** Whether to accept MSSP (telnet option 70) negotiation. Default true
+     *  (matching Mudlet). When false, IAC WILL/DO MSSP is ignored and the
+     *  server's status subnegotiation never arrives. */
+    msspEnabled?: boolean;
+    /** Whether to accept CHARSET (telnet option 42, RFC 2066) negotiation.
+     *  Default true. When false, IAC WILL/DO CHARSET is ignored and the
+     *  session stays on the UTF-8 baseline (so non-ASCII bytes from non-UTF-8
+     *  MUDs render as replacement chars). */
+    charsetEnabled?: boolean;
+    /** Whether to enable MSP (MUD Sound Protocol, telnet option 90). Default
+     *  false. When true the client negotiates the option and strips inline
+     *  `!!SOUND(...)` / `!!MUSIC(...)` tags from MUD text, dispatching them
+     *  as `msp` events. Always parses subnegotiations regardless of this flag
+     *  once negotiated, but in-band parsing is gated to avoid eating literal
+     *  text on MUDs that don't speak MSP. */
+    mspEnabled?: boolean;
+    /** Whether to accept MXP (telnet option 91) negotiation. Default true.
+     *  When false, IAC WILL/DO MXP is ignored so the server never sees a
+     *  positive ack and no in-band MXP markup is parsed (tags pass through as
+     *  literal text). The actual tag parsing lives downstream in the scripting
+     *  engine, gated on the `mxp.negotiated` event this client emits. */
+    mxpEnabled?: boolean;
+    /** Whether to answer telnet option 39 in MNES mode (Mud New-Environ
+     *  Standard). Default false. When on, the client reports the five MNES core
+     *  variables (CHARSET / CLIENT_NAME / CLIENT_VERSION / MTTS / TERMINAL_TYPE),
+     *  framed as NEW_ENVIRON_VAR. MNES takes precedence over plain NEW-ENVIRON
+     *  when both are enabled — matching Mudlet, which restricts the reported set
+     *  to these five whenever MNES is active. */
+    mnesEnabled?: boolean;
+    /** Whether to answer telnet option 39 in plain NEW-ENVIRON mode (RFC 1572,
+     *  "Client Variables Standard"). Default false. When on (and MNES off), the
+     *  client reports the five core variables plus an extended capability set
+     *  (ANSI, 256_COLORS, TRUECOLOR, UTF-8, TLS, WORD_WRAP, …), framed as
+     *  NEW_ENVIRON_USERVAR. Mudlet exposes MNES and NEW-ENVIRON as two separate
+     *  toggles over the same telnet option; mudix mirrors that. */
+    newEnvironEnabled?: boolean;
+    /** 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). */
+    secureTransport?: boolean;
+    /** Whether to advertise screen-reader use, reported as the MTTS SCREEN
+     *  READER bit and the NEW-ENVIRON `SCREEN_READER` capability
+     *  (`setConfig("advertiseScreenReader", …)`). Default false. */
+    screenReaderAdvertised?: boolean;
+    /** Whether to negotiate NAWS / window size (telnet option 31). Default true
+     *  (matching Mudlet). When true the client offers IAC WILL NAWS on connect
+     *  and, once the server accepts (IAC DO NAWS), reports the main output
+     *  area's character grid (columns × rows) and re-sends it on every resize.
+     *  When false the client never offers NAWS and ignores IAC DO NAWS. */
+    nawsEnabled?: boolean;
+    /** Mudlet's "Fix unnecessary linebreaks on GA servers"
+     *  (`setConfig("fixUnnecessaryLinebreaks", …)`, host flag
+     *  `mUSE_IRE_DRIVER_BUGFIX`). Default false. When true *and* the session is
+     *  GA-driven, a single spurious leading newline is stripped from the start
+     *  of each GA-terminated data block — the IRE-server bug Mudlet patches in
+     *  `cTelnet::gotPrompt`. See LineAssembler. */
+    fixUnnecessaryLinebreaks?: 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:
+     *  `binary` (raw telnet over binary frames — the mode mudix decodes),
+     *  `telnet` (FluffOS's equivalent name), `telnet.mudstandards.org` (the
+     *  mudstandards.org proposal). Empty means open a bare socket. Advertising is
+     *  a trade-off: some servers (FluffOS) route a *no-subprotocol* upgrade to a
+     *  non-MUD handler and never send data, while others (e.g. last-outpost.com)
+     *  *reject* an unrecognized subprotocol with HTTP 400 — hence the per-profile
+     *  choice. The server's selection is read back from `socket.protocol` on open
+     *  and emitted via `client.subprotocol`. */
+    subprotocols?: string[];
+}
+/** The WebSocket subprotocol name for the mudstandards.org "full telnet stream
+ *  over binary frames" profile (https://mudstandards.org/websocket/). mudix
+ *  already speaks this wire format; advertising the name lets a conforming
+ *  server confirm the dialect via the RFC 6455 handshake. */
+export declare const MUD_TELNET_SUBPROTOCOL = "telnet.mudstandards.org";
+/**
+ * The MUD-facing transport: telnet over a WebSocket (direct or via the
+ * telnet→WebSocket proxy). Owns the socket lifecycle and the outbound send
+ * paths; the protocol concerns are composed from dedicated pieces —
+ * {@link TelnetNegotiator} (option negotiation + sysTelnetEvent),
+ * {@link SessionCodec}/{@link CharsetHandler} (byte↔char encoding + CHARSET),
+ * {@link LineAssembler} (partial-line buffering + prompt flushing),
+ * `MccpHandler` (compression), `EchoHandler` (password masking), and the
+ * GMCP/MSDP/MSSP subnegotiation streams.
+ */
+export declare class MudClient {
+    private socket;
+    private readonly eventBus;
+    private readonly chunkProcessor;
+    private messageBuffer;
+    private readonly gmcpStream;
+    private readonly msdpStream;
+    private readonly msspStream;
+    private readonly telnetOptionHandler;
+    private readonly mccpHandler;
+    private readonly echoHandler;
+    private readonly negotiator;
+    /** Latches once `sysCharacterModeDetected` has fired for this connection so
+     *  the warning isn't repeated. Reset on each connect(). See
+     *  {@link maybeDetectCharacterMode}. */
+    private charModeDetected;
+    /** Byte↔char codec for the session (inbound streaming decoder + outgoing
+     *  encoding). Swapped between encodings by the CHARSET handler. */
+    private readonly codec;
+    private readonly charsetHandler;
+    /** Whole-line assembly of the decoded text stream (partial-tail buffering,
+     *  GA-driven prompt flushing, the idle-flush safety net). */
+    private readonly assembler;
+    private readonly url;
+    /** Buffers the start of a subnegotiation that arrived without its closing IAC SE. */
+    private pendingSubneg;
+    /** True once the WebSocket handshake has completed; used to differentiate
+     *  "failed to connect" from "connection lost mid-session" in close events. */
+    private opened;
+    /** True once we've sent the GMCP `Core.Hello` / `Core.Supports.Set`
+     *  handshake this session, so a server that re-offers GMCP doesn't make us
+     *  announce ourselves twice. Reset on each connect(). */
+    private gmcpHelloSent;
+    commandEcho: boolean;
+    /** Gates the in-band `!!SOUND(...)` / `!!MUSIC(...)` tag parsing — the tag
+     *  bytes are legitimate text on non-MSP MUDs. */
+    private readonly mspEnabled;
+    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;
+    setMccpEnabled(enabled: boolean): void;
+    isMccpEnabled(): boolean;
+    /** Mudlet `setConfig("fixUnnecessaryLinebreaks", …)`. Takes effect on the
+     *  next GA-driven block; never retroactive. */
+    setFixUnnecessaryLinebreaks(enabled: boolean): void;
+    /** Mudlet `addSupportedTelnetOption(option)`. See TelnetNegotiator. */
+    addSupportedTelnetOption(option: number): boolean;
+    setPromptTimeoutMs(ms: number): void;
+    getPromptTimeoutMs(): number;
+    connect(): void;
+    disconnect(): void;
+    /** Whether MSP is live on this connection (negotiated, not merely allowed
+     *  by the profile config) — gates Mudlet's receiveMSP. */
+    isMspNegotiated(): boolean;
+    /** Qt's QAbstractSocket::UnconnectedState — no socket at all, or one that
+     *  has finished closing. CONNECTING/OPEN/CLOSING are all "not unconnected",
+     *  which is the state feedTelnet refuses to inject into. */
+    isSocketUnconnected(): boolean;
+    isSocketOpen(): boolean;
+    isPasswordMode(): boolean;
+    shouldEchoCommand(): boolean;
+    send(message: string): 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
+     *  outbound byte funnels through here, so it's also where `mudix.debugTelnet`
+     *  mirrors what we send. */
+    private sendBytes;
+    sendGmcp(path: string, payload?: unknown): void;
+    /** Announce ourselves to the server right after GMCP is negotiated, the way
+     *  Mudlet does: `Core.Hello` identifies the client (name + version) and
+     *  `Core.Supports.Set` lists the GMCP modules we understand. Many servers
+     *  won't push any GMCP data (room, char, vitals, …) until they've received
+     *  this hello, so without it GMCP effectively does nothing. Latched so a
+     *  repeated WILL/DO GMCP doesn't re-announce. Reports our own identity
+     *  (see src/version.ts), matching the TTYPE/MNES/MXP handshakes. */
+    private sendGmcpHandshake;
+    /** Route GMCP `Char.Login.*` messages. The server sends `Char.Login.Default
+     *  { "type": [...] }` to request login and then *waits* for the client to
+     *  supply credentials — withholding the normal text "By what name…" prompt
+     *  until it hears back (servers that do this gate on the `Char.Login` module
+     *  we advertise in `Core.Supports.Set`). We surface it as `charLogin.request`
+     *  so the UI can pop a credentials form; the UI replies via
+     *  `sendCharLoginCredentials`, or an empty reply (cancel) to fall back to the
+     *  text login (the behaviour Mudlet/Mudlet#7377 is about). `Char.Login.Result`
+     *  carries the outcome. Path match is case-insensitive — GMCP module casing
+     *  varies between servers. */
+    private handleCharLogin;
+    /** Send the GMCP `Char.Login.Credentials` reply. With an account, sends
+     *  `{ account, password }` (account may be `"account:character"` for games
+     *  with both); with no account it sends the empty `{}` form — the spec's
+     *  "no credentials, fall back to your next auth method" signal, used when the
+     *  user cancels the popup. mudix never stores the password; it only relays it. */
+    sendCharLoginCredentials(account?: string, password?: string): void;
+    sendGmcpRaw(message: string): void;
+    /** Mudlet `sendMSDP(variable, ...values)`. Frames + sends an MSDP
+     *  subnegotiation. Returns false when the socket isn't open. */
+    sendMSDP(variable: string, values: string[]): boolean;
+    /** Mudlet `sendATCP(message)`. Frames `IAC SB ATCP <message> IAC SE` (ATCP =
+     *  telnet option 200, GMCP's predecessor) and sends it raw. Returns false
+     *  when the socket isn't open. */
+    sendATCP(message: string): boolean;
+    /** Mudlet `sendTelnetChannel102(msg)`. Frames `IAC SB 102 <msg> IAC SE`
+     *  (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. */
+    private sendSubnegotiation;
+    /** Mudlet `getServerEncoding()`. The IANA name of the decoder currently
+     *  applied to the inbound stream — 'utf-8' until CHARSET negotiation (or an
+     *  explicit setServerEncoding) swaps it. */
+    getServerEncoding(): string;
+    /** 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;
+    /** Route an `IAC SB MSP ... IAC SE` body to the MSP parser and dispatch
+     *  any parsed commands as `msp` events. Always runs when an MSP subneg
+     *  arrives — once the server has bothered to wrap a tag, we trust it. */
+    private handleMspSubneg;
+    /** Report the main output window's character grid (columns × rows) for NAWS.
+     *  The session calls this on every output-area resize. See TelnetNegotiator. */
+    setWindowSize(cols: number, rows: number): void;
+    /** Mudlet `sendSocket(data)`. Sends literal bytes over the socket with no
+     *  telnet/encoding processing (each char becomes one byte). Returns false
+     *  when the socket isn't open. */
+    sendSocket(data: string): boolean;
+    /** Mudlet `feedTelnet(data)`. Injects raw bytes into the inbound pipeline
+     *  as if they had arrived from the server — they pass through telnet
+     *  stripping, ANSI parsing, the trigger pipeline, and rendering. `data` is
+     *  treated as a Latin-1 byte-string (matching incoming-frame handling). */
+    feedTelnet(data: string): void;
+    output(text?: string | AnsiAwareBuffer, type?: string, timestamp?: number): void;
+    /** Push a line directly into the message buffer for trigger processing + rendering via flushLines. */
+    pushLine(text: string, type: string): void;
+    private processIncomingData;
+    flushMessageBuffer(): void;
+}

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

@@ -0,0 +1,28 @@
+export interface PingEventSource {
+    on(event: 'gmcp.negotiated', handler: () => void): () => void;
+    on(event: 'client.disconnect', handler: () => void): () => void;
+    on(event: 'gmcp.core.ping', handler: () => void): () => void;
+}
+export declare class PingTracker {
+    private readonly sendPingCommand;
+    private readonly onPing;
+    private timer;
+    private probeTimer;
+    private lastSentAt;
+    private lastDuration;
+    private supported;
+    private readonly unsubs;
+    constructor(sendPingCommand: (latencyMs: number) => void, onPing: (duration: number | null) => void, source: PingEventSource);
+    destroy(): void;
+    private probe;
+    private start;
+    private stop;
+    /** Sends the last round-trip we measured, per the GMCP spec's documented
+     *  `Core.Ping <average latency>` form — 0 on the first probe, when there is
+     *  nothing measured yet. The latency is informational to the server; what
+     *  matters here is that the request always carries a body, since a bare
+     *  `Core.Ping` makes servers that unconditionally JSON-parse the part after
+     *  the module name choke on an empty string. */
+    private sendPing;
+    private handlePingResponse;
+}

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

@@ -0,0 +1,188 @@
+import type { EventBus } from "../../core/EventBus";
+import type { MudClientEvents } from "../events";
+export interface TelnetNegotiatorFlags {
+    gmcpEnabled: boolean;
+    mttsEnabled: boolean;
+    msdpEnabled: boolean;
+    msspEnabled: boolean;
+    charsetEnabled: boolean;
+    mspEnabled: boolean;
+    mxpEnabled: boolean;
+    mnesEnabled: boolean;
+    newEnvironEnabled: boolean;
+    nawsEnabled: boolean;
+    /** Whether the game-facing transport is TLS (MTTS SSL bit, NEW-ENVIRON TLS var). */
+    secureTransport: boolean;
+    /** Whether to advertise screen-reader use (MTTS SCREEN READER bit,
+     *  NEW-ENVIRON SCREEN_READER var) — Mudlet's `advertiseScreenReader` config
+     *  key. Default false; some MUDs adjust their output (e.g. suppress ASCII
+     *  art, add extra room-description detail) when this is set. */
+    screenReaderAdvertised: boolean;
+}
+export interface TelnetNegotiatorHooks {
+    sendRaw(data: string): void;
+    /** GMCP came up — send the Core.Hello / Core.Supports.Set handshake
+     *  (latched by the owner so a re-offer doesn't re-announce). */
+    onGmcpNegotiated(): void;
+    /** CHARSET came up — kick off the client-driven REQUEST listing our
+     *  preferred encodings. */
+    onCharsetNegotiated(): void;
+    /** Current inbound encoding (IANA label) — drives the MTTS UTF-8 bit and
+     *  the MNES/NEW-ENVIRON CHARSET variable. */
+    getEncoding(): string;
+}
+/**
+ * Telnet option negotiation for a MUD session. Owns the WILL/WONT/DO/DONT
+ * response policy, the per-session negotiation latches (TTYPE cycle position,
+ * MXP started, NAWS accepted), the Mudlet `addSupportedTelnetOption` registry,
+ * and the `telnet.event` (sysTelnetEvent) surface for everything unrecognized.
+ *
+ * `processFrame` makes a single position-aware walk over each incoming frame's
+ * IAC sequences — skipping subnegotiation payloads and escaped `IAC IAC` bytes
+ * so data bytes can't be mistaken for negotiation commands — and buffers a
+ * trailing incomplete sequence for the next frame. Subnegotiation *bodies*
+ * (SB … SE payloads) are not parsed here; they arrive via the handleXxxSubneg
+ * methods, routed by MudClient's option parser.
+ */
+export declare class TelnetNegotiator {
+    private readonly flags;
+    private readonly eventBus;
+    private readonly hooks;
+    /** Mudlet `addSupportedTelnetOption(option)` registry. On IAC WILL <opt>
+     *  we reply IAC DO <opt>; on IAC DO <opt> we reply IAC WILL <opt>. Options
+     *  negotiated natively (GMCP/MSDP/TTYPE/…) are excluded — they have their
+     *  own response logic. Survives reconnects (matches the old client-field
+     *  lifetime: the registry lives as long as the client instance). */
+    private readonly supportedTelnetOptions;
+    /** Per-incoming-frame dedupe. Keys below 0x100 mark a natively-handled
+     *  option as already answered this frame (mirroring the old one-response-
+     *  per-frame `includes()` behavior); keys `(cmd << 8) | opt` mark a
+     *  `telnet.event` as already raised. Telnet sequences can repeat across
+     *  frames, so we only suppress duplicates within a single frame to avoid
+     *  event storms. */
+    private readonly frameSeen;
+    /** Trailing bytes of a frame that might be the start of a split IAC
+     *  sequence (a bare IAC, IAC WILL with no option byte yet, or an IAC SB
+     *  whose IAC SE hasn't arrived) — prepended to the next frame so
+     *  negotiation commands split across WebSocket frames aren't missed. */
+    private carry;
+    /** MTTS cycle position. The server issues SB TTYPE SEND repeatedly; we walk
+     *  through client name (0), terminal type (1), then the MTTS bitvector (2+).
+     *  Reset on each connect(). */
+    private ttypeStep;
+    /** Latches true once MXP has started for this session — via telnet option 91
+     *  negotiation OR by detecting an in-band MXP line-mode sequence (`ESC[<n>z`).
+     *  Many MUDs enable MXP server-side and just start streaming tags without the
+     *  telnet handshake, so the in-band signal is the reliable trigger. Reset on
+     *  each connect(). */
+    private mxpStarted;
+    /** 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;
+    /** True once the server has accepted NAWS (IAC DO NAWS). Gates whether a
+     *  window-size change is pushed to the server. */
+    private nawsNegotiated;
+    /** True once MSP has actually been negotiated (either direction) this
+     *  connection. Mirrors Mudlet's `ctelnet::enableMSP` — the profile config
+     *  only decides whether we're willing to negotiate; this records that we
+     *  did. See {@link isMspNegotiated}. */
+    private mspNegotiated;
+    /** Latest known main output window size in character columns × rows, fed in
+     *  by the session's resize observer via setWindowSize(). Null until the UI
+     *  has measured the grid at least once. Deliberately NOT cleared by reset()
+     *  so a reconnect keeps reporting the current grid. */
+    private windowSize;
+    /** Latches true once the server has asked us to suppress go-ahead (IAC WILL
+     *  SGA). mudix refuses SGA (line mode only), but records the request:
+     *  combined with active server echo it's the character-at-a-time signature
+     *  the owner uses to raise `sysCharacterModeDetected`. Reset on connect(). */
+    private serverRequestedSGA;
+    constructor(flags: TelnetNegotiatorFlags, eventBus: EventBus<MudClientEvents>, hooks: TelnetNegotiatorHooks);
+    /** Clear the per-connection latches (call on connect). */
+    reset(): void;
+    /** Whether MSP was actually negotiated with the server this connection —
+     *  Mudlet's `ctelnet::enableMSP`, distinct from the profile's `enableMSP`
+     *  config (which only decides whether we agree to negotiate at all). Gates
+     *  `receiveMSP`, which Mudlet refuses unless the option is live. */
+    isMspNegotiated(): boolean;
+    /** Drop the negotiated-MSP latch without resetting the rest of the
+     *  negotiation state — used on disconnect, where the option dies with the
+     *  connection but reset() isn't otherwise run. */
+    clearMspNegotiated(): void;
+    /** Whether the server has asked us to suppress go-ahead this connection
+     *  (IAC WILL SGA). We refuse SGA, but the owner combines this with the
+     *  echo state to detect character-at-a-time mode. */
+    get sgaRequested(): boolean;
+    /** The WebSocket handshake completed — proactively offer NAWS (RFC 1073
+     *  has the window-owning side send WILL). The server replies IAC DO NAWS —
+     *  handled in processFrame — at which point we send the actual dimensions.
+     *  Harmless if the server doesn't support it (it answers DONT or ignores us). */
+    onSocketOpen(): void;
+    /** Mudlet `addSupportedTelnetOption(option)`. Marks the telnet option byte
+     *  (0..255) as one the client will accept: on the next IAC WILL <opt> we
+     *  reply IAC DO <opt>; on IAC DO <opt> we reply IAC WILL <opt>. Natively
+     *  negotiated options (GMCP=201, MSDP=69, TTYPE=24, …) don't need to be
+     *  registered. Returns true if the option was newly added, false if it was
+     *  already present. */
+    addSupportedTelnetOption(option: number): boolean;
+    /** Record the main output window's character grid (columns × rows) for NAWS.
+     *  The value is stored regardless of negotiation state (so a client created
+     *  on a later connect can be seeded with the current size); it's only sent
+     *  to the server once NAWS has been negotiated, and only when it changed. */
+    setWindowSize(cols: number, rows: number): void;
+    /** Walk one incoming frame (post-MCCP Latin-1 byte-string) for telnet IAC
+     *  sequences: answer WILL/WONT/DO/DONT per the option policy, auto-respond
+     *  to registered supported options, raise `telnet.event` for everything
+     *  else (including SB of unrecognized options), and watch for in-band MXP
+     *  line-mode sequences on servers that skip the option-91 handshake. */
+    processFrame(data: string): void;
+    /** One WILL/WONT/DO/DONT for `opt`. Natively-handled options are answered
+     *  at most once per frame (matching the old `includes()`-based scan); the
+     *  supported-options registry answers every occurrence; anything left is
+     *  surfaced as a `telnet.event`. */
+    private handleNegotiationCommand;
+    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). */
+    private noticeSubnegotiation;
+    /** `type` mirrors Mudlet's TLuaInterpreter mapping: 1=WILL, 2=WONT, 3=DO,
+     *  4=DONT, 5=SB. Deduped per (command, option) within the frame so a server
+     *  that spams the same option doesn't flood handlers. */
+    private emitTelnetEvent;
+    /** Reply to a TERMINAL-TYPE / MTTS subnegotiation. `subneg` is the SB body
+     *  with the option byte (24) at [0]; [1] is the request kind (1 = SEND). We
+     *  answer `IAC SB TTYPE IS <value> IAC SE`, cycling client name → terminal
+     *  type → MTTS capability bitvector on successive SENDs, then repeating the
+     *  last value to signal the list is exhausted (RFC 1091 + the MTTS standard). */
+    handleTtypeSubneg(subneg: string): void;
+    /** Handle an `IAC SB MXP IAC SE` subnegotiation. Per spec it carries no
+     *  payload — it merely confirms MXP is active — so we just start MXP. The
+     *  actual MXP markup arrives in-band and is parsed downstream by the
+     *  scripting engine. */
+    handleMxpSubneg(): void;
+    /** Answer an `IAC SB NEW-ENVIRON SEND … IAC SE` request, framed as
+     *  `IAC SB NEW-ENVIRON IS <marker> … VALUE … IAC SE`. Telnet option 39 is
+     *  shared by two modes: MNES reports the five core variables framed as VAR;
+     *  plain NEW-ENVIRON reports the core set plus an extended capability set,
+     *  framed as USERVAR. MNES takes precedence when both toggles are on
+     *  (matching Mudlet). The server may request specific variables or send a
+     *  bare SEND for all; selectMnesVars handles both. No-op when the option is
+     *  off for this profile or on a malformed/non-SEND body. */
+    handleNewEnvironSubneg(subneg: string): void;
+    /** Build the option-39 variable set from live client state. CHARSET tracks
+     *  the negotiated encoding; the extended NEW-ENVIRON capabilities derive from
+     *  the game-facing transport (TLS — false in proxy mode) and the measured
+     *  output grid (WORD_WRAP). The static identity (CLIENT_NAME/VERSION, MTTS,
+     *  TERMINAL_TYPE) and the capability defaults live in buildNewEnvironVars. */
+    private collectNewEnvironVars;
+    /** Latch MXP on for this session and notify listeners. Idempotent — only the
+     *  first call emits `mxp.negotiated`; later calls (repeat WILL/DO, in-band
+     *  detection on subsequent frames) are no-ops. `viaTelnet` distinguishes a
+     *  real option-91 handshake from in-band-only detection (see the event doc). */
+    private startMxp;
+    /** Send the current window size as an `IAC SB NAWS … IAC SE` subnegotiation.
+     *  Falls back to a conventional 80×24 terminal default when the UI hasn't
+     *  reported a real size yet — better than the NAWS 0×0 "no preference"
+     *  sentinel, which some servers treat as "disable wrapping". */
+    private sendNawsSize;
+}

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

@@ -0,0 +1,54 @@
+/**
+ * localStorage-gated diagnostic logging for the MUD connection. Each gate is
+ * toggled from the browser console (e.g. `localStorage.setItem('mudix.debugTelnet',
+ * '1')`) and read live on every use, so logging can be flipped mid-session
+ * without a reconnect.
+ */
+/**
+ * `mudix.debugTelnet` — log every telnet command/subnegotiation byte seen on
+ * each incoming frame, and every byte-string we send. Used to investigate
+ * protocol-negotiation issues (GMCP/MSDP/MCCP not enabling) by revealing
+ * exactly what crosses the wire in both directions.
+ */
+export declare function debugTelnetEnabled(): boolean;
+/**
+ * `mudix.debugFrames` — log WebSocket frame boundaries for the MUD stream.
+ * Used to investigate "extra line break" issues that surface when long MUD
+ * lines arrive split across multiple WebSocket frames.
+ */
+export declare function debugFramesEnabled(): boolean;
+/**
+ * `mudix.debugMsp` — log MSP negotiation, parsed `!!SOUND`/`!!MUSIC` tags
+ * (inline and subneg), and their dispatch into the SoundManager. Use this to
+ * confirm whether a MUD is actually emitting MSP and whether the client is
+ * routing it through.
+ */
+export declare function debugMspEnabled(): boolean;
+/**
+ * `mudix.debugGmcp` — log every parsed GMCP message's path and (truncated) body
+ * as it arrives. Used to see exactly which modules a server drives — e.g.
+ * whether login audio comes over `Client.Media.*` GMCP vs. MSP tags.
+ */
+export declare function debugGmcpEnabled(): boolean;
+/**
+ * `mudix.debugGa` — log every IAC GA / IAC EOR prompt marker the server sends,
+ * plus the one-time moment the client latches into GA-driven prompt mode. Use
+ * this to confirm whether a MUD actually signals its prompts (GA-less MUDs rely
+ * on the `promptTimeoutMs` idle-flush fallback instead).
+ */
+export declare function debugGaEnabled(): boolean;
+/** Scan a Latin-1 byte-string for telnet IAC sequences and log them in
+ *  human-readable form. Logs SB option codes too (e.g. `SB GMCP` / `SB MSDP`). */
+export declare function logTelnetNegotiation(label: string, s: string): void;
+/**
+ * Log an outbound byte-string: the IAC sequences it carries plus the verbatim
+ * body of every subnegotiation, so a handshake payload a server rejects (a GMCP
+ * body it refuses to parse, say) is visible exactly as we framed it — the
+ * inbound `logTelnetNegotiation` only names options, which isn't enough to tell
+ * a malformed body from a well-formed one.
+ *
+ * Bodies only: plain command text is reported as a byte count, never content,
+ * because `send()` also carries typed passwords. `Char.Login.Credentials` is
+ * redacted for the same reason.
+ */
+export declare function logOutboundBytes(s: string): void;