@mudlet/mudlet-web 0.5.0 → 1.0.0

package/dist-lib/ui/cmdline/useCmdLineSelection.d.ts

@@ -0,0 +1,26 @@
+import { type RefObject } from 'react';
+/** Where a script left the command line's caret: at the end with nothing
+ *  selected (printCmdLine, appendCmdLine), or around all of it
+ *  (selectCmdLineText, sendCmdLine). */
+export type CmdLineSelection = 'end' | 'all';
+/**
+ * Place a command line's caret or selection once the text a script put there
+ * has actually reached the input.
+ *
+ * A script's printCmdLine only reaches the input through React state, so the
+ * new value lands on the next commit — and writing a controlled input's value
+ * moves its caret to the end, wiping any selection made before it. Applying
+ * the selection straight away (or from a microtask, which runs before a
+ * render scheduled from a timer) is how `printCmdLine("ghi");
+ * selectCmdLineText()` left nothing selected, so the next keystroke appended
+ * instead of replacing (issue #284). Desktop applies both to the widget
+ * synchronously, so the later call always wins; here the latest request is
+ * held and applied in a layout effect after the commit that carries the text.
+ *
+ * `value` is the input's controlled value. The returned function records a
+ * request and forces a render, so a request with no text change still lands.
+ * A script's request also focuses the input; `focus: false` is for the
+ * client's own selection after a send, which must not pull focus back to an
+ * input the send just let go of (a phone's keyboard).
+ */
+export declare function useCmdLineSelection(inputRef: RefObject<HTMLInputElement | HTMLTextAreaElement | null>, value: string): (selection: CmdLineSelection | null, focus?: boolean) => void;

package/dist-lib/ui/cmdline/useSubCommandLineKeys.d.ts

@@ -0,0 +1,33 @@
+import { type MutableRefObject, type RefObject } from 'react';
+import type React from 'react';
+import type { CmdLineHost, SubCommandLine } from './subCommandLine';
+interface Options {
+    model: SubCommandLine;
+    host: () => CmdLineHost;
+    inputRef: RefObject<HTMLTextAreaElement | null>;
+    /** The line's live text (what getCmdLine reads), kept current by the caller. */
+    valueRef: MutableRefObject<string>;
+    setValue: (text: string) => void;
+    /** Hand one command (one line of the box) to the action, or the game. */
+    dispatch: (command: string) => void;
+    /** The text a script put on this line (printCmdLine and the like) while
+     *  the commands ran, marking it applied; null when none did. */
+    takeScripted: () => string | null;
+}
+/**
+ * Key handling for a named command line — the createCommandLine overlay and a
+ * miniconsole's / user window's own line — driving {@link SubCommandLine}, the
+ * port of desktop's TCommandLine. Returns the textarea's onKeyDown and
+ * onChange.
+ *
+ * The keys desktop's TCommandLine::event takes for itself are taken here too:
+ * Enter sends, Shift+Enter starts another line in the box, Up/Down walk the
+ * history, Tab and Shift+Tab complete, Escape selects everything. Only a Tab
+ * on an empty line, or after a space, is let through, as on the main command
+ * line, so the keyboard can still leave the box (WCAG 2.1.2).
+ */
+export declare function useSubCommandLineKeys({ model, host, inputRef, valueRef, setValue, dispatch, takeScripted }: Options): {
+    onKeyDown: (e: React.KeyboardEvent<HTMLTextAreaElement>) => void;
+    onChange: (e: React.ChangeEvent<HTMLTextAreaElement>) => void;
+};
+export {};

package/dist-lib/ui/codemirror/lineParagraphMarks.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Mudlet's Editor option "Show Line/Paragraphs", as the checkbox is named:
+ * a visible mark where each line of the script ends.
+ *
+ * Desktop currently under-delivers on its own label. `slot_changeShowLineFeeds\
+ * AndParagraphs` (dlgProfilePreferences.cpp:4073) sets edbee's
+ * `useLineSeparator`, which rules a faint horizontal line under each row, and
+ * the method's comment says so: the marks the option is named for "may in the
+ * future" arrive. The tooltip in `profile_preferences.ui:1746` still promises
+ * them — "show line and paragraph ends with visible marks as well as
+ * whitespace" — so that is what this draws, next to `highlightWhitespace()`'s
+ * dots and arrows, which is where the tooltip puts it.
+ *
+ * CodeMirror has no built-in for this (`highlightWhitespace` covers spaces and
+ * tabs only), so it is a decoration: a zero-width widget at every line end,
+ * with the last line marked differently because it has no line feed after it.
+ */
+/** The extension behind the "Show Line/Paragraphs" toggle. */
+export declare function showLineParagraphs(): import("@codemirror/state").Extension[];

