@mudlet/mudlet-web 0.3.0

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

@@ -0,0 +1,90 @@
+import type { MapReader, IArea, IMapReader, ViewportBounds, ViewportDataSource, HashLookupCapable } from 'mudlet-map-renderer';
+import type { MapStore } from './MapStore';
+type RoomShape = ReturnType<MapReader['getRoom']>;
+/**
+ * Live {@link IMapReader} backed by Mudix's {@link MapStore}.
+ *
+ * The renderer is constructed once on panel mount and held for the lifetime of
+ * the panel. Whenever the store mutates (script-built rooms, binary load,
+ * setRoomCoordinates, …) the panel calls {@link refresh}; this rebuilds the
+ * inner reader from the store's current snapshot. The renderer's `MapState`
+ * notices the new `IArea` instance via reference inequality and rebuilds the
+ * scene — no Konva stage / event listener teardown.
+ *
+ * The inner reader is a {@link SkeletonMapReader}: rooms live in compact
+ * typed-array columns and are materialised per viewport, instead of the
+ * concrete `MapReader`'s full object graph. Nothing is dropped — the skeleton
+ * is built from the complete map and keeps every room, with rooms carrying
+ * visual detail (symbols, custom lines, special exits, doors, stubs, exit
+ * locks) materialised in full — it only changes how the *renderer* holds them.
+ * That matters because the concrete reader's costs scale with the whole plane
+ * rather than what's on screen: on a 250k-room map, constructing it took ~7s
+ * and the first scene build ~9s, all synchronous on the main thread.
+ *
+ * Being a {@link ViewportDataSource} is what unlocks that: the interactive
+ * backend pushes padded camera bounds before every scene build and only
+ * rebuilds when the camera leaves the padding. The capability is detected by
+ * duck-typing (`viewportAware === true`), so this wrapper has to re-declare it
+ * and forward — a plain `IMapReader` facade would silently opt out of the
+ * virtualization and fall back to materialising everything.
+ *
+ * The renderer's wire format (`{mapData, colors}`) is produced via
+ * `readerExport(store.toMudletMap())` — the same transformation Mudlet's own
+ * binary-reader pipeline applies. Doing it inside the reader (instead of in
+ * the panel) keeps `MapPanel` pure-view: it never sees the wire format.
+ */
+export declare class MudixMapReader implements IMapReader, ViewportDataSource, HashLookupCapable {
+    private readonly store;
+    readonly viewportAware: true;
+    readonly hashLookupCapable: true;
+    private inner;
+    private snapshotVersion;
+    /** Last viewport the renderer pushed. Held here because a store-driven
+     *  rebuild replaces the inner reader, and a fresh one defaults to
+     *  unbounded — re-applying keeps the next scene build scoped to where the
+     *  camera actually is instead of materialising the whole plane once. */
+    private viewport;
+    constructor(store: MapStore);
+    /** Rebuild the inner reader from MapStore's current snapshot. Safe to
+     *  call from a store-change subscriber — cheap when the store is empty
+     *  and idempotent when no mutation has happened since the last refresh. */
+    refresh(): void;
+    /**
+     * Stale-check before every public read. The renderer can ask for a room
+     * synchronously after a script mutation (e.g. addRoom → centerview),
+     * before MapStore's microtask-delayed notify fires. Running the version
+     * check on every call is O(1); a real rebuild only happens when the
+     * store has actually mutated since the last snapshot.
+     */
+    private ensureFresh;
+    /** True once the store has at least one room; the panel's empty-state
+     *  overlay stays up until this flips. */
+    hasData(): boolean;
+    private buildInner;
+    getArea(areaId: number): IArea;
+    getAreas(): IArea[];
+    /** Note: a viewport-virtualized reader deliberately returns an empty list
+     *  here rather than materialising every room — callers that want rooms go
+     *  through a plane (which is viewport-scoped) or {@link getRoom} by id. */
+    getRooms(): RoomShape[];
+    getRoom(roomId: number): RoomShape;
+    getColorValue(envId: number): string;
+    getSymbolColor(envId: number, opacity?: number): string;
+    setViewport(bounds: ViewportBounds): void;
+    getViewport(): ViewportBounds;
+    getPlaneRoomCount(areaId: number, z: number): number;
+    estimateVisibleCount(areaId: number, z: number, bounds: ViewportBounds): number;
+    forEachInBounds(areaId: number, z: number, bounds: ViewportBounds, fn: (x: number, y: number, envId: number) => void): void;
+    /** O(1) hash → id. Needed because `getRooms()` is empty on a virtualized
+     *  reader, so the scan-based fallback the renderer would otherwise use can
+     *  never resolve anything. */
+    getRoomIdByHash(hash: string): number | undefined;
+    /**
+     * Drop any viewport narrowing, so subsequent reads materialise the whole
+     * map again. The export path needs this: an exporter driven by a reader
+     * still scoped to the on-screen camera would silently render only the
+     * rooms that happen to be visible.
+     */
+    clearViewport(): void;
+}
+export {};

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

