@mudlet/mudlet-web 0.4.1 → 0.4.3

package/dist-lib/map/xmlMapImport.d.ts

@@ -20,9 +20,38 @@
  *   </map>
  */
 import type { MudletMap } from 'mudlet-map-binary-reader';
+/**
+ * Why a document was refused. Mudlet keeps these three apart
+ * (`fileHoldsMapData` in `TMap.cpp`), because they are three different things
+ * to tell a player:
+ *
+ *   `not-a-map`     somebody else's well-formed document — a game's "no map
+ *                   here" page answered with a 200, or a `<MudletPackage>`.
+ *                   Every element parses and none of it means anything, which
+ *                   is what used to count as importing a map successfully.
+ *   `import-failed` a map document that would not parse: the player's own map,
+ *                   damaged. Rooted at `<map>`, so the root test passes and the
+ *                   failure is further in.
+ *   `damaged`       not XML at all — no element to read a root from.
+ *
+ * The root is taken from the first start tag in the text rather than from a
+ * parsed document, exactly as Mudlet's streaming reader does, so a file that is
+ * rooted at `<map>` but truncated is still recognised as a map that broke.
+ */
+export type XmlMapRefusal = 'not-a-map' | 'import-failed' | 'damaged';
+export type XmlMapParse = {
+    ok: true;
+    map: MudletMap;
+} | {
+    ok: false;
+    reason: XmlMapRefusal;
+};
 /**
  * Parse an XML map document into the `MudletMap` shape `loadFromBinary`
  * ingests. Returns null when the text isn't well-formed XML or the root
  * element isn't `<map>` (e.g. an HTML error page served for the map URL).
+ * {@link parseXmlMapResult} is the same parse with the refusal reason kept.
  */
 export declare function parseXmlMap(xmlText: string): MudletMap | null;
+/** {@link parseXmlMap}, reporting *why* a document was refused. */
+export declare function parseXmlMapResult(xmlText: string): XmlMapParse;

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

@@ -316,6 +316,7 @@ export declare class MudSession {
         newEnvironEnabled?: boolean;
         secureTransport?: boolean;
         screenReaderAdvertised?: boolean;
+        osc8HyperlinksEnabled?: boolean;
         nawsEnabled?: boolean;
         subprotocols?: string[];
     }): void;

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