package/dist-lib/ui/codemirror/luaHover.d.ts

@@ -0,0 +1,7 @@
+export declare const luaHoverTheme: import("@codemirror/state").Extension;
+/** Signature + description for the Mudlet function under the pointer. Shared by
+ *  the script editor and by a `.lua` file opened from the file browser — the
+ *  same code deserves the same tooltip whichever door you came in through. */
+export declare const luaHover: import("@codemirror/state").Extension & {
+    active: import("@codemirror/state").StateField<readonly import("@codemirror/view").Tooltip[]>;
+};

package/dist-lib/ui/codemirror/options.d.ts

@@ -0,0 +1,33 @@
+import { Compartment, type Extension } from '@codemirror/state';
+/** Mudlet's Editor preference page, which Mudlet Web had no equivalent of: the
+ *  display options and autocomplete were hard-coded on. Held in a compartment
+ *  so a change reconfigures the live editor instead of remounting it, which is
+ *  what the theme swap alongside it already does.
+ *
+ *  Every CodeMirror surface in the app shares these — the script editor and
+ *  the file browser's editor and JSON viewer. "Show Spaces/Tabs" that only
+ *  applied to one of the three would be a setting you have to remember the
+ *  scope of; `useEditorSettings()` is the single source for all of them. */
+export interface EditorOptions {
+    /** "Autocomplete Lua functions in code editor". */
+    autocomplete: boolean;
+    /** "Show Spaces/Tabs" — dots for runs of spaces, arrows for tabs. */
+    showWhitespace: boolean;
+    /** "Show Line/Paragraphs" — a ¶ where each line ends. */
+    showLineParagraphs: boolean;
+    /** "Show invisible Unicode control characters". */
+    showControlChars: boolean;
+    /** "Theme" — the editor palette, pinned or following the app's. */
+    theme: 'app' | 'dark' | 'light';
+}
+export declare const EDITOR_OPTION_DEFAULTS: EditorOptions;
+export declare const optionsCompartment: Compartment;
+/**
+ * The display options as extensions.
+ *
+ * @param lua whether to offer Lua completion — true for the script editor and
+ *            for a `.lua` file opened from the file browser, false for the
+ *            JSON, XML and plain-text documents the same editor also serves,
+ *            where Mudlet's function list is noise.
+ */
+export declare function optionExtensions(opts: EditorOptions, lua: boolean): Extension[];

package/dist-lib/ui/codemirror/theme.d.ts

@@ -1,5 +1,29 @@
-import { Compartment } from '@codemirror/state';
-import { syntaxHighlighting } from '@codemirror/language';
-export declare const mudixCmTheme: import("@codemirror/state").Extension;
-export declare const highlightCompartment: Compartment;
-export declare function highlightFor(theme: string): ReturnType<typeof syntaxHighlighting>;
+import { Compartment, type Extension } from '@codemirror/state';
+export declare const mudletCmTheme: Extension;
+export declare const paletteCompartment: Compartment;
+/**
+ * Mudlet's Editor → Theme, as far as it makes sense here. Desktop downloads a
+ * catalogue from colorsublime; Mudlet Web ships the two palettes it already has and
+ * lets you pin one, which is the part of that feature people actually use — a
+ * dark editor under a light app theme, or the reverse.
+ *
+ * `app` is the default and keeps the old behaviour exactly.
+ */
+export type EditorTheme = 'app' | 'dark' | 'light';
+export declare const EDITOR_THEME_CHOICES: {
+    value: EditorTheme;
+    label: string;
+}[];
+/**
+ * The whole palette for one editor: syntax colours, plus — when the theme is
+ * pinned — the chrome that goes with them.
+ *
+ * Pinning means pinning: "Atom One Light" under a dark app theme is a light
+ * editor, background and all, not light syntax colours floating on a black
+ * page. `'app'` returns highlighting alone and leaves the chrome on whatever
+ * CSS vars the document carries, which is also what keeps a brand theme's own
+ * surface colours from being flattened into the stock two.
+ *
+ * @param theme the app theme, consulted only when `editorTheme` is 'app'.
+ */
+export declare function paletteFor(theme: string, editorTheme?: EditorTheme): Extension;

