@mudlet/mudlet-web 0.3.0

package/dist-lib/mud/text/hyperlinkVisibility.d.ts

@@ -0,0 +1,37 @@
+/**
+ * OSC 8 hyperlink `visibility` (Mudlet's THyperlinkVisibilityManager).
+ *
+ * Timer- and click-driven actions are wired directly onto the rendered link
+ * element by {@link applyVisibility}:
+ *   - **reveal**            — start hidden, reveal after `delayMs` (from render).
+ *   - **conceal**           — start visible, conceal on click (now, or after
+ *                             `delayMs`); with expire flags, arm instead.
+ *   - **reveal-then-conceal** — reveal after `delayMs`, then conceal on click.
+ *   - **deletesEntireLine** — conceal removes the whole output line.
+ *
+ * Expire-on-event links (conceal on the next user input / prompt / output after
+ * being clicked) can't be driven from the element alone — they're tagged with
+ * `data-osc-vis-*` attributes here, and {@link HyperlinkVisibilityController}
+ * (owned by the session) conceals them when the matching session event fires.
+ * The first occurrence of each trigger is skipped: it's the response to the very
+ * command the click sent, not a fresh event.
+ */
+import type { VisibilitySettings } from "./hyperlinkConfig";
+/** Wire one link element's visibility behaviour. Call *after* the element's base
+ *  style has been applied (it may set `visibility: hidden`, which a later
+ *  `cssText` assignment would wipe). */
+export declare function applyVisibility(el: HTMLElement, vis: VisibilitySettings): void;
+/**
+ * Session-scoped driver for expire-on-event visibility links. The session calls
+ * `onInput`/`onPrompt`/`onOutput` as those events occur; each conceals every
+ * armed link whose trigger set includes that event (after skipping the first
+ * occurrence). `getRoot` supplies the DOM subtree to scan (the live output).
+ */
+export declare class HyperlinkVisibilityController {
+    private readonly getRoot;
+    constructor(getRoot: () => ParentNode | null);
+    onInput(): void;
+    onPrompt(): void;
+    onOutput(): void;
+    private fire;
+}

