@mudlet/mudlet-web 0.5.0 → 1.0.0

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

@@ -2,6 +2,7 @@ import { EventBus } from "../../core/EventBus";
 import { AnsiAwareBuffer } from "../text/FormatState";
 import { type ChunkProcessor } from "../triggers/ChunkProcessor";
 import type { MudClientEvents } from "../events";
+import { type TelnetNegotiatorFlags } from "./TelnetNegotiator";
 export type { MudClientEvents } from "../events";
 export { SUPPORTED_SERVER_ENCODINGS, DEFAULT_SERVER_ENCODING, canonicalServerEncoding, canEncodeForServer } from "../protocol";
 export interface MudClientOptions {
@@ -38,11 +39,11 @@ export interface MudClientOptions {
      *  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. */
+     *  false. When true the client negotiates the option; commands then arrive
+     *  as `IAC SB MSP` subnegotiations and are dispatched as `msp` events.
+     *  Inline `!!SOUND(...)` / `!!MUSIC(...)` tags in MUD text are never
+     *  parsed — as in Mudlet, they stay in the line for triggers to handle
+     *  (typically via `receiveMSP`). */
     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
@@ -62,15 +63,8 @@ export interface MudClientOptions {
      *  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. */
+     *  toggles over the same telnet option; Mudlet Web 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 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
      *  (`setConfig("advertiseScreenReader", …)`). Default false. */
@@ -88,10 +82,10 @@ export interface MudClientOptions {
     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. */
+     *  `mUSE_IRE_DRIVER_BUGFIX`). Default false. When true, a single spurious
+     *  leading newline is stripped from the start of each block of a read that
+     *  ends in GA/EOR — the IRE-server bug Mudlet patches in
+     *  `cTelnet::gotPrompt`. See LineAssembler.stripPromptBlockNewline. */
     fixUnnecessaryLinebreaks?: boolean;
     /** Mudlet's `Host::mUndoServerWrap` — rejoin the lines the game wrapped
      *  itself, so triggers and rendering see whole logical lines. Default false.
@@ -141,7 +135,7 @@ export interface MudClientOptions {
     /** 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),
+     *  `binary` (raw telnet over binary frames — the mode Mudlet Web 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
@@ -152,10 +146,13 @@ export interface MudClientOptions {
     subprotocols?: string[];
 }
 /** The WebSocket subprotocol name for the mudstandards.org "full telnet stream
- *  over binary frames" profile (https://mudstandards.org/websocket/). mudix
+ *  over binary frames" profile (https://mudstandards.org/websocket/). Mudlet Web
  *  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";
+/** Whether a slice that has run `elapsed` ms should give the event loop its
+ *  turn. Exported for the tests. */
+export declare function inboundSliceDue(elapsed: number, hasInput?: () => boolean): boolean;
 /**
  * The MUD-facing transport: telnet over a WebSocket (direct or via the
  * telnet→WebSocket proxy). Owns the socket lifecycle and the outbound send
@@ -180,6 +177,16 @@ export declare class MudClient {
     private readonly mccpHandler;
     private readonly echoHandler;
     private readonly negotiator;
+    /** Writes back the IAC SE a server left off a subnegotiation, before any
+     *  inbound parser reads the bytes (see SubnegotiationRepair). */
+    private readonly subnegRepair;
+    /** The negotiator's option toggles, held here because they are the
+     *  profile's and the profile can change under a live connection. Mudlet
+     *  reads `mEnableMSSP` and friends at negotiation time, so a setting
+     *  switched off mid-session must be obeyed by the next offer rather than
+     *  by the next dial. Mutated in place by setProtocolFlags — the
+     *  negotiator holds this same object. */
+    private readonly negotiatorFlags;
     /** Latches once `sysCharacterModeDetected` has fired for this connection so
      *  the warning isn't repeated. Reset on each connect(). See
      *  {@link checkCharacterModePattern}. */
@@ -196,27 +203,57 @@ export declare class MudClient {
      *  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;
+    /** Buffers a telnet sequence the frame ended in the middle of — a lone
+     *  IAC, an option command missing its option byte, or a subnegotiation
+     *  without its closing IAC SE — until the next frame completes it. */
+    private pendingTelnet;
     /** 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;
+    /** When the game command now awaiting a reply went out (`performance.now()`),
+     *  or null when nothing is being timed. Mudlet's
+     *  `cTelnet::begin/finishNetworkLatencyMeasurement`: on a server that marks
+     *  its prompts with GA/EOR, the time from a command to the first read
+     *  off the socket after it is the network latency `getNetworkLatency()` reports
+     *  — the only reading there is, as Mudlet sends no GMCP `Core.Ping`. Timed from the first command of a
+     *  burst, so a queued speedwalk isn't credited with the replies to its
+     *  earlier steps. */
+    private latencyStartedAt;
     /** 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;
+    /** Whether this socket goes to a telnet proxy rather than to the game. Only
+     *  the wording of a connection error depends on it. */
+    private readonly viaProxy;
     /** 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;
+    /** The proxy reported a completed TLS handshake with the game on this
+     *  socket. Half of {@link gameTransportSecure}. */
+    private tlsEstablishedThisSocket;
+    /** The negotiated `Char.Login` version — `min(client, server)`, learned
+     *  from `Char.Login.Default` and echoed back on every client→server message
+     *  so both ends agree on it even though base GMCP negotiation is
+     *  one-directional. 1 until a server says otherwise, which is also the
+     *  right answer for a version 1 server. Per socket: reset on connect, not on
+     *  each `Char.Login.Default` (Mudlet splits resetForNewConnection and
+     *  resetPerConnectionState the same way). */
+    private charLoginVersion;
+    /** True once `client.established` has been emitted for the current socket —
+     *  the several signals that can prove the game leg is up all funnel through
+     *  {@link markEstablished}, and only the first of them counts. */
+    private gameEstablished;
+    /** Fires while the game has been silent for {@link IDLE_PROBE_MS}; see
+     *  {@link probeIdleConnection}. */
+    private idleProbe;
+    /** `performance.now()` of the last game frame on the current socket. */
+    private lastInboundAt;
+    /** True once the server has sent a telnet command (any IAC) on the current
+     *  socket — only then is an `IAC NOP` probe something it knows to ignore. */
+    private telnetSeen;
     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;
@@ -233,7 +270,7 @@ export declare class MudClient {
     /** 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, osc8HyperlinksEnabled, nawsEnabled, fixUnnecessaryLinebreaks, undoServerWrap, undoServerWrapWidth, inputLineStrictUnixEndings, specialForceGAOff, versionInTTYPE, promptForVersionInTTYPE, promptForMXPProcessorOn, specialForceMXPProcessorOn, subprotocols, }: MudClientOptions, eventBus: EventBus<MudClientEvents>);
+    constructor({ url, mccpEnabled, commandEcho, chunkProcessor, promptTimeoutMs, gmcpEnabled, mttsEnabled, msdpEnabled, msspEnabled, charsetEnabled, mspEnabled, mxpEnabled, mnesEnabled, newEnvironEnabled, screenReaderAdvertised, osc8HyperlinksEnabled, 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
@@ -260,7 +297,7 @@ export declare class MudClient {
     setMccpEnabled(enabled: boolean): void;
     isMccpEnabled(): boolean;
     /** Mudlet `setConfig("fixUnnecessaryLinebreaks", …)`. Takes effect on the
-     *  next GA-driven block; never retroactive. */
+     *  next block that ends in a prompt marker; never retroactive. */
     setFixUnnecessaryLinebreaks(enabled: boolean): void;
     /**
      * Mudlet `setConfig("specialForceGAOff", …)`. Only an UNCONNECTED client
@@ -286,15 +323,59 @@ export declare class MudClient {
     addSupportedTelnetOption(option: number): boolean;
     setPromptTimeoutMs(ms: number): void;
     getPromptTimeoutMs(): number;
+    /** True once the server has sent IAC GA / IAC EOR at least once — Mudlet's
+     *  `cTelnet::mGA_Driver`. Prompt-line triggers only ever fire on a game
+     *  that sends one, so the editor greys the `prompt` pattern type without it
+     *  (dlgTriggerEditor.cpp:7226-7234). */
+    get promptMarkerSeen(): boolean;
     connect(): void;
+    /** Announce that the link to the game itself is up, once per socket —
+     *  Mudlet's `slot_socketConnected`, which is both where it says so
+     *  (`client.connect` → "Open connection made.", sysConnectionEvent) and
+     *  where `mConnectionTimer` starts (`client.established`). */
+    private markEstablished;
+    /** Whether the current socket ever reached the game — false for an attempt
+     *  that failed before connecting (Mudlet's `slot_socketError` case). */
+    get established(): boolean;
     /** 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;
+    /** A disconnect() whose events are still waiting on unwritten output. */
+    private pendingDisconnect;
+    /** The tail of disconnect(), once the socket is really gone. */
+    private finishDisconnect;
+    private armIdleProbe;
+    private stopIdleProbe;
+    /** Make a long-silent connection prove it is still there (issue #454). A
+     *  game host that dies without closing leaves the WebSocket looking healthy
+     *  — through a proxy the browser's leg really is — so nothing ever closes,
+     *  nothing reconnects, and the player's next command goes into the dead
+     *  socket. An `IAC NOP` costs the game nothing (telnet servers discard it),
+     *  but it puts bytes on every leg: a peer that has come back answers them
+     *  with a reset, one that is gone fails their retransmission, and either
+     *  way the socket errors and closes, which is the ordinary disconnect and
+     *  auto-reconnect path. It also keeps a NAT from forgetting a quiet flow.
+     *
+     *  This is the client's own check, for a direct `ws(s)://` endpoint or a
+     *  proxy without TCP keepalive. The bundled proxy keeps that watch on the
+     *  game socket itself (`proxy/gameSocket.ts`) and finds a dead peer in about
+     *  70 s — before this probe's first NOP, which would otherwise hold off its
+     *  keepalive by leaving data unacknowledged. */
+    private probeIdleConnection;
+    /** Raise the disconnect, then hand over the text the final flush left in
+     *  the message buffer. cTelnet raises sysDisconnectionEvent first and only
+     *  then is the unterminated last line printed and its triggers run — a
+     *  `"Server full, bye"` sent without a newline before the close still
+     *  reaches the screen, the buffer and the trigger engine, just after the
+     *  event. Before the notices `client.disconnected` posts, which follow it
+     *  on desktop too. */
+    private emitDisconnect;
     /** Whether MSP is live on this connection (negotiated, not merely allowed
      *  by the profile config) — gates Mudlet's receiveMSP. */
+    isGmcpEnabled(): boolean;
     isMspNegotiated(): boolean;
     /** Qt's QAbstractSocket::UnconnectedState — no socket at all, or one that
      *  has finished closing. CONNECTING/OPEN/CLOSING are all "not unconnected",
@@ -308,10 +389,17 @@ export declare class MudClient {
      *  character-at-a-time detection. Credentials and internal protocol replies
      *  route through here too and must not. */
     send(message: string, isGameCommand?: boolean): void;
+    /** Start timing a command's round trip — only once the server has shown it
+     *  marks prompts (GA/EOR latched), since without a marker there is no
+     *  "reply arrived" to stop at. See {@link latencyStartedAt}. */
+    private beginLatencyMeasurement;
+    /** Stop the clock at the first socket read after a timed command and
+     *  publish the reading (ms) as `network.latency`. */
+    private finishLatencyMeasurement;
     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`
+     *  outbound byte funnels through here, so it's also where `mudlet.debugTelnet`
      *  mirrors what we send. */
     private sendBytes;
     sendGmcp(path: string, payload?: unknown): void;
@@ -319,39 +407,103 @@ export declare class MudClient {
      *  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
+     *  this hello, so without it GMCP effectively does nothing. Every server
+     *  offer (IAC WILL GMCP) is answered with it, as Mudlet does: a server that
+     *  turned GMCP off and on again — copyover, reboot — has dropped the module
+     *  list and would otherwise never send another packet. A server's IAC DO
+     *  GMCP is answered with WILL alone, as Mudlet does — the handshake waits
+     *  for the server's own offer (mudlet-web#362). 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. */
+    /**
+     * Whether the link to the *game* is encrypted — Mudlet's
+     * `cTelnet::currentlySecure()`, and the gate on every `Char.Login` bearer
+     * secret. Not "is the WebSocket wss:": in proxy mode a `wss://` proxy URL
+     * only secures the browser↔proxy hop, and the proxy↔game leg is plaintext
+     * telnet unless the proxy reports a completed TLS handshake with the game.
+     * A direct websocket connection is the game, so its scheme is the answer.
+     */
+    get gameTransportSecure(): boolean;
+    /** The `Char.Login` version negotiated on this socket. */
+    get negotiatedCharLoginVersion(): number;
+    /** Route GMCP `Char.Login.*` messages. The server sends `Char.Login.Default`
+     *  to request login and then *waits* for the client to answer — withholding
+     *  its 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`). Each message is parsed here and surfaced as a
+     *  `charLogin.*` event; `CharLoginController` decides what to answer. Path
+     *  match is case-insensitive — GMCP module casing varies between servers.
+     *
+     *  `Char.Login.Token` carries a bearer token that signs the profile in
+     *  without a password. It is never logged — a malformed frame reports
+     *  nothing of its body. It does still reach the Lua `gmcp` table like any
+     *  other message, as it does in Mudlet (cTelnet calls setGMCPTable for
+     *  Char.Login too); profile scripts already run with full access to this
+     *  profile. JS strings are immutable and garbage-collected, so Mudlet's
+     *  SecureStringUtils scrubbing has no equivalent here. */
     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;
+    /** The two fields every client→server `Char.Login` message may carry: the
+     *  negotiated version we are acting on, and `token_storage` — whether a
+     *  reconnect token minted on this connection would actually be kept. A
+     *  version 1 server gets them too: an unknown member is inert to it. */
+    private charLoginCommonFields;
+    /**
+     * Send `Char.Login.Credentials`. With an account, `{account, password}`
+     * (account may be `"account:character"` on games with both) plus the common
+     * fields. Without one it is the hand-off: from version 2 the message with no
+     * account — carrying `token_storage` is the point, since it reaches the game
+     * before it writes its sign-in screen, the last moment it can decide whether
+     * to offer to remember the player — and on version 1 the bare `{}` Mudlet
+     * has always sent such servers. Mudlet Web never stores the password here;
+     * it only relays it.
+     */
+    sendCharLoginCredentials(account?: string, password?: string, tokenStorage?: boolean): void;
+    /**
+     * Replay a saved password-less sign-in — `Char.Login.Reconnect`. Returns
+     * false when it refused: a token the issuing server scoped to an encrypted
+     * transport (`secureOnly`) never goes out in the clear. Re-checked here, at
+     * send time, as well as in the decision, in case the transport changed.
+     */
+    sendCharLoginReconnect(account: string, token: string, secureOnly: boolean, tokenStorage?: boolean): boolean;
+    /** Ask the game to restart a provider's browser sign-in — the *resume* form
+     *  of `Char.Login.Credentials`, `{account, provider}` and no password. */
+    sendCharLoginResume(account: string, provider: string, tokenStorage?: boolean): void;
+    /**
+     * Complete a client-driven OAuth sign-in — `Char.Login.AuthCode`. Returns
+     * false when it refused: the standard forbids it on a cleartext connection,
+     * since the code and PKCE verifier together let an eavesdropper redeem the
+     * code at the provider.
+     */
+    sendCharLoginAuthCode(auth: {
+        code: string;
+        codeVerifier: string;
+        redirectUri: string;
+        nonce?: string;
+    }, tokenStorage?: boolean): boolean;
     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. */
+     *  when ATCP isn't negotiated or 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. */
+     *  (the zMUD generic out-of-band channel) and sends it raw. False only
+     *  when the server has not enabled the channel: Mudlet gates on that
+     *  alone and reports success whatever the socket then does with the
+     *  bytes, so a script is told about the option and not the connection. */
     sendTelnetChannel102(msg: string): boolean;
+    /** An `IAC SB 102 <var> <value> IAC SE` body: the option byte, then the
+     *  two payload bytes Aardwolf's channel carries. Mudlet reads them as
+     *  numbers (`setChannel102Variables`) and ignores anything shorter. */
+    private handleChannel102Subneg;
+    /** An `IAC SB ATCP <message> IAC SE` body — Mudlet's ATCP branch of
+     *  `processTelnetCommand`. The message, decoded under the server encoding,
+     *  becomes one `atcp` table entry and event (`setATCPVariables`); an empty
+     *  one is ignored. `Auth.Request` is then answered with the hello. Like
+     *  desktop, neither depends on ATCP having been negotiated. */
+    private handleAtcpSubneg;
     /** 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
@@ -364,8 +516,23 @@ export declare class MudClient {
     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. */
+     *  current encoding untouched — when the name isn't one we can decode.
+     *
+     *  Asked for while a read's text is being decoded — by one of its
+     *  triggers — the switch waits for the next text to be decoded: TBuffer
+     *  reads cTelnet's encoding once, at the start of each translateToPlainText,
+     *  so the rest of the read keeps the encoding it arrived in. That next text
+     *  is the next read, or a feed the trigger makes of its own
+     *  ({@link adoptPendingEncoding}), which then applies to the rest of the
+     *  read as well. */
     setServerEncoding(name: string): boolean;
+    /** Apply a setServerEncoding() a trigger made part way through a read —
+     *  where TBuffer::translateToPlainText would next read the encoding. */
+    adoptPendingEncoding(): void;
+    /** True while a read's text is decoded and handed to its triggers. */
+    private decodingRead;
+    /** An encoding a trigger switched to while {@link decodingRead}. */
+    private pendingEncoding;
     /** 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. */
@@ -373,18 +540,89 @@ export declare class MudClient {
     /** 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;
+    /** Report the main console's wrap column (Mudlet's `Host::mWrapAt`, 0 for
+     *  off), which caps the NAWS width and is the NEW-ENVIRON WORD_WRAP. */
+    setWrapAt(wrapAt: number): void;
+    /** Report whether the main console draws its timestamp gutter, which comes
+     *  off the NAWS width as on desktop. */
+    setTimestampsShown(shown: boolean): 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;
+    /** Apply changed profile protocol toggles to the live connection. Only
+     *  the ones the negotiator reads: the rest of MudClientOptions is either
+     *  fixed at dial time (the URL, the subprotocols) or owned by a handler
+     *  with a setter of its own (MCCP). */
+    setProtocolFlags(flags: Partial<TelnetNegotiatorFlags>): void;
     /** 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;
+    /** A chunk of a replay. A replay holds what the game sent after
+     *  decompression, and desktop plays it back through a parser of its own
+     *  (cTelnet::slot_processReplayChunk) that knows nothing of MCCP, so
+     *  unlike {@link feedTelnet} this skips it. */
+    feedReplay(data: string): void;
+    /** One read from the game, or bytes injected as if they were one: split
+     *  where compression starts or ends, and each piece run through the
+     *  pipeline on its own. Desktop processes the plain text before an MCCP
+     *  start (gotRest) before it inflates anything, and the inflated text
+     *  before what follows the end of the stream, so a trigger on the last
+     *  line of one part never sees GMCP from the next (mudlet-web#384). The
+     *  MCCP warnings desktop posts while inflating land between the pieces,
+     *  where it posts them. Synchronous: the whole read is through when this
+     *  returns. Socket reads go through {@link pumpInbound} instead. */
+    private ingest;
+    private readonly inbound;
+    /** A slice is running: a drain from inside one (a trigger calling
+     *  disconnect(), say) leaves the rest of the read to the slices. */
+    private inboundRunning;
+    private inboundScheduled;
+    /** Run a slice of the queued socket reads, and book the next if any are
+     *  left. */
+    private pumpInbound;
+    /** Run every queued socket read now, unless a slice is already running. */
+    private drainInbound;
+    /** Forget the queued reads not yet begun, when a trigger in a slice lets
+     *  go of the socket: their onmessage would have found its handler gone.
+     *  The rest of the read the trigger is in carries on, as it always has. */
+    private dropQueuedReads;
+    /** Take reads off the head of `queue` and through the pipeline. In a
+     *  `slice`, text goes in INBOUND_SLICE_LINES lines at a time, and this
+     *  returns false — the rest still queued — once the slice's time is up
+     *  and the stream is at a clean break. */
+    private runInbound;
     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;
+    /** `receivedAt` (`performance.now()`) is given only for bytes read off the
+     *  socket, so injected ones (feedTelnet, replay) never stop the latency
+     *  clock. */
     private processIncomingData;
+    /** Negotiate, strip, decode and assemble one run of a frame. `hasPrompt`
+     *  means the run ends in an IAC GA/EOR. */
+    private processSegment;
+    private decodeAndAssemble;
     flushMessageBuffer(): void;
 }
+/** How long the game may stay silent before the client probes the connection
+ *  with an `IAC NOP` (and again each time as long again passes). Past the
+ *  ~70 s the bundled proxy's keepalive takes, so the two don't overlap. */
+export declare const IDLE_PROBE_MS = 120000;
+/**
+ * What to tell the user about a socket that closed.
+ *
+ * `viaProxy` distinguishes the two very different things a close can mean. In
+ * proxy mode the socket is to the proxy, so "the proxy refused it" is a real
+ * possibility; in websocket mode no proxy is involved at all, and blaming one
+ * sent people to check infrastructure that was not in the path (issue #56).
+ *
+ * A connect that never opened also gets the advice Mudlet gives, because the
+ * cause is not decidable from here: a Cloudflare-Worker proxy reports the same
+ * "cannot connect to the specified address" for a hostname that does not
+ * resolve and for a port with nothing listening, and `connect()` exposes
+ * nothing finer. Naming both possibilities beats implying one.
+ */
+export declare function formatCloseError(event: CloseEvent, wasOpened: boolean, viaProxy: boolean): string;

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

@@ -0,0 +1,24 @@
+/**
+ * Closes a subnegotiation that runs into the next telnet command without its
+ * IAC SE, the way Mudlet's `cTelnet::processSocketData` recovers one (#4385):
+ * inside IAC SB, an IAC followed by anything but SE or a second IAC cannot be
+ * part of the payload, so the SE is taken to have gone missing. The
+ * subnegotiation is ended there and the IAC starts the next command.
+ *
+ * Done once, on the byte stream every inbound parser reads (the negotiator, the
+ * ECHO scan, the option parser), by writing the missing SE back in — so they
+ * all agree on where the subnegotiation ended, rather than one acting on the
+ * command and another swallowing it into a payload. Stateful across frames: an
+ * SB, or the IAC deciding it, can be split between two reads, and an IAC at the
+ * end of a frame is passed on as it is, since the SE that may follow it goes
+ * after it either way.
+ */
+export declare class SubnegotiationRepair {
+    private inSb;
+    private iac;
+    private warned;
+    reset(): void;
+    /** `data` is a Latin-1 byte-string; returns it with any missing IAC SE
+     *  written back in. */
+    process(data: string): string;
+}