package/dist-lib/ui/commands/addonCommands.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Mudlet's addon command API — the commands a package places on the client's
+ * own surfaces (`addCommand`, `removeCommand`, `enableCommand`, …).
+ *
+ * This holds the state and the answers; the argument contract in front of it
+ * lives in Bridge.lua, because the refusals name the Lua type of what they were
+ * given ("surfaces has to be a list of surface names and this one holds a
+ * boolean") and a value's Lua type is exactly what does not survive the trip
+ * across wasmoon.
+ *
+ * What "reserved" means here is worth being straight about. On desktop Mudlet
+ * answers "is this key free?" by asking Qt what is currently wired to the
+ * window. There is no widget tree to ask in a browser tab, so the keys Mudlet
+ * itself holds are written down below instead — a mirror of another
+ * application's keyboard map, and it will need revisiting when Mudlet moves a
+ * shortcut. The alternative was to reserve nothing, which is technically true
+ * of a client with no menu bar and useless to a package author: a shortcut
+ * accepted here and refused on desktop is a bug report either way, and the
+ * quiet version (Qt disables BOTH bindings when two things claim one key) is
+ * the worse of the two to debug.
+ */
+/** Where a command can be placed. Absent means both, never neither. */
+export type CommandSurface = 'menu' | 'toolbar' | 'both';
+export interface AddonCommand {
+    id: number;
+    name: string;
+    icon: string;
+    tooltip: string;
+    menuPath: string;
+    shortcut: string;
+    surfaces: CommandSurface;
+    enabled: boolean;
+    checked: boolean;
+    /** Mudlet shows a pinned command in every profile's window, not just its
+     *  own. A page here holds one profile, so this is kept and reported but
+     *  there is no second window for it to appear in. */
+    pinned: boolean;
+    pulse: {
+        colour: string;
+        altColour: string;
+        intervalMs: number;
+    } | null;
+    /** The package or module whose code placed it, or '' for the profile's. */
+    owner: string;
+}
+/** A request as Bridge.lua hands it over, already type-checked there. */
+export interface CommandRequest {
+    name: string;
+    icon?: string;
+    tooltip?: string;
+    menuPath?: string;
+    shortcut?: string;
+    surfaces?: CommandSurface;
+    owner?: string;
+}
+/** Qt's QKeySequence holds four steps and silently drops the rest, so a longer
+ *  sequence binds a key nobody asked for. */
+export declare const MAX_SHORTCUT_STEPS = 4;
+/** Normalised for comparison only — case and spacing carry no meaning in a Qt
+ *  key sequence, so "Ctrl+Alt+L" and "ctrl+alt+l" are one key. */
+export declare function normaliseShortcut(shortcut: string): string;
+export declare class AddonCommandRegistry {
+    private readonly commands;
+    /** Monotonic and never reused: an id that has been removed must answer as
+     *  unknown for good, not come back as a different command. */
+    private nextId;
+    private listeners;
+    /** Whether the buffer search currently holds its key. Pushed in rather than
+     *  read out, so this file needs no store dependency. */
+    private searchActive;
+    /** Which platform's key map Mudlet would be answering from. Pushed in for
+     *  the same reason. */
+    private reserved;
+    /**
+     * What the client's own commands hold right now, normalised key → the name
+     * to quote back. Separate from `reserved` because that one is a mirror of
+     * Mudlet's fixed map, while these move: the player can rebind any of them
+     * (see `appShortcuts.ts`), and a package asking about the key they moved it
+     * TO deserves the truth rather than "free".
+     */
+    private clientKeys;
+    setPlatform(platform: string): void;
+    /** Told by the UI whenever the client's own bindings change: normalised key
+     *  → the command's name. */
+    setClientShortcuts(keys: ReadonlyMap<string, string>): void;
+    subscribe(fn: () => void): () => void;
+    private notify;
+    list(): AddonCommand[];
+    get(id: number): AddonCommand | undefined;
+    /**
+     * Who holds `shortcut`, or null when it is free. `null` for an empty
+     * shortcut too — asking for no key is not a clash.
+     *
+     * A command of THIS profile is named outright; Mudlet's own keys answer
+     * with the reserved name. The spec tells the two apart deliberately: a
+     * package author can fix a clash with their own command, and needs to know
+     * when they cannot.
+     */
+    holderOf(shortcut: string, ignoreId?: number): string | null;
+    /** Commands currently on `shortcut` — what the buffer search needs to know
+     *  before it takes its key back. */
+    commandsOn(shortcut: string): AddonCommand[];
+    get searchHoldsItsKey(): boolean;
+    get searchShortcut(): string;
+    /** Told by the config layer, because the search is a preference rather than
+     *  anything this registry owns. */
+    setSearchActive(active: boolean): void;
+    add(request: CommandRequest): number;
+    remove(id: number): boolean;
+    /** Take away every command the package or module `owner`'s code placed —
+     *  once it is gone nothing knows their ids, and left behind they would
+     *  stay on screen and hold their shortcuts against its own reinstall. */
+    removeOwnedBy(owner: string): void;
+    setEnabled(id: number, enabled: boolean): boolean;
+    setChecked(id: number, checked: boolean): boolean;
+    setPinned(id: number, pinned: boolean): boolean;
+    setIcon(id: number, icon: string): boolean;
+    setTooltip(id: number, tooltip: string): boolean;
+    setPulse(id: number, pulse: AddonCommand['pulse']): boolean;
+    /** Whether the command has a button to colour — the pulse needs one, and a
+     *  menu-only command has none. */
+    hasButton(id: number): boolean;
+    private mutate;
+    /** The commands with a button, in placement order — what the toolbar draws.
+     *  A disabled command keeps its button and is drawn unavailable, which is
+     *  what enableCommand/disableCommand are for; a removed one is gone. */
+    buttons(): AddonCommand[];
+    /** The commands with a menu entry, in placement order — what the menu bar
+     *  draws. Same rule as `buttons()`: a disabled one keeps its entry and is
+     *  drawn unavailable, and only a removed one is gone. */
+    menuItems(): AddonCommand[];
+    /** Profile teardown. */
+    clear(): void;
+}

package/dist-lib/ui/commands/appShortcuts.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The client's own keyboard shortcuts — Mudlet's menu accelerators, and the
+ * handful of things this client has that Mudlet does not.
+ *
+ * Mudlet's are fixed, compiled into the menu actions. These are defaults: the
+ * settings dialog can move any of them, and the stored override is what the
+ * dispatcher and the menu labels both read. That is the one place this
+ * deliberately goes further than Mudlet — in a browser a shortcut can collide
+ * with something the browser or an extension already holds, and a player who
+ * cannot reach the script editor because Alt+E is spoken for has no recourse
+ * unless the binding moves.
+ *
+ * The keys themselves are Mudlet's, including the platform split: the menu
+ * group is Alt on Windows and Linux and Ctrl on macOS (mudlet.cpp:1462-1512),
+ * where Alt is a text-entry modifier. Commands Mudlet has no key for start
+ * unbound rather than being given one this client invented — a player who wants
+ * one can say so, and a default that disagreed with Mudlet's would be a trap
+ * for anyone who uses both.
+ *
+ * Mudlet's profile-switching keys (Ctrl+1…9, Ctrl+Tab) are absent by design:
+ * multiple profiles here are multiple browser tabs, and the browser owns those
+ * keys. `addonCommands.ts` still reserves them against packages, because a
+ * package written for desktop Mudlet will expect them to be taken.
+ */
+import { type StockToolbarButton } from '../../branding';
+/** Everything the client can be asked to do from the keyboard. */
+export type AppCommandId = 'connect' | 'disconnect' | 'reconnect' | 'closeProfile' | 'scriptEditor' | 'map' | 'notepad' | 'files' | 'logs' | 'toggleReplay' | 'preferences' | 'toggleTimestamps' | 'mute' | 'toggleLogging' | 'fullscreen' | 'toggleButtonBar' | 'inputLine' | 'docs' | 'help' | 'about';
+export interface AppShortcutDef {
+    id: AppCommandId;
+    label: string;
+    /**
+     * The stock button this command belongs to, where it has one. A brand that
+     * hid the button has removed the feature, so the shortcut goes with it —
+     * both the binding and its row in the settings. A key that still opened the
+     * script editor after the brand took the script editor away would be a back
+     * door into something they deliberately removed.
+     */
+    stock?: StockToolbarButton;
+    /** The menu this command lives in, so the settings list is grouped the way
+     *  the menu bar is rather than as one flat run of nineteen rows. */
+    group: 'Games' | 'Toolbox' | 'Options' | 'Window' | 'Help';
+    /** Mudlet's key on Windows and Linux, and on macOS. Empty on both where
+     *  Mudlet has no key for it. */
+    defaultKey: string;
+    defaultKeyMac: string;
+}
+/** Mudlet's menu group: Alt+<letter> on Windows and Linux, Ctrl+<letter> on
+ *  macOS. Written out rather than generated so each entry is greppable. */
+export declare const APP_SHORTCUTS: readonly AppShortcutDef[];
+/**
+ * The commands this build actually exposes.
+ *
+ * A brand that hid a stock button removed the feature, and a shortcut is
+ * another door onto the same room — so the binding goes with the button, and so
+ * does its row in the settings. Otherwise a white-label client that took the
+ * script editor away would still open it on Alt+E, and offer to rebind it.
+ *
+ * Commands with no `stock` id (timestamps, logging, fullscreen, the bars, the
+ * command line, About) belong to no button and are always available.
+ */
+export declare function availableShortcuts(): readonly AppShortcutDef[];
+/** The order the settings list draws the groups in — the menu bar's own. */
+export declare const SHORTCUT_GROUPS: readonly AppShortcutDef['group'][];
+/** Which key map this machine gets, in the same spelling `getOS()` uses so the
+ *  addon-command registry and this agree on what "mac" means. */
+export declare function shortcutPlatform(): string;
+/** What the client would use with nothing overridden. `platform` is what
+ *  `getOS()` reports: 'mac' picks Mudlet's macOS key. */
+export declare function defaultShortcut(def: AppShortcutDef, platform: string): string;
+/** What a stored override means. A key that is present and empty is a binding
+ *  the player deliberately cleared, which is not the same as never having
+ *  touched it — clearing has to survive a default changing under them. */
+export type ShortcutOverrides = Readonly<Record<string, string>>;
+/** The key actually in force for `def`. */
+export declare function effectiveShortcut(def: AppShortcutDef, overrides: ShortcutOverrides | undefined, platform: string): string;
+/** A reader for one command's key, for the menu entries that draw it beside
+ *  their label. Undefined rather than empty for an unbound command, so a menu
+ *  entry can leave the column blank rather than drawing nothing-in-particular. */
+export declare function shortcutLookup(overrides: ShortcutOverrides | undefined, platform: string): (id: AppCommandId) => string | undefined;
+/** Every command with a key, as `{id, label, shortcut}`. Commands with no key
+ *  are left out — there is nothing to dispatch or to warn about. */
+export declare function boundShortcuts(overrides: ShortcutOverrides | undefined, platform: string): {
+    id: AppCommandId;
+    label: string;
+    shortcut: string;
+}[];

package/dist-lib/ui/commands/hostCommands.d.ts

@@ -0,0 +1,88 @@
+/**
+ * `addCommand` for the application embedding this client.
+ *
+ * A package written in Lua can already place a command on the toolbar and the
+ * menu bar and change it afterwards. A white-label host had no equivalent: it
+ * could declare buttons in its `BrandConfig` at boot and nothing after, so a
+ * command that appears when the player logs in, or greys out while a request is
+ * in flight, meant re-rendering the whole client with a new brand object.
+ *
+ * This is the same contract from JavaScript. It is a module-level singleton
+ * rather than a React context on purpose — a host app's command usually lives
+ * next to the state that decides whether it should be there, which is rarely a
+ * component inside the client's tree.
+ *
+ * Ids are strings and never reused, so a removed command's id answers as
+ * unknown for good rather than coming back as something else.
+ */
+import type { ReactNode } from 'react';
+import type { BrandToolbarContext } from '../../branding';
+import type { CommandSurface } from './addonCommands';
+export interface HostCommandRequest {
+    /** The caller's own id, if it wants one — `commands.remove('roll')` then
+     *  works without holding on to what `add` returned. Absent gets a generated
+     *  one. Placing a second command under an id that is taken replaces it. */
+    id?: string;
+    /** Shown on the button and the menu entry. */
+    name: string;
+    /** An image URL, or any node — an inline SVG needs no round trip through a
+     *  file. Sized to the text by the stylesheet either way. */
+    icon?: ReactNode;
+    tooltip?: string;
+    /** Where on the menu bar: '/'-separated, the first segment naming a
+     *  top-level menu (an existing title joins it, a new one opens a menu at
+     *  the end of the bar). Absent puts it among the other package tools. */
+    menuPath?: string;
+    /** Qt-style key sequence, e.g. "Ctrl+Alt+K". */
+    shortcut?: string;
+    /** Which bars it appears on. Absent means both. */
+    surfaces?: CommandSurface;
+    enabled?: boolean;
+    checked?: boolean;
+    /**
+     * Run when the command is picked. The context is the same one brand
+     * toolbar buttons get: `send` a command as if typed, `raiseEvent` for the
+     * profile's Lua handlers, and the open profile's id.
+     *
+     * Called with null when no profile is open — a command can be placed before
+     * the player has picked one, and refusing to fire silently would be worse
+     * than letting the host decide.
+     */
+    onClick: (ctx: BrandToolbarContext | null) => void;
+}
+export interface HostCommand extends HostCommandRequest {
+    id: string;
+    surfaces: CommandSurface;
+    enabled: boolean;
+    checked: boolean;
+}
+export declare class HostCommandRegistry {
+    private readonly commands;
+    private next;
+    private readonly listeners;
+    /** The snapshot handed to React. Rebuilt on change rather than on read, so
+     *  `useSyncExternalStore` sees a stable reference between changes and does
+     *  not re-render on every commit. */
+    private snapshot;
+    subscribe: (fn: () => void) => (() => void);
+    /** Every placed command, in placement order — which is drawing order. */
+    list: () => readonly HostCommand[];
+    private changed;
+    /** Place a command. Returns its id, for everything below. */
+    add(request: HostCommandRequest): string;
+    /** False for an id nobody knows, rather than throwing — one sequence covers
+     *  every command, so an unknown id names nothing at all. */
+    remove(id: string): boolean;
+    /** Change anything about a placed command except its id. */
+    update(id: string, patch: Partial<HostCommandRequest>): boolean;
+    setEnabled(id: string, enabled: boolean): boolean;
+    setChecked(id: string, checked: boolean): boolean;
+    setIcon(id: string, icon: string): boolean;
+    setTooltip(id: string, tooltip: string): boolean;
+    /** Drop everything. For a host tearing its own UI down; the client never
+     *  calls this, since these commands outlive any one profile. */
+    clear(): void;
+}
+/** The one registry the client reads. Exported from the package root as
+ *  `commands`. */
+export declare const hostCommands: HostCommandRegistry;

package/dist-lib/ui/commands/keyMatch.d.ts

@@ -0,0 +1,20 @@
+/**
+ * One step in its canonical spelling: modifiers in a fixed order, lower case,
+ * joined to the key by '+'. "Ctrl+Alt+L", "alt+ctrl+l" and "CTRL+ALT+L" all
+ * become "ctrl+alt+l".
+ */
+export declare function canonicalStep(step: string): string;
+/** A whole sequence as canonical steps, or null when Qt could not read it. */
+export declare function canonicalSequence(shortcut: string): string[] | null;
+/** The key half of a step, from a physical key code. Null for a modifier key
+ *  pressed on its own — holding Ctrl is not yet a shortcut. */
+export declare function keyNameFromCode(code: string): string | null;
+/** A keypress in the same spelling as `canonicalStep`, or null when it is not
+ *  a key a shortcut can be built from. */
+export declare function stepFromEvent(e: Pick<KeyboardEvent, 'code' | 'ctrlKey' | 'altKey' | 'shiftKey' | 'metaKey'>): string | null;
+/** Whether a step carries a modifier. A bare key is not safe to dispatch while
+ *  the player is typing into something. */
+export declare function stepHasModifier(step: string): boolean;
+/** Written the way a person reads it: "Ctrl+Alt+L", "Alt+E", "F3". Steps in a
+ *  multi-step sequence are joined with ", " as Qt writes them. */
+export declare function formatSequence(steps: readonly string[]): string;

package/dist-lib/ui/commands/keySequence.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Qt key-sequence parsing, as much of it as deciding whether to accept a
+ * package's shortcut needs.
+ *
+ * Counting the steps in "Ctrl+Alt+F1, Ctrl+Alt+F2" looks like splitting on
+ * commas until you meet the two characters that are both punctuation AND keys:
+ *
+ *   "Ctrl+,"        the comma key. One step, not two of nothing.
+ *   "Ctrl++"        the plus key. One step whose last character is the same
+ *                   one that joins a modifier to its key.
+ *   "Ctrl+,, X"     the comma key, then a separator, then X. Two steps.
+ *   "Ctrl++, X"     the plus key, then a separator, then X. Two steps — and
+ *                   the reading that looks at what precedes the comma calls
+ *                   this one, which is how a five-step sequence slipped past
+ *                   the length check to be truncated by Qt after all.
+ *
+ * So this parses rather than splits: each step is its modifiers, then exactly
+ * one key, and only a comma that follows a completed key is a separator. Qt
+ * steps over that separator and the single space after it, which is why a
+ * sequence written with a trailing one — what generating a list in a loop
+ * produces — is the steps it names and not one more of nothing.
+ */
+/** Qt's QKeySequence holds this many steps and silently drops the rest. */
+export declare const MAX_STEPS = 4;
+export interface SequenceProblem {
+    /** 'length' when the sequence has more steps than Qt can hold, 'key' when a
+     *  step names something Qt cannot read. */
+    kind: 'length' | 'key';
+    /** The unreadable chunk, for a 'key' problem. */
+    chunk?: string;
+}
+/**
+ * The steps in a Qt key sequence, or a problem describing why it is not one.
+ * An empty (or whitespace-only) shortcut is no shortcut at all and parses to
+ * zero steps, which is not an error — a command may simply have no key.
+ */
+export declare function parseKeySequence(shortcut: string): {
+    steps: string[];
+} | {
+    problem: SequenceProblem;
+};
+/**
+ * A shortcut as a key binding would hold it: one DOM `KeyboardEvent.code` plus
+ * the modifiers pressed with it.
+ *
+ * Null for anything a binding cannot be: a sequence of more than one step (a
+ * binding is one key and its modifiers, so a two-step sequence can never be the
+ * one holding it — as `mudlet::addonShortcutUsable` decides with
+ * `sequence.count() == 1`), an empty shortcut, or a key the browser has no code
+ * for.
+ */
+export declare function shortcutAsBinding(shortcut: string): {
+    code: string;
+    modifiers: string[];
+} | null;
+/** The refusal a package should read, or null when the sequence is fine. */
+export declare function shortcutProblemMessage(shortcut: string): string | null;

package/dist-lib/ui/components/ContextMenu.d.ts

@@ -3,7 +3,27 @@ interface ContextMenuProps {
     x: number;
     y: number;
     onClose: () => void;
+    /** Accessible name for the menu, e.g. "Output actions". */
+    label?: string;
+    /** Override for popups that are not lists of commands — the script editor's
+     *  colour picker is a grid of swatches, and calling that a menu when it holds
+     *  no menuitem misdescribes it. */
+    role?: 'menu' | 'group';
+    /** Where to hand focus back on close, when that is not the element the menu
+     *  was opened from. The output console needs this: a right-click focuses the
+     *  console (it is a tab stop), but the player types into the command line, so
+     *  returning focus to the opener would send their next keystroke nowhere. */
+    returnFocusTo?: () => HTMLElement | null | undefined;
+    /** Extra class on the menu box, for a screen that styles its menus to
+     *  match its own layout (the launcher's are larger than the app's). */
+    className?: string;
     children: React.ReactNode;
 }
-export declare function ContextMenu({ x, y, onClose, children }: ContextMenuProps): import("react").ReactPortal;
+/**
+ * Where an arrow/Home/End press should move within a menu of `count` entries,
+ * given the currently focused index (-1 when focus is outside). Returns null for
+ * keys the menu doesn't handle. Wraps at both ends. Pure — exported for testing.
+ */
+export declare function nextMenuIndex(count: number, current: number, key: string): number | null;
+export declare function ContextMenu({ x, y, onClose, label, role, returnFocusTo, className, children }: ContextMenuProps): import("react").ReactPortal;
 export {};

package/dist-lib/ui/components/FontPicker.d.ts

@@ -4,6 +4,10 @@ interface FontPickerProps {
     value: OutputFontSource | undefined;
     onChange: (next: OutputFontSource | undefined) => void;
     vfs: ProfileVFS | null;
+    /** What is drawn with when nothing is chosen. The main display falls back to
+     *  the browser's monospace; the map's room symbols to the bundled Bitstream
+     *  Vera Sans Mono — so the picker has to be told, rather than assert one. */
+    fallbackLabel?: string;
 }
-export declare function FontPicker({ value, onChange, vfs }: FontPickerProps): import("react/jsx-runtime").JSX.Element;
+export declare function FontPicker({ value, onChange, vfs, fallbackLabel }: FontPickerProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist-lib/ui/components/useModalFocus.d.ts

@@ -12,8 +12,20 @@ export interface ModalFocusOptions {
      *  modal manages its own initial focus (e.g. a specific field or button). */
     autoFocus?: boolean;
     /** Close on Escape via `onClose`. Default true. Set false when the modal has
-     *  its own Escape handling (then `onClose` may be omitted). */
+     *  its own Escape handling (then `onClose` may be omitted). Read live on
+     *  every key, so it may vary over the dialog's life — a dialog can hand
+     *  Escape to an inner editor for exactly as long as that editor is open
+     *  (the file browser's inline rename does) without the trap being torn
+     *  down and re-armed, which would re-grab focus. */
     closeOnEscape?: boolean;
+    /** Gate for a dialog whose node is not in the DOM on the first render — a
+     *  portal whose container is only known after a layout effect, say. The
+     *  setup below runs once, off a null ref, and refs don't re-render, so
+     *  without this the trap, the Escape handler and the focus restore are all
+     *  silently skipped (issue #49). Flip it true in the render that mounts the
+     *  dialog node. One-way: flipping it back to false counts as a close and
+     *  restores focus to the opener. Default true (node present immediately). */
+    ready?: boolean;
     /** Where focus should land on close, instead of the opener. Use when the
      *  dialog was raised by the game rather than by a click, so "the opener" is
      *  either nothing or a control that has since gone away — the GMCP login

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

@@ -11,6 +11,21 @@ export interface HelpTopic {
 }
 export declare const HELP_TOPICS: HelpTopic[];
 export declare const DEFAULT_HELP_TOPIC: string;
+/**
+ * Add a topic that only some builds have.
+ *
+ * The manual is otherwise a fixed list, but a few features are stock-app-only —
+ * the credential vault above all — and a branded build must not carry
+ * documentation for something it doesn't ship. Those topics are registered from
+ * `main.tsx` at boot, alongside the feature itself, so they never enter the
+ * library's module graph. See `vault/vaultAccess` for the same seam.
+ *
+ * Idempotent, and ordered by `after` rather than appended, so an added topic
+ * lands next to the one it relates to instead of at the bottom.
+ */
+export declare function registerHelpTopic(topic: HelpTopic, opts?: {
+    after?: string;
+}): void;
 /** Resolve a markdown link href to a topic id, or null if it isn't one of ours.
  *  Handles `./storage.md`, `storage.md`, `docs/help/storage.md` and a `#anchor`
  *  suffix — the shapes a relative link between these files can take. */