@@ -0,0 +1,18 @@
+import type { MapState, SceneOverlay, SceneOverlayContext, Shape, ViewportBounds } from 'mudlet-map-renderer';
+import type { MapStore } from './MapStore';
+import type { MudixMapReader } from './MudixMapReader';
+export declare class MudletHighlightOverlay implements SceneOverlay {
+    private readonly mapStore;
+    private readonly reader;
+    private ctx?;
+    private mapStoreUnsub?;
+    private areaHandler?;
+    constructor(mapStore: MapStore, reader: MudixMapReader);
+    attach(ctx: SceneOverlayContext): void;
+    detach(): void;
+    /** Force a re-render from outside. The renderer's `refresh()` doesn't
+     *  emit any state event we listen to, but a change to settings.roomSize
+     *  moves every highlight circle's radius. */
+    refresh(): void;
+    render(state: MapState, _bounds: ViewportBounds): Shape[] | void;
+}

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

@@ -0,0 +1,26 @@
+import type { Settings as MapRendererSettings } from 'mudlet-map-renderer';
+import type { MapStore } from './MapStore';
+import type { MapperSettings } from '../storage';
+/**
+ * Copy user-set fields from MapperSettings onto a live renderer settings
+ * object. Anything left undefined in `mapper` is intentionally not touched
+ * so the renderer's own createSettings() defaults stay in effect.
+ */
+export declare function applyMapperSettings(target: MapRendererSettings, mapper: MapperSettings | undefined): void;
+/**
+ * Mudlet `exportAreaImage` — render one area (optionally a single z-level) to
+ * PNG bytes. Returns null when the area is unknown or the render fails.
+ *
+ * Deliberately standalone: the export builds its own reader, settings and
+ * off-screen container, so it never touches — or needs — a mounted map panel.
+ * The live panel's reader is scoped to the camera's viewport (that is what
+ * keeps big maps fast), so an export driven through it would contain only the
+ * rooms currently on screen; and requiring a panel would make the API
+ * unreachable from a script that runs before React has mounted one. (Mudlet
+ * does require its mapper open, but that is a Qt artefact of where its
+ * renderer lives, not part of the API's meaning.)
+ *
+ * The off-screen container only exists to give the Konva backend real
+ * dimensions so getAreaBounds can resolve an aspect ratio.
+ */
+export declare function exportAreaImage(mapStore: MapStore, mapper: MapperSettings | undefined, areaId: number, zLevel?: number): Uint8Array | null;

