@mudlet/mudlet-web 0.4.0 → 0.4.2

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/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/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 {
@@ -72,12 +79,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/ui/sound/SoundManager.d.ts

@@ -1,4 +1,4 @@
-import type { MediaCaptionInfo } from './closedCaption';
+import type { MediaCaptionInfo, MediaKind } from './closedCaption';
 type LoaderFn = (path: string) => Promise<ArrayBuffer | null>;
 /** Which mute gate a playback belongs to. `api` = triggered by a Lua script
  *  (playSoundFile / playMusicFile); `game` = triggered by the server (MSP, and
@@ -54,13 +54,25 @@ export declare class SoundManager {
      * tearing them down.
      */
     private muted;
+    /**
+     * Raised when a tracked source starts playing. ScriptingEngine wires this
+     * to Mudlet's `sysMediaStarted(file, path, mediaType, key, tag)` — the same
+     * five arguments TMedia.cpp appends when a player reaches PlayingState.
+     *
+     * Fired after `source.start()` has actually been accepted, so a decode
+     * failure or a rejected start never announces a playback that isn't
+     * happening. Mudlet withholds it for preload-volume loads; mudix has no
+     * preload volume (`preload()` only warms the decode cache and never builds
+     * a source), so there is nothing to withhold it for.
+     */
+    onMediaStarted?: (file: string, path: string, mediaType: MediaKind, key: string, tag: string) => void;
     /**
      * Raised when a tracked source ends — whether it played out naturally or
      * was stopped. ScriptingEngine wires this to raise Mudlet's
-     * `sysMediaFinished(name, path)`. `stopAll()` nulls each source's onended
-     * before stopping, so engine teardown never fires it.
+     * `sysMediaFinished(file, path, mediaType, key, tag)`. `stopAll()` nulls
+     * each source's onended before stopping, so engine teardown never fires it.
      */
-    onMediaFinished?: (name: string, path: string) => void;
+    onMediaFinished?: (file: string, path: string, mediaType: MediaKind, key: string, tag: string) => void;
     /**
      * Raised when a tracked source starts ('plays') or ends ('stops'), so the
      * engine can print a closed caption (Mudlet's enableClosedCaption). Fires

package/dist-lib/ui/video/VideoManager.d.ts

@@ -33,9 +33,14 @@ export declare class VideoManager {
      * still reports what the script asked for.
      */
     private muted;
+    /** Fires once the element has actually begun playing — mirrors Mudlet's
+     *  sysMediaStarted. Deliberately after `el.play()` resolves rather than
+     *  beside the caption below it: autoplay policy can reject the play, and an
+     *  event announcing a playback that never started is worse than none. */
+    onStarted: ((file: string, path: string) => void) | null;
     /** Fires when a video ends naturally or is stopped — mirrors Mudlet's
      *  sysMediaFinished. */
-    onEnded: ((name: string, path: string) => void) | null;
+    onEnded: ((file: string, path: string) => void) | null;
     /** Raised when a video starts ('plays') or finishes ('stops') so the engine
      *  can print a closed caption (Mudlet's enableClosedCaption). */
     onMediaCaption: ((info: MediaCaptionInfo) => void) | null;

package/dist-lib/utils/githubRawUrl.d.ts

@@ -0,0 +1 @@
+export declare function githubRawUrl(url: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mudlet/mudlet-web",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "type": "module",
   "description": "Mudlet Web — Mudlet in the browser, usable standalone or as a library for branded builds",
   "license": "GPL-2.0-or-later",