package/dist-lib/mud/text/oscLinkManager.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Session-scoped state for stateful OSC 8 links — `selection` groups and
+ * `:visited` tracking (Mudlet's selection manager + visited links).
+ *
+ * The styling itself is precomputed by the renderer and stashed on each link
+ * element as `data-css-base` / `data-css-selected` / `data-css-visited`; this
+ * manager only holds the *state* (which group values are selected, which links
+ * have been activated) and re-applies the right stashed style to the live link
+ * elements when state changes. Restyling queries the document, so it updates
+ * every rendered run of a group across lines — not just the clicked one.
+ */
+export declare class OscLinkManager {
+    /** group → set of currently-selected values. */
+    private readonly selected;
+    /** Activated link keys (the command URI), for `:visited` styling. */
+    private readonly visited;
+    isSelected(group: string, value: string): boolean;
+    isVisited(key: string): boolean;
+    /**
+     * Toggle `(group, value)` and return its new selected state. `exclusive`
+     * groups behave like radio buttons (one value at a time); non-exclusive like
+     * checkboxes (independent toggles).
+     */
+    toggleSelection(group: string, value: string, exclusive: boolean): boolean;
+    /** Seed an initially-selected value (server sent `selection.selected:true`). */
+    select(group: string, value: string, exclusive: boolean): void;
+    markVisited(key: string): void;
+    /**
+     * Re-apply the correct stashed style to every OSC link element under `root`,
+     * based on current selection/visited state. Selection wins over visited.
+     * No-op when `root` is null (e.g. a headless call with no DOM).
+     */
+    restyle(root: ParentNode | null | undefined): void;
+    clear(): void;
+}

package/dist-lib/mud/text/wcwidth.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Terminal display-width tables (a wcwidth-style implementation).
+ *
+ * MUD output is laid out on a monospace grid: every character occupies an
+ * integer number of cells (0, 1, or 2). Browsers don't enforce that — a glyph
+ * the chosen font lacks falls back to another font with a different advance
+ * width, wide CJK/emoji render at their natural width, and combining marks add
+ * code-unit length but no visual width. The renderer uses these tables to box
+ * each grapheme into a fixed `Nch` cell so columns stay aligned regardless of
+ * the font.
+ *
+ * Ranges follow Markus Kuhn's wcwidth (combining + East Asian Wide/Fullwidth),
+ * extended with the Supplementary-plane emoji/symbol blocks. BMP dingbats and
+ * miscellaneous symbols (☎ ★ ♠ …) are East Asian *Ambiguous* and kept at width
+ * 1, matching the common "narrow" terminal rendering.
+ */
+/**
+ * Display width of a single Unicode code point, in monospace cells.
+ * Returns 0 for combining/zero-width, 2 for wide, 1 otherwise. C0/C1 control
+ * characters (which shouldn't reach the renderer) are treated as 0.
+ */
+export declare function codePointWidth(cp: number): 0 | 1 | 2;
+/**
+ * Display width of a grapheme cluster (base + any combining marks / ZWJ
+ * sequence). Width is the widest code point in the cluster, so an emoji ZWJ
+ * sequence stays 2 and a base+diacritic stays at the base's width.
+ */
+export declare function clusterWidth(cluster: string): 0 | 1 | 2;
+/** Total display width of a string, in monospace cells. */
+export declare function stringWidth(text: string): number;
+export interface DisplayCell {
+    /** The grapheme cluster occupying this cell. */
+    text: string;
+    /** Number of monospace cells the grapheme occupies (0, 1, or 2). */
+    width: 0 | 1 | 2;
+}
+/**
+ * Split text into display cells, one per grapheme cluster. Uses
+ * `Intl.Segmenter` for proper cluster boundaries (so combining marks fold into
+ * their base), falling back to per-code-point iteration where it is missing.
+ */
+export declare function segmentCells(text: string): DisplayCell[];
+/** Fast check: pure printable ASCII renders at exactly 1 cell with no boxing. */
+export declare function isPlainAscii(text: string): boolean;

package/dist-lib/mud/text/xterm256.d.ts

@@ -0,0 +1,2 @@
+declare const xterm256: string[];
+export default xterm256;

package/dist-lib/mud/timers/TimerEngine.d.ts

@@ -0,0 +1,61 @@
+import type { TimerNode } from '../../storage/schema';
+export type { TimerNode };
+type TempFn = () => void;
+type ExecuteFn = (timer: TimerNode) => void;
+export declare class TimerEngine {
+    private readonly temp;
+    /** Permanent timers keyed by stored TimerNode id (uuid). Two timers can
+     *  share a name; we keep id as the canonical handle and build a separate
+     *  name → id index for Mudlet's name-based lookups. */
+    private readonly perm;
+    /** Name → first matching id, used by remainingTime / kill-by-name. */
+    private readonly permNameToId;
+    private nextId;
+    /** Number of live session-scoped temp timers (Mudlet `getProfileStats` temp count). */
+    get tempCount(): number;
+    addTemp(seconds: number, fn: TempFn, repeat?: boolean): number;
+    /**
+     * Fire every one-shot timer that has come due, without waiting for the
+     * event loop to deliver its setTimeout.
+     *
+     * This exists for `waitForEvent`, the busted-only helper Mudlet implements
+     * by spinning a nested QEventLoop. A browser can't re-enter its event loop,
+     * so a synchronous wait would block the very setTimeout it is waiting on and
+     * deadlock; pumping the due timers by hand is the equivalent of Qt draining
+     * its timer queue inside that nested loop.
+     *
+     * Repeating timers are deliberately skipped: their setInterval is still
+     * armed, and firing them here would double-fire each tick. A repeat timer
+     * therefore misses ticks across a synchronous wait — the same thing that
+     * happens whenever the main thread is busy.
+     *
+     * Returns the number of timers fired.
+     */
+    pumpDue(now?: number): number;
+    killTimer(id: number): boolean;
+    /**
+     * Cached previous load. `nodes` is the TimerNode keyed by id, `desc` is the
+     * shape that determines whether the running setTimeout/setInterval is still
+     * correct (seconds, repeat, isGroup, code presence, name) — if `desc` is
+     * unchanged AND the timer is still enabled, the live handle is left alone.
+     * This makes a name-toggle that disables one timer cost one clearTimeout
+     * instead of "clear all + recreate all".
+     */
+    private readonly prevDesc;
+    private descOf;
+    loadPerm(timers: TimerNode[], executeFn: ExecuteFn): void;
+    private startPerm;
+    private killPermHandle;
+    /**
+     * Mudlet `remainingTime(idOrName)` — seconds until the next fire. For
+     * non-repeating timers, returns the time left before the one and only
+     * fire. For repeating timers, returns the time until the next tick.
+     * Returns -1 if no live timer matches (Mudlet's miss sentinel).
+     *   - Numeric arg: looks up tempTimer ids only.
+     *   - String arg: looks up permanent timer names; falls back to the stored
+     *     TimerNode id when the string is a uuid that no name matched.
+     */
+    remainingTime(idOrName: number | string): number;
+    private stopPerm;
+    destroy(): void;
+}

package/dist-lib/mud/triggers/ChunkProcessor.d.ts

@@ -0,0 +1,11 @@
+import type { MudClient } from '../connection/MudClient';
+export interface ChunkProcessor {
+    /** Called with the full sanitized text chunk from each WebSocket frame. */
+    processChunk(data: string, timestamp: number, client: MudClient): void;
+}
+/**
+ * Passthrough — pushes each chunk to the message buffer so it travels through
+ * flushLines → ScriptingEngine, which handles both rendering (via 'message')
+ * and trigger processing in one pass.
+ */
+export declare function createPassthroughProcessor(): ChunkProcessor;

package/dist-lib/mud/triggers/TriggerEngine.d.ts

@@ -0,0 +1,188 @@
+import type { TriggerNode } from '../../storage/schema';
+export type { TriggerNode };
+type Capture = string | undefined;
+type TempFn = (matches: Capture[], spans?: {
+    captureSpans: CaptureSpan[];
+    namedSpans?: Record<string, CaptureSpan>;
+    matchSpan?: CaptureSpan;
+}, namedGroups?: Record<string, string>) => void;
+/**
+ * Result of matching a trigger pattern against a line.
+ *
+ * `captureSpans` and `namedSpans` describe where each capture sits in the
+ * source line — needed by `selectCaptureGroup` so it can re-select the
+ * actual occurrence rather than picking the first textual match. Spans line
+ * up positionally with `captures` (so `captureSpans[0]` is the position of
+ * `captures[0]`, i.e. capture group 1). Both are optional because non-PCRE
+ * matchers (substring/exactMatch/etc.) don't produce capture-group spans.
+ */
+type CaptureSpan = {
+    start: number;
+    length: number;
+};
+/**
+ * What `matchPerm`/`processAndTrigger` hand back to the engine. Adds the
+ * trigger node and the AND-trigger-only `multimatches` array on top of the
+ * raw `MatchResult`.
+ */
+export type TriggerMatch = {
+    trigger: TriggerNode;
+    captures: Capture[];
+    matchedText: string;
+    multimatches?: Capture[][];
+    namedGroups?: Record<string, string>;
+    captureSpans?: CaptureSpan[];
+    namedSpans?: Record<string, CaptureSpan>;
+    matchStart?: number;
+};
+export declare class TriggerEngine {
+    private readonly temp;
+    private nextId;
+    private inProcessTemp;
+    private permCompiled;
+    private allById;
+    private regCounter;
+    private permReg;
+    private unified;
+    private orderDirty;
+    private cache;
+    private lineCounter;
+    private readonly chainOpenUntil;
+    private hasChildren;
+    private andStates;
+    private filterActiveText;
+    private filterActiveOffset;
+    /** Resolves once PCRE wasm is initialized and patterns can be compiled. */
+    static ready(): Promise<void>;
+    /** Number of live session-scoped temp triggers (Mudlet `getProfileStats` temp count). */
+    get tempCount(): number;
+    /**
+     * Register a temp trigger. `kind` selects the match strategy:
+     *   - `'regex'`     — PCRE, same syntax as permanent triggers (Mudlet
+     *                     `tempRegexTrigger`). The callback receives
+     *                     `[fullMatch, capture1, capture2, ...]`; unmatched
+     *                     optional groups surface as empty strings.
+     *   - `'substring'` — literal `String.prototype.includes` (Mudlet
+     *                     `tempTrigger`). The callback receives `[pattern]`
+     *                     so capture-group access against the substring is a
+     *                     no-op rather than a metacharacter trap.
+     *   - `'startOfLine'`— literal `String.prototype.startsWith` (Mudlet
+     *                     `tempBeginOfLineTrigger`). Not anchored regex —
+     *                     just a prefix check, which is why it's cheap.
+     *                     Callback receives `[pattern]`.
+     *   - `'exactMatch'`— full-line equality (Mudlet
+     *                     `tempExactMatchTrigger`). Callback receives `[line]`.
+     *   - `'prompt'`    — fires on every line the server flags as a prompt
+     *                     (Mudlet `tempPromptTrigger`); `pattern` is ignored.
+     *                     Callback receives `[line]`.
+     * Invalid regex patterns return a no-op disposer so callers don't need
+     * to special-case compile failures.
+     */
+    addTemp(pattern: string, fn: TempFn, kind?: 'regex' | 'substring' | 'startOfLine' | 'exactMatch' | 'prompt'): () => void;
+    /**
+     * Mudlet `tempLineTrigger(from, howMany, fn)`. A position-based trigger with
+     * no pattern: it fires `fn([lineText])` on `howMany` consecutive lines,
+     * starting `from` lines ahead (`from = 1` → the next line). It self-expires
+     * after the last fire. When created from within a handler, the line on which
+     * it was created is skipped (see `inProcessTemp`/`skipFirst`) so `from`
+     * counts from the next line in every creation context. Returns a disposer
+     * for early cancellation.
+     */
+    addTempLine(from: number, howMany: number, fn: TempFn): () => void;
+    loadPerm(items: TriggerNode[]): void;
+    /** Fresh compile for an item not present in the cache. Returns a CachedEntry
+     * with `compiled: null` when no patterns produced a usable matcher — that
+     * negative result is cached so we don't retry on every loadPerm. */
+    private compileItem;
+    processTemp(line: string, isPrompt?: boolean): void;
+    /** Match + fire a single temp trigger against `line`. Self-expiring `line`
+     *  triggers delete themselves (and dirty the unified order) when spent. */
+    private fireTempEntry;
+    matchPerm(line: string, isPrompt?: boolean): TriggerMatch[];
+    /**
+     * Match one permanent compiled entry against `line`, appending any matches
+     * to `out`. Updates chain/AND/filter state exactly as the old inline loop
+     * did. `seen` dedupes a single OR/group item within one line pass; it is
+     * shared across all entries processed for that line.
+     */
+    private matchPermEntry;
+    /**
+     * Mudlet-faithful single pass: walk the one ordered list of permanent and
+     * temporary triggers (see the ordering notes on the fields) and, for each
+     * node in turn, match + act on it before moving to the next. Permanent
+     * matches are handed to `exec` inline (the caller runs the trigger's
+     * command/code); temporary triggers fire their own callback. Because a
+     * runtime temp sorts after the permanent triggers that existed when it was
+     * created, a permanent trigger on a line runs before a temp that also
+     * matches it — which is exactly the order Mudlet produces.
+     *
+     * The processing list is snapshotted up front (like Mudlet's
+     * `copyOfNodeList`), so triggers created mid-pass don't fire on the current
+     * line, and `inProcessTemp` is saved/restored to stay correct under the
+     * re-entrancy a handler can cause via `feedTriggers`.
+     */
+    process(line: string, isPrompt: boolean, exec: (match: TriggerMatch) => void): void;
+    /** Rebuild the merged, path-sorted processing list from the current
+     *  permanent entries and temporary triggers. Called lazily from process()
+     *  when either source changed. */
+    private rebuildOrder;
+    /** The registration-seq path from the root ancestor down to `item`. */
+    private permPath;
+    setLuaEval(fn: ((code: string, line: string) => boolean) | null): void;
+    /**
+     * Wire the buffer-aware colour check used by `colorTrigger` patterns. The
+     * matcher receives the parsed `(fg, bg)` indices and asks the registered
+     * callback whether the line just appended to the main console carries any
+     * segment with those colours. ScriptingEngine sets this to delegate to
+     * `ScriptingAPI.currentLineMatchesColor`. Passing `null` disables every
+     * colour trigger (e.g. during runtime teardown).
+     */
+    setColorMatcher(fn: ((fg: number, bg: number) => boolean) | null): void;
+    destroy(): void;
+    private processAndTrigger;
+    /**
+     * Record a chain-head match: open the chain for `fireLength` more lines and,
+     * if the trigger is also a filter, stash the captured/matched text so
+     * descendants see it as their effective input.
+     */
+    private openChain;
+    /**
+     * Mudlet `setTriggerStayOpen(name, lines)`: keep the named chain head(s)
+     * open for `lines` more lines of input, starting from the line currently
+     * being processed. This is transient runtime state — it mutates only the
+     * `chainOpenUntil` window, never the persisted `fireLength` on the node, so
+     * the trigger's stored definition is untouched and the override expires
+     * naturally as input scrolls past.
+     *
+     * `matchPerm` post-increments `lineCounter`, so during a trigger's script
+     * the line just matched is `lineCounter - 1`; the window math then mirrors
+     * `openChain` exactly. Negative counts clamp to 0 (open for the current
+     * line only). `ids` are resolved by name by the caller.
+     */
+    setStayOpen(ids: string[], lines: number): void;
+    /**
+     * Returns the effective line to match against for `item`.
+     * If a filter-trigger ancestor has active filter text, that text is used instead.
+     * Innermost filter wins.
+     */
+    private getEffectiveLine;
+    /** The offset within the ORIGINAL line at which `item`'s effective (filtered)
+     *  input begins — 0 unless it sits under a filter ancestor. Mirrors
+     *  getEffectiveLine: the innermost filter ancestor's recorded offset. */
+    private getEffectiveOffset;
+    /** Return a copy of `r` with every span (matchStart, captureSpans, namedSpans)
+     *  shifted by `offset` — used to re-base a filtered descendant's spans onto
+     *  the original line so selectCaptureGroup/selectString hit the right column.
+     *  Zero-length (unmatched-group) placeholders keep length 0. */
+    private shiftResultSpans;
+    /**
+     * A trigger is chain-accessible if every patterned ancestor has an open
+     * chain (matched within the last fireLength lines, inclusive of the current
+     * line). Pattern-less ancestors (pure folders) always grant access. This
+     * applies regardless of whether the ancestor is a folder or a leaf with its
+     * own script — Mudlet treats any patterned trigger with children as a chain
+     * head.
+     */
+    private isChainAccessible;
+    private computeDepth;
+}

package/dist-lib/mud/triggers/pcre/Pcre2.d.ts

@@ -0,0 +1,26 @@
+export type Pcre2MatchGroup = {
+    start: number;
+    end: number;
+    match: string;
+    name?: string;
+    group?: number;
+};
+export type Pcre2Match = {
+    length: number;
+    [k: number]: Pcre2MatchGroup;
+    [k: string]: Pcre2MatchGroup | number;
+};
+/** Drop the cached line so the next match re-encodes. Used after teardown or
+ *  when callers want to be sure a stale buffer can't be reused. */
+export declare function resetLineBuffer(): void;
+export default class Pcre2 {
+    private codePtr;
+    private matchData;
+    private readonly nametable;
+    static init(): Promise<void>;
+    constructor(pattern: string, flags?: string);
+    destroy(): void;
+    match(subject: string, start?: number): Pcre2Match | null;
+    matchAll(subject: string): Pcre2Match[];
+    private getLastError;
+}

package/dist-lib/scripting/EngineHost.d.ts

@@ -0,0 +1,152 @@
+import type { InstallOutcome } from './ScriptingAPI';
+/**
+ * Everything {@link ScriptingAPI} needs from {@link ScriptingEngine}.
+ *
+ * `ScriptingAPI` is constructed before the engine (the engine takes the API in
+ * its own constructor), so the API cannot simply hold an engine reference — the
+ * dependency is genuinely circular in construction order. That used to be
+ * worked around with 57 individual nullable callback fields, each with its own
+ * `setXxxCallback` setter and its own `?.() ?? fallback` at the call site:
+ * ~400 lines of indirection where a missed wiring failed silently at runtime.
+ *
+ * This interface replaces all of that with a single late-bound reference. The
+ * method names are the engine's own — `ScriptingEngine` satisfies the interface
+ * with the methods it already had, so binding is `api.setHost(this)` once.
+ *
+ * Members are grouped the way the engine groups them, not alphabetically.
+ */
+export interface EngineHost {
+    /** Run a chunk of Lua on behalf of a clicked hyperlink. Errors are reported
+     *  through the API's error channel rather than thrown. */
+    runLinkCode(code: string): void;
+    /** Push text through the full alias pipeline, sending it to the MUD if no
+     *  alias consumes it. Backs Mudlet's `expandAlias`. */
+    expandAlias(text: string, echo: boolean): void;
+    /** Raise `sysDataSendRequest` and report whether a handler vetoed the send
+     *  by calling `denyCurrentSend()`. */
+    dispatchSendRequest(text: string): boolean;
+    /** Dial a connection through the engine's load gate, so a `connect()` made
+     *  during initial script load defers until scripts and triggers are ready. */
+    requestConnect(url: string): void;
+    /** Mudlet `reconnect()` — redial the last URL. Goes through the engine so
+     *  it observes the same teardown gate as {@link requestConnect}; calling
+     *  `session.reconnect()` directly would open a socket during disposal. */
+    requestReconnect(): boolean;
+    /** Run a synthetic batch of lines through the same pipeline as network
+     *  output, so `feedTriggers` shares ordering semantics with real data. */
+    processFlushBatch(groups: {
+        text: string;
+        type: string;
+    }[]): void;
+    /** Apply any coalesced trigger/alias reloads immediately instead of on the
+     *  scheduled microtask. The Mudlet `perm…`, `enableTrigger` and
+     *  `disableTrigger` families take effect at once, so a script that creates
+     *  or toggles a trigger and then feeds a line in the same chunk must see the
+     *  new state — the microtask cannot run until that chunk returns. */
+    flushPendingApplies(): void;
+    /** Raise a Mudlet event with the given arguments. */
+    raiseEvent(event: string, args: unknown[]): void;
+    installPackageFromVfsPath(path: string): InstallOutcome;
+    uninstallPackageByName(name: string): boolean;
+    getPackageNames(): string[];
+    getPackageInfo(name: string): Record<string, string>;
+    setPackageInfo(name: string, key: string, value: string): boolean;
+    installModuleFromPath(path: string): InstallOutcome;
+    uninstallModuleByName(name: string): boolean;
+    syncModuleToFile(name: string): Promise<void>;
+    reloadModuleFromFile(name: string): boolean;
+    setModuleSync(name: string, sync: boolean): void;
+    getModuleSync(name: string): boolean;
+    setModulePriority(name: string, priority: number): boolean;
+    getModulePriority(name: string): number;
+    getModuleNames(): string[];
+    getModulePath(name: string): string | null;
+    setModuleInfo(name: string, key: string, value: string): boolean;
+    /** Module manifest fields as a flat record, with any Lua-set overrides
+     *  applied. Null when no module by that name is installed. */
+    getModuleInfoRecord(name: string): Record<string, unknown> | null;
+    /** Rewrite VFS-relative `url(...)` references in a stylesheet to the paths
+     *  the service worker serves. Returns the CSS unchanged with no VFS. */
+    rewriteCss(css: string): string;
+    /** Rewrite profile-local asset refs (`<img src>`, inline `style` url(...))
+     *  in Lua-supplied HTML to the paths the service worker serves. Returns the
+     *  HTML unchanged with no VFS. */
+    rewriteHtml(html: string): string;
+    /** Read raw bytes from the profile VFS, or null if missing/unreadable.
+     *  Backs synchronous binary consumers such as setMovie's GIF decoder. */
+    readFileBytes(path: string): Uint8Array | null;
+    toggleScriptByName(name: string, enabled: boolean): boolean;
+    toggleTriggerByName(name: string, enabled: boolean): boolean;
+    toggleTimerByName(name: string, enabled: boolean): boolean;
+    toggleAliasByName(name: string, enabled: boolean): boolean;
+    toggleKeyByName(name: string, enabled: boolean): boolean;
+    toggleToolBarByName(name: string, show: boolean): boolean;
+    setTriggerStayOpenByName(name: string, lines: number): boolean;
+    /** The saved keybinding carrying this numeric id, or null — getKeyCode
+     *  resolves a permanent key by the id permKey returned, not only by name. */
+    keyNodeByNumericId(numericId: number): {
+        key: string;
+        modifiers: string[];
+    } | null;
+    /** Mudlet's Host::setForceMXPProcessorOn — run the in-band MXP parser with
+     *  no option-91 handshake. */
+    setForceMxpProcessorOn(on: boolean): void;
+    /** Mudlet `exists(nameOrId, type)` — count of matching items. */
+    existsByName(nameOrId: string | number, type: string): number;
+    /** enable/disable a script-created temp trigger or alias by its numeric id.
+     *  False when no live temp item has that id. */
+    setTempItemEnabled(id: number, enabled: boolean): boolean;
+    /** Mudlet `isActive(nameOrId, type)` — count of matching *active* items. */
+    isActiveByName(nameOrId: string | number, type: string, checkAncestors: boolean): number;
+    ancestorsById(id: number, type: string): Array<{
+        id: number;
+        name: string;
+        node: string;
+        isActive: boolean;
+    }> | null;
+    findItemsByName(name: string, type: string, exact: boolean, caseSensitive: boolean): number[];
+    isAncestorsActiveById(id: number, type: string): boolean | null;
+    getProfileStats(): Record<string, unknown>;
+    createPermScript(name: string, parent: string, code: string): number;
+    createPermRegexTrigger(name: string, parent: string, regexes: string[], code: string): number;
+    createPermSubstringTrigger(name: string, parent: string, patterns: string[], code: string): number;
+    createPermBeginOfLineStringTrigger(name: string, parent: string, patterns: string[], code: string): number;
+    createPermExactMatchTrigger(name: string, parent: string, patterns: string[], code: string): number;
+    createPermPromptTrigger(name: string, parent: string, code: string): number;
+    createPermAlias(name: string, parent: string, pattern: string, code: string): number;
+    createPermTimer(name: string, parent: string, delay: number, code: string): number;
+    /** `modifier` arrives as a Qt::KeyboardModifier int; the engine translates
+     *  it back into `["ctrl", …]` strings to store on the KeyNode. */
+    createPermKey(name: string, parent: string, modifier: number, key: string | number, code: string): number;
+    createTempButton(toolbar: string, name: string, code: string, orientation: number): number;
+    createTempButtonToolbar(name: string, orientation: number, location: number): number;
+    setButtonStateByName(name: string, state: boolean): boolean;
+    getButtonStateByName(name: string): boolean | null;
+    setButtonStyleSheetByName(name: string, css: string): boolean;
+    setScriptByName(name: string, code: string, pos: number): number;
+    getScriptByName(name: string, pos: number): {
+        code: string;
+        count: number;
+    } | null;
+    /** Mudlet's killTimer/killAlias/killTrigger/killKey by permanent-item name. */
+    killByName(kind: 'timer' | 'alias' | 'trigger' | 'key', name: string): boolean;
+    /** Mudlet `resetProfile()` — reload the profile with a fresh Lua VM. */
+    resetProfile(): void;
+    /** Render a map area to a PNG inside the profile VFS. */
+    exportAreaImageToVfs(areaId: number, filePath: string, zLevel?: number): {
+        path: string;
+    } | {
+        error: string;
+    };
+}
+/**
+ * The host used before a real engine is bound.
+ *
+ * `ScriptingAPI` outlives any single engine (a profile switch destroys the
+ * engine and builds a new one), and a handful of API methods can be reached
+ * during that window — so rather than making every call site re-check for null,
+ * the API always holds *a* host. Each method here returns exactly the fallback
+ * the old `?.() ?? …` expressions produced, keeping behaviour identical while
+ * collecting the "not wired yet" policy in one readable place.
+ */
+export declare const NULL_ENGINE_HOST: EngineHost;

package/dist-lib/scripting/GlobalEventChannel.d.ts

@@ -0,0 +1,36 @@
+/** A value that can cross the global-event channel. Mudlet's raiseGlobalEvent
+ *  accepts only these (string/number/boolean/nil) — tables and functions can't
+ *  cross a profile boundary. nil is represented as null. */
+export type GlobalEventArg = string | number | boolean | null;
+/**
+ * Cross-tab transport for Mudlet's `raiseGlobalEvent` — delivers an event to
+ * every OTHER open profile. Each profile lives in its own browser tab (the
+ * per-profile lock guarantees one tab per profile), so "other profiles" means
+ * "other tabs". A `BroadcastChannel` carries the event; crucially it does NOT
+ * echo a message back to the sender's own channel object, which matches Mudlet's
+ * rule that the sending profile never receives its own global event.
+ *
+ * Degrades to a no-op when BroadcastChannel is unavailable (legacy browser).
+ */
+export declare class GlobalEventChannel {
+    /** Called when a global event arrives from another tab — dispatch it
+     *  locally (through the runtime's emitEvent) so handlers fire. */
+    private readonly onEvent;
+    /** This profile's name, appended to outgoing events (see `raise`). */
+    private readonly senderName;
+    private channel;
+    constructor(
+    /** Called when a global event arrives from another tab — dispatch it
+     *  locally (through the runtime's emitEvent) so handlers fire. */
+    onEvent: (name: string, args: GlobalEventArg[]) => void, 
+    /** This profile's name, appended to outgoing events (see `raise`). */
+    senderName: () => string);
+    /**
+     * Raise a global event in all other tabs' profiles. Mirrors Mudlet: accepts
+     * string/number/boolean/nil args only (throws otherwise, surfacing as a Lua
+     * error), and appends the sending profile's name as the final argument so
+     * handlers can tell which profile it came from. Returns true.
+     */
+    raise(name: string, args: unknown[]): boolean;
+    close(): void;
+}