package/dist-lib/map/mapParser.worker.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,35 @@
+import type { MudletMap, MudletMapHeader, MudletRoom } from 'mudlet-map-binary-reader';
+/** Callbacks driving a streamed parse. `onHeader` fires once before any room,
+ *  `onRooms` once per batch, in map order; the returned promise settles after
+ *  the last batch has been handed over. */
+export interface MapStreamSink {
+    onHeader(header: MudletMapHeader, totalRooms: number): void;
+    onRooms(rooms: [number, MudletRoom][]): void;
+    /** Rooms ingested so far / the header's total (0 when the total is unknown). */
+    onProgress?(loaded: number, total: number): void;
+}
+/**
+ * Parse a Mudlet binary map off the main thread. The buffer is transferred —
+ * caller must not reuse it after the call. Resolves with the parsed MudletMap
+ * (deep-cloned by structured-clone on its way back).
+ */
+export declare function parseMapInWorker(buf: ArrayBuffer): Promise<MudletMap>;
+/**
+ * Streaming sibling of {@link parseMapInWorker}: the worker walks the map
+ * room-by-room and pushes the header, then batches of rooms, into `sink`
+ * instead of materialising the whole graph and cloning it back in one piece.
+ * Peak memory is roughly halved (the graph no longer exists on both sides at
+ * once) and the batch counter gives a progress signal for large maps.
+ *
+ * The buffer is transferred — the caller must not reuse it. Resolves once the
+ * last batch has been delivered; rejects if the worker fails mid-stream, in
+ * which case the sink has seen a partial map and the caller owns the cleanup.
+ */
+export declare function streamMapInWorker(buf: ArrayBuffer, sink: MapStreamSink): Promise<void>;
+/**
+ * Serialise a MudletMap to the Mudlet binary `.dat` format off the main thread.
+ * The map is structured-cloned to the worker (so the caller's object isn't
+ * touched); the resulting bytes are transferred back as a standalone
+ * ArrayBuffer the caller owns.
+ */
+export declare function serializeMapInWorker(map: MudletMap): Promise<ArrayBuffer>;

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

@@ -0,0 +1,52 @@
+import type { MudletRoom } from 'mudlet-map-binary-reader';
+/**
+ * Verdict from a `setExitWeightFilter` callback for one candidate exit.
+ * `blocked` drops the edge from the graph entirely; `weightOverride` replaces
+ * the edge cost that the exit weight / target room weight would have given.
+ * Both unset means "leave this exit alone".
+ */
+export interface ExitWeightFilterResult {
+    blocked?: boolean;
+    weightOverride?: number;
+}
+/**
+ * Called once per candidate exit while the graph is explored, with the room
+ * being expanded and the exit's key — the short direction name ("e", "up") for
+ * stock exits, or the verbatim command for special exits. Mirrors Mudlet's
+ * `applyExitWeightFilter(source, exitKey)` (TMap.cpp).
+ */
+export type ExitWeightFilter = (roomId: number, exitCommand: string) => ExitWeightFilterResult;
+export interface PathfindResult {
+    /** Room ids visited in order, excluding the start room. Matches Mudlet's
+     *  speedWalkPath, which prepends each step until reaching `from` but never
+     *  prepends `from` itself. */
+    path: number[];
+    /** Direction taken at each step — short name ("n"/"ne"/"up"/"down"/"in"/"out")
+     *  for stock exits or the verbatim command string for special exits. Same
+     *  length as `path` / `weights`. */
+    dirs: string[];
+    /** Edge cost per step (target room weight, or per-exit weight override). */
+    weights: number[];
+    /** Sum of `weights` — Mudlet's getPath returns this alongside the bool. */
+    totalWeight: number;
+}
+/**
+ * Mudlet `findPath(from, to)` — A* shortest path. Heuristic mirrors Mudlet's
+ * TAstar.h: 3D Euclidean distance when both rooms share an area, constant 1
+ * (equivalent to Dijkstra) when they don't — Mudlet falls back because raw
+ * coordinates aren't comparable across areas. Edge cost is the per-exit
+ * override in `exitWeights[key]` if set, otherwise the target room's `weight`
+ * (clamped to ≥1 to keep the heap monotonic).
+ *
+ * Skips locked rooms (`isLocked`), locked stock-direction exits (`exitLocks`
+ * carries the 1-12 dir codes), and locked special exits. Special-exit locks are
+ * per COMMAND in Mudlet; pass `isSpecialExitLocked` to resolve them that way.
+ * Without it the room's `mSpecialExitLocks` is used, which the binary reader
+ * keys by destination room id — that loses per-command resolution when several
+ * commands share a destination, but it is the on-disk representation.
+ *
+ * Trivial `from == to` returns an empty path with totalWeight 0 (also
+ * Mudlet's behavior). Returns null when either room is missing or no route
+ * exists.
+ */
+export declare function findPath(rooms: ReadonlyMap<number, MudletRoom>, from: number, to: number, exitFilter?: ExitWeightFilter | null, isSpecialExitLocked?: (roomId: number, command: string) => boolean): PathfindResult | null;

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