@@ -75,6 +75,11 @@ export interface MudClientOptions {
      *  READER bit and the NEW-ENVIRON `SCREEN_READER` capability
      *  (`setConfig("advertiseScreenReader", …)`). Default false. */
     screenReaderAdvertised?: boolean;
+    /** Whether OSC 8 hyperlinks are enabled for this profile (Mudlet 5.0's
+     *  `mEnableOSC8Hyperlinks`). Reported as the `OSC_HYPERLINKS_*` NEW-ENVIRON
+     *  capability block — all "0" when off. Default true. The rendering half of
+     *  the toggle lives in the ANSI parser, not here. */
+    osc8HyperlinksEnabled?: 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
@@ -228,7 +233,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, 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, secureTransport, 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

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

@@ -11,6 +11,12 @@ export declare class PingTracker {
     private lastSentAt;
     private lastDuration;
     private supported;
+    /** The responsiveness beat, live only while a ping is outstanding. */
+    private beatTimer;
+    private lastBeatAt;
+    /** Longest interval the event loop went undelivered during the current
+     *  wait — see {@link MAX_BEAT_GAP_MS}. */
+    private worstBeatGapMs;
     private readonly unsubs;
     constructor(sendPingCommand: (latencyMs: number) => void, onPing: (duration: number | null) => void, source: PingEventSource);
     destroy(): void;
@@ -24,5 +30,12 @@ export declare class PingTracker {
      *  `Core.Ping` makes servers that unconditionally JSON-parse the part after
      *  the module name choke on an empty string. */
     private sendPing;
+    /** Begin witnessing the event loop for the wait that starts now. */
+    private startBeat;
+    private recordBeatGap;
+    /** Stop the beat and answer the worst gap it saw, counting the stretch
+     *  between the final beat and now — a stall that began after the last beat
+     *  and ran until the reply is still a stall the reading spans. */
+    private stopBeat;
     private handlePingResponse;
 }

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

@@ -18,6 +18,12 @@ 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 OSC 8 hyperlinks are enabled for this profile — Mudlet 5.0's
+     *  `mEnableOSC8Hyperlinks`. Drives only the `OSC_HYPERLINKS_*` NEW-ENVIRON
+     *  capability block here; the rendering side of the same toggle is a gate in
+     *  the ANSI parser (see hyperlinkConfig's setOsc8HyperlinksEnabled). Default
+     *  true, matching Mudlet. */
+    osc8HyperlinksEnabled: 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

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

@@ -0,0 +1,33 @@
+/**
+ * Transcoding between the wire and JS strings, for the protocol handlers that
+ * carry UTF-8 text inside a telnet subnegotiation (GMCP, MSDP, MSSP).
+ *
+ * Everything upstream of these speaks *byte-strings*: `bytesToLatin1` in
+ * `MudClient.ts` maps each socket byte to one char, and the client's `sendBytes`
+ * reverses it with `charCodeAt(i) & 0xff`. Subnegotiations are extracted from that byte-string
+ * before the session codec ever runs (`stripTelnetSequences` precedes
+ * `codec.decode`), which is what makes these three protocols independent of the
+ * session's text encoding — and what obliges each of them to do its own
+ * transcoding here.
+ */
+export interface DecodedByteString {
+    text: string;
+    /** The bytes weren't valid UTF-8, so `text` contains U+FFFD where they were.
+     *  Callers that can report it should; nothing downstream is able to notice,
+     *  since the substitution is indistinguishable from a legitimate U+FFFD. */
+    malformed: boolean;
+}
+/** Decode a Latin-1 byte-string (one char per byte, as produced upstream) as
+ *  UTF-8. Decoding is lenient by design — a replacement character in one field
+ *  beats dropping the whole message — but a strict pass runs first so the
+ *  caller can tell the two apart and say so. */
+export declare const fromByteString: (s: string) => DecodedByteString;
+/** UTF-8-encode into a Latin-1 byte-string, for `MudClient.sendBytes`. Inverse
+ *  of {@link fromByteString} for well-formed input only — both directions are
+ *  non-fatal, so invalid UTF-8 inbound and lone surrogates outbound each
+ *  collapse to U+FFFD rather than round-tripping. Plain ASCII is unchanged. */
+export declare const toByteString: (s: string) => string;
+/** Render a byte-string as hex, for diagnostics that would otherwise print the
+ *  post-decode text — where every malformed sequence has already collapsed to
+ *  an indistinguishable U+FFFD. Truncated: the head is where the fault is. */
+export declare const toHex: (s: string) => string;

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

@@ -3,9 +3,6 @@ export interface GmcpEnvelope {
     value: unknown;
 }
 export type TelnetOptionHandler = (data: string) => string;
-/** 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
@@ -21,10 +18,18 @@ export declare const encodeGmcp: (path: string, payload: unknown) => string;
 /** Encode a GMCP frame from a single pre-formatted body (e.g. `"Module.Sub args"`).
  *  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. */
+ *  the session's outgoing encoding, so a JS caller can't use it to place arbitrary
+ *  raw bytes on the wire: `U+00FF` goes out as `c3 bf`, not as `ff`. 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.
+ *
+ *  From Lua the same limit holds, but it isn't this call that imposes it — the
+ *  bytes are gone a layer earlier. wasmoon marshals Lua→JS strings through
+ *  `UTF8ToString`, which UTF-8-*decodes* them, so `"\1\200"` reaches `sendGMCP`
+ *  as `U+0001 U+0200` and `"\1\255"` as a lone surrogate. Re-encoding here
+ *  restores the caller's original Lua bytes rather than destroying them.
+ *  Carrying genuinely arbitrary bytes across that bridge needs numbers, or the
+ *  `%XX` armoring the VFS io path uses. */
 export declare const encodeGmcpRaw: (message: string) => string;
 export interface GmcpStreamOptions {
     onEnvelope: (payload: GmcpEnvelope) => void;

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

@@ -2,10 +2,11 @@ export * from "./constants";
 export * from "./gmcp";
 export * from "./msdp";
 export * from "./mssp";
+export { toByteString } from "./byteString";
 export { MccpHandler } from "./mccp";
 export { EchoHandler } from "./echo";
 export { MspParser, type MspCommand, type MspKind } from "./msp";
 export { MxpParser, splitMxpResultLines, type MxpLink, type MxpLineResult } from "./mxp";
-export { parseMnesRequest, encodeMnesIs, selectMnesVars, buildNewEnvironVars, CLIENT_NAME, CLIENT_VERSION, TERMINAL_TYPE, type MnesVar, type MnesRequest, type NewEnvironState } from "./mnes";
+export { parseMnesRequest, encodeMnesIs, selectMnesVars, MNES_UNMAINTAINED, 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, DEFAULT_SERVER_ENCODING, canonicalServerEncoding, canEncodeForServer, type CharsetHandlerHooks } from "./charset";

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

@@ -1,9 +1,16 @@
 import { CLIENT_NAME, CLIENT_VERSION, TERMINAL_TYPE } from "../../version";
 /** A single MNES variable the client reports back, e.g. `{ name: "CHARSET",
- *  value: "UTF-8" }`. */
+ *  value: "UTF-8" }`.
+ *
+ *  A null `value` means **undefined** rather than empty. RFC 1572 draws the
+ *  distinction structurally: a name followed by VALUE is defined (and, with
+ *  nothing after the VALUE, defined-but-empty), while a name followed by the
+ *  next marker or IAC with no VALUE at all is undefined. That is how a variable
+ *  the client deliberately does not supply is answered — see
+ *  {@link MNES_UNMAINTAINED}. */
 export interface MnesVar {
     name: string;
-    value: string;
+    value: string | null;
 }
 /** Result of parsing an `IAC SB NEW-ENVIRON SEND … IAC SE` request body. */
 export interface MnesRequest {
@@ -53,6 +60,12 @@ export interface NewEnvironState {
      *  bit, NEW-ENVIRON SCREEN_READER var) — `setConfig("advertiseScreenReader", …)`.
      *  Defaults to false (matching Mudlet's opt-in behaviour). */
     screenReader?: boolean;
+    /** Whether OSC 8 hyperlinks are enabled for this profile (Mudlet 5.0's
+     *  `Host::mEnableOSC8Hyperlinks`). Every `OSC_HYPERLINKS_*` capability
+     *  reports "0" while it is off, exactly as Mudlet's
+     *  `cTelnet::getNewEnvironOSCHyperlinks*` do — a server that would light up
+     *  its links for us must be told we won't render them. Defaults to true. */
+    osc8Hyperlinks?: boolean;
 }
 /** The five core variables MNES standardises (https://tintin.mudhalla.net/protocols/mnes/).
  *  Plain NEW-ENVIRON reports these too, plus the extended capability set below.
@@ -72,12 +85,28 @@ export { CLIENT_NAME, CLIENT_VERSION, TERMINAL_TYPE };
  * the result with VAR (MNES) or USERVAR (NEW-ENVIRON) via encodeMnesIs.
  */
 export declare function buildNewEnvironVars(state: NewEnvironState, extended: boolean): MnesVar[];
+/** MNES names the standard defines that mudix deliberately does not supply.
+ *  They are still *known*, so a server that asks for one is told it is
+ *  undefined rather than left with silence — Mudlet's `isMNESVariable` lists
+ *  IPADDRESS alongside the five it reports, and answers it with a name and no
+ *  VALUE. (A browser tab has no way to learn its own address, and the client is
+ *  not the right party to guess: the server already sees the peer address.) */
+export declare const MNES_UNMAINTAINED: ReadonlyArray<string>;
 /**
- * Pick which of the client's `available` MNES variables to report in response
- * to a parsed request. A bare SEND (no specific names) returns everything;
- * otherwise the requested names are returned in request order, filtered to the
- * ones we actually know. If the server asked only for names we don't report,
- * we fall back to sending everything rather than an empty reply — the server
- * still learns who we are.
+ * Pick which of the client's `available` variables to report in response to a
+ * parsed request, mirroring Mudlet's `sendIsMNESValues` /
+ * `sendIsNewEnvironValues`:
+ *
+ *   - A bare SEND (no names) asks for everything, and gets it.
+ *   - Named variables come back in request order, each either with its value or
+ *     — for a name in `undefinedNames` — as undefined (no VALUE).
+ *   - A name that is neither is left out entirely.
+ *
+ * A request naming only names we do not report therefore selects **nothing**.
+ * It used to fall back to sending everything on the reasoning that the server
+ * still learns who we are, but that answers a question nobody asked: a server
+ * probing for one specific variable gets an unsolicited dump of the whole set,
+ * which is not what Mudlet does and not what the request meant. The caller
+ * decides what an empty selection is framed as.
  */
-export declare function selectMnesVars(request: MnesRequest, available: ReadonlyArray<MnesVar>): MnesVar[];
+export declare function selectMnesVars(request: MnesRequest, available: ReadonlyArray<MnesVar>, undefinedNames?: ReadonlyArray<string>): MnesVar[];

package/dist-lib/mud/text/hyperlinkConfig.d.ts

@@ -128,6 +128,10 @@ interface ExtractedQuery {
  * Mudlet's hand-rolled scan; everything else is `&`-delimited `key=value`.
  */
 export declare function extractQuery(uri: string): ExtractedQuery;
+/** Enable/disable OSC 8 hyperlink parsing (Mudlet `mEnableOSC8Hyperlinks`). */
+export declare function setOsc8HyperlinksEnabled(enabled: boolean): void;
+/** Whether OSC 8 hyperlinks are currently honoured. */
+export declare function isOsc8HyperlinksEnabled(): boolean;
 /** Session-scoped store of `preset:NAME` definitions. Holds raw config objects
  *  (shorthand un-expanded, as Mudlet does) so a later `?preset=NAME` can deep-
  *  merge an override before expansion. */

package/dist-lib/scripting/ScriptingAPI.d.ts

@@ -41,6 +41,10 @@ declare class ScriptingWindowsAPI {
     isMiniConsole(id: string): boolean;
     move(id: string, x: number, y: number): void;
     setParent(id: string, parent?: string): boolean;
+    /** Re-applies a docking area to a window that is already open — Mudlet's
+     *  Host::openWindow honours the `area` argument on every call, not just
+     *  the one that creates the dock widget. 'main' means floating. */
+    setDockArea(id: string, area: string): void;
     bringToFront(id: string): void;
     sendToBack(id: string): void;
     resize(id: string, width: number, height: number): void;

package/dist-lib/scripting/lua/bindings/commandLine.d.ts

@@ -8,4 +8,4 @@ import type { BindingContext } from './context';
  * user window's embedded input, and a free-floating createCommandLine widget -
  * which cmdLineKind below resolves from the name Lua passed.
  */
-export declare function installCommandLineBindings({ lua, api, channel, emitEvent }: BindingContext): void;
+export declare function installCommandLineBindings({ lua, api, emitEvent }: BindingContext): void;

package/dist-lib/scripting/lua/bindings/output.d.ts

@@ -7,4 +7,4 @@ import type { BindingContext } from './context';
  * Colour channels are validated through the shared 0..255 coercion; Mudlet
  * silently no-ops on an out-of-range channel rather than raising.
  */
-export declare function installOutputBindings({ lua, api, channel }: BindingContext): void;
+export declare function installOutputBindings({ lua, api }: BindingContext): void;

package/dist-lib/storage/schema.d.ts

@@ -210,6 +210,27 @@ export interface ProfileSettings {
      *  (reset). When disabled, those sequences are ignored and the user palette
      *  stands. Off by default — only an explicit `true` enables it. */
     serverRedefineColors?: boolean;
+    /** Mudlet 5.0's `Host::mEnableOSC8Hyperlinks` ("Enable OSC 8 hyperlinks").
+     *  When disabled, an OSC 8 sequence that *opens* a link is ignored so the
+     *  text renders plain, and the whole `OSC_HYPERLINKS_*` NEW-ENVIRON
+     *  capability block reports "0" — the two things Mudlet's toggle drives
+     *  (TBuffer::decodeOSC and cTelnet::getNewEnvironOSCHyperlinks*). A
+     *  *closing* sequence is always honoured, or a link open when the toggle
+     *  flipped would never end. On by default: only an explicit `false`
+     *  disables it, matching Mudlet's `= true` default. Unlike most of these,
+     *  Mudlet exposes no `setConfig` key for it — preferences and the profile
+     *  XML only — so mudix doesn't invent one either. */
+    osc8Hyperlinks?: boolean;
+    /** Mudlet 5.0's `Host::mUndoServerWrap` ("Undo the game's own wrapping",
+     *  experimental). Rejoins the lines a game hard-wrapped itself before
+     *  triggers see them, so a pattern can't be split mid-sentence; the client's
+     *  own wrap then applies for display. Off by default. Also readable and
+     *  writable from Lua as `getConfig`/`setConfig("undoServerWrap", …)`. */
+    undoServerWrap?: boolean;
+    /** The column the game wraps at, for {@link undoServerWrap} — Mudlet's
+     *  `mUndoServerWrapWidth`, bounded 20–500 and defaulting to 80 (very often
+     *  the right answer). `setConfig("undoServerWrapWidth", …)`. */
+    undoServerWrapWidth?: number;
     /** Mudlet "Network packet timeout": how long (ms) to buffer a partial line
      *  (text after the last `\n` of a WebSocket frame) before flushing it as a
      *  prompt. Mitigates spurious mid-line breaks when long MUD lines arrive