@mudlet/mudlet-web 0.5.0 → 1.0.1

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

@@ -1,6 +1,7 @@
 import type { AnsiAwareBuffer } from './text/FormatState';
 import type { MspCommand } from './protocol';
 import type { ScriptLogSource } from './MudSession';
+import type { CharLoginCapabilities, CharLoginResult, CharLoginToken, CharLoginUrl } from './protocol/charLoginFlow';
 export type SessionStatus = 'disconnected' | 'connecting' | 'connected';
 /** The peer certificate as reported by the proxy. Mirrors the four fields
  *  Mudlet shows (issuer / issued-to / expiry / serial) plus a little extra for
@@ -69,9 +70,35 @@ export type MudClientEvents = {
     'open': [event: Event];
     'close': [event: CloseEvent];
     'error': [error: unknown];
+    /** The link to the game is up — Mudlet's `slot_socketConnected`. Through
+     *  the proxy this waits for the proxy to reach the game (see
+     *  `client.established`, which always follows it), so a dial that never
+     *  gets there never raises it. */
     'client.connect': void;
+    /** The connection, or the attempt at one, is over. Raised for an attempt
+     *  that failed too — Mudlet raises sysDisconnectionEvent for both — which
+     *  listeners tell apart by whether `client.connect` came first. */
     'client.disconnect': void;
+    /** Raised straight after `client.disconnect`, once every listener on it has
+     *  run. Mudlet reports a lost connection *after* sysDisconnectionEvent
+     *  (ctelnet.cpp slot_socketDisconnected), so the notice hangs off this. */
+    'client.disconnected': void;
     'client.error': [message: string];
+    /** One of cTelnet's `[ WARN  ]` notices about the data stream (a broken
+     *  MCCP stream, a read too big to inflate), in desktop's words: the first
+     *  line carries the prefix, any after a `\n` are its continuation. */
+    'client.warning': [message: string];
+    /** The link to the *game* is up — the point in Mudlet's
+     *  `slot_socketConnected` where `mConnectionTimer` starts (ctelnet.cpp:723).
+     *  Emitted immediately after `client.connect`, for the same socket; kept as
+     *  its own event for the things that time a session (the proxy accepts our
+     *  WebSocket before it dials the game, so the WebSocket opening is never the
+     *  moment to measure from). Fires at most once per socket,
+     *  on whichever comes first of the proxy's `game.connected` control frame, a
+     *  completed TLS handshake, or the first byte of game traffic — and
+     *  immediately on open for a direct websocket, where there is no second leg.
+     *  Anything measuring how long a session lasted wants this one. */
+    'client.established': void;
     /** The WebSocket subprotocol the server selected from our advertised list
      *  (RFC 6455), or '' if none — only emitted when we advertised any. */
     'client.subprotocol': [protocol: string];
@@ -94,6 +121,9 @@ export type MudClientEvents = {
         port: number;
     }];
     'gmcp.negotiated': void;
+    /** Round trip (ms) from a game command to the next GA/EOR prompt marker —
+     *  Mudlet's command-reply network latency measurement. */
+    'network.latency': [duration: number];
     'msdp.negotiated': void;
     'mssp.negotiated': void;
     'msp.negotiated': void;