@@ -0,0 +1,28 @@
+/**
+ * Mudlet XML map import — the IRE-style `map.xml` format games publish via
+ * GMCP `Client.Map` (MMP) and that Mudlet's `loadMap("...xml")` accepts.
+ * Faithful port of XMLimport::readMap/readArea/readRoom/readEnvColor
+ * (Mudlet src/XMLimport.cpp), producing the same in-memory `MudletMap` shape
+ * the binary reader yields so `MapStore.loadFromBinary` can ingest it.
+ *
+ * Format sketch:
+ *
+ *   <map>
+ *     <areas><area id="2" name="Riverside"/></areas>
+ *     <rooms>
+ *       <room id="1" area="2" title="On a hill" environment="3">
+ *         <coord x="0" y="0" z="0"/>
+ *         <exit direction="north" target="2" door="1"/>
+ *         <exit special="1" command="enter hole" target="7" hidden="1"/>
+ *       </room>
+ *     </rooms>
+ *     <environments><environment id="3" color="4"/></environments>
+ *   </map>
+ */
+import type { MudletMap } from 'mudlet-map-binary-reader';
+/**
+ * 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).
+ */
+export declare function parseXmlMap(xmlText: string): MudletMap | null;

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

@@ -0,0 +1,236 @@
+import { EventBus } from '../core/EventBus';
+import { WindowManager } from '../ui/windows/WindowManager';
+import { LabelManager } from '../ui/labels/LabelManager';
+import { CommandLineManager } from '../ui/cmdline/CommandLineManager';
+import { ScrollBoxManager } from '../ui/scrollbox/ScrollBoxManager';
+import { SoundManager } from '../ui/sound/SoundManager';
+import { VideoManager } from '../ui/video/VideoManager';
+import { CmdLineMenuRegistry } from '../ui/CmdLineMenuRegistry';
+import { MouseEventRegistry } from '../ui/MouseEventRegistry';
+import { type MudClientOptions } from './connection/MudClient';
+import { type MudEvents, type SessionStatus } from './events';
+import type { Console } from './text/Console';
+import { type ControlCharacterMode } from './text/controlCharacterMode';
+export type { SessionStatus, MudEvents } from './events';
+export type { ControlCharacterMode } from './text/controlCharacterMode';
+export type MudSessionOptions = Omit<MudClientOptions, 'url'>;
+/** Mudlet `showSentText` modes — controls local echo of commands you send.
+ *  `never`: never echo. `script`: echo unless a script passes `send(cmd, false)`
+ *  (the default). `always`: echo even when a script passes `send(cmd, false)`. */
+export type ShowSentTextMode = 'never' | 'script' | 'always';
+/** Mudlet `blankLinesBehaviour` modes — controls how empty server lines render.
+ *  `show`: render the blank line as-is (default). `hide`: suppress it entirely.
+ *  `replacewithspace`: render it as a single space (so screen readers announce
+ *  it — Mudlet's QTBUG-105035 workaround). */
+export type BlankLinesBehaviour = 'show' | 'hide' | 'replacewithspace';
+export type ScriptLogSourceKind = 'script' | 'alias' | 'trigger' | 'timer' | 'key' | 'button';
+export interface ScriptLogSource {
+    kind: ScriptLogSourceKind;
+    id: string;
+    name: string;
+    line?: number;
+}
+export interface ScriptLogEntry {
+    text: string;
+    level: 'error' | 'info';
+    timestamp: number;
+    source?: ScriptLogSource;
+}
+export declare class MudSession {
+    readonly events: EventBus<MudEvents>;
+    private readonly overlayLayerOrder;
+    readonly windows: WindowManager;
+    readonly labels: LabelManager;
+    readonly cmdLines: CommandLineManager;
+    readonly scrollBoxes: ScrollBoxManager;
+    readonly sounds: SoundManager;
+    readonly videos: VideoManager;
+    readonly cmdLineMenu: CmdLineMenuRegistry;
+    readonly mouseEvents: MouseEventRegistry;
+    /** Per-window Console instances. 'main' registered by ScriptingAPI; named windows by WindowManager. */
+    readonly consoles: Map<string, Console>;
+    private client;
+    /** The most recent URL passed to connect() — replayed by reconnect(). */
+    private lastUrl;
+    private pingTracker;
+    private stateUnsubs;
+    private _status;
+    private _ping;
+    private _outputReady;
+    private _destroyed;
+    /** Latest main output area character grid (columns × rows), tracked here so
+     *  it survives client teardown and seeds a freshly-created client on the
+     *  next connect(). Fed by the WindowManager's main-console resize callback
+     *  and forwarded to the live client for NAWS (telnet option 31). */
+    private windowSize;
+    /** Active Mudlet-format replay recording, or null. Fed from the
+     *  `socket.incoming` tap in the constructor — the post-MCCP,
+     *  pre-telnet-parsing stream, the same point Mudlet records at. */
+    private replayRecorder;
+    /** Active replay playback, or null. */
+    private replayPlayer;
+    /** Playback speed divisor (1..1024). Read per-chunk, so changing it
+     *  mid-replay affects the remaining chunks — matching Mudlet. */
+    private _replaySpeed;
+    /** Colors for the local echo of sent commands. Re-applied from the active
+     *  profile by ProfileSession. `fg` defaults to Mudlet's olive; `bg` empty =
+     *  no background. Consumed by echoCommand() to wrap the echo in ANSI. */
+    commandEchoColor: {
+        fg: string;
+        bg: string;
+    };
+    /** Mudlet `setConfig("showSentText", ...)`. Controls local echo of sent
+     *  commands (the server-side ECHO suppression in `shouldEchoCommand` still
+     *  applies independently). `script` (the default) echoes only when send()'s
+     *  `echo` flag is set, so scripts can suppress per command via
+     *  `send(cmd, false)`; `always` echoes even then; `never` never echoes.
+     *  Toggled live by the config registry in ScriptingAPI. */
+    showSentText: ShowSentTextMode;
+    /** Mudlet `setConfig("blankLinesBehaviour", ...)`. Controls how empty server
+     *  lines render in the main output. Read by ScriptingEngine.processFlushBatch
+     *  per line; toggled live (and persisted) by the config registry in
+     *  ScriptingAPI. */
+    blankLinesBehaviour: BlankLinesBehaviour;
+    /** Bounded script.log buffer so the editor panel can backfill entries that
+     *  arrived before it was first opened (e.g. errors during initial load). */
+    private static readonly SCRIPT_LOG_LIMIT;
+    private _scriptLog;
+    private readonly options;
+    /** Warn before the tab closes while a connection is live. Owned here rather
+     *  than by MudClient — a fresh client is created on every connect(), so a
+     *  per-client listener would accumulate one leaked closure per reconnect. */
+    private readonly beforeUnload;
+    constructor(options?: MudSessionOptions);
+    get scriptLog(): readonly ScriptLogEntry[];
+    clearScriptLog(): void;
+    get status(): SessionStatus;
+    get ping(): number | null;
+    get outputReady(): boolean;
+    markOutputReady(): void;
+    markOutputGone(): void;
+    connect(url: string): void;
+    disconnect(): void;
+    /** Whether a send() carrying the given per-call `echo` flag should produce a
+     *  local echo, under the current showSentText mode. `script` defers to the
+     *  flag; `always`/`never` ignore it. */
+    private shouldEchoSentText;
+    echoCommand(text: string): void;
+    /** Wrap the echoed command in ANSI truecolor escapes from commandEchoColor
+     *  so it renders in the configured foreground (and optional background). */
+    private styleEchoCommand;
+    send(text: string, echo?: boolean): void;
+    /** Send credentials/secrets that must NEVER be echoed locally — regardless of
+     *  the showSentText mode (including `always`) or the server-echo state. Used
+     *  for auto-login passwords. The normal `send(text, false)` only suppresses
+     *  the echo in `script` mode; `always` would override it, so a password must
+     *  take this path instead of relying on the per-call echo flag. */
+    sendSecret(text: string): void;
+    sendGmcpRaw(message: string): void;
+    /** Reply to a GMCP `Char.Login.Default` request. Pass an account + password
+     *  to authenticate, or no arguments to send the empty "fall back to text
+     *  login" reply (the credentials popup's Cancel). The password is relayed
+     *  straight to the wire and never persisted. */
+    sendCharLoginCredentials(account?: string, password?: string): void;
+    sendMSDP(variable: string, values: string[]): boolean;
+    sendSocket(data: string): boolean;
+    /** True when there is no live socket — see MudClient.isSocketUnconnected. */
+    isSocketUnconnected(): boolean;
+    feedTelnet(data: string): void;
+    sendATCP(message: string): boolean;
+    sendTelnetChannel102(msg: string): boolean;
+    /** Whether MSP was negotiated on the live connection. False with no client,
+     *  which is what a never-connected profile should report. */
+    isMspNegotiated(): boolean;
+    get replaySpeed(): number;
+    get isReplayRecording(): boolean;
+    get isReplaying(): boolean;
+    /** Set the playback speed divisor, clamped to Mudlet's 1..1024 range.
+     *  Takes effect from the next chunk of an active replay. */
+    setReplaySpeed(speed: number): void;
+    /** Start recording the inbound stream to Mudlet's replay format. Returns
+     *  false when a recording is already running. */
+    startReplayRecording(): boolean;
+    /** Stop recording and return the captured stream as a Mudlet .dat file's
+     *  bytes, or null when no recording was running. The caller decides where
+     *  the bytes go (profile VFS, browser download, …). */
+    stopReplayRecording(): Uint8Array | null;
+    /** Start playing a Mudlet-format replay (the Lua `loadReplay` core).
+     *  Works offline — with no live connection the chunks feed a detached
+     *  client's parsing pipeline. Returns null on success or a human-readable
+     *  failure reason (mirroring Mudlet's loadReplay error strings). */
+    loadReplayData(bytes: Uint8Array): string | null;
+    /** Stop the active replay without delivering its remaining chunks.
+     *  Returns false when no replay is running. */
+    abortReplay(): boolean;
+    /** The client whose parsing pipeline replay chunks feed into. Reuses the
+     *  live client when one exists; otherwise creates a detached MudClient
+     *  that is never connect()ed — the inbound pipeline works without a
+     *  socket, and any replies the replayed IAC traffic provokes are dropped
+     *  by the readyState guards, which is exactly right for playback. */
+    private ensureReplayClient;
+    private postReplayInfo;
+    /** Mudlet `reconnect()`. Disconnect and redial the most recently connected
+     *  URL (set by connect(), so it covers both the app and Lua connect paths).
+     *  Returns false when nothing has been dialed yet. */
+    reconnect(): boolean;
+    /** Mudlet `getServerEncoding()`. The live client's inbound decoder name;
+     *  'utf-8' when no client is attached. */
+    getServerEncoding(): string;
+    /** Mudlet `setServerEncoding(name)`. Returns false when no client is
+     *  attached or the name isn't supported. */
+    setServerEncoding(name: string): boolean;
+    /** Mudlet `getServerEncodingsList()`. The fixed set of encodings mudix can
+     *  decode — available even before a connection is dialed. */
+    getServerEncodingsList(): string[];
+    /** Mudlet `addSupportedTelnetOption(option)`. Forwards to the live
+     *  MudClient when one is attached so the option will be auto-negotiated
+     *  on the next IAC WILL/DO from the server. Returns false when no client
+     *  is wired up yet. */
+    addSupportedTelnetOption(option: number): boolean;
+    /** Updates both the active client (if any) and the stored options so the
+     *  setting survives a reconnect. */
+    setPromptTimeoutMs(ms: number): void;
+    getPromptTimeoutMs(): number | null;
+    /** Mudlet `setConfig("fixUnnecessaryLinebreaks", …)`. Updates the live client
+     *  and the stored options so the setting survives a reconnect. */
+    setFixUnnecessaryLinebreaks(enabled: boolean): void;
+    /** Mudlet `setConfig("controlCharacterHandling", …)`. Applies immediately —
+     *  every console/text window re-renders control characters (and tab-stops)
+     *  under the new mode on their next paint. */
+    setControlCharacterMode(mode: ControlCharacterMode): void;
+    /** Update the telnet protocol toggles applied on the next connect.
+     *  Mid-session changes do not retroactively renegotiate — the values are
+     *  read by MudClient's constructor, so the next dial sees them. */
+    setProtocolOptions(opts: {
+        gmcpEnabled?: boolean;
+        mttsEnabled?: boolean;
+        msdpEnabled?: boolean;
+        msspEnabled?: boolean;
+        charsetEnabled?: boolean;
+        mspEnabled?: boolean;
+        mccpEnabled?: boolean;
+        mxpEnabled?: boolean;
+        mnesEnabled?: boolean;
+        newEnvironEnabled?: boolean;
+        secureTransport?: boolean;
+        screenReaderAdvertised?: boolean;
+        nawsEnabled?: boolean;
+        subprotocols?: string[];
+    }): void;
+    /** Record the main output area's character grid (columns × rows) and forward
+     *  it to the live client for NAWS. Stored on the session so a client created
+     *  on a later connect() is seeded with the current size. Called by the
+     *  WindowManager whenever the main console's grid changes. */
+    setWindowSize(cols: number, rows: number): void;
+    private teardownClient;
+    get destroyed(): boolean;
+    /** Release resources that live outside the JS heap. In-memory state (maps,
+     *  arrays, sub-managers) is reclaimed by GC once the instance is dropped, so
+     *  this only handles the three things that don't self-clean: the WebSocket
+     *  + ping timer (via `teardownClient`), Web Audio nodes, and any EventBus
+     *  listeners with an AbortSignal cleanup still pending. Idempotent. */
+    destroy(): void;
+    private setStatus;
+    private setPing;
+    private reportConnectionError;
+}

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

