@mudlet/mudlet-web 0.3.0

package/dist-lib/ui/output/outputCopy.d.ts

@@ -0,0 +1,15 @@
+/** True when the current selection touches any line inside `container`. */
+export declare function hasSelectionIn(container: HTMLElement): boolean;
+/** Select every line in the container (Range over its contents). */
+export declare function selectAll(container: HTMLElement): void;
+/** Copy the native selection text verbatim (character-precise). */
+export declare function copySelectionText(): Promise<void>;
+/**
+ * Copy the selected lines as a complete, self-contained HTML document. The full
+ * document source goes on the clipboard as both `text/html` (so rich targets
+ * paste it rendered) and `text/plain` (so plain targets paste the HTML markup
+ * itself), with a `writeText` fallback for browsers without ClipboardItem.
+ */
+export declare function copySelectionAsHtml(container: HTMLElement): Promise<void>;
+/** Copy the selected lines to the clipboard as a PNG image. */
+export declare function copySelectionAsImage(container: HTMLElement): Promise<void>;

package/dist-lib/ui/preventPinchZoom.d.ts

@@ -0,0 +1 @@
+export declare function installPinchZoomGuard(): void;

package/dist-lib/ui/scrollbox/ScrollBoxManager.d.ts

@@ -0,0 +1,62 @@
+import { OverlayLayerOrder } from '../layout/overlayLayerOrder';
+export interface ScrollBoxCreateOptions {
+    /** Parent window id ('main' for the main viewport, or a userwindow / another
+     *  scroll box name for nesting). */
+    parent?: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface ScrollBoxState {
+    name: string;
+    parent: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    visible: boolean;
+    /** Raw Qt-style CSS string from a future setScrollBoxStyleSheet — stored for
+     *  parity; Geyser.ScrollBox:setStyleSheet is itself unimplemented upstream. */
+    styleSheet?: string;
+}
+type Listener = (scrollBoxes: ScrollBoxState[]) => void;
+/**
+ * Registry for overlay scroll-box widgets (Mudlet createScrollBox). A scroll box
+ * is an absolutely-positioned, scrollable container on top of a parent viewport
+ * that other overlay widgets (labels, command lines, nested scroll boxes) can be
+ * created *inside* by passing the box's name as their parent — mirroring
+ * Mudlet's Geyser.ScrollBox, which treats the box as its own "window".
+ *
+ * Shares the per-parent subscriber shape of {@link CommandLineManager} /
+ * {@link LabelManager}; the React {@link ScrollBoxOverlay} renders each box and
+ * mounts the child overlays scoped to the box's name within its scroll area.
+ */
+export declare class ScrollBoxManager {
+    readonly overlayZ: OverlayLayerOrder;
+    private readonly boxes;
+    private readonly listeners;
+    constructor(overlayZ?: OverlayLayerOrder);
+    /** Mudlet createScrollBox([parent,] name, x, y, w, h) — false when a scroll
+     *  box with that name already exists. */
+    create(name: string, opts: ScrollBoxCreateOptions): boolean;
+    has(name: string): boolean;
+    get(name: string): ScrollBoxState | undefined;
+    destroy(name: string): boolean;
+    move(name: string, x: number, y: number): boolean;
+    resize(name: string, width: number, height: number): boolean;
+    /** Mudlet setWindow — reparent a scroll box into another window's
+     *  overlay. Both the old and the new parent's overlays re-render.
+     *  Cycle prevention is the caller's job (ScriptingAPI.setWindow). */
+    setParent(name: string, parent: string): boolean;
+    show(name: string): boolean;
+    hide(name: string): boolean;
+    raise(name: string): boolean;
+    lower(name: string): boolean;
+    setStyleSheet(name: string, css: string): boolean;
+    list(parent: string): ScrollBoxState[];
+    subscribe(parent: string, fn: Listener): () => void;
+    clearAll(): void;
+    private notify;
+}
+export {};

package/dist-lib/ui/scrollbox/ScrollBoxOverlay.d.ts

@@ -0,0 +1,25 @@
+import type { ScrollBoxManager } from './ScrollBoxManager';
+import type { LabelManager } from '../labels/LabelManager';
+import type { CommandLineManager } from '../cmdline/CommandLineManager';
+import './ScrollBoxOverlay.css';
+interface ScrollBoxOverlayProps {
+    manager: ScrollBoxManager;
+    labels: LabelManager;
+    cmdLines: CommandLineManager;
+    /** Viewport whose scroll boxes this overlay renders ('main', a userwindow
+     *  id, or — when nested — another scroll box's name). */
+    parent: string;
+}
+/**
+ * Renders the {@link ScrollBoxManager}'s boxes for a given parent viewport as
+ * absolutely-positioned scrollable containers. Each box hosts the child overlays
+ * (labels, command lines, and nested scroll boxes) scoped to the box's own name,
+ * so widgets created with `parent = boxName` render inside it.
+ *
+ * Scrolling: the children are absolutely positioned and don't expand their
+ * containers on their own, so each box wraps them in a content div sized to the
+ * extent of its children (the furthest child edge). When that extent exceeds the
+ * box, the box's `overflow:auto` produces real scrollbars.
+ */
+export declare function ScrollBoxOverlay({ manager, labels, cmdLines, parent }: ScrollBoxOverlayProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist-lib/ui/sound/SoundManager.d.ts

@@ -0,0 +1,149 @@
+import type { MediaCaptionInfo } 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
+ *  GMCP media). Mirrors Mudlet's muteMediaAPI / muteMediaGame split, where API
+ *  media maps to MediaProtocolAPI and game media to MSP/GMCP. */
+export type MediaOrigin = 'api' | 'game';
+export interface PlaySoundOptions {
+    name: string;
+    /** 0..100 — Mudlet scale. Default 50. */
+    volume?: number;
+    /** Fade-in duration in milliseconds. */
+    fadein?: number;
+    /** Fade-out duration in milliseconds (on natural end or stop). */
+    fadeout?: number;
+    /** Start offset within the buffer, in milliseconds. */
+    start?: number;
+    /** Loop count. 1 = play once (default). -1 = infinite. N>1 = N total plays. */
+    loops?: number;
+    /** Dedupe key — calling again with same key replaces the previous one. */
+    key?: string;
+    /** Group tag — stopMusic({tag=...}) and stopSounds() filter on this. */
+    tag?: string;
+    /** Which mute gate governs this playback. Default 'api'. */
+    origin?: MediaOrigin;
+    /** Optional closed-caption text (Mudlet's media `caption`). Shown verbatim
+     *  when closed captions are on; absent → a caption is synthesized from the
+     *  kind + filename. */
+    caption?: string;
+}
+export interface PlayMusicOptions extends PlaySoundOptions {
+    /** If true and a music track with the same name+key is already playing, do nothing. */
+    continue?: boolean;
+}
+export interface StopMusicOptions {
+    name?: string;
+    key?: string;
+    tag?: string;
+    /** Fade-out duration in milliseconds. Overrides the source's own fadeout. */
+    fadeout?: number;
+}
+export declare class SoundManager {
+    private nextId;
+    private active;
+    private loader;
+    /** 0..1, applied as an extra multiplier on every source's gain. */
+    private masterVolume;
+    /**
+     * Persistent per-origin mute gates — Mudlet's muteMediaAPI / muteMediaGame.
+     * A muted origin's sources keep playing (their position advances) but their
+     * gain is pinned to 0, and new sources of that origin start silent; nothing
+     * is stopped, so unmuting restores audibility mid-track. This mirrors Mudlet
+     * toggling QAudioOutput::setMuted on the live players by protocol rather than
+     * tearing them down.
+     */
+    private muted;
+    /**
+     * 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.
+     */
+    onMediaFinished?: (name: string, path: string) => void;
+    /**
+     * Raised when a tracked source starts ('plays') or ends ('stops'), so the
+     * engine can print a closed caption (Mudlet's enableClosedCaption). Fires
+     * regardless of the caption setting — the consumer decides whether to show
+     * it. Not fired by `stopAll()` (teardown nulls each onended first).
+     */
+    onMediaCaption?: (info: MediaCaptionInfo) => void;
+    setLoader(fn: LoaderFn | null): void;
+    setMasterVolume(value: number): void;
+    /**
+     * Mudlet `muteMediaAPI` / `muteMediaGame`. Sets the persistent mute gate for
+     * a playback origin. While muted, that origin's currently-playing sources are
+     * silenced in place (gain → 0, position keeps advancing) and any new ones
+     * start silent — but nothing is stopped, so unmuting restores audibility
+     * mid-track. `api` gates script playback (playSoundFile/playMusicFile);
+     * `game` gates server-driven media (MSP / GMCP).
+     */
+    setOriginMuted(origin: MediaOrigin, muted: boolean): void;
+    isOriginMuted(origin: MediaOrigin): boolean;
+    /** Output gain for a source: its own volume scaled by the master volume,
+     *  pinned to 0 while its origin is muted. */
+    private effectiveGain;
+    playSound(opts: PlaySoundOptions): Promise<number>;
+    playMusic(opts: PlayMusicOptions): Promise<number>;
+    stopSounds(): void;
+    /**
+     * Mudlet `pauseSounds([channel])`. Web Audio source nodes can be
+     * scheduled to start but not paused once playing — they're transient by
+     * design, with no equivalent of QMediaPlayer::pause(). We approximate
+     * Mudlet's contract by stopping the matching sources outright (so the
+     * mute happens immediately) and let the player retrigger them with
+     * `playSoundFile` to resume. The optional `channel` filters by the
+     * source's `tag` (matches Mudlet's "channel" semantics: a Tag string
+     * passed to playSoundFile). Music sources are untouched — they have a
+     * separate `stopMusic` codepath.
+     */
+    pauseSounds(channel?: string): void;
+    /**
+     * Mudlet `pauseMusic([settings])`. Web Audio source nodes can't truly
+     * pause once started (same constraint as {@link pauseSounds}), so this is
+     * an immediate fade-out + stop of the matching music sources — re-trigger
+     * `playMusicFile` to "resume". The optional `channel`/tag filters which
+     * music tracks are affected; sound effects are untouched.
+     */
+    pauseMusic(channel?: string): void;
+    stopMusic(opts?: StopMusicOptions): void;
+    /**
+     * Mudlet getPlayingSounds / getPlayingMusic. Returns the currently-playing
+     * sources of the requested `kind` (default 'sound' — music is reported
+     * separately by getPlayingMusic) optionally filtered by name/key/tag.
+     * Volume is reported on Mudlet's 0..100 scale.
+     */
+    getPlaying(filter?: {
+        name?: string;
+        key?: string;
+        tag?: string;
+    }, kind?: 'sound' | 'music'): Array<{
+        name: string;
+        key?: string;
+        tag?: string;
+        volume: number;
+    }>;
+    /**
+     * Mudlet loadSoundFile. Preloads (decodes + caches) a sound so the first
+     * playSoundFile has no decode latency. Fire-and-forget: warms `decodeCache`
+     * via the same path playSound uses, so a later play of the same name hits
+     * the cache. Returns false when no AudioContext is available yet.
+     */
+    preload(name: string): boolean;
+    /**
+     * Mudlet `purgeMediaCache()` — drop every decoded-audio buffer so the next
+     * play of any file re-fetches and re-decodes it. Active playback is
+     * untouched (the cache only fronts the decode step). Always returns true.
+     */
+    purgeCache(): boolean;
+    /** Stop everything this manager owns. Call on engine teardown. */
+    stopAll(): void;
+    destroy(): void;
+    private play;
+    private fadeAndStop;
+    private isMusicPlaying;
+    private stopMusicMatching;
+    private updateMediaSessionState;
+    private firstActiveMusicName;
+}
+export {};

package/dist-lib/ui/sound/closedCaption.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Closed captions for media (Mudlet's `enableClosedCaption`). When enabled,
+ * each sound / music / video that starts or stops prints a short text line into
+ * the main output so deaf / hard-of-hearing players know audio fired — and, via
+ * the normal output path, screen-reader users hear it announced.
+ *
+ * Faithful to Mudlet `TMedia::printClosedCaption` (TMedia.cpp:2084-2110):
+ * captions cover audio + video ONLY — there is no image media type, so images
+ * are never captioned. This module holds the pure formatter; the SoundManager /
+ * VideoManager raise the lifecycle events and ScriptingEngine prints the line.
+ */
+/** Media families Mudlet captions. Notably no `image` — images never flow
+ *  through the media player and so are never captioned. */
+export type MediaKind = 'sound' | 'music' | 'video';
+/** The player-lifecycle verb shown in the caption. Mudlet also has pauses/fades,
+ *  but mudix's Web Audio model collapses those into a stop, so we expose the two
+ *  transitions that map cleanly. */
+export type CaptionAction = 'plays' | 'stops';
+export interface MediaCaptionInfo {
+    kind: MediaKind;
+    /** The path or name handed to the player; the trailing segment is shown. */
+    name: string;
+    /** Media key, when one was supplied. */
+    key?: string;
+    /** Explicit caption from the media packet / Lua `caption` arg, if any. */
+    caption?: string;
+    action: CaptionAction;
+}
+/**
+ * Format one caption line, mirroring Mudlet's text exactly:
+ *   - with an explicit caption:           `[<caption> <action>]`
+ *   - else, with a key:   `[<kind> <key> "<file>" <action>]`
+ *   - else:                       `[<kind> "<file>" <action>]`
+ * `<file>` is the trailing path segment of `name` (Mudlet shows the bare
+ * filename, not the resolved path).
+ */
+export declare function formatClosedCaption(info: MediaCaptionInfo): string;

package/dist-lib/ui/textedit/TextEditManager.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Registry for Mudlet `createTextEdit` widgets — a multi-line text editor pane.
+ *
+ * This is the data model behind the `*TextEdit*` Lua API (text content, the
+ * editor properties scripts set, and geometry/visibility). The on-screen
+ * QPlainTextEdit-equivalent rendering is not wired yet; scripts can create
+ * editors and round-trip their text/properties, which is what the Mudlet API
+ * surface (and the busted TextEdit spec) exercises.
+ */
+export interface TextEditState {
+    parent: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    text: string;
+    readOnly: boolean;
+    placeholder: string;
+    styleSheet: string;
+    font: string;
+    fontSize: number;
+    tabMovesFocus: boolean;
+    visible: boolean;
+}
+export declare class TextEditManager {
+    private edits;
+    has(name: string): boolean;
+    /** Read-only handle on a text edit's stored state, for the geometry and
+     *  visibility getters (getWindowGeometry, windowVisible). */
+    get(name: string): Readonly<TextEditState> | undefined;
+    /** Create (or replace) a text edit. Returns true (Mudlet always succeeds). */
+    create(name: string, opts: {
+        parent: string;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): boolean;
+    destroy(name: string): boolean;
+    /** Returns the editor's text, or null when no editor of that name exists. */
+    getText(name: string): string | null;
+    setText(name: string, text: string): boolean;
+    clear(name: string): boolean;
+    setReadOnly(name: string, value: boolean): boolean;
+    setPlaceholder(name: string, text: string): boolean;
+    setStyleSheet(name: string, css: string): boolean;
+    setFont(name: string, font: string): boolean;
+    setFontSize(name: string, size: number): boolean;
+    setTabMovesFocus(name: string, value: boolean): boolean;
+    show(name: string): boolean;
+    hide(name: string): boolean;
+    move(name: string, x: number, y: number): boolean;
+    /** Mudlet setWindow — reparent a text edit into another window. */
+    setParent(name: string, parent: string): boolean;
+    resize(name: string, width: number, height: number): boolean;
+}

package/dist-lib/ui/tts/TtsManager.d.ts

@@ -0,0 +1,68 @@
+export type TtsState = 'ttsSpeechReady' | 'ttsSpeechStarted' | 'ttsSpeechPaused' | 'ttsSpeechError' | 'ttsUnknownState';
+type EmitFn = (event: string, args: unknown[]) => void;
+export declare class TtsManager {
+    private readonly emit;
+    private readonly synth;
+    private pending;
+    private current;
+    private state;
+    private rate;
+    private pitch;
+    private volume;
+    private voiceName;
+    private gen;
+    private destroyed;
+    private readonly onVoicesChanged;
+    constructor(emit: EmitFn);
+    /** Mudlet ttsSpeak — speak `text` immediately, interrupting anything in
+     *  progress. The queue is untouched and resumes once `text` finishes. */
+    speak(text: string): void;
+    /** Mudlet ttsQueue — append `text` to the queue (or insert at 1-based
+     *  `index`). Starts playback if nothing is currently speaking. */
+    queue(text: string, index?: number): void;
+    /** Mudlet ttsSkip — stop the current utterance and move on to the next
+     *  queued one (if any). */
+    skip(): void;
+    /** Mudlet ttsPause — pause the current utterance. */
+    pause(): void;
+    /** Mudlet ttsResume — resume a paused utterance. */
+    resume(): void;
+    /** Mudlet ttsClearQueue — drop the whole pending queue, or just the item at
+     *  1-based `index`. Returns false when `index` is out of bounds (the
+     *  currently-speaking utterance is never in the queue and is unaffected). */
+    clearQueue(index?: number): boolean;
+    /** Mudlet ttsGetQueue — the pending texts (1-based index returns one item,
+     *  or false if out of bounds; no index returns the whole list). */
+    getQueue(): string[];
+    getQueue(index: number): string | false;
+    /** Mudlet ttsGetState — one of the tts* state strings. */
+    getState(): TtsState;
+    /** Mudlet ttsGetCurrentLine — the text being spoken, or null when idle
+     *  (Ready) / errored. The Lua wrapper maps null to (nil, reason). */
+    getCurrentLine(): string | null;
+    /** Mudlet ttsGetVoices — the available voice names. */
+    getVoices(): string[];
+    /** Mudlet ttsGetCurrentVoice — the selected voice name, falling back to the
+     *  engine's first available voice when none was set. */
+    getCurrentVoice(): string;
+    getRate(): number;
+    getPitch(): number;
+    getVolume(): number;
+    /** Mudlet ttsSetRate — clamps to -1..1, stores it, raises ttsRateChanged. */
+    setRate(rate: number): void;
+    /** Mudlet ttsSetPitch — clamps to -1..1, stores it, raises ttsPitchChanged. */
+    setPitch(pitch: number): void;
+    /** Mudlet ttsSetVolume — clamps to 0..1, stores it, raises ttsVolumeChanged. */
+    setVolume(volume: number): void;
+    /** Mudlet ttsSetVoiceByName — selects a voice by name. Returns false when no
+     *  voice matches; otherwise stores it and raises ttsVoiceChanged. */
+    setVoiceByName(name: string): boolean;
+    /** Mudlet ttsSetVoiceByIndex — selects a voice by 1-based index. Returns
+     *  false when out of bounds. */
+    setVoiceByIndex(index: number): boolean;
+    destroy(): void;
+    private advance;
+    private beginUtterance;
+    private setState;
+}
+export {};

package/dist-lib/ui/useBrandLogin.d.ts

@@ -0,0 +1,19 @@
+import type { LandingProps } from '../branding';
+export interface UseBrandLoginResult {
+    account: string;
+    setAccount: (value: string) => void;
+    password: string;
+    setPassword: (value: string) => void;
+    /** Find-or-create the profile, stash credentials in memory, and open it.
+     *  `connect` dials immediately; false opens offline. */
+    enter: (connect: boolean) => void;
+}
+/**
+ * Shared login-form state for custom branded landings. Handles the
+ * find-or-create-profile + in-memory-credential-stash + open sequence common
+ * to every branded login screen, and prefills from the last credentials
+ * entered this page (e.g. after backing out of a profile) — nothing is ever
+ * read from or written to storage. Bring your own markup; for a ready-made
+ * form see `BrandLoginFields`.
+ */
+export declare function useBrandLogin({ openProfile, ensureBrandProfile }: Pick<LandingProps, 'openProfile' | 'ensureBrandProfile'>): UseBrandLoginResult;

package/dist-lib/ui/useCommandHistory.d.ts

@@ -0,0 +1,7 @@
+/** Reactive MRU command history wrapper around localStorage. History is scoped
+ *  to `connectionId` so each profile keeps its own. `saveSize` caps how many
+ *  entries are persisted (Mudlet's `commandLineHistorySaveSize`). */
+export declare function useCommandHistory(connectionId: string | null, saveSize?: number): {
+    history: string[];
+    add: (item: string) => void;
+};

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

@@ -0,0 +1,56 @@
+import type { MediaCaptionInfo } from '../sound/closedCaption';
+type LoaderFn = (path: string) => Promise<ArrayBuffer | null>;
+export interface PlayVideoOptions {
+    name: string;
+    /** 0..100 — Mudlet scale. Default 50. */
+    volume?: number;
+    /** Loop count. 1 = play once (default). -1 = infinite. */
+    loops?: number;
+    /** CSS units; default fills the viewport. */
+    width?: string;
+    height?: string;
+    /** Optional closed-caption text (Mudlet's media `caption`). */
+    caption?: string;
+}
+export declare class VideoManager {
+    private loader;
+    /** Returns the DOM element that videos should be attached to. Set by
+     *  WindowManager.observeMain so videos drop onto the main viewport. */
+    private getMount;
+    private active;
+    /** Buffers fetched ahead of play via loadVideoFile, keyed by VFS path. */
+    private prefetched;
+    /** Fires when a video ends naturally or is stopped — mirrors Mudlet's
+     *  sysMediaFinished. */
+    onEnded: ((name: 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;
+    setLoader(fn: LoaderFn | null): void;
+    setMountPoint(fn: (() => HTMLElement | null) | null): void;
+    /**
+     * Mudlet `loadVideoFile`. Preloads (fetches + caches) a VFS-backed video so
+     * the first playVideoFile has no fetch latency. http(s)/data/blob URLs need
+     * no preloading (the element fetches them directly) and report success.
+     * Returns false when no loader is wired or the fetch fails.
+     */
+    preload(path: string): Promise<boolean>;
+    play(path: string, opts: PlayVideoOptions): Promise<boolean>;
+    pauseAll(): void;
+    /**
+     * Mudlet `getPlayingVideos([settings])` / `getPausedVideos([settings])`.
+     * Lists the videos currently in the requested play state, optionally
+     * filtered by name. Volume is reported on Mudlet's 0..100 scale.
+     */
+    getByState(wantPaused: boolean, filter?: {
+        name?: string;
+    }): Array<{
+        name: string;
+        path: string;
+        volume: number;
+    }>;
+    stopAll(): void;
+    private stopByName;
+    destroy(): void;
+}
+export {};

package/dist-lib/ui/windows/ScriptEditorModal.d.ts

@@ -0,0 +1,13 @@
+import type { MudSession } from '../../mud/MudSession';
+import type { ProfileVFS } from '../../scripting/vfs/ProfileVFS';
+import type { ScriptingEngine } from '../../scripting/ScriptingEngine';
+interface Props {
+    connectionId: string;
+    session: MudSession;
+    vfs: ProfileVFS | null;
+    scriptingEngineRef?: React.RefObject<ScriptingEngine | null>;
+    onClose: () => void;
+    onOpenVfsFile?: (path: string, line?: number) => void;
+}
+export declare function ScriptEditorModal({ connectionId, session, vfs, scriptingEngineRef, onClose, onOpenVfsFile }: Props): import("react/jsx-runtime").JSX.Element;
+export {};