@mudlet/mudlet-web 0.5.0 → 1.0.1

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

@@ -52,7 +52,9 @@ export declare class MudSession {
     private client;
     /** The most recent URL passed to connect() — replayed by reconnect(). */
     private lastUrl;
-    private pingTracker;
+    /** How many times connect() has dialed, so a caller can tell whether a
+     *  dial it asked for has been overtaken by another. */
+    private dials;
     private stateUnsubs;
     /** The profile's server encoding, as `getServerEncodingsList()` spells it.
      *  Lives here rather than on the client so it survives having none — see
@@ -67,6 +69,13 @@ export declare class MudSession {
      *  next connect(). Fed by the WindowManager's main-console resize callback
      *  and forwarded to the live client for NAWS (telnet option 31). */
     private windowSize;
+    /** The main console's wrap column (Mudlet's `Host::mWrapAt`), held like
+     *  `windowSize` so each new client starts with it — it caps the NAWS width
+     *  and is the NEW-ENVIRON WORD_WRAP. Null until the scripting API reports
+     *  the profile's value; the client then assumes desktop's default of 100. */
+    private wrapAt;
+    /** Whether the main console draws its timestamp gutter (off the NAWS width). */
+    private timestampsShown;
     /** Active Mudlet-format replay recording, or null. Fed from the
      *  `socket.incoming` tap in the constructor — the post-MCCP,
      *  pre-telnet-parsing stream, the same point Mudlet records at. */
@@ -100,6 +109,39 @@ export declare class MudSession {
     private static readonly SCRIPT_LOG_LIMIT;
     private _scriptLog;
     private readonly options;
+    /** True between a dial and the disconnect that answers it. Guards against
+     *  narrating a teardown of something that was never dialed (an injected
+     *  replay's parsing-only client, a second `destroy()`). */
+    private dialAnnounced;
+    /** Whether the outstanding dial asked the proxy for TLS (`&tls=1`) or is a
+     *  `wss://` direct connection — Mudlet's `mCurrent_sslTsl`, sampled at dial
+     *  time so a mid-session settings change can't rewrite the notices. */
+    private secureDial;
+    /** `performance`-independent stand-in for Mudlet's `mConnectionTimer`: when
+     *  the link to the *game* came up (`client.established`), or null while
+     *  nothing has. Not the WebSocket's own open: in `mud` mode that one is to
+     *  the proxy, which accepts it before dialling the game at all. */
+    private connectedAt;
+    /** The socket-level failure behind the disconnect now in flight, stashed by
+     *  {@link reportConnectionError}. cTelnet reads the equivalent straight off
+     *  `mpSocket->errorString()` when it composes the message. */
+    private disconnectReason;
+    /** What the outstanding dial is reaching — kept for the failed-attempt
+     *  notice, which names it as cTelnet's does. */
+    private dialTarget;
+    /** Whether the current dial's WebSocket opened. Through the proxy, a dial
+     *  that failed without it never reached the proxy at all — Mudlet's "via
+     *  proxy" failure — rather than the proxy failing to reach the game. */
+    private socketOpened;
+    /** The close frame that ended the current socket, when the other end ended
+     *  it; null for a disconnect() of our own. */
+    private lastClose;
+    /** cTelnet's `mFailedConnectionCount`: attempts in a row that never reached
+     *  the game, which is what the retry delay doubles on. Cleared by a
+     *  connection being made and by a deliberate disconnect. */
+    private failedConnectionCount;
+    /** cTelnet's `mTimerFailedConnectionRetry`. */
+    private failedConnectionRetry;
     /** Warn before the tab closes while a connection is live. Owned here rather
      *  than by MudClient — a fresh client is created on every connect(), so a
      *  per-client listener would accumulate one leaked closure per reconnect. */
@@ -112,7 +154,36 @@ export declare class MudSession {
     get outputReady(): boolean;
     markOutputReady(): void;
     markOutputGone(): void;
+    /** The URL the session last dialed (and reconnect() would redial). */
+    get dialedUrl(): string | null;
+    /** The number of dials so far — see {@link dialedUrl}. */
+    get dialCount(): number;
     connect(url: string): void;
+    /**
+     * Whether the last disconnect was asked for rather than suffered. The
+     * disconnect notice reads it to name the user rather than guessing at the
+     * server — cTelnet's `mDontReconnect` in its reason-naming role
+     * (ctelnet.cpp:803, :859). Cleared by {@link connect}.
+     */
+    deliberateDisconnect: boolean;
+    /**
+     * Whether the disconnect now in flight must not be auto-reconnected —
+     * cTelnet's `mDontReconnect` in its *other* role (ctelnet.cpp:920).
+     *
+     * Mudlet uses the one flag for both, which is why a rejected GMCP login
+     * there reports the drop as "User Disconnected": GMCPAuthenticator raises
+     * `mDontReconnect` at rejection time (GMCPAuthenticator.cpp:613), long
+     * before the reason is composed. Splitting the two keeps "the user asked
+     * for it" honest while still suppressing the redial — the certificate and
+     * login paths in ProfileSession set this one alone, and Mudlet's own
+     * ordering makes the certificate case agree either way (it raises the flag
+     * *after* naming the reason, ctelnet.cpp:819).
+     *
+     * Set by {@link disconnect} too, so hanging up by hand is never undone, and
+     * cleared by {@link connect} — it only ever suppresses the one cycle it was
+     * raised for, as Mudlet's `mDontReconnect = false` at ctelnet.cpp:923 does.
+     */
+    dontReconnect: boolean;
     disconnect(): void;
     /** Whether a send() carrying the given per-call `echo` flag should produce a
      *  local echo, under the current showSentText mode. `script` defers to the
@@ -123,10 +194,30 @@ export declare class MudSession {
      *  by {@link echoCommand}, which must not close a partial the deferral is
      *  about to emit itself. */
     scriptEchoDeferred: boolean;
-    /** Host::send's echo stage: print a command the player (or an item acting
-     *  for them) sent, under the showSentText mode. `wantPrint` is the per-call
-     *  flag `script` mode defers to — `always` and `never` overrule it. */
-    echoSentCommand(text: string, wantPrint: boolean): void;
+    /** Set by ScriptingAPI alongside {@link scriptEchoDeferred}: where a command
+     *  echoed while a trigger runs is queued, so it is drawn after the line the
+     *  trigger fired on — in line with that trigger's `echo()` output — rather
+     *  than above it (mudlet-web#452). The buffer already has it in the right
+     *  place; only the 'message' event waits. */
+    deferCommandEcho: ((styled: string) => void) | null;
+    /**
+     * Host::send's echo stage: print a command the player (or an item acting
+     * for them) sent, under the showSentText mode. `wantPrint` is the per-call
+     * flag `script` mode defers to — `always` and `never` overrule it.
+     *
+     * Returns the command as Host::send goes on to split it, which is not
+     * always the text it was given: `TConsoleModel::printCommand` takes the
+     * command by reference and appends the line feed that ends the echoed line
+     * to it — unless it puts the echo on the end of a waiting prompt line, which
+     * needs no line feed — and inside a trigger it also puts one in front when
+     * the line being processed has text. Host::send then splits that on the
+     * separator, skips only parts that are empty BEFORE it strips line feeds,
+     * and so runs the aliases on an empty command where the text had nothing
+     * after its last separator. That is how an echoed empty Enter, `x;;` or
+     * `expandAlias("")` reaches a `^$` alias on desktop, while
+     * `expandAlias("", false)` goes out as a bare line feed without one.
+     */
+    echoSentCommand(text: string, wantPrint: boolean): string;
     echoCommand(text: string): void;
     /** Wrap the echoed command in ANSI truecolor escapes from commandEchoColor
      *  so it renders in the configured foreground (and optional background). */
@@ -173,10 +264,27 @@ export declare class MudSession {
     sendSecret(text: string): void;
     sendGmcpRaw(message: string): void;
     /** Reply to a GMCP `Char.Login.Default` request. Pass an account + password
-     *  to authenticate, or no arguments to send the empty "fall back to text
-     *  login" reply (the credentials popup's Cancel). The password is relayed
-     *  straight to the wire and never persisted. */
-    sendCharLoginCredentials(account?: string, password?: string): void;
+     *  to authenticate, or no account for the hand-off to the game's own
+     *  sign-in (the credentials popup's "Use text login"). `tokenStorage` is the
+     *  honest answer to whether a sign-in token minted now would be kept. The
+     *  password is relayed straight to the wire and never persisted here. */
+    sendCharLoginCredentials(account?: string, password?: string, tokenStorage?: boolean): void;
+    /** Replay a saved sign-in token (`Char.Login.Reconnect`). False when the
+     *  client refused — see `MudClient.sendCharLoginReconnect`. */
+    sendCharLoginReconnect(account: string, token: string, secureOnly: boolean, tokenStorage?: boolean): boolean;
+    /** Ask the game to restart a remembered provider's browser sign-in. */
+    sendCharLoginResume(account: string, provider: string, tokenStorage?: boolean): void;
+    /** Complete a client-driven OAuth sign-in (`Char.Login.AuthCode`). False
+     *  when refused over an unencrypted connection. */
+    sendCharLoginAuthCode(auth: {
+        code: string;
+        codeVerifier: string;
+        redirectUri: string;
+        nonce?: string;
+    }, tokenStorage?: boolean): boolean;
+    /** Whether the link to the *game* is encrypted right now — the gate on every
+     *  `Char.Login` bearer secret. False with no socket. */
+    get gameTransportSecure(): boolean;
     sendMSDP(variable: string, values: string[]): boolean;
     sendSocket(data: string): boolean;
     /** True when there is no live socket — see MudClient.isSocketUnconnected. */
@@ -191,11 +299,20 @@ export declare class MudSession {
      *  borrows the detached one replay playback already builds for the same
      *  reason: the telnet/ANSI/trigger path needs no socket to run. */
     feedTelnet(data: string): void;
+    /** A feedTriggers() is text the buffer reads, so an encoding a trigger
+     *  switched to part way through a read takes effect there, and for the
+     *  rest of that read (see MudClient.setServerEncoding). */
+    adoptPendingEncoding(): void;
     sendATCP(message: string): boolean;
     sendTelnetChannel102(msg: string): boolean;
+    /** Whether GMCP is negotiated on the live connection. False with no client. */
+    isGmcpEnabled(): boolean;
     /** Whether MSP was negotiated on the live connection. False with no client,
      *  which is what a never-connected profile should report. */
     isMspNegotiated(): boolean;
+    /** Mudlet `Host::isRemoteEchoingActive` — the server is echoing (password
+     *  entry), so no command is echoed locally. False with no client. */
+    isRemoteEchoingActive(): boolean;
     get replaySpeed(): number;
     get isReplayRecording(): boolean;
     get isReplaying(): boolean;
@@ -216,8 +333,16 @@ export declare class MudSession {
     /** Start playing a Mudlet-format replay (the Lua `loadReplay` core).
      *  Works offline — with no live connection the chunks feed a detached
      *  client's parsing pipeline. Returns null on success or a human-readable
-     *  failure reason (mirroring Mudlet's loadReplay error strings). */
-    loadReplayData(bytes: Uint8Array): string | null;
+     *  failure reason (mirroring Mudlet's loadReplay error strings).
+     *
+     *  `readAt`, when given, reads the file the bytes came from as it is now:
+     *  each chunk is read again from it as it comes up, as Mudlet reads its
+     *  replay file a chunk at a time while playing (cTelnet::loadReplayChunk),
+     *  and a chunk header that has gone bad since the load ends the replay as
+     *  corrupt rather than playing on. It throws when the file cannot be read at
+     *  all, and then the bytes loaded here are played: Mudlet holds the file
+     *  open, and an open file outlives its name being removed. */
+    loadReplayData(bytes: Uint8Array, readAt?: (position: number, length: number) => Uint8Array): string | null;
     /** Stop the active replay without delivering its remaining chunks.
      *  Returns false when no replay is running. */
     abortReplay(): boolean;
@@ -248,9 +373,16 @@ export declare class MudSession {
     getServerEncoding(): string;
     setServerEncoding(name: string): boolean;
     /** Called when CHARSET negotiation settles on a name, so the profile-level
-     *  setting reflects what the connection actually agreed. */
-    noteNegotiatedEncoding(name: string): void;
-    /** Mudlet `getServerEncodingsList()`. The fixed set of encodings mudix can
+     *  setting reflects what the connection actually agreed.
+     *
+     *  An encoding this client ACCEPTed from a server's REQUEST is also raised
+     *  as `charset.accepted` for saving to the profile, as Mudlet's
+     *  `setEncoding(acceptedEncoding, true)` saves it — and, like that, only
+     *  when it changed the encoding: cTelnet::setEncoding writes nothing when
+     *  the name is already the one in use. A REJECTED request never gets here,
+     *  and neither does a server's ACCEPTED reply, which Mudlet ignores. */
+    noteNegotiatedEncoding(name: string, acceptedRequest?: boolean): void;
+    /** Mudlet `getServerEncodingsList()`. The fixed set of encodings Mudlet Web can
      *  decode — available even before a connection is dialed. */
     getServerEncodingsList(): string[];
     /** Mudlet `addSupportedTelnetOption(option)`. Forwards to the live
@@ -262,9 +394,32 @@ export declare class MudSession {
      *  setting survives a reconnect. */
     setPromptTimeoutMs(ms: number): void;
     getPromptTimeoutMs(): number | null;
+    /** True once this session's game has sent IAC GA / IAC EOR — Mudlet's
+     *  `mGA_Driver`. False with no client, which is also what the editor wants:
+     *  nothing has proved the game sends one. Latched per client, so it resets
+     *  on reconnect; the `prompt` event fires on every marker, which is what the
+     *  editor listens to for the transition. */
+    get promptMarkerSeen(): boolean;
     /** Mudlet `setConfig("fixUnnecessaryLinebreaks", …)`. Updates the live client
      *  and the stored options so the setting survives a reconnect. */
     setFixUnnecessaryLinebreaks(enabled: boolean): void;
+    /** Mudlet `mUSE_FORCE_LF_AFTER_PROMPT` — the "Force new line on empty
+     *  commands" checkbox. Only consulted while the GA linebreak fix is on;
+     *  see {@link shouldEchoEmptyCommand}. */
+    forceLfAfterPrompt: boolean;
+    /**
+     * Whether pressing Enter on an empty command line should echo a blank line.
+     *
+     * Mudlet's rule, from `Host::send` (Host.cpp:1461):
+     *
+     *     if (!cmd.isEmpty() || !mUSE_IRE_DRIVER_BUGFIX || mUSE_FORCE_LF_AFTER_PROMPT)
+     *
+     * The GA linebreak fix exists because those servers already put the cursor
+     * on a fresh line after a prompt, so echoing the empty command adds a
+     * second blank one. With the fix off — the default, and every non-GA game —
+     * an empty command echoes exactly as it always did here.
+     */
+    private shouldEchoEmptyCommand;
     /** Mudlet `Host::mUndoServerWrap` / `mUndoServerWrapWidth`, as getConfig
      *  reads them back. */
     get undoServerWrap(): boolean;
@@ -274,6 +429,30 @@ export declare class MudSession {
     setUndoServerWrap(enabled: boolean): void;
     /** Mudlet `setConfig("undoServerWrapWidth", …)`. */
     setUndoServerWrapWidth(width: number): void;
+    private consoleBufferLines;
+    /** The preference pair a script's setConsoleBufferSize("main", …) just
+     *  wrote, until the profile setting comes back carrying it. */
+    private scriptedBufferPreference;
+    /** The resolved scrollback cap for the main console, in lines. */
+    get consoleBufferSize(): number;
+    /**
+     * Mudlet's preference pair. `useMaximum` mirrors `checkBox_useMaxBufferSize`
+     * — desktop substitutes `TBuffer::getMaxBufferSize()`, a figure derived from
+     * physical memory; a browser tab gets {@link MAX_CONSOLE_BUFFER_SIZE}.
+     * Applies immediately to the main console when it exists.
+     */
+    setConsoleBufferSize(lines: number, useMaximum?: boolean): void;
+    /**
+     * Record a size a script gave the main console (`Host::setMainConsoleBufferSize`,
+     * which sets `mConsoleBufferSize` and `mUseMaxConsoleBufferSize` as well as
+     * the live buffer), so the preference it saves is not then applied over the
+     * live buffer a second time. The caller has already resized the console.
+     */
+    noteScriptedConsoleBufferSize(lines: number, useMaximum: boolean): void;
+    /** Push the resolved size onto a console, batch-deletion size and all —
+     *  the `setBufferSize(bufferSize, max(100, bufferSize / 5))` of
+     *  mudlet.cpp:2270-2271. */
+    applyConsoleBufferSize(console: Console): void;
     /** Commit a line held for a wrap continuation whose flush delay has passed —
      *  the busted `pumpEvents` path, which cannot wait for a real timer. */
     pumpServerWrap(): boolean;
@@ -286,9 +465,10 @@ export declare class MudSession {
      *  the change land early. See MudClient.setForceGaOff. */
     setSpecialForceGAOff(enabled: boolean): void;
     /** Mudlet `setConfig("versionInTTYPE", …)` / `("promptForVersionInTTYPE", …)`.
-     *  Stored only: TTYPE is negotiated at connect, so both take effect on the
-     *  next dial — the same reconnect requirement Mudlet's own auto-detect works
-     *  around by redialing for you. */
+     *  Stored for the next dial and applied to the live client too: desktop
+     *  reads `mVersionInTTYPE` when it answers each `SB TTYPE SEND`, so the
+     *  server's next request already carries (or drops) the version
+     *  (mudlet-web#379). */
     setVersionInTTYPE(enabled: boolean, prompted?: boolean): void;
     /** Mudlet `setConfig("promptForMXPProcessorOn", …)` / `("specialForceMXPProcessorOn", …)`.
      *  Stored only — together they gate whether an in-band `ESC[<n>z` may still
@@ -300,9 +480,10 @@ export declare class MudSession {
      *  every console/text window re-renders control characters (and tab-stops)
      *  under the new mode on their next paint. */
     setControlCharacterMode(mode: ControlCharacterMode): void;
-    /** Update the telnet protocol toggles applied on the next connect.
-     *  Mid-session changes do not retroactively renegotiate — the values are
-     *  read by MudClient's constructor, so the next dial sees them. */
+    /** Update the telnet protocol toggles. A live client is told too, so a
+     *  toggle switched off mid-session is obeyed by the next offer the server
+     *  makes (Mudlet reads its equivalents at negotiation time). Options
+     *  already negotiated are not retroactively withdrawn. */
     setProtocolOptions(opts: {
         gmcpEnabled?: boolean;
         mttsEnabled?: boolean;
@@ -314,7 +495,6 @@ export declare class MudSession {
         mxpEnabled?: boolean;
         mnesEnabled?: boolean;
         newEnvironEnabled?: boolean;
-        secureTransport?: boolean;
         screenReaderAdvertised?: boolean;
         osc8HyperlinksEnabled?: boolean;
         nawsEnabled?: boolean;
@@ -325,15 +505,92 @@ export declare class MudSession {
      *  on a later connect() is seeded with the current size. Called by the
      *  WindowManager whenever the main console's grid changes. */
     setWindowSize(cols: number, rows: number): void;
+    /** Record the main console's wrap column (0 for off) and pass it to the
+     *  live client: desktop reports `min(columns, wrap)` as the NAWS width and
+     *  the wrap itself as WORD_WRAP, and re-sends NAWS when it changes. Called
+     *  by the scripting API whenever the profile's `outputWrapAt` is applied. */
+    setWrapAt(wrapAt: number): void;
+    /** Record whether the main console shows its timestamp gutter, which
+     *  desktop takes off the NAWS width. Called by the main output view. */
+    setTimestampsShown(shown: boolean): void;
     private teardownClient;
     get destroyed(): boolean;
     /** Release resources that live outside the JS heap. In-memory state (maps,
      *  arrays, sub-managers) is reclaimed by GC once the instance is dropped, so
      *  this only handles the three things that don't self-clean: the WebSocket
-     *  + ping timer (via `teardownClient`), Web Audio nodes, and any EventBus
+     *  (via `teardownClient`), Web Audio nodes, and any EventBus
      *  listeners with an AbortSignal cleanup still pending. Idempotent. */
     destroy(): void;
     private setStatus;
     private setPing;
     private reportConnectionError;
+    /** One of cTelnet's `postMessage()` notices. Emitted as a normal `message`,
+     *  so it reaches the console, the session log and a saved replay alike —
+     *  the whole point of the issue: a transcript that ends mid-sentence should
+     *  say why. Prefix colours follow the ones already used for the TLS notices
+     *  in ProfileSession. */
+    private postSocketMessage;
+    /** cTelnet's postMessage prints into the main console like anything else,
+     *  so its notices are lines getLineCount() counts and getLines() returns —
+     *  a script indexing lines after a connect or a disconnect lands where it
+     *  does on desktop only if they are (mudlet-web#339). Stored as well as
+     *  rendered, as {@link warnIfUnencodable} does, and wrapped at the main
+     *  window's width like any other line. */
+    /** Host::postMessage for a notice from elsewhere in the client (a failed
+     *  exportAreaImage save): a stored main-console line, as cTelnet's are. */
+    postMessageLine(styled: string): void;
+    private postSocketLine;
+    /** cTelnet's "[ INFO ]  - Attempting an open connection to %1:%2 ..."
+     *  (ctelnet.cpp:1485/1494 for IPv4, :1454/1463 for IPv6) and its secure
+     *  variant (:1362-1430). `mud`-mode profiles reach
+     *  the game through the telnet→WebSocket proxy, which is what Mudlet's
+     *  "via proxy" wording describes, so it is used for exactly those. */
+    private announceConnecting;
+    /** cTelnet's open-connection notice (ctelnet.cpp:920-935). Desktop always
+     *  names the address family it won the dual-stack race with — "Open
+     *  connection made (IPv4)." / "(IPv6)." — because it opens both and reports
+     *  whichever answered. A browser WebSocket exposes no such thing, so the
+     *  suffix is dropped rather than guessed at; this is the one notice here
+     *  that is not Mudlet's string verbatim. */
+    private announceConnected;
+    /** cTelnet's slot_socketError / host-lookup failure notice, for a dial that
+     *  never reached the game (ctelnet.cpp slot_socketError,
+     *  slot_socketHostFound). No "Socket got disconnected" and no connection
+     *  time: nothing was connected. Posted before sysDisconnectionEvent, as
+     *  handleFailedConnection raises it only after the player has been told.
+     *  An attempt called off by the player is not news, and says nothing. */
+    private announceFailedConnection;
+    /** How many attempts in a row have failed to reach the game. */
+    get failedConnections(): number;
+    /**
+     * The retry half of cTelnet's `handleFailedConnection`, for a profile set to
+     * reconnect automatically: say when, then try again after 5 s, doubling per
+     * failure in a row up to 60 s. The caller decides whether a retry is wanted
+     * at all (the profile option, `dontReconnect`); the timer is ours, so that
+     * a Connect, a Disconnect or closing the profile calls it off, as each of
+     * them stops `mTimerFailedConnectionRetry`.
+     */
+    scheduleFailedConnectionRetry(redial: () => void): void;
+    private cancelFailedConnectionRetry;
+    /** A `[ WARN  ]` notice from the client, laid out as cTelnet::postMessage
+     *  does: the prefix in cyan and the text in orange (here the ANSI yellow
+     *  its other notices use), each further line indented to the end of the
+     *  prefix. */
+    private postClientWarning;
+    /** The indented, yellow second row of a two-line notice — Mudlet's "%1\n%2"
+     *  renders as two rows, and a `message` here is one. */
+    private postSocketContinuation;
+    /** cTelnet's disconnect pair: the reason (ctelnet.cpp:1073-1136) and then
+     *  the connection time (ctelnet.cpp:994-999). Posted on *every* disconnect — a clean
+     *  server close and an idle kick used to produce nothing at all, because
+     *  they never reach the abnormal-close path. */
+    private announceDisconnected;
 }
+/** cTelnet's `FAILED_CONNECTION_RETRY_DELAY` / `_MAX_DELAY` (ctelnet.cpp):
+ *  how long to leave a game that could not be reached before trying again,
+ *  doubling with each failure in a row. */
+export declare const FAILED_CONNECTION_RETRY_DELAY_MS = 5000;
+export declare const FAILED_CONNECTION_RETRY_MAX_DELAY_MS = 60000;
+/** The wait before retry number `failures` (1-based) —
+ *  `min(DELAY * 2^min(failures - 1, 5), MAX_DELAY)`, as cTelnet computes it. */
+export declare function failedConnectionRetryDelayMs(failures: number): number;

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

@@ -1,3 +1,4 @@
+import Pcre2 from './triggers/pcre/Pcre2';
 type TempFn = (matches: RegExpMatchArray) => void;
 type PatternItem = {
     id: string;
@@ -9,25 +10,163 @@ type PatternItem = {
     isGroup: boolean;
     parentId: string | null;
 };
+/**
+ * An alias pattern, compiled with PCRE2 the way TAlias::compileRegex does —
+ * not as a JS RegExp, whose dialect has no inline `(?i)`/`(?x)`, no atomic or
+ * possessive groups, no `\A`/`\Z`, and reads `\p{L}` as a literal `p{L}`.
+ *
+ * Compiled on first use rather than on construction: the PCRE wasm loads
+ * asynchronously, and aliases (saved ones, and temp ones a script makes while
+ * the profile loads) can be registered before it has. Nobody types a command
+ * before then, so the first match is the earliest a compile is ever needed.
+ * A pattern that fails to compile stays failed and never matches.
+ */
+export declare class AliasPattern {
+    readonly source: string;
+    private re;
+    private failed;
+    constructor(source: string);
+    /** The compiled pattern, or null while PCRE is still loading or when the
+     *  pattern does not compile. */
+    compiled(): Pcre2 | null;
+    /** Whether PCRE has rejected the pattern — Mudlet's `mOK_init = false`,
+     *  which leaves the alias inactive. False while PCRE is still loading. */
+    invalid(): boolean;
+    /** Free the wasm-side pattern. It never matches again afterwards. */
+    destroy(): void;
+}
+/** A temporary item: the temporary half of desktop's one tree per kind,
+ *  keyed by the id the script was handed. A temp item is named after its id
+ *  (startTempAlias: setName(QString::number(id))). */
+export interface TempPatternItem {
+    /** A null pattern is an empty one, which can never match; an
+     *  uncompilable one is an AliasPattern that never compiles. See
+     *  {@link PatternEngine.addTemp}. */
+    pattern: AliasPattern | null;
+    fn: TempFn;
+    seq: number;
+    /** enableAlias/disableAlias — Tree::mActive. */
+    enabled: boolean;
+    /** Killed, waiting for the deferred cleanup (mCleanupSet): no longer
+     *  fires, and it and everything under it read as gone to exists/isActive/
+     *  findItems, but it is still counted by getProfileStats until freed. */
+    dead: boolean;
+    /** Its script did not compile: made and findable, but never fires and
+     *  isActive() says 0 (TAlias::setScript). */
+    uncompiled: boolean;
+    /** Run once when the item is killed or removed, to release its callback. */
+    onFree?: () => void;
+    freed?: boolean;
+}
+/** What a caller can tell the engine about a temp item. */
+export interface TempPatternOptions {
+    /** The id to file it under, drawn by the caller from the profile's shared
+     *  sequence; the engine draws its own when absent (a bare test engine). */
+    id?: number;
+    uncompiled?: boolean;
+    onFree?: () => void;
+}
 export declare class PatternEngine<T extends PatternItem> {
-    protected readonly temp: Map<number, {
-        pattern: RegExp;
-        fn: TempFn;
-    }>;
-    /** Key for this engine's own temp map. NOT an item id: addTemp hands the
-     *  caller an unsubscribe function, and the id Lua sees is allocated by the
-     *  runtime from the profile's shared sequence. Drawing from that sequence
-     *  here would burn a number per temp item and put permAlias/tempAlias out
-     *  of step (Alias_spec pins the run of ids). */
-    protected nextInternalId: number;
+    protected readonly temp: Map<number, TempPatternItem>;
+    /** Fallback id source for a bare engine — see TempPatternOptions.id. */
+    private idSeq;
+    /** Each permanent item hanging off a temporary one (as of the last
+     *  loadPerm) → that temporary root's id; and the parent refs in use. */
+    protected permTempRoot: Map<string, number>;
+    private tempParentRefs;
+    private orphanedParents;
+    private onOrphans;
     protected permCompiled: Array<{
         item: T;
-        re: RegExp;
+        re: AliasPattern;
+    }>;
+    /** {@link permCompiled} by item id — what is loaded and active right now. */
+    protected permById: Map<string, {
+        item: T;
+        re: AliasPattern;
     }>;
-    /** Number of live session-scoped temp items (Mudlet `getProfileStats` temp count). */
+    /** Every permanent item with a pattern, active or not, in tree order. A
+     *  fresh array on each {@link loadPerm}, so a pass can keep walking the one
+     *  it started with — Mudlet's `copyOfNodeList` — while a script it runs
+     *  enables or disables items, which reloads this engine synchronously. */
+    protected permOrder: readonly string[];
+    protected regCounter: number;
+    private readonly permReg;
+    /** Each item in {@link permOrder} → the seq of the root it hangs under. */
+    protected permRootSeq: Map<string, number>;
+    /** Temp items in the tree — killed ones too, until the cleanup frees them
+     *  (desktop's getProfileStats walks the root list unfiltered). */
     get tempCount(): number;
-    addTemp(pattern: string | RegExp, fn: TempFn): () => void;
-    loadPerm(items: T[]): void;
+    /**
+     * Register a temporary item. A pattern that will never match is still an
+     * item: TAlias::compileRegex records a compile failure rather than refusing
+     * to build the alias, and TAlias::match then returns false on every line
+     * (`if (re == nullptr)`, and `mRegexCode.isEmpty()` a few lines later). The
+     * caller gets a real id back either way, which is what lets a broken alias
+     * be seen in the editor and repaired instead of vanishing.
+     *
+     * Both cases used to leak: an uncompilable pattern threw the RegExp
+     * SyntaxError out through the Lua binding, and an EMPTY one compiled to
+     * //, which matches every command typed and consumed the lot. A pattern
+     * that PCRE rejects now simply never matches — see {@link AliasPattern}.
+     */
+    addTemp(pattern: string, fn: TempFn, opts?: TempPatternOptions): () => void;
+    /** {@link addTemp}, handing back the item's id rather than a disposer. */
+    createTemp(pattern: string, fn: TempFn, opts?: TempPatternOptions): number;
+    /** Take a temp item out of the tree now, releasing its callback. Its
+     *  permanent children are left for the owner to remove (see
+     *  takeOrphanedParents). */
+    removeTemp(id: number): void;
+    private release;
+    /** Mudlet `killAlias` on a temp item: it stops at once and is queued for
+     *  the deferred cleanup, which frees it with its whole subtree. False for
+     *  an unknown id or one already waiting to be freed. */
+    killTemp(id: number): boolean;
+    /** `killAlias(name)` for the temporaries: the newest live one so named. */
+    killTempByName(name: string): boolean;
+    /** Free every temp item killed since the last call — the unit's
+     *  doCleanup(). */
+    reapKilled(): void;
+    /** Tree keys of freed temp items 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, killed or not. */
+    hasTemp(id: number): boolean;
+    /** In the tree and not killed — what exists() counts. */
+    hasLiveTemp(id: number): boolean;
+    /** Live, switched on and compiled — isActive(). */
+    tempIsActive(id: number): boolean;
+    /** Live temp ids, ascending, whose name — the id itself — passes `test`. */
+    liveTempIds(test: (name: string) => boolean): number[];
+    /** The temp item named `name` — its id's exact spelling — or null; a
+     *  killed one only when `includeDead` (perm* parent resolution). */
+    newestTempByName(name: string, includeDead: boolean): number | null;
+    /** enable/disable a live temp item. False for an unknown or killed one —
+     *  re-enabling a corpse would resurrect it. */
+    setTempEnabled(id: number, enabled: boolean): boolean;
+    /** The order seq of a permanent item's root: its own root's, or — for one
+     *  hanging off a temporary item — that item's. */
+    protected rootSeqOf(id: string): number;
+    /** Whether a permanent item's temporary root (if it has one) is live and
+     *  active: desktop reaches it only through that parent's match(). */
+    protected reachable(id: string): boolean;
+    /**
+     * Give the profile's saved items their place in the firing order before
+     * any script can make a temporary one. Desktop builds them from the
+     * profile XML before a script runs, so a temp item 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;
+    /** `blocked`: items whose code will not compile, which Mudlet leaves
+     *  inactive — see buildEffectivelyEnabledIds. */
+    loadPerm(items: T[], blocked?: ReadonlySet<string>): void;
+    /** Whether the permanent item `id` is loaded with a pattern PCRE rejects. */
+    hasInvalidPattern(id: string): boolean;
     destroy(): void;
 }
 export {};