@@ -0,0 +1,28 @@
+type TempFn = (matches: RegExpMatchArray) => void;
+type PatternItem = {
+    id: string;
+    name: string;
+    pattern: string;
+    code: string;
+    language: 'lua' | 'js';
+    enabled: boolean;
+    isGroup: boolean;
+    parentId: string | null;
+};
+export declare class PatternEngine<T extends PatternItem> {
+    protected readonly temp: Map<number, {
+        pattern: RegExp;
+        fn: TempFn;
+    }>;
+    protected nextId: number;
+    protected permCompiled: Array<{
+        item: T;
+        re: RegExp;
+    }>;
+    /** Number of live session-scoped temp items (Mudlet `getProfileStats` temp count). */
+    get tempCount(): number;
+    addTemp(pattern: string | RegExp, fn: TempFn): () => void;
+    loadPerm(items: T[]): void;
+    destroy(): void;
+}
+export {};

package/dist-lib/mud/aliases/AliasEngine.d.ts

@@ -0,0 +1,15 @@
+import type { AliasNode } from '../../storage/schema';
+import { PatternEngine } from '../PatternEngine';
+export type { AliasNode };
+export declare class AliasEngine extends PatternEngine<AliasNode> {
+    /** Returns true and fires the first matching temp alias. Stops at first match. */
+    processTemp(input: string): boolean;
+    /** Returns the first matching perm alias, or null. `matchedText` is the
+     *  portion of `input` the regex actually matched (Mudlet's `matches[1]`),
+     *  which differs from the whole input for an unanchored pattern. */
+    matchPerm(input: string): {
+        alias: AliasNode;
+        matchedText: string;
+        captures: string[];
+    } | null;
+}

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

