@mudlet/mudlet-web 0.5.0 → 1.0.0

package/dist-lib/storage/schema.d.ts

@@ -1,6 +1,6 @@
 import type { WindowOpenOptions } from '../ui/windows/types';
 import type { MudletVariable } from '../import/mudletVariables';
-export declare const DEFAULT_PROXY_URL = "wss://mudix.delwing.workers.dev";
+export declare const DEFAULT_PROXY_URL = "wss://web-proxy.mudlet.org";
 export type ConnectionMode = 'mud' | 'websocket';
 export interface MudConnection {
     id: string;
@@ -15,6 +15,20 @@ export interface MudConnection {
      *  `undefined`/`false` = open offline (default); the "Connect" button always
      *  dials regardless. */
     autoReconnect?: boolean;
+    /** Mudlet's *other* connection option, `autoreconnect` (read per profile in
+     *  `Host.cpp:344-345`, written by
+     *  `dlgConnectionProfiles::slot_updateAutoReconnect`): when a connection
+     *  that had settled drops for any reason the user didn't ask for, redial it
+     *  once, straight away and silently (`cTelnet::slot_socketDisconnected`,
+     *  ctelnet.cpp:918-923).
+     *
+     *  {@link autoReconnect} above is Mudlet's `autologin` in spite of its name
+     *  — it only decides whether *opening* the profile dials — and renaming it
+     *  would orphan every existing profile unless something moved them, the
+     *  way `storageMigration.ts` moved the storage keys. Nobody has written that
+     *  for this field, so the second option gets a name of its own. See
+     *  `hooks/useAutoReconnect`. */
+    reconnectOnDrop?: boolean;
     /** Profile icon shown on the connection-selection screen (Mudlet's profile
      *  icon, set by setProfileIcon / read by getProfileIcon / cleared by
      *  resetProfileIcon). Stored as a self-contained `data:` URI. Lives on the
@@ -56,6 +70,12 @@ export interface MudConnection {
      *  profiles created after it shipped, and never lands on top of a layout
      *  someone already built. See `stockDefaults`. */
     createdAt?: string;
+    /** When this profile last reached its game (ms since epoch), stamped on
+     *  `client.established` — a socket that opened but never got through to the
+     *  game, or a profile opened offline, doesn't count. Orders the launcher
+     *  (most recent first, the newest in the "Continue playing" banner). Absent
+     *  means never played since the field shipped. */
+    lastConnectedAt?: number;
     /** Connect to the game over TLS — Mudlet's `mSslTsl` / the connection
      *  dialog's "secure connection" checkbox. Meaningful in `mud` (proxy) mode
      *  only: the browser cannot wrap a raw socket itself, so the proxy performs
@@ -125,6 +145,16 @@ export interface ClientSettings {
      *  triggered (a real user gesture), so the first script notification can fire
      *  without a surprise permission pop-up. */
     notificationsEnabled?: boolean;
+    /**
+     * Keyboard-shortcut overrides, keyed by `AppCommandId` (see
+     * `ui/commands/appShortcuts.ts`), each a Qt-style sequence such as
+     * "Ctrl+Alt+L". Application-wide rather than per-profile, as Mudlet's are.
+     *
+     * An id that is absent uses the default for the platform. An id present
+     * with an empty string is a binding the player deliberately cleared, which
+     * is not the same thing — clearing has to survive a default changing.
+     */
+    shortcuts?: Record<string, string>;
 }
 /** Per-profile settings. Scripts (setBorder, setFont, setBackgroundColor, …) and
  *  the in-profile settings modal write here. Each field's value falls through to
@@ -155,6 +185,11 @@ export interface ProfileSettings {
      *  ("Allow secure connection reminder"), settable from Lua via
      *  `setProfileConfig("askTlsAvailable", …)`. */
     askTlsAvailable?: boolean;
+    /** Which engine the console's "Search on …" context-menu entry uses. A key
+     *  of {@link SEARCH_ENGINES}; anything else (or undefined) falls back to
+     *  {@link DEFAULT_SEARCH_ENGINE}, the way Mudlet's `Host::getSearchEngine`
+     *  does. Per-profile, because Mudlet keeps it on the Host. */
+    searchEngine?: string;
     showTimestamps: boolean;
     fontSize: number;
     outputBackground: string;
@@ -169,8 +204,10 @@ export interface ProfileSettings {
     /** Background color for the local echo of commands you send. Empty/undefined = none. */
     commandEchoBackground?: string;
     outputFont?: OutputFontSource;
-    /** Mudlet setWindowWrap("main", N). 0/undefined disables character-based wrap
-     *  (text fills the window width). */
+    /** Mudlet setWindowWrap("main", N) — Host::mWrapAt. Defaults to 100, as on
+     *  desktop: lines longer than it are stored and drawn as several lines. 0
+     *  turns the character wrap off (text fills the window width), a Mudlet Web
+     *  escape hatch the Settings field offers and setWindowWrap refuses. */
     outputWrapAt?: number;
     /** Mudlet setWindowWrapIndent("main", N). Indent (chars) of newline-started lines. */
     outputWrapIndent?: number;
@@ -211,8 +248,8 @@ export interface ProfileSettings {
      *  the built-in default). `undefined` for the whole array = no override. */
     ansiPalette?: (string | undefined)[];
     /** Mudlet "Allow server to redefine your colors". When enabled, the server
-     *  may remap the ANSI/256 palette at runtime via OSC 4 (set color) / OSC 104
-     *  (reset). When disabled, those sequences are ignored and the user palette
+     *  may remap the sixteen ANSI colours at runtime via `ESC]P<i><rrggbb>` (set
+     *  colour) / `ESC]R` (reset). When disabled, those sequences are ignored and the user palette
      *  stands. Off by default — only an explicit `true` enables it. */
     serverRedefineColors?: boolean;
     /** Mudlet 5.0's `Host::mEnableOSC8Hyperlinks` ("Enable OSC 8 hyperlinks").
@@ -224,7 +261,7 @@ export interface ProfileSettings {
      *  flipped would never end. On by default: only an explicit `false`
      *  disables it, matching Mudlet's `= true` default. Unlike most of these,
      *  Mudlet exposes no `setConfig` key for it — preferences and the profile
-     *  XML only — so mudix doesn't invent one either. */
+     *  XML only — so Mudlet Web doesn't invent one either. */
     osc8Hyperlinks?: boolean;
     /** Mudlet 5.0's `Host::mUndoServerWrap` ("Undo the game's own wrapping",
      *  experimental). Rejoins the lines a game hard-wrapped itself before
@@ -236,11 +273,80 @@ export interface ProfileSettings {
      *  `mUndoServerWrapWidth`, bounded 20–500 and defaulting to 80 (very often
      *  the right answer). `setConfig("undoServerWrapWidth", …)`. */
     undoServerWrapWidth?: number;
+    /** Mudlet's `Host::mConsoleBufferSize` ("Main display size") — how many
+     *  lines of scrollback the main output keeps before the oldest are dropped
+     *  in batches. Bounded 100 … 1,000,000; `undefined` uses
+     *  {@link MAIN_CONSOLE_BUFFER_SIZE} (100,000 lines, `Host.h`).
+     *  Round-trips through the profile XML as `consoleBufferSize`
+     *  (XMLexport.cpp:617). `setConsoleBufferSize("main", …)` writes it (and
+     *  {@link useMaxConsoleBufferSize}) back, as desktop's
+     *  `Host::setMainConsoleBufferSize` does, so a script's size is saved. */
+    consoleBufferSize?: number;
+    /** Mudlet's `Host::mUseMaxConsoleBufferSize` ("use the maximum buffer size
+     *  your system can handle", `checkBox_useMaxBufferSize`). When true the
+     *  configured {@link consoleBufferSize} is ignored in favour of the ceiling.
+     *  Desktop derives that ceiling from physical memory
+     *  (`TBuffer::getMaxBufferSize()`); a browser tab cannot ask, so Mudlet Web uses
+     *  a fixed 1,000,000-line cap. Off unless explicitly true. */
+    useMaxConsoleBufferSize?: boolean;
     /** Mudlet "Network packet timeout": how long (ms) to buffer a partial line
      *  (text after the last `\n` of a WebSocket frame) before flushing it as a
      *  prompt. Mitigates spurious mid-line breaks when long MUD lines arrive
      *  fragmented. `undefined` = use MudClient's built-in default (300ms). */
     promptTimeoutMs?: number;
+    /** Mudlet's "Server data encoding": how the game's bytes are decoded into
+     *  text, for games that don't negotiate CHARSET. One of
+     *  `SUPPORTED_SERVER_ENCODINGS`, spelled as that list spells it. Applied on
+     *  profile open and carried across reconnects by `MudSession`. A script's
+     *  `setServerEncoding()` rewrites it, and so does an encoding the client
+     *  ACCEPTs from a server's CHARSET REQUEST when that changes the encoding —
+     *  both as cTelnet::setEncoding(…, true) saves it in Mudlet. A REJECTED
+     *  request leaves it alone. Older saves may say `CP1161` — see
+     *  `savedServerEncoding`. `undefined` = UTF-8. */
+    serverEncoding?: string;
+    /** Mudlet's "Highlight history": a command recalled with Up/Down comes back
+     *  selected rather than with the caret at its end, so the next keystroke
+     *  replaces it, and Up/Down with typed text searches history by prefix.
+     *  On unless explicitly false, as on desktop (XMLimport's
+     *  readDefaultTrueBool). */
+    highlightHistory?: boolean;
+    /** Mudlet's "Disable password masking": show the characters in the command
+     *  line while the game has echo off. Off unless explicitly true. */
+    disablePasswordMasking?: boolean;
+    /** Mudlet's "React to all keybindings on the same key": when several
+     *  keybindings share a key and modifiers, run every enabled one instead of
+     *  stopping at the first that matches. Off unless explicitly true. */
+    reactToAllKeybindings?: boolean;
+    /** Mudlet's "Stop selecting a word on these characters": the extra
+     *  characters a double-click treats as a word boundary in the main display.
+     *  Empty or unset uses the browser's own word rules. */
+    doubleClickIgnore?: string;
+    /** Mudlet's "Make 'Ambiguous' E. Asian width characters wide": render the
+     *  Unicode East Asian *Ambiguous* characters (box-drawing glyphs, ★ ♠ and
+     *  friends) two columns wide instead of one. A tri-state, like Mudlet's
+     *  checkbox: true or false is a chosen width, unset is "auto" — wide only
+     *  for the CJK server encodings (see effectiveAmbiguousWidthWide). Read and
+     *  written by `get/setConfig("ambiguousEAsianWidthCharacters")` as well. */
+    ambiguousWidthWide?: boolean;
+    /** Mudlet's "Enable text analyzer" (`Host::mEnableTextAnalyzer`): put an
+     *  "Analyse characters" entry on a console's right-click menu, reporting the
+     *  UTF-16/UTF-8 encoding of the selected text. Off unless explicitly true,
+     *  as on desktop — it is a diagnostic for a pattern that will not match, not
+     *  something to carry in the menu every day. */
+    enableTextAnalyzer?: boolean;
+    /** Mudlet's "Expect Color Space Id in SGR...(3|4)8;2;...m codes": read
+     *  24-bit colour as `38;2;<id>;r;g;b` (the ITU T.416 spelling, with a
+     *  colour-space id) rather than `38;2;r;g;b`. Off unless explicitly true. */
+    expectColorSpaceId?: boolean;
+    /** Mudlet's Editor preference page. Each field falls back to
+     *  `EDITOR_OPTION_DEFAULTS` when unset. */
+    editor?: EditorSettings;
+    /** Mudlet's "System/Mudlet dictionary" spell-check switch, as near as a
+     *  browser gets: turn the browser's own spellchecker on for the command
+     *  line. Off unless explicitly true — a MUD command line is full of words
+     *  no dictionary has, so red underlines everywhere is the wrong default.
+     *  Never applied to the password field. */
+    spellCheckInput?: boolean;
     /** Per-area MapPanel last-viewed z-level. Each area remembers which level
      *  you were on so switching between areas (or reopening the panel) restores
      *  it. Zoom is no longer kept here — it lives in the map file (per-area
@@ -254,6 +360,16 @@ export interface ProfileSettings {
      *  area on panel mount; the matching {@link mapViewStates} entry drives
      *  the initial level. Falls through to the first area in the map. */
     mapLastAreaId?: number;
+    /** Mudlet's "report map issues on screen" (`mudlet::mShowMapAuditErrors`):
+     *  post the map's sanity-check report on the main console when a map is
+     *  loaded, instead of keeping it to itself. Off unless explicitly true, as
+     *  on desktop — and the audit only runs at all when it is on, so a clean
+     *  profile pays nothing for it on a large map.
+     *
+     *  Desktop's alternative when this is off is a report file it points you at;
+     *  there is no such file here (nothing writes outside the profile VFS on its
+     *  own), so off means the report is simply not made. */
+    reportMapIssues?: boolean;
     /** Whether the map widget's control bar — area picker, z-level buttons,
      *  options menu — is shown. Mudlet's `Host::mShowPanel`: toggled by the
      *  collapse arrow drawn over the map, readable/writable from Lua as
@@ -267,18 +383,35 @@ export interface ProfileSettings {
      *  enabled so existing profiles opt in without a migration; set to `false`
      *  to stop recording for this profile. */
     loggingEnabled?: boolean;
+    /** The Notepad's send controls (Send all / line / selection, Prepend,
+     *  Stop) are shown. Hidden unless set, as desktop keeps them
+     *  (`Notepad/SendControlsVisible` in the profile's ini). */
+    notepadSendControls?: boolean;
     /** Flash the browser tab title (Mudlet's taskbar-blink equivalent) when new
-     *  server data arrives while the mudix tab/window is unfocused. Off unless
+     *  server data arrives while the Mudlet Web tab/window is unfocused. Off unless
      *  explicitly set to true. */
     notifyOnNewData?: boolean;
     /** Mirror script/trigger/alias/timer errors into the main output window (in
      *  red), in addition to the script editor's Errors tab. Mudlet's "Show
      *  errors in main console" preference. Off unless explicitly set to true. */
     showErrorsInMainWindow?: boolean;
-    /** Fullscreen mode: hide the top toolbar so the output area fills the whole
-     *  window, revealing the toolbar only when the pointer nears the top edge (or
-     *  it takes keyboard focus). Off unless explicitly set to true. */
-    fullscreen?: boolean;
+    /** Mudlet's menu-bar visibility (Settings → "Icons and toolbars"): the row
+     *  holding the client's own menus. On unless explicitly set to false.
+     *
+     *  Mudlet's setting has three values — never, only without a loaded
+     *  profile, always — and the middle one describes a window this client does
+     *  not have: the session screen only exists once a profile IS loaded, so
+     *  "only without one" and "never" would be the same switch. Hence a
+     *  two-state one. */
+    showMenuBar?: boolean;
+    /** The same for Mudlet's main toolbar — the row of buttons under the menus.
+     *  On unless explicitly set to false.
+     *
+     *  Never false at the same time as `showMenuBar`: a client with neither has
+     *  no way back to its own settings, which is the clash Mudlet's preference
+     *  guards against too (its "Never" entry greys out in one control while the
+     *  other holds it). */
+    showToolbar?: boolean;
     /** User-tunable subset of mudlet-map-renderer's Settings object. Fields
      *  are forwarded onto the live renderer.settings on mount and whenever
      *  the user changes them in the Mapper tab. Missing fields fall through
@@ -305,7 +438,7 @@ export interface ProfileSettings {
     uninstalledPackages?: string[];
     /** Catch-all bag for Mudlet `setConfig`/`getConfig` option keys that have no
      *  dedicated structured home above (accessibility, input-line, and other
-     *  preferences mudix persists for round-trip fidelity but does not yet act
+     *  preferences Mudlet Web persists for round-trip fidelity but does not yet act
      *  on). Keys with a structured home — protocol toggles, mapper settings,
      *  autoClearInput — are NOT stored here; the registry in ScriptingAPI reads
      *  and writes their real fields so the Settings UI stays in sync. Merged
@@ -369,7 +502,7 @@ export interface ProtocolSettings {
      *  `Sec-WebSocket-Protocol` header (RFC 6455), in preference order — the
      *  server selects at most one. These are mutually-exclusive stream *modes*,
      *  not layers (see {@link WS_SUBPROTOCOL_CHOICES}). Defaults to `['binary']`:
-     *  the raw telnet stream over binary frames is exactly what mudix decodes,
+     *  the raw telnet stream over binary frames is exactly what Mudlet Web decodes,
      *  and `binary` is accepted by both FluffOS and servers like last-outpost.com.
      *  An empty list opens a bare socket (no header). Applies to direct
      *  `websocket`-mode connections; the bundled telnet proxy ignores it. */
@@ -383,18 +516,18 @@ export interface ProtocolSettings {
  *  never negotiate option 90, they just emit the tags); the tag bytes are
  *  legitimate text on non-MSP MUDs but that collision is rare in practice. */
 export declare const PROTOCOL_DEFAULTS: Required<ProtocolSettings>;
-/** The WebSocket subprotocol names mudix can advertise, in canonical preference
+/** The WebSocket subprotocol names Mudlet Web can advertise, in canonical preference
  *  order. Mutually-exclusive stream modes the server picks *one* of — not
  *  layers that stack:
  *  - `binary`  — raw telnet byte stream over WebSocket binary frames. Every byte
  *                (IAC, GMCP/MSDP, MCCP, high-bit charset) survives; this is the
- *                only mode mudix's binary-frame decoder actually consumes.
+ *                only mode Mudlet Web's binary-frame decoder actually consumes.
  *  - `telnet`  — FluffOS binds this to the same telnet handler as `binary`; an
  *                alternate name some servers register instead of `binary`.
  *  - `telnet.mudstandards.org` — the mudstandards.org WebSocket proposal, same
  *                on-the-wire profile under the standardised name.
  *  (`ascii` — text frames with telnet stripped — is deliberately omitted: it's a
- *  dumb-terminal mode mudix can't decode.) The Settings UI renders one checkbox
+ *  dumb-terminal mode Mudlet Web can't decode.) The Settings UI renders one checkbox
  *  per entry; the selection is passed to MudClient in this order so the server
  *  sees `binary` first. */
 export declare const WS_SUBPROTOCOL_CHOICES: readonly ["binary", "telnet", "telnet.mudstandards.org"];
@@ -410,6 +543,38 @@ export type BooleanProtocolKey = {
  *  more renderer options get exposed. Keep all fields optional so the
  *  patcher can ship partial updates and unset fields fall through to the
  *  renderer's own createSettings() defaults. */
+/** The code editor's display options — desktop Mudlet's Editor preference
+ *  page. `showItemIds` is the tree's, the other four the code view's; all are
+ *  optional and fall back to `EDITOR_OPTION_DEFAULTS`.
+ *
+ *  They apply to every CodeMirror surface in the app, not just the script
+ *  editor: the file browser's editor and its JSON viewer read the same
+ *  settings, because they are the same editor opened on a different document. */
+export interface EditorSettings {
+    /** "Autocomplete Lua functions in code editor". Default on. */
+    autocomplete?: boolean;
+    /** "Show Spaces/Tabs". Default off. */
+    showWhitespace?: boolean;
+    /** "Show Line/Paragraphs" — a visible mark where each line ends. Default
+     *  off. Desktop's checkbox is named for "line and paragraph ends with
+     *  visible marks" but currently only rules a separator under each row:
+     *  `slot_changeShowLineFeedsAndParagraphs` sets edbee's `useLineSeparator`
+     *  (dlgProfilePreferences.cpp:4073), which the method's own comment calls a
+     *  stand-in for the marks it was named for. Mudlet Web draws the marks. */
+    showLineParagraphs?: boolean;
+    /** "Show invisible Unicode control characters". Default off. */
+    showControlChars?: boolean;
+    /** "Show Items' ID number" — the numeric id beside each script, alias,
+     *  trigger and so on in the editor's tree. Default off. */
+    showItemIds?: boolean;
+    /** "Theme" — the code editor's palette. `'app'` (the default) follows the
+     *  app theme, as it always did; the other two pin it, and pinning covers
+     *  the editor's chrome as well as its syntax colours, so a light editor is
+     *  light-backgrounded even under a dark app theme. Typed as a plain string
+     *  here so the schema does not depend on the CodeMirror layer;
+     *  `EDITOR_THEME_CHOICES` is the authority on the values. */
+    theme?: 'app' | 'dark' | 'light';
+}
 export interface MapperSettings {
     /** renderer.settings.roomSize — diameter/side of a room in map units. */
     roomSize?: number;
@@ -432,6 +597,27 @@ export interface MapperSettings {
     showDefaultArea?: boolean;
     /** renderer.settings.gridEnabled — background grid overlay. */
     gridEnabled?: boolean;
+    /** Mudlet's "Grid color" (Mapper colors page). Unset uses the renderer's
+     *  own default. */
+    gridColor?: string;
+    /** Mudlet's "Grid width" (`mMapGridLineSize`): how *thick* the grid lines
+     *  are, in map units — not how far apart they sit. The renderer calls that
+     *  `gridLineWidth`; its `gridSize` is the spacing and has no Mudlet
+     *  counterpart. Unset uses the renderer's own default. */
+    gridLineWidth?: number;
+    /** Mudlet's "2D Map Room Symbol Font" (`mMapSymbolFont`) — the font room
+     *  symbols and the area-name header are drawn in. The bundled Bitstream Vera
+     *  Sans Mono stays behind it as the fallback; unset uses that bundled font,
+     *  which is Mudlet's default too.
+     *
+     *  The same {@link OutputFontSource} the main display's font uses, so a
+     *  symbol font can be installed, fetched from a URL or read out of the
+     *  profile's own files — which matters more here than for body text: room
+     *  symbols are picked for their *glyphs*, and the font that has the glyph a
+     *  map wants is often one the machine does not have. A bare string is the
+     *  older shape (a family name, nothing to load) and is still read; see
+     *  {@link symbolFontSource}. */
+    symbolFont?: string | OutputFontSource;
     /** renderer.settings.lodEnabled — level-of-detail for very dense planes.
      *  Above {@link lodExitBudget} rooms on the drawn (area, z-level) the
      *  renderer drops exit lines, and above {@link lodRoomBudget} it replaces
@@ -495,6 +681,16 @@ export interface PlayerMarkerSettings {
  *  that the user has actually set, so the renderer's own defaults stay in
  *  charge for anything untouched. */
 export declare const PLAYER_MARKER_DEFAULTS: Required<PlayerMarkerSettings>;
+/**
+ * A mapper symbol font in its current shape, whatever shape it was stored in.
+ *
+ * The field started life as a family name and became an {@link OutputFontSource}
+ * so the same picker (and the same URL/profile-file loading) could serve it. A
+ * profile written by an older build still holds the string, in localStorage and
+ * in its VFS `profile.json` both, so it is normalised on read rather than
+ * migrated: a family name is exactly a `system` source with nothing to load.
+ */
+export declare function symbolFontSource(font: string | OutputFontSource | undefined): OutputFontSource | undefined;
 export declare const MAPPER_DEFAULTS: Required<MapperSettings>;
 /** RGBA channels (0..255) for the map-info widget background. Stored in the
  *  profile `config` bag under `mapInfoColor` (Mudlet's `setConfig` key) and
@@ -507,6 +703,15 @@ export interface MapInfoBgColor {
 }
 /** Mudlet's default `mapInfoColor` (mMapInfoBg) — translucent grey. */
 export declare const MAP_INFO_BG_DEFAULT: MapInfoBgColor;
+/** Engines offered by the console's "Search on …" entry, mirroring Mudlet's
+ *  `Host::mSearchEngineData` (`src/Host.cpp`). Each value is the prefix the
+ *  percent-encoded selection is appended to. */
+export declare const SEARCH_ENGINES: Record<string, string>;
+/** What an unset or unrecognised `searchEngine` resolves to, as in Mudlet's
+ *  `Host::getSearchEngine`. */
+export declare const DEFAULT_SEARCH_ENGINE = "Google";
+/** The stored engine name when we know it, else {@link DEFAULT_SEARCH_ENGINE}. */
+export declare function resolveSearchEngine(name: string | undefined): string;
 /** Defaults for profile settings. Reads fall through to these whenever a
  *  profile hasn't set the field. */
 export declare const PROFILE_DEFAULTS: ProfileSettings;
@@ -553,7 +758,7 @@ export interface PackageManifest {
      * This is what `getPackageInfo`/`getModuleInfo` answer with, so it has to
      * stay the package author's own set: Mudlet reports what the manifest said
      * and nothing more, which means a package that shipped no config.lua has no
-     * info at all rather than a table of things mudix worked out for itself
+     * info at all rather than a table of things Mudlet Web worked out for itself
      * (the derived name, the install timestamp). Absent when there was no
      * config.lua to read.
      */
@@ -606,6 +811,11 @@ export interface TriggerPattern {
     text: string;
     type: TriggerPatternType;
 }
+/** Widest line delta a multiline (AND) trigger can ask for. Mudlet's control is
+ *  a plain QSpinBox with no maximum set (`ui/triggers_main_area.ui`,
+ *  spinBox_lineMargin), so Qt's default 99 is the ceiling a profile written
+ *  there can carry — matching it keeps our XML readable by desktop Mudlet. */
+export declare const MAX_CONDITION_LINE_DELTA = 99;
 export interface TriggerNode extends BaseNode {
     patterns: TriggerPattern[];
     code: string;
@@ -616,23 +826,59 @@ export interface TriggerNode extends BaseNode {
     delta: number;
     isFilter: boolean;
     /**
-     * Session-scoped: created by `tempComplexRegexTrigger`, which needs a real
-     * trigger node rather than the flat temp-trigger primitive because it can
-     * ask for multiline-AND, a filter chain, a fire length, a line delta — all
-     * of them properties of a node in the tree — and can be named as another
-     * trigger's parent.
+     * Session-scoped: an `isTempTrigger="yes"` trigger from a package or
+     * profile XML, which desktop loads as a temporary TTrigger in the tree.
+     * (Script-created temporary triggers, tempComplexRegexTrigger's included,
+     * never reach the store: they live in the trigger engine — see
+     * TEMP_PARENT_PREFIX.) killTrigger can remove it.
      *
-     * Not persisted (see serializeProfileData), and neither is anything hanging
-     * under it: a permanent trigger parented to a temporary one goes when its
-     * parent does, so saving it would restore a child pointing at a parent that
-     * no longer exists.
+     * Not persisted (see persistableNodes), and neither is anything hanging
+     * under it: desktop's XMLexport skips a temporary root's whole subtree.
      */
     temporary?: boolean;
+    /**
+     * Mudlet TTrigger::mIsColorizerTrigger — the master switch for `highlight`.
+     * The colours below persist independently of it (desktop defaults them to
+     * red/yellow and writes them whatever the switch says), so turning
+     * colorization off and back on keeps them. Read it through `isColorizing`,
+     * never directly: profiles written before this field existed carry only
+     * `highlight`, and a highlight there meant the switch was on.
+     */
+    colorize?: boolean;
     highlight?: {
         fg?: string;
         bg?: string;
     };
     command?: string;
+    /**
+     * Mudlet TTrigger::mTriggerType (TTrigger.h:204) — one of the REGEX_* kinds
+     * defined at TTrigger.h:49-56, the same numbering `patterns[].type` uses.
+     * It is a *node*-level kind that desktop keeps beside the per-pattern kinds
+     * in `regexCodePropertyList`, and does nothing with beyond storing it: the
+     * only readers are the XML reader (XMLimport.cpp:1379), the XML writer
+     * (XMLexport.cpp:1017) and the editor's copy/paste helper
+     * (EditorItemXMLHelpers.cpp:316). Kept as the raw integer so a value we do
+     * not recognise still survives a linked-profile write-back unchanged.
+     */
+    triggerType?: number;
+    /**
+     * TTrigger::mSoundTrigger (TTrigger.h:149) — play `soundFile` on every fire,
+     * before the command and the script (TTrigger.cpp:1320-1330).
+     */
+    soundTrigger?: boolean;
+    /** TTrigger::mSoundFile (TTrigger.h) — the file `soundTrigger` plays. */
+    soundFile?: string;
+    /**
+     * TTrigger::mColorTrigger (TTrigger.h:152) and its two colours
+     * (mColorTriggerFgColor / mColorTriggerBgColor). This is desktop's *legacy*
+     * per-node colour trigger, set by dlgColorTrigger, and distinct from the
+     * per-pattern `colorTrigger` kind this client actually matches on. Nothing
+     * here drives matching; the fields exist so a profile that carries them
+     * survives the round trip instead of being blanked on write-back.
+     */
+    colorTrigger?: boolean;
+    colorTriggerFgColor?: string;
+    colorTriggerBgColor?: string;
 }
 export interface TimerNode extends BaseNode {
     seconds: number;
@@ -640,26 +886,70 @@ export interface TimerNode extends BaseNode {
     language: 'lua' | 'js';
     repeat: boolean;
     command?: string;
+    /**
+     * Session-scoped: an `isTempTimer="yes"` timer from a package or profile
+     * XML. Desktop loads it as a TTimer with mIsTempTimer set, so it fires once
+     * — its script only, never its command — and is then deleted, the way a
+     * `tempTimer` is. Not persisted (see persistableNodes), and neither is
+     * anything hanging under it.
+     */
+    temporary?: boolean;
 }
 export interface KeyNode extends BaseNode {
     key: string;
     modifiers: string[];
+    /** The Qt::Key the binding was made with (permKey, desktop XML, the key
+     *  recorder), when known. `key` alone is lossy — `!` and `1` are both
+     *  Digit1 — and desktop matches on this, so a Key_Exclam binding without
+     *  Shift never fires for a plain 1. getKeyCode and XML export report it. */
+    qtKey?: number;
     code: string;
     language: 'lua' | 'js';
     command?: string;
 }
 export type ButtonLocation = 'top' | 'bottom' | 'left' | 'right' | 'floating';
 export type ButtonOrientation = 'horizontal' | 'vertical';
+/**
+ * Mudlet `TAction::mButtonRotation` — the index of `comboBox_action_button_rotation`
+ * (ui/actions_main_area.ui:272), stored as that integer in `<buttonRotation>`.
+ *
+ * 0 = upright; 1 turns the control clockwise, so its text reads downwards; 2
+ * turns it anticlockwise, reading upwards. The combo box labels those "90°
+ * rotation to the left" and "…to the right", which is the opposite way round
+ * from the turn they produce — the direction below is what desktop actually
+ * paints (`TFlipButton::paintEvent`: `rotate(90)` for index 1 and `rotate(-90)`
+ * for index 2, clockwise-positive in Qt's y-down space), so match that and
+ * leave the labels alone.
+ */
+export type ButtonRotation = 0 | 1 | 2;
+/** Coerce an arbitrary `<buttonRotation>` integer to one of the three the combo
+ *  box offers; anything else means upright, as `qMax(0, currentIndex())` does. */
+export declare function asButtonRotation(n: number): ButtonRotation;
+/**
+ * Clamp a toolbar's filler offset to what its grid can hold: Mudlet allows up to
+ * one less than the row/column count, and disables the control entirely below 2
+ * of them — a filler as wide as the grid would push every button off it (Mudlet
+ * #9332). Applied both on save and at render, so a profile written elsewhere
+ * cannot lay out differently from one written here.
+ */
+export declare function clampFillerOffset(offset: number, columns: number): number;
 /**
  * Mudlet-style action node. Groups are toolbars; leaves are buttons.
  * Mirrors Mudlet's TAction (mLocation/mOrientation/mPushDownButton/...).
- * `styleSheet` is persisted but not applied yet (no stylesheet support).
  */
 export interface ButtonNode extends BaseNode {
     orientation: ButtonOrientation;
     location: ButtonLocation;
     /** Number of columns for the toolbar grid. 0 = auto / single line (Mudlet TToolBar.mButtonColumns). */
     columns: number;
+    /**
+     * Blank cells held before the first button — Mudlet's filler widget, sized
+     * by `TAction::mButtonFillerOffset` (`<buttonFillerOffset>`; spinBox_action_bar_
+     * offsetToFirstButton). Spans that many cells along the wrapping axis at
+     * (0, 0), so 0 (or a toolbar under 2 rows/columns, where desktop disables
+     * the control) means no filler at all.
+     */
+    fillerOffset?: number;
     /** Floating-toolbar geometry (groups with location='floating'). */
     posX?: number;
     posY?: number;
@@ -672,6 +962,8 @@ export interface ButtonNode extends BaseNode {
     /** Path to icon image, relative to the profile VFS root (typically inside a package dir). */
     icon?: string;
     tooltip?: string;
+    /** Quarter-turn applied to the button's label. See {@link ButtonRotation}. */
+    rotation?: ButtonRotation;
     /** Lua code; runs on every click regardless of state direction (Mudlet TAction.mScript). */
     code: string;
     language: 'lua' | 'js';
@@ -679,15 +971,78 @@ export interface ButtonNode extends BaseNode {
     command?: string;
     /** Command sent only when a two-state button goes DOWN (Mudlet commandButtonDown). */
     commandDown?: string;
-    /** Accepted but currently unused — Mudlet stylesheet text. */
+    /**
+     * Mudlet stylesheet text (`<css>`), applied to the button or the toolbar it
+     * is on. Only the flat-declaration subset survives the Qt→CSS conversion —
+     * pseudo-state selectors (`:hover`, `:pressed`) are dropped.
+     */
     styleSheet?: string;
 }
+/**
+ * Whether a trigger colorizes the text it matched. `colorize` is authoritative;
+ * a trigger from a profile saved before that field existed falls back to the old
+ * rule, where a highlight's presence was itself the switch.
+ */
+export declare function isColorizing(t: Pick<TriggerNode, 'colorize' | 'highlight'>): boolean;
+/**
+ * The items that belong in a save: everything except the session-scoped
+ * (`temporary`) ones, and anything hanging under them.
+ *
+ * The descendants matter as much as the temporaries themselves. A permanent
+ * item can be parented to a temporary one — Mudlet allows it, and its own
+ * specs do it — and that child dies with its parent at the end of the session.
+ * Saving it alone would restore an item whose `parentId` names a node that
+ * was never written, leaving it orphaned in the tree. Desktop's XMLexport
+ * skips a temporary item the same way, subtree and all.
+ */
+export declare function persistableNodes<T extends {
+    id: string;
+    parentId: string | null;
+    temporary?: boolean;
+}>(items: T[]): T[];
+/** Prefix of a `parentId` that names a temporary item rather than a node. */
+export declare const TEMP_PARENT_PREFIX = "temp:";
+/** The `parentId` a permanent child of temporary item `id` carries. */
+export declare function tempParentRef(id: number): string;
+/** Whether `parentId` names a temporary item (see TEMP_PARENT_PREFIX). */
+export declare function isTempParentRef(parentId: string | null | undefined): parentId is string;
+/** The temporary item's id a temp parent ref names, or null for anything else. */
+export declare function tempRefId(parentId: string | null | undefined): number | null;
+/**
+ * The temporary item a node ultimately hangs off, or null when its whole
+ * ancestry is in the store. Temporary items are always roots (no temp* API
+ * takes a parent), so this is the top store ancestor's parent ref.
+ */
+export declare function tempRootOf<T extends {
+    id: string;
+    parentId: string | null;
+}>(node: T, byId: ReadonlyMap<string, T>): number | null;
+/** The nodes the script editor shows: everything but the permanent items that
+ *  hang off a temporary one, which desktop's editor drops along with their
+ *  parent's subtree whenever it saves (see TEMP_PARENT_PREFIX). */
+export declare function visibleTreeNodes<T extends {
+    id: string;
+    parentId: string | null;
+}>(items: T[]): T[];
 /** Returns true if the item and all its ancestors are enabled. */
 export declare function isEffectivelyEnabled<T extends {
     id: string;
     enabled: boolean;
     parentId: string | null;
 }>(item: T, allItems: T[]): boolean;
+/**
+ * The items in tree order: Mudlet's pre-order walk, each node immediately
+ * followed by its whole subtree, siblings in the order the flat array holds
+ * them. The flat array alone is not that order — an item added to an older
+ * group (`permAlias`/`permKey` into a group made earlier) is appended at the
+ * end, after root items created since, while desktop puts it inside its group.
+ * An item whose parent is missing is walked as a root where it stands; a
+ * malformed cycle is broken rather than dropped.
+ */
+export declare function inTreeOrder<T extends {
+    id: string;
+    parentId: string | null;
+}>(items: readonly T[]): T[];
 /**
  * One-pass build of the set of ids whose item and every ancestor is enabled.
  * Engines iterating large trees should call this once per loadPerm rather than
@@ -698,7 +1053,11 @@ export declare function buildEffectivelyEnabledIds<T extends {
     id: string;
     enabled: boolean;
     parentId: string | null;
-}>(items: T[]): Set<string>;
+}>(items: T[], 
+/** Ids that cannot be active whatever their switch says — Mudlet's items
+ *  whose code or pattern failed to compile (`Tree::state()` false). They
+ *  count as switched off, so their descendants are left out too. */
+blocked?: ReadonlySet<string>): Set<string>;
 export interface ModalBounds {
     x: number;
     y: number;
@@ -729,6 +1088,17 @@ export interface ScriptEditorBounds extends ModalBounds {
 export interface ProfileVariables {
     saveList: string[];
     values: MudletVariable[];
+    /**
+     * Variables the user has hidden from the Variables view (Mudlet's
+     * `VarUnit::mHiddenVariables`, written as `<HiddenVariables>`). Optional so
+     * a profile saved before this existed still parses.
+     *
+     * Entries are the path as Lua reads it — `myTable.sub`, `myTable[3]` — so a
+     * nested key can be hidden too. Mudlet has only ever been observed writing
+     * this block empty, so its nested spelling is unverified; a path it does not
+     * recognise simply shows the variable there rather than hiding it.
+     */
+    hidden?: string[];
 }
 export interface AppSchema {
     connections: MudConnection[];
@@ -769,6 +1139,17 @@ export declare const APP_DEFAULTS: AppSchema;
  * `useAppStore(s => selectProfileField(s, id, 'fontSize'))`.
  */
 export declare function selectProfileField<K extends keyof ProfileSettings>(s: Pick<AppSchema, 'connectionProfile'>, connectionId: string | null, key: K): ProfileSettings[K];
+/**
+ * Append the dial parameters to a proxy base URL.
+ *
+ * Built with `URL`/`URLSearchParams` rather than string concatenation, which
+ * emitted a second `?` for a base that already carried a query — breaking any
+ * self-hosted proxy protected by a token in its query string, the natural way
+ * to protect one (issue #56). A base we cannot parse is concatenated as before
+ * rather than dropped: a profile that somehow holds one should still dial the
+ * thing it used to.
+ */
+export declare function withProxyParams(base: string, params: [string, string][]): string;
 export declare function connectionUrl(c: MudConnection, userProxyUrl?: string): string;
 /** The proxy a `mud`-mode connection will actually dial, applying the same
  *  precedence as {@link connectionUrl}: per-connection > user's own > brand >
@@ -783,20 +1164,15 @@ export declare function effectiveProxyUrl(c: MudConnection, userProxyUrl?: strin
  * no certificate and no way to waive a validation failure — the options would be
  * silently ignored, so the UI disables them instead of pretending.
  *
- * Recognised by the `workers.dev` hostname, which covers the built-in default
- * proxy and anything deployed from `worker/`. A Worker on a custom domain can't
- * be told apart from a Node proxy up front; that case is corrected at runtime by
- * the `certInspection: false` flag the proxy reports on `tls.established`.
+ * Recognised by the `workers.dev` hostname, which covers anything deployed
+ * from `worker/` under its own subdomain — plus the built-in default, which is
+ * a Worker on a custom domain and so cannot be recognised by its name at all.
+ * Any other Worker on a custom domain can't be told apart from a Node proxy up
+ * front; that case is corrected at runtime by the `certInspection: false` flag
+ * the proxy reports on `tls.established`.
  */
 export declare function proxyCanInspectCertificates(proxyUrl: string): boolean;
 export declare function connectionDisplayAddr(c: MudConnection): string;
-/** Whether the connection's link to the *game server* is TLS-encrypted — the
- *  signal reported as the NEW-ENVIRON `TLS` variable. In `websocket` mode the
- *  browser connects straight to the game, so a `wss://` URL is end-to-end TLS.
- *  In `mud` (proxy) mode the browser↔proxy hop being `wss://` says nothing about
- *  the proxy↔game hop: that leg is a plaintext telnet socket unless `tls` is set,
- *  which makes the proxy perform a TLS handshake with the game instead. */
-export declare function connectionSecureTransport(c: MudConnection): boolean;
 /**
  * Whether `name` is already some other profile's, ignoring case.
  *
@@ -810,6 +1186,102 @@ export declare function connectionSecureTransport(c: MudConnection): boolean;
  * not a clash.
  */
 export declare function connectionNameTaken(name: string, connections: MudConnection[], exceptId?: string): boolean;
+/** The port a `mud`-mode connection falls back to when none was typed — the
+ *  Port field's placeholder, and the telnet default both proxies assume. */
+export declare const DEFAULT_MUD_PORT = 23;
+export type PortValidation = {
+    ok: true;
+    port: number;
+} | {
+    ok: false;
+    reason: 'notANumber' | 'outOfRange';
+    message: string;
+};
+/**
+ * Validate what the user typed into a Port field.
+ *
+ * `parseInt` is not a validator: it stops at the first character it doesn't
+ * understand and returns what it read so far, so `1e3` becomes 1, `0x50`
+ * becomes 0 and `23abc` becomes 23 — a *different* port from the one typed,
+ * saved without a word. So the text is matched against `^\d+$` first, exactly
+ * as Mudlet does (`src/dlgConnectionProfiles.cpp:2140-2160`), and only then
+ * range-checked. The two messages are Mudlet's, verbatim.
+ *
+ * The range is the one both proxies already enforce server-side
+ * (`proxy/server.ts`, `worker/index.js`) — where the rejection reason never
+ * reaches the user, who is instead told the proxy is unreachable.
+ *
+ * An empty field is accepted as {@link DEFAULT_MUD_PORT}: it is what the
+ * placeholder promises, and Mudlet's validator likewise skips an empty port.
+ */
+export declare function validatePort(text: string): PortValidation;
+export type HostValidation = {
+    ok: true;
+    host: string;
+} | {
+    ok: false;
+    reason: 'empty' | 'malformed' | 'tooLong' | 'rawIpWithTls';
+    message: string;
+};
+/**
+ * Validate what the user typed into the Host field of a `mud`-mode profile.
+ *
+ * Nothing used to: `my host with spaces`, `ws://achaea.com`, `achaea.com/path`
+ * and a 1200-character string were all accepted and stored verbatim, and only
+ * failed much later as the proxy's generic connect error (issue #56). Mudlet
+ * refuses them at the dialog, and refuses a raw IP when TLS is ticked because a
+ * certificate cannot name one — both messages below are Mudlet's.
+ *
+ * `tls` is the profile's TLS switch; the raw-IP rule only applies with it on.
+ */
+export declare function validateHost(text: string, tls?: boolean): HostValidation;
+export type UrlValidation = {
+    ok: true;
+    url: string;
+    insecure: boolean;
+} | {
+    ok: false;
+    reason: 'empty' | 'malformed' | 'wrongScheme';
+    message: string;
+};
+/**
+ * Validate the URL of a `websocket`-mode profile.
+ *
+ * `http://example.com`, `not a url` and `javascript:alert(1)` all used to save
+ * without complaint, and the `ws://`-on-`https://` case only surfaced on
+ * Connect as the browser's own "An insecure WebSocket connection may not be
+ * initiated from a page loaded over HTTPS." The scheme is decidable here, so it
+ * is decided here.
+ *
+ * `insecure` reports the one case that is well-formed but cannot work from this
+ * page — `ws://` served over `https://` — so the caller can warn rather than
+ * refuse: it is correct on an `http://` dev server, and the page's own scheme
+ * is not the URL's fault.
+ */
+export declare function validateWsUrl(text: string, pageProtocol?: string): UrlValidation;
+export type ProxyValidation = {
+    ok: true;
+    url: string;
+    insecure: boolean;
+} | {
+    ok: false;
+    reason: 'malformed' | 'relative' | 'wrongScheme' | 'hasQuery';
+    message: string;
+};
+/**
+ * Validate the per-profile proxy override. Empty is valid — it means "use the
+ * default".
+ *
+ * Three things used to go wrong silently (issue #56): a bare `proxy.example`
+ * resolved *relative to the page*, so the profile dialed
+ * `https://mudlet-web.mudlet.org/proxy.example?host=…`; an `http://` override
+ * could only ever fail as mixed content; and an override already carrying a
+ * query string — the natural way to put a token on a self-hosted proxy — was
+ * concatenated into a second `?`, which no server can parse. The query case is
+ * now supported rather than rejected ({@link connectionUrl} merges parameters),
+ * so it is only reported here when the URL is otherwise unusable.
+ */
+export declare function validateProxyUrl(text: string, pageProtocol?: string): ProxyValidation;
 /**
  * `name` if no other profile has it, otherwise the first free `name (2)`,
  * `name (3)`, … — the same shape Mudlet gives a profile copied over an existing