@@ -117,8 +147,10 @@ export type MudClientEvents = {
      *  on a server that skipped negotiation. Only telnet-negotiated MXP gets the
      *  `<SUPPORTS>`/`<VERSION>` handshake replies — an in-band-only server's
      *  inbound MXP channel isn't confirmed, so replying would spam it with
-     *  invalid commands. */
-    'mxp.negotiated': [viaTelnet: boolean];
+     *  invalid commands. `viaSubnegotiation` marks a bare `IAC SB MXP IAC SE`,
+     *  which is reported every time it arrives — each one puts the processor
+     *  back in locked mode — where the rest are reported once. */
+    'mxp.negotiated': [viaTelnet: boolean, viaSubnegotiation?: boolean];
     /** Fired for every `!!SOUND` / `!!MUSIC` tag parsed from the in-band text
      *  stream (or an `IAC SB MSP ... IAC SE` subnegotiation body). The
      *  scripting engine wires this to the SoundManager. */
@@ -126,11 +158,18 @@ export type MudClientEvents = {
     /** Fires when a CHARSET (RFC 2066) negotiation completes — either the
      *  server's REQUEST was ACCEPTED or our advertised REQUEST was ACCEPTED.
      *  Argument is the IANA charset name as agreed (the wire spelling, e.g.
-     *  "UTF-8"). */
-    'charset.negotiated': [encoding: string];
+     *  "UTF-8"). `acceptedRequest` is true only when it was the server's
+     *  REQUEST that this client ACCEPTED — the one case Mudlet saves. */
+    'charset.negotiated': [encoding: string, acceptedRequest?: boolean];
     'socket.incoming': [data: string];
     'socket.outgoing': [data: string];
-    'message': [text?: string | AnsiAwareBuffer, type?: string, timestamp?: number, isPrompt?: boolean];
+    /** `joinedTo`: the buffer lines this text was written onto instead of a
+     *  line of its own — a command echoed onto the GA prompt line it was typed
+     *  at (TConsole::printCommand's insertInLine branch). */
+    'message': [text?: string | AnsiAwareBuffer, type?: string, timestamp?: number, isPrompt?: boolean, joinedTo?: AnsiAwareBuffer[]];
+    /** A line from the game that a trigger deleted before it was shown, so
+     *  no `message` carries it (TBuffer::commitLine's gagged branch). */
+    'line.gagged': [];
     'flushLines': [groups: {
         text: string;
         type: string;
@@ -153,20 +192,38 @@ export type MudClientEvents = {
         name: string;
         value: string;
     }];
-    'gmcp.core.ping': [value: unknown];
-    /** Fires when the server requests GMCP login (Char.Login.Default). The
-     *  argument is the list of supported authentication methods it advertised
-     *  (e.g. `["password-credentials"]`). The UI shows a credentials popup and
-     *  replies via `sendCharLoginCredentials` — or an empty reply (cancel) to
-     *  fall back to the server's text login prompt. */
-    'charLogin.request': [methods: string[]];
+    /** A zMUD channel-102 subnegotiation (telnet option 102), which carries
+     *  exactly two bytes: Aardwolf's variable number and its value. Reaches Lua
+     *  as the `channel102` table plus a `channel102Message` event. */
+    'channel102': [payload: {
+        variable: number;
+        value: number;
+    }];
+    /** An inbound ATCP message (telnet option 200), split as desktop's
+     *  `setATCPVariables` does: `name` keys the Lua `atcp` table and is the
+     *  event raised, `value` the string both carry. */
+    'atcp': [payload: {
+        name: string;
+        value: string;
+    }];
+    /** Fires when the server requests GMCP login (Char.Login.Default), with
+     *  everything the frame advertised: the negotiated version, the methods
+     *  (e.g. `["password-credentials", "oauth"]`) and any client-driven OAuth
+     *  capability. `CharLoginController` decides how to answer. */
+    'charLogin.request': [capabilities: CharLoginCapabilities];
+    /** Fires on `Char.Login.URL` — the game offering a page to sign in on.
+     *  `null` when the address was missing, unparseable or not http(s), which
+     *  is reported rather than rendered: it arrives unauthenticated. Can arrive
+     *  at any point in a session, not just at login. */
+    'charLogin.url': [link: CharLoginUrl | null];
+    /** Fires on `Char.Login.Token` — a password-less reconnect token, issued at
+     *  the game's discretion. A bearer secret: never log it. A malformed frame
+     *  raises nothing. */
+    'charLogin.token': [token: CharLoginToken];
     /** Fires when the server reports a GMCP login outcome (Char.Login.Result).
      *  `success` is true on a successful authentication; on failure `message`
      *  carries the server's human-readable reason (e.g. "Invalid credentials"). */
-    'charLogin.result': [result: {
-        success: boolean;
-        message?: string;
-    }];
+    'charLogin.result': [result: CharLoginResult];
     /** Fires when the command input should switch in/out of password masking.
      *  True only for a genuine password prompt (server enabled ECHO *after* it
      *  began sending output); a connect-time server-wide ECHO suppresses local
@@ -177,21 +234,34 @@ export type MudClientEvents = {
      *  point the client sends `IAC DONT ECHO` and refuses any further ECHO
      *  negotiation for the rest of the connection. */
     'telnet.echo.anomaly': void;
-    /** Mudlet `sysTelnetEvent(type, option, message)` — fired for telnet
-     *  IAC commands the client doesn't natively recognise (everything other
-     *  than the hardcoded GMCP/MSDP/TTYPE/MCCP/ECHO negotiations). */
+    /** Mudlet `sysTelnetEvent(type, option, message)` — fired for every
+     *  telnet IAC command except GA/EOR, handled options included. `type` is
+     *  the command byte (251 WILL, 252 WONT, 253 DO, 254 DONT, 250 SB, …),
+     *  `message` a byte-string: a subnegotiation's unescaped payload without
+     *  its framing, any other command whole. */
     'telnet.event': [type: number, option: number, message: string];
     /** Mudlet `raiseProtocolEvent("sysProtocolRejected", name)` — a telnet
-     *  option mudix deliberately refuses. mudix, like Mudlet, operates in line
+     *  option Mudlet Web deliberately refuses. Mudlet Web, like Mudlet, operates in line
      *  mode only, so it rejects SUPPRESS_GO_AHEAD (option 3) and LINEMODE
      *  (option 34) rather than let the server switch it into character-at-a-
      *  time / server-driven line editing. The payload is the protocol name
      *  (`'SUPPRESS_GO_AHEAD'` or `'LINEMODE'`). */
     'protocol.rejected': [protocol: string];
+    /** Mudlet `raiseProtocolEvent("sysProtocolEnabled", name)` — a telnet
+     *  option the client has just agreed to (the server offered it with WILL,
+     *  or asked for it with DO, and the profile allows it). The payload is
+     *  Mudlet's name for the protocol, which is what reaches Lua as the second
+     *  argument of `sysProtocolEnabled`: `GMCP`, `MSDP`, `MSSP`, `MSP`, `MXP`,
+     *  `CHARSET`, `NEW_ENVIRON`, `NAWS` or `channel102`. */
+    'protocol.enabled': [protocol: string];
+    /** The other half of the pair: the option is off again, because the server
+     *  withdrew it (WONT/DONT) or because the profile refuses an offer it had
+     *  previously taken up. Same names as `protocol.enabled`. */
+    'protocol.disabled': [protocol: string];
     /** Mudlet `sysCharacterModeDetected`. Fires once per connection when the
      *  server has both asked to suppress go-ahead (IAC WILL SGA) *and* kept
      *  server-side echo on across a submitted game command — the
-     *  character-at-a-time signature that mudix, a line-based client, can't
+     *  character-at-a-time signature that Mudlet Web, a line-based client, can't
      *  drive well. The three-second delay is what separates it from an ordinary
      *  password mask, which negotiates the same pair but releases echo as soon
      *  as the masked line is in. Lets scripts / the UI warn the user that input
@@ -204,16 +274,26 @@ export type MudClientEvents = {
      *  redials. Fires at most once per connection, and never once the profile's
      *  `promptForVersionInTTYPE` latch is set. */
     'kavir.detected': void;
+    /** An IAC GA/EOR arrived. The next line flushed is the one it ended — an
+     *  empty one for a bare marker, as in Mudlet. */
+    'prompt': void;
 } & Record<string, any>;
 export type MudEvents = MudClientEvents & {
     'status': [status: SessionStatus];
+    /** The client ACCEPTed a server's CHARSET REQUEST and that changed the
+     *  session's encoding. Argument is the `SUPPORTED_SERVER_ENCODINGS`
+     *  spelling. Raised by MudSession for ScriptingAPI to save to the profile,
+     *  as cTelnet does with `setEncoding(acceptedEncoding, true)`. */
+    'charset.accepted': [encoding: string];
     'ping': [duration: number | null];
     'script.log': [text: string, level: 'error' | 'info', source?: ScriptLogSource];
     'output.ready': void;
     'script.deleteline': void;
     'script.clearwindow': void;
     'script.appendcmd': [text: string];
-    'script.setcmd': [text: string];
+    /** `selectAll`: sendCmdLine and link PROMPTs select what they put there;
+     *  printCmdLine and appendCmdLine leave the caret at the end. */
+    'script.setcmd': [text: string, selectAll?: boolean];
     'script.clearcmd': void;
     'script.selectcmd': void;
     'script.cmdlinesuggestions': [items: string[]];
@@ -227,7 +307,6 @@ export type MudEvents = MudClientEvents & {
      *  (ProfileSession) shows the in-app VFS picker and resolves the request
      *  via `request.onPick`. See {@link FileDialogRequest}. */
     'script.filedialog': [request: FileDialogRequest];
-    'prompt': void;
     'script.movecursorup': void;
     'script.movecursordown': void;
     /** A Mudlet-format replay started playing. Payload is the recording's

package/dist-lib/mud/games/bundledGames.d.ts

@@ -1,3 +1,6 @@
+/** How a game installs its own full interface (Mudlet's `GameDetail::OwnUi`,
+ *  less `None`). */
+export type GameOwnUi = 'bundledLoader' | 'clientGui';
 /** One entry of Mudlet's bundled-game catalogue (its C++ `GameDetail`). */
 export interface BundledGame {
     name: string;
@@ -13,9 +16,11 @@ export interface BundledGame {
      *  the bundler only emits assets it can see referenced. */
     iconFile?: string;
     description: string;
-    /** The game's own loader installs its full interface, so the generic
-     *  starter UI is not preinstalled for it. */
-    providesOwnUi?: boolean;
+    /** How the game installs its own full interface, if it does (Mudlet's
+     *  `GameDetail::OwnUi`): `bundledLoader` — a loader bundled with Mudlet
+     *  fetches it; `clientGui` — the game sends a Client.GUI package, often
+     *  only after login. Absent means neither (`OwnUi::None`). */
+    ownUi?: GameOwnUi;
     /** Other hostnames the game answers on. */
     alternateHostUrls?: string[];
 }
@@ -23,7 +28,7 @@ export declare const BUNDLED_GAMES: readonly BundledGame[];
 /** The bundled game called `name`, matched the way Mudlet matches it
  *  (TGameDetails::findGame — exact, case-sensitive). */
 export declare function findBundledGame(name: string): BundledGame | null;
-/** Whether the game reachable at `hostUrl` installs its own full interface,
- *  in which case the generic starter UI is not preinstalled (Mudlet's
- *  TGameDetails::gameProvidesOwnUi). */
-export declare function gameProvidesOwnUi(hostUrl: string): boolean;
+/** How the game reachable at `hostUrl` (or any of its alternate hostnames,
+ *  case-insensitively) installs its own full interface — `'none'` when it
+ *  doesn't, or isn't a bundled game at all. Mudlet's TGameDetails::gameOwnUi. */
+export declare function gameOwnUi(hostUrl: string): GameOwnUi | 'none';

package/dist-lib/mud/games/gameLinks.d.ts

@@ -0,0 +1,40 @@
+import { type BundledGame } from './bundledGames';
+import type { MudConnection } from '../../storage';
+/**
+ * Deep links into the bundled-game catalogue, so a page elsewhere (mudlet.org's
+ * game list, a MUD's own site) can hand someone a "Play Astaria" button that
+ * lands them in the client with that game already picked.
+ *
+ * The link never creates anything on its own: the landing screen offers the
+ * player's existing profiles for the game and a prefilled Add form, the same
+ * choice a click on the game's tile gives. A bookmarked link is therefore safe
+ * to open repeatedly — it can't quietly pile up profiles.
+ */
+/** Query parameter carrying the game — `?play=astaria`. */
+export declare const GAME_LINK_PARAM = "play";
+/** URL-safe id for a game name: lowercase, runs of anything else collapsed to
+ *  a single dash. "Avalon.de" → `avalon-de`, "God Wars II" → `god-wars-ii`.
+ *  No two catalogue entries share a slug (pinned by a test). */
+export declare function gameSlug(name: string): string;
+/**
+ * The games this client offers — listed in the grid, and the only ones a
+ * `?play=` link resolves to. Sorted by name, which is the order the grid draws
+ * them in.
+ */
+export declare const PLAYABLE_GAMES: readonly BundledGame[];
+/** The playable game a `?play=` value names. Accepts the slug or the exact
+ *  name (`?play=Avalon.de` works as well as `?play=avalon-de`), so a hand-written
+ *  link doesn't have to know the slugging rule. Null for anything else. */
+export declare function findGameByLink(value: string | null | undefined): BundledGame | null;
+/** The link that opens `game` in a client hosted at `base`. What you paste into
+ *  a "Play <game>" button on a website. */
+export declare function gameLinkUrl(game: BundledGame, base: string): string;
+/** The player's existing profiles for `game`, in launcher order. */
+export declare function profilesForGame(game: BundledGame, connections: MudConnection[]): MudConnection[];
+/** The bundled game a profile is for, or null if it isn't one of them. What
+ *  lets the launcher draw the game's logo on a profile that carries no icon of
+ *  its own — including one renamed, or created as a second "Achaea (2)". */
+export declare function findGameForConnection(connection: MudConnection): BundledGame | null;
+/** The connection record a game turns into. Mudlet's catalogue is host/port, so
+ *  these are proxied `mud` profiles — the same thing the Add form builds. */
+export declare function connectionFromGame(game: BundledGame): Omit<MudConnection, 'id'>;

package/dist-lib/mud/games/websiteLinks.d.ts

@@ -0,0 +1,21 @@
+import type { BundledGame } from './bundledGames';
+/**
+ * Mudlet's catalogue carries each game's off-site links as a small HTML
+ * fragment (`websiteInfo`), which desktop drops straight into a `website_entry`
+ * label (`dlgConnectionProfiles.cpp`). A browser must not do the same: the
+ * fragment is vendored upstream data, and injecting foreign HTML into the page
+ * to render two anchors is a poor trade. So we read the anchors out and let the
+ * caller render real elements.
+ */
+export interface GameLink {
+    /** Anchor text as shown — "Website", "Forum", "Discord". */
+    label: string;
+    href: string;
+}
+/** The off-site links a game's `websiteInfo` names, in the order it lists them.
+ *  Anchors with no label, no usable href, or a duplicate href are dropped. */
+export declare function parseWebsiteLinks(websiteInfo: string | undefined): GameLink[];
+/** Whether `game` should show for a catalogue filter of `query`. Matches the
+ *  name, the address and the blurb, so both "achaea" and "roleplay" find
+ *  something; an empty query matches everything. */
+export declare function gameMatchesQuery(game: BundledGame, query: string): boolean;

package/dist-lib/mud/keybindings/KeyEngine.d.ts

@@ -7,18 +7,63 @@ export interface KeyCodeInfo {
     keyCode: number;
     modifiers: number;
 }
+/** A permanent key's getKeyCode answer: the Qt::Key it was made with when
+ *  known, else its code's, and the mask with the Keypad bit a Numpad* code
+ *  implies. A group has no key of its own, and a code outside Qt's range — a
+ *  group's -1 in a package, or a number no key has — reads as Key_unknown, as
+ *  desktop's TKey keeps it. */
+export declare function permKeyCode(node: Pick<KeyNode, 'key' | 'modifiers' | 'qtKey'> & {
+    isGroup?: boolean;
+}): KeyCodeInfo;
 export declare class KeyEngine {
     private readonly temp;
     private perm;
     /** Shared with every other engine in the profile — see ItemIdSequence. */
     private idSeq;
     setIdSequence(seq: ItemIdSequence): void;
-    /** Number of live session-scoped temp keys (Mudlet `getProfileStats` temp
-     *  count). Killed-but-unreaped keys are not live and don't count. */
+    private regCounter;
+    private readonly permReg;
+    /** Each key in {@link perm} → the seq of the root it hangs under. */
+    private permRootSeq;
+    /** Temp keys in the tree (Mudlet `getProfileStats` temp count) — killed
+     *  ones too, until the cleanup frees them: KeyUnit::assembleReport walks
+     *  the tree, and a killed key stays in it until doCleanup(). */
     get tempCount(): number;
+    /** Of {@link tempCount}, the keys that are still active. */
+    get tempActiveCount(): number;
+    /** Each permanent key hanging off a temporary one (as of the last
+     *  loadPerm) → that temporary root's id; and the parent refs in use. */
+    private permTempRoot;
+    private tempParentRefs;
+    private orphanedParents;
+    private onOrphans;
+    /** Tree keys of freed temp keys that had permanent children, since the
+     *  last call. Their owner removes those subtrees from the store. */
+    takeOrphanedParents(): string[];
+    /** Told when {@link takeOrphanedParents} has something to hand over. */
+    setOrphanListener(fn: (() => void) | null): void;
+    /** In the tree and not killed — what exists() and findItems() count. */
+    hasLiveTemp(id: number): boolean;
+    /** Live, switched on and compiled — isActive(). */
+    tempIsActive(id: number): boolean;
+    /** Live temp key ids, ascending, whose name — the id itself — passes `test`. */
+    liveTempIds(test: (name: string) => boolean): number[];
+    /** The temp key named `name` — a temp key is named after its id — or
+     *  null; a killed one only when `includeDead` (perm* parent resolution). */
+    newestTempByName(name: string, includeDead: boolean): number | null;
+    /** `killKey(name)` for the temporaries. */
+    killTempByName(name: string): boolean;
+    /** The order seq of a permanent key's root — for one hanging off a
+     *  temporary key, that key's. */
+    private rootSeqOf;
+    /** Whether a permanent key is reached at all: under a temporary key only
+     *  while that key is active (TKey::match tests its children only then). */
+    private reachable;
     addTemp(key: string, modifiers: string[], fn: TempFn, qt?: {
         keyCode: number;
         modifier: number;
+        uncompiled?: boolean;
+        onFree?: () => void;
     }): number;
     /** Whether a temp key with this id is live — backs exists(id, "key"). */
     hasTemp(id: number): boolean;
@@ -36,8 +81,69 @@ export declare class KeyEngine {
     /** Free every key killed since the last call. Runs once per processed line
      *  batch, mirroring the deferred cleanup Mudlet's TKeyUnit does. */
     reapKilled(): void;
-    processTemp(event: KeyboardEvent): boolean;
-    loadPerm(keybindings: KeyNode[]): void;
+    /** @param all Mudlet's "React to all keybindings on the same key": run
+     *  every enabled match instead of stopping at the first. Snapshot the
+     *  values first — a handler may create or kill a temp key, and mutating the
+     *  map mid-iteration is exactly the case Mudlet's deferred `reapKilled`
+     *  exists to avoid. */
+    processTemp(event: KeyboardEvent, all?: boolean): boolean;
+    /** Run one temp key if it is live and `event` is its key. */
+    private fireTemp;
+    /**
+     * A keypress's whole key pass: temporary and permanent keys alike, in the
+     * one order desktop's `mKeyRootNodeList` holds them (creation order, see
+     * the unified-ordering note above). The first match fires and ends the
+     * pass, unless `all` (Mudlet's "React to all keybindings on the same key")
+     * asks for every match. Running all the temps first put a tempKey made
+     * after a permKey ahead of it (mudlet-web#340). Temps fire themselves; a
+     * permanent hit goes to `firePerm`. Both lists are snapshots taken when the
+     * pass began — a handler may make, kill or toggle keys. True when anything
+     * fired.
+     */
+    process(event: KeyboardEvent, all: boolean, firePerm: (binding: KeyNode) => void): boolean;
+    /** `blocked`: bindings whose code will not compile, which Mudlet leaves
+     *  inactive — see buildEffectivelyEnabledIds. */
+    loadPerm(keybindings: KeyNode[], blocked?: ReadonlySet<string>): void;
+    /** Every saved binding with a key, switched on or not — see {@link holderOf}. */
+    private permHolders;
+    /**
+     * Give the profile's saved keys their place in the firing order before any
+     * script can make a temporary one. Desktop builds them from the profile
+     * before a script runs, so a tempKey a script makes at load time sorts
+     * after them — but here the scripts run before the first {@link loadPerm},
+     * which then reuses the seqs reserved here.
+     */
+    reserveOrder(items: readonly {
+        id: string;
+    }[]): void;
+    /** The first permanent keybinding the event matches, in tree order — the
+     *  permanent half of {@link process}, for callers that ask about the
+     *  saved keys alone. */
     matchPerm(event: KeyboardEvent): KeyNode | null;
+    /** Every permanent keybinding the event matches, in tree order. The list
+     *  form of {@link matchPerm}, for Mudlet's "React to all keybindings on the
+     *  same key". */
+    matchAllPerm(event: KeyboardEvent): KeyNode[];
+    /**
+     * Which binding of this profile holds `key` + `modifiers` — Mudlet's
+     * `KeyUnit::firstMatch`, asked with a key rather than an event.
+     *
+     * What needs it is `addCommand`: a key binding is the one holder a
+     * command's shortcut cannot see, since it lives here and is matched from
+     * the command line's key handling rather than by any menu or widget, so a
+     * command placed on a binding's key takes the event and the binding simply
+     * stops firing. Temporary and permanent are searched alike (they are one
+     * list in Mudlet's key unit), and a temporary one answers with no name: it
+     * is named after its own id, which names nothing a player could go and look
+     * for.
+     *
+     * A switched-off binding still holds its key — on its own or through its
+     * group — since scripts switch bindings on and off and enableKey() does not
+     * look for commands; one killed does not, as it can never fire again.
+     */
+    holderOf(key: string, modifiers: string[]): {
+        name: string;
+        temporary: boolean;
+    } | null;
     destroy(): void;
 }

package/dist-lib/mud/keybindings/browserReservedKeys.d.ts

@@ -2,7 +2,7 @@
  * Some keyboard shortcuts are owned by the browser (or the OS) and are handled
  * *above* the web page — Ctrl+T opens a new tab, Ctrl+W closes it, F12 opens
  * devtools. The page never receives the keydown (or can't suppress it), so a MUD
- * keybinding on one of these can never fire in mudix.
+ * keybinding on one of these can never fire in mudlet.
  *
  * Real Mudlet runs natively and binds these freely; opened in a browser they
  * silently do nothing, which is baffling. We scan the loaded keybindings on
@@ -11,7 +11,7 @@
  *
  * We deliberately do NOT warn about page-level shortcuts the browser owns but a
  * page can still capture with preventDefault — Ctrl+R (reload), Ctrl+S (save),
- * Ctrl+P (print), Ctrl+F (find), F5, Ctrl+L, etc. mudix intercepts those, so they
+ * Ctrl+P (print), Ctrl+F (find), F5, Ctrl+L, etc. Mudlet Web intercepts those, so they
  * work exactly like they do in Mudlet: while the client has keyboard focus.
  *
  * Keys are stored as DOM `KeyboardEvent.code` strings (see {@link KeyNode}), so we

package/dist-lib/mud/keybindings/keyEventTarget.d.ts

@@ -10,8 +10,69 @@
  * Typing a command is the app's resting state, not a text-entry mode that
  * should own every hotkey.
  *
+ * The command lines scripts make are command lines too, not text entry:
+ * `createCommandLine` (and Geyser.CommandLine on top of it) and a miniconsole's
+ * or user window's `enableCommandLine`. Every desktop TCommandLine — main,
+ * SubCommandLine and ConsoleCommandLine alike — runs the same `event()`, which
+ * offers its keys to the KeyUnit, so a binding fires from any of them.
+ *
  * Real text entry elsewhere — the Lua script editor (CodeMirror, so
  * `contentEditable`), a modal's form field, the script tree's filter box —
  * does keep the event to itself.
  */
 export declare function isTextEntryTarget(target: EventTarget | null): boolean;
+/** Whether `target` is a command line — the main one or a script-made one. */
+export declare function isCommandLineTarget(target: EventTarget | null): boolean;
+/**
+ * Whether the command line claims `e` for itself before any keybinding sees it.
+ *
+ * Desktop's `TCommandLine::event` handles these combinations outright and only
+ * offers a key to the keybinding engine when it is pressed with some OTHER set
+ * of modifiers — so a binding on plain Up never fires from the command line,
+ * while one on Alt+Up does:
+ *
+ *  - Return: plain (send), Ctrl (clearSplit), Shift (newline)
+ *  - Up/Down: plain (history), Ctrl (move the caret between rows)
+ *  - Tab and Space: plain or Shift (completion, typing)
+ *  - Backspace: plain, Ctrl and/or Shift (editing)
+ *  - Escape, PageUp, PageDown, Delete: plain
+ *
+ * Cmd counts as Ctrl, as Qt maps it on macOS.
+ *
+ * None of that holds on the numpad. Qt reports a numpad key with
+ * KeypadModifier set, so "plain" Enter or Up there is not plain to
+ * TCommandLine: numpad Enter and NumLock-off numpad 8/2/9 reach the key unit
+ * first, and a Keypad+Enter or Keypad+Up binding fires instead of sending the
+ * command or walking the history. With no binding on the key the command line
+ * still gets it (the keybinding listener lets the event through), so numpad
+ * Enter sends as before.
+ */
+export declare function commandLineReservesKey(e: KeyboardEvent): boolean;
+/**
+ * Wire the keybinding engine to `doc`'s keydown events; returns the cleanup.
+ *
+ * Keys typed into the command line are offered in the CAPTURE phase, before
+ * CommandBar's own handler runs, and a binding that fires consumes the key —
+ * desktop's TCommandLine::event asks the key unit first and stops there, so a
+ * bound Alt+Return must not also stage a newline (and send an empty command
+ * with the next Enter). The combinations the command line reserves (see
+ * {@link commandLineReservesKey}) never reach a binding from there.
+ *
+ * That capture listener sits on the WINDOW, not the document. The client's own
+ * shortcuts (Ctrl+F's find bar, Ctrl+Shift+P's quick-open, F3) are capture
+ * listeners on the document, and `stopPropagation` does not stop a sibling
+ * listener on the same node — so with both on the document a binding on one of
+ * those keys ran AND opened the find bar, which then took focus and the rest
+ * of the typing (mudlet-web#340). The window's capture runs before any of them,
+ * and a binding that fires stops the event there, as desktop's binding
+ * replaces the find bar.
+ *
+ * The exception is a menu accelerator (`yieldTo`): on desktop Alt+K is a
+ * QAction's shortcut, which Qt resolves before the command line ever sees the
+ * key, so a binding on it does not run. A key `yieldTo` claims is left alone.
+ *
+ * Everywhere else keeps a bubble-phase listener, so a modal's own key handling
+ * still gets first say, and real text entry (see {@link isTextEntryTarget})
+ * keeps its keys.
+ */
+export declare function listenForKeybindings(doc: Document, processKey: (e: KeyboardEvent) => boolean, yieldTo?: (e: KeyboardEvent) => boolean): () => void;