@@ -0,0 +1,84 @@
+export declare const DEFAULT_PROMPT_TIMEOUT_MS = 300;
+/**
+ * Keep prompt-flush timeouts in a sane range. 0 disables the safety net (only
+ * a real GA/EOR or the next chunk's newline will flush a partial tail) — handy
+ * for tests but risky for GA-less MUDs. The upper bound stops a typo from
+ * stalling output for minutes.
+ */
+export declare function clampPromptTimeout(ms: number): number;
+export interface LineAssemblerCallbacks {
+    /** Deliver assembled whole lines (or a flushed prompt tail) downstream —
+     *  the trigger pipeline and rendering treat each chunk as complete lines. */
+    onChunk(text: string, ts: number): void;
+    /** Fired after a prompt marker (IAC GA/EOR) flushed the held tail — the
+     *  owner emits its `prompt` event here. */
+    onPrompt(): void;
+    /** Fired after an idle-timer flush so the owner can render any messages
+     *  the flushed chunk produced (MudClient.flushMessageBuffer). */
+    onIdleFlush(): void;
+}
+export interface LineAssemblerOptions {
+    promptTimeoutMs?: number;
+    /** Mudlet `mUSE_IRE_DRIVER_BUGFIX` — strip a spurious leading newline from
+     *  GA-driven prompt blocks. Off by default; toggled live via
+     *  setFixUnnecessaryLinebreaks (setConfig). */
+    fixUnnecessaryLinebreaks?: boolean;
+}
+/**
+ * Assembles the decoded MUD text stream into whole lines. WebSocket frames can
+ * split a long line at an arbitrary byte (mid-word, mid-ANSI-escape), so the
+ * trailing partial line of each frame is held back until the next frame
+ * supplies the rest, a prompt marker (IAC GA/EOR) flushes it, or the idle
+ * timer fires. Our render path finalizes every emitted chunk and has no
+ * downstream open-line carry (unlike Mudlet's TBuffer), so the "line ends only
+ * at \n or GA" invariant is enforced here. The live-partial parity work is
+ * deferred — see docs/line-assembly-tbuffer-port.md.
+ */
+export declare class LineAssembler {
+    private readonly callbacks;
+    /** Trailing text (after the last `\n`) held back from rendering until either
+     *  the next frame supplies the rest of the line, a prompt marker arrives, or
+     *  the idle-flush timer fires. Prevents spurious line breaks when a long MUD
+     *  line is split across multiple WebSocket frames. */
+    private pendingLineTail;
+    private pendingTailTimer;
+    private promptTimeoutMs;
+    /** Set true once the server has sent IAC GA / IAC EOR at least once.
+     *  Mirrors Mudlet's `mGA_Driver` latch (`cTelnet::gotRest`). From then on
+     *  the held partial tail is flushed by the prompt marker rather than the
+     *  idle timer. Note: unlike Mudlet's cTelnet — which posts GA-mode chunks
+     *  verbatim and reassembles split lines in TBuffer — we keep buffering
+     *  partial lines here, because our render path finalizes every emitted
+     *  chunk and has no downstream open-line carry. */
+    private _gaDriver;
+    /** True at the start of a GA-driven data block — i.e. before any content of
+     *  the current post-GA transmission has been seen. Drives the
+     *  `fixUnnecessaryLinebreaks` leading-newline strip, which fires at most once
+     *  per block. Set true on connect and after each prompt flush, cleared once
+     *  the block's leading-newline question has been settled. */
+    private atPromptBlockStart;
+    private fixUnnecessaryLinebreaks;
+    constructor(callbacks: LineAssemblerCallbacks, options?: LineAssemblerOptions);
+    /** True once the session has latched into GA-driven prompt mode. */
+    get gaDriver(): boolean;
+    setPromptTimeoutMs(ms: number): void;
+    getPromptTimeoutMs(): number;
+    /** Mudlet `setConfig("fixUnnecessaryLinebreaks", …)`. Takes effect on the
+     *  next GA-driven block; never retroactive. */
+    setFixUnnecessaryLinebreaks(enabled: boolean): void;
+    /** Drop all held state (call on connect and after close). */
+    reset(): void;
+    /** Feed one frame's decoded text plus whether the frame carried a prompt
+     *  marker (IAC GA/EOR). Emits only whole lines (text up to and including
+     *  the last `\n`) and holds the trailing partial in `pendingLineTail`
+     *  until the rest of the line arrives, a prompt marker flushes it, or the
+     *  idle timer fires. */
+    feed(decoded: string, hasPrompt: boolean, ts: number): void;
+    /** Flush a held-back partial line (text after the final `\n` of a frame).
+     *  Triggered by prompt markers (IAC GA/EOR), the idle-flush timer, or
+     *  socket close. Pushes the tail through the normal chunk path so triggers
+     *  and rendering treat it as a complete line. */
+    flush(ts: number, final?: boolean): void;
+    private scheduleTailFlush;
+    private clearTailTimer;
+}