@mudlet/mudlet-web 0.5.0 → 1.0.1

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

@@ -15,21 +15,37 @@ export interface PlaySoundOptions {
     fadeout?: number;
     /** Start offset within the buffer, in milliseconds. */
     start?: number;
+    /** Position in the track, in milliseconds, at which playback ends (Mudlet's
+     *  `finish`). Absent → the end of the file. Each pass of a loop ends there. */
+    finish?: 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;
+    /** 1..100 — Mudlet's media priority (sounds only). A sound with a priority
+     *  is refused while one of equal or higher priority is playing, and stops
+     *  the lower-priority ones when it does play (TMedia::
+     *  doesMediaHavePriorityToPlay). Absent → no priority, never refused. */
+    priority?: number;
     /** 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;
+    /** Sounds only: -100 (left) to 100 (right), already held to that range —
+     *  Client.Media 2's `pan`. Wins over a direction. */
+    pan?: number;
+    /** Sounds only: where the sound comes from, as canonicalMediaDirection
+     *  spells it — panned by the way the listener faces. */
+    direction?: string;
 }
 export interface PlayMusicOptions extends PlaySoundOptions {
-    /** If true and a music track with the same name+key is already playing, do nothing. */
+    /** If true and a music track with the same name (and key, when one is
+     *  given) is already playing, do nothing. Mudlet's default is true; the
+     *  callers supply it, so absent here means false. */
     continue?: boolean;
 }
 export interface StopMusicOptions {
@@ -38,11 +54,62 @@ export interface StopMusicOptions {
     tag?: string;
     /** Fade-out duration in milliseconds. Overrides the source's own fadeout. */
     fadeout?: number;
+    /** Mudlet's `fadeaway`: fade out before stopping — over `fadeout`, else
+     *  the source's own fadeout, else {@link DEFAULT_FADEAWAY_MS} — and keep
+     *  the media listed as playing until the fade is over. */
+    fadeaway?: boolean;
 }
+/**
+ * Which playing media a stop, pause or query applies to. Every field that is
+ * set must match. `name` matches the name a source was played under, the path
+ * it resolved to, or either's trailing filename; `priority` is a ceiling — a
+ * query passes over a source whose own priority is above it, and a stop or
+ * pause also spares one whose priority equals it (only lower priorities are
+ * stopped, as on desktop). A source without a priority counts as 0; `origin`
+ * narrows to script- or server-started media.
+ */
+export interface MediaFilter {
+    name?: string;
+    key?: string;
+    tag?: string;
+    priority?: number;
+    origin?: MediaOrigin;
+}
+export interface StopSoundsOptions extends MediaFilter {
+    /** Fade-out duration in milliseconds. Overrides the source's own fadeout. */
+    fadeout?: number;
+    /** See {@link StopMusicOptions.fadeaway}. */
+    fadeaway?: boolean;
+}
+/** How long a `fadeaway` stop fades for when neither the stop nor the media
+ *  names a fadeout — desktop's TMedia default. */
+export declare const DEFAULT_FADEAWAY_MS = 5000;
+/**
+ * Turns a media name into the path that is actually played. The engine wires
+ * one that finds the file in the profile VFS (so the media events carry its
+ * full path, as desktop's do) and expands a `*`/`?` wildcard to one matching
+ * file. Null means there is no such file: the request is refused there and
+ * then, and never listed as playing. Without a resolver, the name is played as
+ * given.
+ */
+export type MediaPathResolver = (name: string) => string | null;
 export declare class SoundManager {
     private nextId;
     private active;
     private loader;
+    private resolver;
+    /**
+     * Bumped by every {@link stopAll}. `play()` has to await a fetch + decode
+     * before it can build a source, and a profile close (or resetProfile)
+     * landing inside that window would otherwise start the sound *after*
+     * teardown stopped everything — the manager has nothing to stop yet, so the
+     * track begins playing over a closed profile with no way left to reach it.
+     * A play captures the epoch before awaiting and abandons itself if it moved.
+     */
+    private epoch;
+    /** Set by {@link destroy}. Unlike an epoch bump this is permanent: the
+     *  session is gone, so no in-flight or later play may start. */
+    private destroyed;
     /** 0..1, applied as an extra multiplier on every source's gain. */
     private masterVolume;
     /**
@@ -54,6 +121,11 @@ export declare class SoundManager {
      * tearing them down.
      */
     private muted;
+    /** The way the listener faces (TMedia::mListenerFacing), and the one a
+     *  script last chose, which a game's Client.Media.Listener does not
+     *  overwrite (mScriptListenerFacing). */
+    private listenerFacing;
+    private scriptListenerFacing;
     /**
      * Raised when a tracked source starts playing. ScriptingEngine wires this
      * to Mudlet's `sysMediaStarted(file, path, mediaType, key, tag)` — the same
@@ -61,9 +133,11 @@ export declare class SoundManager {
      *
      * 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.
+     * happening. A paused source raises it again when it resumes, as a player
+     * re-entering PlayingState does. Mudlet withholds it for preload-volume
+     * loads; Mudlet Web 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;
     /**
@@ -73,6 +147,9 @@ export declare class SoundManager {
      * each source's onended before stopping, so engine teardown never fires it.
      */
     onMediaFinished?: (file: string, path: string, mediaType: MediaKind, key: string, tag: string) => void;
+    /** Raised when pauseSounds / pauseMusic hold a playing source — Mudlet's
+     *  `sysMediaPaused`, with the same five arguments. */
+    onMediaPaused?: (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
@@ -81,6 +158,7 @@ export declare class SoundManager {
      */
     onMediaCaption?: (info: MediaCaptionInfo) => void;
     setLoader(fn: LoaderFn | null): void;
+    setPathResolver(fn: MediaPathResolver | null): void;
     setMasterVolume(value: number): void;
     /**
      * Mudlet `muteMediaAPI` / `muteMediaGame`. Sets the persistent mute gate for
@@ -97,44 +175,70 @@ export declare class SoundManager {
     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?: {
+    /**
+     * Mudlet `updateSounds` / Client.Media.Update — TMedia::updateMedia. Moves
+     * the script- (or game-) started media `filter` names to a new volume
+     * (1..100), pan or direction, gliding over `glideMs`. Sounds only, unless
+     * `filter.kinds` says otherwise: a Client.Media.Update without a type
+     * reaches music too. A key or tag must be the source's own; a name matches
+     * as a stop's does. Loading and paused sources move too. Pan and direction
+     * place sounds only, and a new direction takes over from a pan given
+     * earlier, or it would never be heard. Returns how many moved.
+     */
+    updateSounds(filter: {
         name?: string;
         key?: string;
         tag?: string;
-    }, kind?: 'sound' | 'music'): Array<{
-        name: string;
-        key?: string;
-        tag?: string;
-        volume: number;
-    }>;
+        origin: MediaOrigin;
+        kinds?: readonly ('sound' | 'music')[];
+    }, change: {
+        volume?: number;
+        pan?: number;
+        direction?: string;
+        glideMs?: number;
+    }): number;
+    /**
+     * Turn the listener to `facing` (canonical; a compass word or degrees) —
+     * TMedia::setListenerFacing. Refused (false) for up, down and the words
+     * relative to the player. Every placed sound without a pan of its own
+     * turns with it.
+     */
+    setListenerFacing(facing: string, setBy: 'script' | 'game'): boolean;
+    /** The way the listener faces now (TMedia::listenerFacing). */
+    getListenerFacing(): string;
+    /** Face the way a script last chose, or north — TMedia::resetListenerFacing,
+     *  for a new connection. */
+    resetListenerFacing(): void;
+    private applyPan;
+    /** Mudlet `stopSounds([filter])` — stop the sounds matching `filter`
+     *  (every sound when it is empty). Only priorities below the filter's are
+     *  stopped. */
+    stopSounds(opts?: StopSoundsOptions): void;
+    /**
+     * Mudlet `pauseSounds([filter])`. A Web Audio source node can't be paused,
+     * so a paused source drops its node and remembers its position; playing
+     * the same name and key again ({@link play}) resumes it from there on a new
+     * node. A string filters by tag, Mudlet's "channel". Music is untouched —
+     * {@link pauseMusic} covers it.
+     */
+    pauseSounds(channel?: string | MediaFilter): void;
+    /** Mudlet `pauseMusic([filter])` — {@link pauseSounds} for music. */
+    pauseMusic(channel?: string | MediaFilter): void;
+    stopMusic(opts?: StopMusicOptions & {
+        origin?: MediaOrigin;
+    }): void;
+    /**
+     * Mudlet getPlayingSounds / getPlayingMusic. Returns the sources of the
+     * requested `kind` (default 'sound' — music is reported separately by
+     * getPlayingMusic) that are playing — from the moment they are asked to
+     * play until they end, a fade-out included — optionally filtered. Mudlet
+     * lists only the media its Lua API started, so the Lua bindings pass
+     * `origin: 'api'`. Volume is reported on Mudlet's 0..100 scale.
+     */
+    getPlaying(filter?: MediaFilter, kind?: 'sound' | 'music'): MediaListing[];
+    /** Mudlet getPausedSounds / getPausedMusic — {@link getPlaying} for the
+     *  sources pauseSounds / pauseMusic hold. */
+    getPaused(filter?: MediaFilter, kind?: 'sound' | 'music'): MediaListing[];
     /**
      * Mudlet loadSoundFile. Preloads (decodes + caches) a sound so the first
      * playSoundFile has no decode latency. Fire-and-forget: warms `decodeCache`
@@ -143,19 +247,81 @@ export declare class SoundManager {
      */
     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.
+     * Mudlet `purgeMediaCache()` — stop every sound and music track, each
+     * raising its sysMediaFinished as TMedia::stopAllMediaPlayers does, and
+     * drop every decoded-audio buffer so the next play re-fetches and
+     * re-decodes. Deleting the cached files themselves is the caller's part.
+     * Always returns true.
      */
     purgeCache(): boolean;
-    /** Stop everything this manager owns. Call on engine teardown. */
+    /** Stop everything this manager owns — including plays still awaiting a
+     *  decode, which abandon themselves rather than starting afterwards. Call
+     *  on engine teardown. */
     stopAll(): void;
     destroy(): void;
+    private resolve;
+    private list;
     private play;
+    /**
+     * Start a pass of `a` at `offsetSec` on a fresh node (a node can be started
+     * once). Web Audio's loop flag only repeats forever, so it serves -1 alone,
+     * looping between start and finish when a finish is set; a finite count
+     * plays each pass on its own node, and each pass is reported with its own
+     * sysMediaStarted / sysMediaFinished, as Mudlet's playlist does. A finish
+     * ends each finite pass there.
+     */
+    private startPass;
+    private onPassEnded;
+    /**
+     * Take `a` off the books and report its end. A stop reports it inside the
+     * call, as desktop's does, but prints the closing caption a turn later:
+     * TMedia releases a stopped player one event-loop turn late, and that turn
+     * is what prints it.
+     */
+    private end;
+    /**
+     * Mudlet's media events are (file, path, mediaType, key, tag): the played
+     * file's name, then its full path. An absent key or tag is an empty
+     * QString there, so it must be '' here and not undefined — a nil would
+     * shift every argument after it in Lua.
+     */
+    private eventArgs;
+    private announceStart;
+    private announceFinish;
+    private pauseKind;
+    /** Where in the track `a`'s current pass has got to, in seconds. */
+    private position;
+    /** Resume the paused source a play request names — see {@link resume}. */
+    private resumeMatching;
+    /**
+     * Resume a paused source of `kind` that the request matches, the way
+     * desktop's isMediaMatch() picks one: each of name, key and tag that the
+     * request gives must match, and it must give at least one. This is how a
+     * server resumes over GMCP with a key or tag alone. Returns the source's
+     * id, or undefined when nothing paused matches.
+     */
+    resume(kind: 'sound' | 'music', req: {
+        name?: string;
+        key?: string;
+        tag?: string;
+        origin?: MediaOrigin;
+    }): number | undefined;
     private fadeAndStop;
-    private isMusicPlaying;
+    /** The music track a `continue` request would carry on with: the same
+     *  name, and the same key when the request gives one. */
+    private playingMusic;
     private stopMusicMatching;
     private updateMediaSessionState;
     private firstActiveMusicName;
 }
+/** One entry of {@link SoundManager.getPlaying} / {@link SoundManager.getPaused}. */
+export interface MediaListing {
+    name: string;
+    key?: string;
+    tag?: string;
+    volume: number;
+    priority?: number;
+    pan?: number;
+    direction?: string;
+}
 export {};

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

@@ -13,7 +13,7 @@
  *  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
+ *  but Mudlet Web'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 {
@@ -24,6 +24,9 @@ export interface MediaCaptionInfo {
     key?: string;
     /** Explicit caption from the media packet / Lua `caption` arg, if any. */
     caption?: string;
+    /** Sounds only: where it comes from (canonical), shown after the caption
+     *  so where a sound comes from never depends on hearing it. */
+    direction?: string;
     action: CaptionAction;
 }
 /**

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

@@ -0,0 +1,35 @@
+/**
+ * Where a sound comes from, and which way the player faces — the placement half
+ * of Mudlet's Client.Media 2 (TMedia::canonicalMediaDirection,
+ * mediaDirectionBearing and stereoPan).
+ *
+ * A direction is kept as desktop keeps it: a compass word ("north",
+ * "northeast", ...), one of the words relative to the player ("ahead",
+ * "behind", "left", "right"), "up" / "down", or whole degrees as a string
+ * ("0" to "359", 0 being north and 90 east).
+ */
+/** The pan range, TMediaData::MediaPanLeft / MediaPanRight. */
+export declare const MEDIA_PAN_LEFT = -100;
+export declare const MEDIA_PAN_RIGHT = 100;
+/** A direction spelled as TMedia keeps it, or '' when it names none. A number
+ *  (or a string reading as one) is whole degrees, wrapped onto 0..359. */
+export declare function canonicalMediaDirection(direction: string | number): string;
+/** The bearing of a canonical direction in degrees, and whether it is relative
+ *  to the way the player faces; null for up, down and anything unknown. */
+export declare function mediaDirectionBearing(direction: string): {
+    bearing: number;
+    relative: boolean;
+} | null;
+/** Whether `facing` is a way a player can turn to: a compass word or degrees,
+ *  not up, down or a word relative to the player. */
+export declare function isListenerFacing(facing: string): boolean;
+/**
+ * The stereo pan (-100..100) a sound is heard at — TMedia::stereoPan. A pan of
+ * its own wins; otherwise its direction is turned by the way the player faces,
+ * clockwise of which is to the right. Ahead and behind both centre, as stereo
+ * cannot tell front from back. Undefined when the sound is not placed at all.
+ */
+export declare function stereoPan(pan: number | undefined, direction: string | undefined, facing: string): number | undefined;
+/** A direction as a caption shows it, after the caption text:
+ *  TMedia::mediaDirectionCaption. */
+export declare function mediaDirectionCaption(direction: string): string;

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

@@ -0,0 +1,53 @@
+/** How much of the main console TCommandLine::handleTabCompletion reads. */
+export declare const TAB_COMPLETION_LINES = 500;
+/**
+ * The candidate words, in the order desktop builds them: the buffer lines
+ * joined with spaces and split at word boundaries, then the suggestions, with
+ * anything on the blacklist (compared case-insensitively) taken out. Only the
+ * word runs of the buffer are kept — the runs between them start with a
+ * non-word character, so no completion pattern could match one anyway.
+ */
+export declare function tabCompletionPool(lines: readonly string[], suggestions?: Iterable<string>, blacklist?: Iterable<string>): string[];
+export interface TabCompletionMatches {
+    /** The text kept in front of the proposal (`mTabCompletionTyped.left(typePosition)`). */
+    userWords: string;
+    /** Candidates in Tab order, newest first; never empty. */
+    matches: string[];
+}
+/**
+ * What a Tab on `typed` can complete to, or null when desktop would do nothing:
+ * nothing typed, a trailing space, or no candidate.
+ *
+ * The word completed is the run of word characters at the very end; a
+ * candidate has to start with it (ignoring case) and carry at least one more
+ * word character straight after (`^<word>\w+`), so `zq` never offers
+ * `zq-thing` and `zqo` never offers `zqo'brien`. Repeats collapse only when
+ * spelled exactly alike — `zqcase` and `ZQCASE` are two candidates — and each
+ * candidate takes the place of its LAST occurrence, so the most recently seen
+ * comes first. When the text ends in some other character there is no word,
+ * desktop's `left(-1)` keeps the whole text, and any word at all is appended.
+ */
+export declare function tabCompletionMatches(typed: string, pool: readonly string[]): TabCompletionMatches | null;
+/**
+ * One command line's Tab state — desktop's mTabCompletionTyped /
+ * mTabCompletionCount / mTabCompletionOld. The first Tab remembers what was
+ * typed; later presses complete that same text again, stepping forward (Tab)
+ * or back (Shift+Tab) through the candidates and stopping at either end rather
+ * than wrapping. Typing anything in between starts over from the new text.
+ */
+export declare class TabCompletionCycle {
+    private typed;
+    private count;
+    private lastWritten;
+    /** Forget the cycle: Escape, Space, Enter, or an edit. */
+    reset(): void;
+    /**
+     * A Tab (`dir` 1) or Shift+Tab (-1) on a line holding `current`. Returns the
+     * new line text and the proposal, or null when there is nothing to complete
+     * (the line is then left as it is).
+     */
+    step(current: string, dir: 1 | -1, pool: () => readonly string[]): {
+        text: string;
+        proposal: string;
+    } | null;
+}

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

@@ -22,13 +22,21 @@ export interface TextEditState {
     tabMovesFocus: boolean;
     visible: boolean;
 }
+/**
+ * The text a QPlainTextEdit gives back for `text` set into it. setPlainText
+ * splits blocks at CR, CRLF and LF alike, and toPlainText joins them — and any
+ * Unicode line or paragraph separator — with LF, turns a no-break space into a
+ * plain one, and leaves off a leading byte order mark.
+ */
+export declare function toPlainText(text: string): string;
 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 a text edit. False when one of that name already exists — it is
+     *  left as it was, as TMainConsole::createTextBox leaves it. */
     create(name: string, opts: {
         parent: string;
         x: number;
@@ -37,7 +45,8 @@ export declare class TextEditManager {
         height: number;
     }): boolean;
     destroy(name: string): boolean;
-    /** Returns the editor's text, or null when no editor of that name exists. */
+    /** Returns the editor's text as QPlainTextEdit::toPlainText() hands it
+     *  back, or null when no editor of that name exists. */
     getText(name: string): string | null;
     setText(name: string, text: string): boolean;
     clear(name: string): boolean;

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

@@ -1,7 +1,7 @@
 /**
  * Connection ids currently open in *another* browser tab.
  *
- * Every open profile holds an exclusive Web Lock named `mudix:profile:<id>`
+ * Every open profile holds an exclusive Web Lock named `mudlet:profile:<id>`
  * (see profileLock.ts), and `navigator.locks.query()` lists held locks across
  * all same-origin tabs — so the held profile locks are exactly the open set.
  * The connection screen renders with no profile active, so this tab holds no

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

@@ -33,6 +33,13 @@ export declare class VideoManager {
      * still reports what the script asked for.
      */
     private muted;
+    /** Bumped by every {@link stopAll}. `play()` awaits a fetch before it can
+     *  build the element, and a profile close inside that window would mount a
+     *  video after teardown already cleared them — the sound-side twin is
+     *  `SoundManager`'s epoch. */
+    private epoch;
+    /** Set by {@link destroy} — permanent, unlike an epoch bump. */
+    private destroyed;
     /** 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