@mudlet/mudlet-web 0.3.0

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

@@ -0,0 +1,806 @@
+import type { MudSession } from '../mud/MudSession';
+import type { AliasEngine } from '../mud/aliases/AliasEngine';
+import { TriggerEngine } from '../mud/triggers/TriggerEngine';
+import type { TimerEngine } from '../mud/timers/TimerEngine';
+import type { KeyEngine } from '../mud/keybindings/KeyEngine';
+import type { ButtonNode, ScriptNode } from '../storage/schema';
+import { type InstallOutcome } from './ScriptingAPI';
+import type { EngineHost } from './EngineHost';
+import type { LuaGlobalEntry } from './IScriptingRuntime';
+import { ProfileVFS } from './vfs/ProfileVFS';
+import type { PackageManifest } from '../storage/schema';
+export declare class ScriptingEngine implements EngineHost {
+    private readonly session;
+    private readonly aliasEngine;
+    private readonly triggerEngine;
+    private readonly timerEngine;
+    private readonly keyEngine;
+    private readonly proxyUrlGetter;
+    private runtimes;
+    private readonly unsubs;
+    private readonly api;
+    private promptPending;
+    private mudCarryState;
+    private gmcpNegotiated;
+    private msdpNegotiated;
+    private msspNegotiated;
+    private mnesNegotiated;
+    private mxpNegotiated;
+    /** True once MXP (telnet option 91) has been negotiated on the live
+     *  connection. Gates in-band MXP markup parsing in processFlushBatch so
+     *  non-MXP MUDs (where `<grin>` is literal text) are untouched. Reset on
+     *  connect/disconnect. */
+    private mxpActive;
+    /** Mudlet's Host::mForceMXPProcessorOn — setConfig("specialForceMXPProcessorOn")
+     *  runs the in-band parser without an option-91 handshake, which is how a
+     *  script can drive MXP markup through feedTriggers on a profile that never
+     *  negotiated it. Does NOT enable the handshake replies. */
+    forceMxpProcessorOn: boolean;
+    /** Whether MXP `<SUPPORTS>`/`<VERSION>` handshake replies may be sent. Only
+     *  true when MXP was started via the telnet option-91 handshake — an
+     *  in-band-detected server's inbound MXP isn't confirmed, so we'd otherwise
+     *  spam it with text it reads as invalid commands. */
+    private mxpHandshakeEnabled;
+    /** Per-session OSC 8 preset registry (`preset:NAME` definitions). Shared
+     *  between the MXP parser and the plain-ANSI render path so a preset defined
+     *  in either mode resolves in both. */
+    private readonly osc8Presets;
+    /** Drives expire-on-event OSC 8 visibility links (conceal on the next user
+     *  input / prompt / output after they're clicked). Scans the live output. */
+    private readonly visibility;
+    /** Per-session MXP parser. The send callback carries the in-band
+     *  `<SUPPORTS>`/`<VERSION>` handshake replies (gated on
+     *  `mxpHandshakeEnabled`); `api` is read lazily at call time so this
+     *  initializer is safe before the constructor body runs. */
+    private readonly mxp;
+    private vfs;
+    private readonly runtimeReady;
+    private readonly scriptsLoaded;
+    private resolveScriptsLoaded;
+    private scriptsLoadComplete;
+    private pendingConnectUrl;
+    private readonly mapOpen;
+    private readonly connectionId;
+    private storeUnsub;
+    private triggersReady;
+    private triggersDirty;
+    private prevScripts;
+    private resetting;
+    private disposed;
+    private moduleSyncTimers;
+    private static readonly MODULE_SYNC_DEBOUNCE_MS;
+    private profileDataSaveTimer;
+    private static readonly PROFILE_DATA_SAVE_DEBOUNCE_MS;
+    /** For a linked Mudlet profile: the timestamped current/*.xml filename this
+     *  session writes back to (created lazily on first write, reused thereafter). */
+    private mudletSaveName;
+    private mspBaseUrl;
+    private gmcpMediaDefaultUrl;
+    private exitFired;
+    private readonly beforeUnload;
+    private uuidToNumericId;
+    private nextNumericId;
+    private numericIdFor;
+    constructor(session: MudSession, aliasEngine: AliasEngine, triggerEngine: TriggerEngine, timerEngine: TimerEngine, keyEngine: KeyEngine, connectionId: string, connectionName?: string, proxyUrlGetter?: () => string | undefined, injectedVfs?: ProfileVFS | null);
+    /**
+     * Subscribe to the appStore and apply diffs synchronously on every
+     * mutation. Zustand fires subscribers synchronously inside `set()`, so a
+     * UI action like `installPackage(...)` immediately propagates into the
+     * Lua runtime — handlers register before the caller's next line runs.
+     * That guarantee is what lets `notifyPackageInstalled` raise its event
+     * right after the store update without a React commit in between.
+     *
+     * Covers all five entity types — scripts, aliases, triggers, timers,
+     * keybindings — so the engine is the single owner of the
+     * store-to-runtime mapping. The UI just dispatches store actions.
+     *
+     * The first apply is gated on `output.ready` because some scripts open
+     * windows on load and the dock system needs to be wired up first.
+     * Triggers additionally wait for the PCRE wasm via TriggerEngine.ready()
+     * — patterns won't compile before that.
+     */
+    private attachToStore;
+    /**
+     * For each installed module, re-parse its on-disk XML and replace its tagged
+     * nodes in the store. Errors are logged but don't abort the rest of profile
+     * load — a corrupted module shouldn't take the whole session down.
+     */
+    private reloadModulesFromVfs;
+    /**
+     * Detect whether any node tagged with a sync-enabled module's name changed
+     * between two store states; for each module that changed, schedule a
+     * debounced write of its current XML to disk. Comparison is done per
+     * collection so an unrelated change in another module doesn't cause a write.
+     */
+    private scheduleModuleSyncForChanges;
+    private queueModuleSync;
+    /** Debounce a write of this profile's automation data to its VFS. */
+    private scheduleProfileDataSave;
+    /** Write this profile's automation data to its VFS now. */
+    private flushProfileData;
+    /**
+     * Restore this profile's saved Lua globals (Mudlet `<VariablePackage>`) into
+     * `_G`. Called once before the initial script load so handlers see their
+     * persisted state, and again after a profile reset (fresh global table).
+     */
+    private restoreSavedVariables;
+    /**
+     * Snapshot the save-listed globals out of `_G` into the store, just before a
+     * profile-data flush so the values land in `.mudix/profile.json`. Updates
+     * only the values (the save-list array reference is preserved), so the save
+     * subscription — which keys on the save-list — doesn't reschedule a flush.
+     */
+    private captureSavedVariables;
+    /**
+     * Write the live store state back into a linked Mudlet folder's profile save.
+     * Bases on the newest parseable save (so external Mudlet edits to Host/unknown
+     * fields are preserved), replaces the automation + variable packages with
+     * mudix's current data, and writes a Mudlet-style timestamped file in current/
+     * — one per session, overwritten on subsequent saves (the overwrite is safe
+     * now that the folder backend truncates). Mudlet loads the newest such file.
+     */
+    private writeBackLinkedProfile;
+    /** `_G` entries for the Variables view (user globals nested, built-ins
+     *  flagged). Empty until the runtime is up. */
+    listGlobals(): LuaGlobalEntry[];
+    /**
+     * Write the current in-store nodes for a module back to its XML file on disk.
+     * Used both by the auto-sync debounce and the "Sync to file" UI action.
+     */
+    syncModuleToFile(moduleName: string): Promise<void>;
+    /**
+     * Re-read a module's XML from disk and replace its tagged nodes in the store.
+     * Pairs with the "Reload from file" UI action.
+     */
+    reloadModuleFromFile(moduleName: string): boolean;
+    /** Toggle a module's sync flag. Updates the manifest in the store. */
+    setModuleSync(moduleName: string, sync: boolean): void;
+    /** Read a module's sync flag. Returns false if the package isn't a module. */
+    getModuleSync(moduleName: string): boolean;
+    /**
+     * Set a module's load priority. Negative values cause its scripts to load
+     * before profile scripts on the next full reload. The priority is metadata
+     * only — changing it doesn't re-run anything; the new order takes effect on
+     * the next profile open or explicit reload.
+     */
+    setModulePriority(moduleName: string, priority: number): boolean;
+    /** Read a module's load priority (default 0). Returns 0 for non-modules. */
+    getModulePriority(moduleName: string): number;
+    /** List installed module names. Order matches install order. */
+    getModuleNames(): string[];
+    /** Snapshot of a module's manifest, or null if not installed / not a module. */
+    getModuleInfo(moduleName: string): PackageManifest | null;
+    /**
+     * In-memory custom info fields set via setPackageInfo / setModuleInfo. These
+     * mirror Mudlet's mPackageInfo / mModuleInfo — volatile string→string maps
+     * that overlay the manifest-derived fields, repopulated by scripts as
+     * needed (Mudlet itself loses them on restart too).
+     */
+    private packageInfoOverrides;
+    private moduleInfoOverrides;
+    /** Manifest's standard info fields as a string→string map (Mudlet's
+     *  config.lua-derived package info keys). Empty values are omitted. */
+    private manifestInfoBase;
+    /** Overlay the in-memory custom fields for `name` onto `base` (mutates). */
+    private applyInfoOverrides;
+    /** Mudlet `getPackageInfo(name)`. Manifest fields overlaid with anything set
+     *  via setPackageInfo. Empty table when the package is unknown and nothing
+     *  was set for that name. */
+    getPackageInfo(name: string): Record<string, string>;
+    /** Mudlet `setPackageInfo(name, key, value)`. Records a custom info field.
+     *  Always succeeds (matches Mudlet, which sets the map unconditionally). */
+    setPackageInfo(name: string, key: string, value: string): boolean;
+    /** Mudlet `setModuleInfo(name, key, value)`. Records a custom info field
+     *  surfaced by getModuleInfo. Always succeeds. */
+    setModuleInfo(name: string, key: string, value: string): boolean;
+    /**
+     * Mudlet `getModulePath(name) → path`. Absolute VFS path of an installed
+     * module's XML. Modules referencing a file outside the managed package dir
+     * store it verbatim in `xmlVfsPath`; packaged modules store an XML path
+     * relative to `<profilePath>/<name>/`. Null when not installed, not a
+     * module, or no path is resolvable.
+     */
+    getModulePath(moduleName: string): string | null;
+    /**
+     * Install a module from a path inside the profile VFS. Plain XML stays in
+     * place (manifest holds the absolute VFS path). Zips/.mpackages extract into
+     * the standard pkgDir. Raises sysInstall, sysInstallPackage and
+     * sysInstallModule on success — sysInstallModule is the module-specific
+     * counterpart to sysInstallPackage. This method is reached only via the
+     * Lua `installModule()` binding, so it also raises Mudlet's
+     * `sysLuaInstallModule` (name, fileName) for ported-script parity.
+     */
+    installModuleFromPath(path: string): InstallOutcome;
+    /**
+     * Uninstall a module by name. Refuses to act on regular packages so callers
+     * can keep installPackage/uninstallPackage and installModule/uninstallModule
+     * cleanly separated. Modules unlink — the on-disk XML is left in place.
+     */
+    uninstallModuleByName(moduleName: string): boolean;
+    private findManifest;
+    private applyAliasesFromStore;
+    private applyTriggersFromStore;
+    private scheduleTriggerApply;
+    /**
+     * Drain any pending coalesced reloads synchronously. Callers that raise
+     * events whose handlers may depend on the just-mutated store (e.g.
+     * notifyPackageInstalled → sysInstallPackage) must call this between the
+     * store update and the event so handlers see the post-mutation engine state.
+     */
+    flushPendingApplies(): void;
+    private applyTimersFromStore;
+    private applyKeybindingsFromStore;
+    /**
+     * On profile open, warn about enabled keybindings the browser intercepts
+     * above the page (Ctrl+T new tab, Ctrl+W close tab, F12 devtools, …). Native
+     * Mudlet packages bind these freely, but in a browser they can never reach
+     * mudix — the warning explains why they "do nothing". Page-level shortcuts
+     * mudix can still capture (Ctrl+R, Ctrl+S, F5, …) are intentionally not
+     * flagged: they work while the client is focused, same as in Mudlet.
+     * Fired once at load (not on every store change) so it can't spam the output.
+     */
+    private warnBrowserReservedKeybindings;
+    private applyScriptsFromStore;
+    /** Map of module name → priority. Profile (no packageName) is implicitly 0. */
+    private modulePriorityMap;
+    private initRuntime;
+    /** Run a chunk of Lua on behalf of a clicked hyperlink. */
+    runLinkCode(code: string): void;
+    /** Mudlet `expandAlias` — run text through the alias pipeline, sending it
+     *  to the MUD when nothing consumes it. */
+    expandAlias(text: string, echo: boolean): void;
+    /** Mudlet `reconnect()` — redial the last URL, refused during teardown. */
+    requestReconnect(): boolean;
+    /** Raise sysDataSendRequest; true means a handler called denyCurrentSend(). */
+    dispatchSendRequest(text: string): boolean;
+    /** Names of every package installed in this profile. */
+    getPackageNames(): string[];
+    /** Module manifest fields as a flat record, with Lua-set overrides applied. */
+    getModuleInfoRecord(name: string): Record<string, unknown> | null;
+    /** Rewrite VFS-relative url(...) references to service-worker paths. */
+    rewriteCss(css: string): string;
+    /** Rewrite VFS-relative `<img src>` / inline-style refs in Lua-supplied
+     *  HTML to service-worker paths. */
+    rewriteHtml(html: string): string;
+    /** Raw-bytes reader for synchronous binary consumers (setMovie's GIF
+     *  decoder). ProfileVFS resolves leading-slash paths absolutely (so
+     *  getMudletHomeDir()-prefixed paths work) and relative ones against the
+     *  profile root. */
+    readFileBytes(path: string): Uint8Array | null;
+    private createRuntime;
+    /**
+     * Tear down a script's event-handler registrations. Used when a script is
+     * removed or transitions enabled→disabled so its handlers stop firing
+     * before the next full runtime reload.
+     *
+     * Runs synchronously once the runtime is up so the store-subscription
+     * pipeline (script removed → handlers gone) completes inside the same
+     * tick as the store mutation. See attachToStore for the rationale.
+     */
+    unloadScript(scriptId: string): void;
+    /**
+     * Raise sysInstall / sysInstallPackage. The caller is expected to have
+     * just committed the package's items to the appStore — our subscription
+     * loads the new scripts synchronously inside that commit, so by the time
+     * this method runs the package's event handlers are already registered.
+     */
+    notifyPackageInstalled(packageName: string): void;
+    /**
+     * Raise sysUninstall / sysUninstallPackage. Call this BEFORE removing the
+     * package's items from the store so the package's own handlers (and the
+     * scripts they live in) are still loaded when the event fires.
+     */
+    notifyPackageUninstalled(packageName: string): void;
+    /**
+     * Stage a File dropped on a window into the profile VFS, then raise Mudlet's
+     * sysDropEvent(filepath, suffix, x, y, name) with the resulting VFS path. The
+     * bundled packageDrop handler (Other.lua) picks it up and routes acceptable
+     * suffixes to verbosePackageInstall / verboseModuleInstall — so dropping an
+     * XML/.mpackage/.zip onto the main console or a userwindow installs it, the
+     * same as Mudlet. Non-package files just land in the profile home dir, which
+     * matches the harmless no-op packageDrop does for unrecognised suffixes.
+     */
+    private stageDroppedFile;
+    /**
+     * Install a package from a path inside the VFS. Reads the bytes synchronously,
+     * commits to the store (which loads scripts into Lua synchronously via the
+     * store subscription), then raises sysInstallPackage. The disk flush happens
+     * in the background. Returns { ok: false, error } on any failure (file
+     * missing, parse error, etc.) — the error string is both printed to the
+     * script log and handed back to Lua for Mudlet's (ok, err) contract.
+     */
+    installPackageFromVfsPath(path: string): InstallOutcome;
+    /**
+     * Handle a `Client.GUI` GMCP message: download the URL and install the
+     * resulting package. Honors `client.allowMudPackageInstall` (default true,
+     * undefined = true). Deduplicates against previously-installed packages
+     * via `manifest.sourceUrl` + `manifest.sourceVersion` so the same MUD
+     * telling us to install on every connect doesn't churn the file system.
+     * The server's declared version is recorded as `sourceVersion` and never
+     * overwrites the package's own `version` — matching Mudlet, which keeps it
+     * in a separate `Host::mServerGUI_Package_version`.
+     */
+    /**
+     * Dispatch a parsed `!!SOUND` / `!!MUSIC` tag to the SoundManager. `Off`
+     * stops playback; otherwise the file is resolved against `<profile>/media/`
+     * (downloading from `U=` on cache miss) and the resulting VFS path is
+     * handed to the SoundManager.
+     */
+    /**
+     * Print a closed caption for a media play/stop, when `enableClosedCaption`
+     * is on (Mudlet's `TMedia::printClosedCaption`). The line is emitted as
+     * normal main-output text so it renders, is logged, and rides the screen-
+     * reader announce path — exactly as Mudlet's `mpConsole->print()` does.
+     */
+    private printClosedCaption;
+    private handleMspCommand;
+    /**
+     * Resolve an MSP `file` (+ optional `U=` base URL) to a VFS-relative path
+     * the SoundManager loader can read. Per the MSP spec `U=` is a *directory*
+     * the filename is appended to (not a full URL). Downloads land in
+     * `<profile>/media/` and are reused on subsequent plays and across page
+     * reloads. Returns null when the file can't be located or fetched.
+     */
+    private resolveMspMedia;
+    /**
+     * Resolve a media `file` (+ optional base `url` directory) to a VFS-relative
+     * path under `media/` the SoundManager loader can read, downloading and
+     * caching it on a miss. Shared by MSP (`resolveMspMedia`) and the GMCP media
+     * protocol (`handleClientMedia`). The whole filename — including any
+     * subdirectories — is appended to the base URL and mirrored under `media/`,
+     * so the cache layout matches the server's. `..`/`.` segments are rejected
+     * so a hostile server can't escape the cache root. Returns null when the
+     * file can't be located or fetched.
+     */
+    private resolveMediaFile;
+    /**
+     * Handle a GMCP media message (`Client.Media.Play/Load/Stop/Default`).
+     * Mirrors Mudlet's `TMedia` MediaProtocolGMCP. The payload is the already-
+     * parsed JSON body; `action` is the lowercased segment after `Client.Media`
+     * (defaulting to `play`, matching Mudlet's bare `Client.Media`). Server-
+     * driven, so playback rides the `game` mute gate like MSP.
+     */
+    private handleClientMedia;
+    private handleClientGuiInstall;
+    /** Guards against overlapping downloads — Mudlet TMap::mImportRunning. */
+    private mapDownloadRunning;
+    /**
+     * Mudlet TMap::downloadMap + slot_replyFinished: fetch the map the game
+     * published (GMCP `Client.Map` MMP location, or an explicit URL), load it
+     * into the map store, and raise `sysMapDownloadEvent` once it has parsed
+     * successfully. Like Mudlet, `.xml` locations go through the XML map
+     * importer and everything else through the binary `.dat` reader.
+     */
+    downloadMap(remoteUrl?: string): Promise<boolean>;
+    /**
+     * Uninstall a previously installed package by name. Raises sysUninstallPackage
+     * before the store removal so the package's own handlers can still run.
+     * Removes the on-disk package directory in the background.
+     */
+    uninstallPackageByName(packageName: string): boolean;
+    /**
+     * Toggle a script's enabled flag by name (Mudlet enableScript/disableScript).
+     * The store subscription picks up the change synchronously and either loads
+     * or unloads handlers in the runtime.
+     */
+    toggleScriptByName(name: string, enabled: boolean): boolean;
+    /**
+     * Toggle triggers' enabled flag by name (Mudlet enableTrigger/disableTrigger).
+     * Mudlet matches every trigger or group sharing the name, so we do the same:
+     * toggling a group cascades to children via isEffectivelyEnabled. All
+     * matching ids are flipped in one `set()` so the store subscription (and
+     * the trigger recompile it triggers) fires exactly once.
+     */
+    toggleTriggerByName(name: string, enabled: boolean): boolean;
+    /**
+     * Mudlet `setTriggerStayOpen(name, lines)`. Keeps every trigger matching the
+     * name open for `lines` more lines of input (Mudlet matches by name, which
+     * need not be unique). This affects only the *current* run: it adjusts the
+     * engine's transient chain window, leaving the persisted trigger (and its
+     * `fireLength`) untouched. Negative line counts clamp to 0, matching Mudlet.
+     */
+    setTriggerStayOpenByName(name: string, lines: number): boolean;
+    /**
+     * Toggle timers' enabled flag by name (Mudlet enableTimer/disableTimer).
+     * Same batching as toggleTriggerByName: one set() collapses N matches into
+     * a single subscription tick (and a single TimerEngine.loadPerm rebuild).
+     */
+    toggleTimerByName(name: string, enabled: boolean): boolean;
+    /**
+     * Toggle aliases' enabled flag by name (Mudlet enableAlias/disableAlias).
+     * Mirrors trigger/timer batching: flipping a group cascades to children via
+     * isEffectivelyEnabled at compile time, so one set() rebuilds AliasEngine once.
+     */
+    toggleAliasByName(name: string, enabled: boolean): boolean;
+    /**
+     * Toggle keybindings' enabled flag by name (Mudlet enableKey/disableKey).
+     * Mudlet matches every key (or group) sharing the name. The store has no
+     * batch keybinding update, so matches are flipped one at a time; the store
+     * subscription coalesces the resulting KeyEngine reloads within the tick.
+     */
+    toggleKeyByName(name: string, enabled: boolean): boolean;
+    /**
+     * Mudlet `exists(nameOrId, type)`. With a name string, returns the count of
+     * items matching the name in the named collection. With a numeric id, looks
+     * up the perm item by its monotonic id (the one permScript/permRegexTrigger
+     * etc. return) and reports 1 if it lives in the matching collection, else 0.
+     * Type aliases follow Mudlet: "key" and "keybind" both target keybindings.
+     * Unknown types return 0.
+     */
+    /** The saved keybinding carrying this numeric id, or null. Lets getKeyCode
+     *  answer for a permanent key by the id permKey handed back, not just by
+     *  name — the key engine only indexes permanent keys by name. */
+    keyNodeByNumericId(numericId: number): {
+        key: string;
+        modifiers: string[];
+    } | null;
+    /** enable/disable a script-created temp trigger or alias by numeric id.
+     *  Those live in the Lua runtime, not the saved tree. */
+    setTempItemEnabled(id: number, enabled: boolean): boolean;
+    setForceMxpProcessorOn(on: boolean): void;
+    existsByName(nameOrId: string | number, type: string): number;
+    /**
+     * Mudlet `isActive(nameOrId, type [, checkAncestors])`. Returns the count of
+     * *active* items matching the name (1 or 0 for a numeric id). An item is
+     * active when its own enabled flag is set; with `checkAncestors` every
+     * ancestor group must be enabled too (isEffectivelyEnabled). Type aliases
+     * and the collection lookup mirror `existsByName`. Unknown types return 0.
+     */
+    isActiveByName(nameOrId: string | number, type: string, checkAncestors: boolean): number;
+    /**
+     * Shared type→node-list lookup for the tree-walking APIs (ancestors,
+     * findItems, isAncestorsActive). Type aliases mirror Mudlet: "key" and
+     * "keybind" both target keybindings. Unknown types return an empty list.
+     */
+    private nodeListForType;
+    private nodeTypeLabel;
+    /**
+     * Mudlet `ancestors(id, type)`. Walks from the item's immediate parent up to
+     * the root, returning each ancestor as `{id, name, node, isActive}` where
+     * `node` is "package"/"group"/"item" and `isActive` is that ancestor's own
+     * enabled flag. Returns null when no item of `type` carries the numeric `id`
+     * (the Lua wrapper turns that into a `(false, errMsg)` miss).
+     */
+    ancestorsById(id: number, type: string): Array<{
+        id: number;
+        name: string;
+        node: string;
+        isActive: boolean;
+    }> | null;
+    /**
+     * Mudlet `findItems(name, type [, exact [, caseSensitive]])`. Returns the
+     * numeric ids of every item (and group) whose name matches. `exact` (default
+     * true) toggles exact vs substring; `caseSensitive` (default true) toggles
+     * case folding. Empty array when nothing matches or the type is unknown.
+     */
+    findItemsByName(name: string, type: string, exact: boolean, caseSensitive: boolean): number[];
+    /**
+     * Mudlet `isAncestorsActive(id, type)`. True when every ancestor group of
+     * the item is enabled (the item's own state is ignored); true when the item
+     * sits at root with no ancestors. Returns null when no item of `type`
+     * carries the numeric `id`.
+     */
+    isAncestorsActiveById(id: number, type: string): boolean | null;
+    /**
+     * Mudlet `getProfileStats()`. Counts of total/active items per family plus
+     * the trigger pattern tally. Temporary items (tempTimer/tempAlias/... ) are
+     * not kept in the persisted node tree but live in the per-family engines, so
+     * their counts come from those engines: `temp` is the live temp count and
+     * is folded into `total`/`active` (a live temp is always active), matching
+     * Mudlet's report. Scripts have no temp form. There's no animated-GIF
+     * tracker, so `gifs` is always zero.
+     */
+    getProfileStats(): Record<string, unknown>;
+    /**
+     * Mudlet `permScript(name, parent, luaCode)`. Creates a saved Lua script
+     * named `name` under the script group `parent` (empty = root). Returns the
+     * new script's id on success, -1 if `parent` is given but no script group
+     * with that name exists. The store subscription loads the script's
+     * handlers synchronously inside the addScript commit.
+     */
+    createPermScript(name: string, parent: string, code: string): number;
+    /**
+     * Mudlet `permRegexTrigger(name, parent, regexes, luaCode)`. Creates a saved
+     * trigger named `name` under the trigger group `parent` (empty = root) with
+     * one or more regex patterns; matches fire OR-style. An empty `regexes` table
+     * creates a trigger group instead — matches the convention `permGroup` uses
+     * to bootstrap folders. Returns the new trigger's id, or -1 if `parent` is
+     * given but no trigger group with that name exists.
+     */
+    createPermRegexTrigger(name: string, parent: string, regexes: string[], code: string): number;
+    /**
+     * Mudlet `permSubstringTrigger(name, parent, patterns, luaCode)`. Same
+     * shape as createPermRegexTrigger but each pattern matches by substring
+     * (the temp-trigger semantics: literal `String.prototype.includes`).
+     */
+    createPermSubstringTrigger(name: string, parent: string, patterns: string[], code: string): number;
+    /**
+     * Mudlet `permBeginOfLineStringTrigger(name, parent, patterns, luaCode)`.
+     * Same shape as createPermSubstringTrigger but each pattern only matches at
+     * the start of the line (`String.prototype.startsWith`).
+     */
+    createPermBeginOfLineStringTrigger(name: string, parent: string, patterns: string[], code: string): number;
+    /**
+     * Mudlet `permExactMatchTrigger(name, parent, patterns, luaCode)`. Same
+     * shape as createPermSubstringTrigger but each pattern matches only on
+     * full-line equality (the temp-trigger `exactMatch` semantics).
+     */
+    createPermExactMatchTrigger(name: string, parent: string, patterns: string[], code: string): number;
+    /**
+     * Mudlet `permPromptTrigger(name, parent, luaCode)`. Creates a persistent
+     * trigger that fires on every server prompt line (GA/EOR). It carries a
+     * single pattern of type 'prompt' with empty text — not a group.
+     */
+    createPermPromptTrigger(name: string, parent: string, code: string): number;
+    private createPermTrigger;
+    /**
+     * Mudlet `permAlias(name, parent, regex, luaCode)`. Creates a saved alias
+     * named `name` under the alias group `parent` (empty = root). The pattern
+     * is treated as a PCRE regex (matches Mudlet's TAlias.mRegexCode).
+     * Returns the new alias id, or -1 if `parent` is non-empty but no alias
+     * group of that name exists.
+     */
+    createPermAlias(name: string, parent: string, pattern: string, code: string): number;
+    /**
+     * Mudlet `permTimer(name, parent, seconds, luaCode)`. Creates a saved
+     * one-shot timer under the timer group `parent` (empty = root). Returns
+     * the new timer id, or -1 if `parent` is non-empty but no timer group of
+     * that name exists.
+     */
+    createPermTimer(name: string, parent: string, delay: number, code: string): number;
+    /**
+     * Mudlet `permKey(name, parent, modifier, key, code)`. Creates a saved
+     * keybinding under the key group `parent` (empty = root). `modifier` uses
+     * the Qt::KeyboardModifier int (1=shift, 2=ctrl, 4=alt, 8=meta); -1 means
+     * "no modifier" — used by `permGroup(name,"key")` to make a key folder.
+     * Returns the new id or -1 when `parent` is non-empty but no key group of
+     * that name exists.
+     */
+    createPermKey(name: string, parent: string, modifier: number, key: string | number, code: string): number;
+    /**
+     * Mudlet `tempButton(toolbar, name, code[, orientation])`. Appends a
+     * transient button under an existing toolbar group. Returns the new id, or
+     * -1 when no toolbar of that name exists. `orientation` is round-tripped
+     * onto the leaf for parity with Mudlet — the renderer doesn't use it at the
+     * leaf, but ports that read it back via the store get a stable value.
+     */
+    createTempButton(toolbar: string, name: string, code: string, _orientation: number): number;
+    /**
+     * Mudlet `tempButtonToolbar(name [, orientation [, location]])`. Creates a
+     * transient toolbar (ButtonNode group). `orientation`: 0=horizontal,
+     * 1=vertical. `location`: 0=top, 1=bottom, 2=left, 3=right, 4=floating.
+     * Returns -1 when a toolbar group of that name already exists.
+     */
+    createTempButtonToolbar(name: string, orientation: number, location: number): number;
+    /** Mudlet `setButtonState(name, state)`. Flips the buttonState on the named
+     *  two-state button. */
+    setButtonStateByName(name: string, state: boolean): boolean;
+    /** Mudlet `getButtonState(name)`. Reads the pressed state on a two-state
+     *  button by name. Returns null when no such button (the Lua binding maps
+     *  that to nil — Mudlet returns false/error). */
+    getButtonStateByName(name: string): boolean | null;
+    /** Mudlet `setButtonStyleSheet(name, css)`. Stores raw CSS on the
+     *  ButtonNode; ButtonsBar applies it inline. */
+    setButtonStyleSheetByName(name: string, css: string): boolean;
+    /** Mudlet `showToolBar(name)` / `hideToolBar(name)`. Toggles the toolbar
+     *  group's enabled flag (the ButtonsBar already filters by
+     *  isEffectivelyEnabled, so this is the show/hide hook). */
+    toggleToolBarByName(name: string, show: boolean): boolean;
+    /**
+     * Mudlet `setScript(name, luaCode[, pos])`. Replaces the source of the
+     * `pos`-th script (1-indexed; default 1) named `name`. Updating via the
+     * store re-runs the script load through the regular subscription pipeline,
+     * so handlers re-register cleanly. Returns true on success, -1 if no such
+     * script exists.
+     */
+    setScriptByName(name: string, code: string, pos: number): number;
+    /**
+     * Mudlet `getScript(name [, pos]) → code, count`. Returns the source of the
+     * pos-th (1-indexed; default 1) script named `name` and how many scripts
+     * share that name. Returns null when none match — the Bridge.lua wrapper
+     * turns that into ("", 0).
+     */
+    getScriptByName(name: string, pos: number): {
+        code: string;
+        count: number;
+    } | null;
+    /**
+     * Mudlet `killTimer/killAlias/killTrigger/killKey(name)` deletes every
+     * permanent item sharing the given name. Returns true if at least one was
+     * removed. Mirrors `toggleTriggerByName`'s "all matches" semantics so
+     * groups and their sibling-named items vanish together. The store
+     * subscription tears down the runtime side (timers stop firing, triggers
+     * recompile) on the next tick.
+     */
+    killByName(kind: 'timer' | 'alias' | 'trigger' | 'key', name: string): boolean;
+    /**
+     * Run a single script on the existing runtime without restarting it.
+     *
+     * Runs synchronously when the runtime is already up. That sync path is
+     * load-bearing: notifyPackageInstalled raises sysInstallPackage right
+     * after applyScriptsFromStore returns, and the package's own event
+     * handlers (and the function `_G[scriptName]` they dispatch to) must be
+     * defined by then. An `await` here — even on an already-resolved promise
+     * — would defer the load to a microtask and the event would fire against
+     * an empty handler set.
+     */
+    reloadScript(script: ScriptNode): void;
+    /**
+     * Force-run a profile script's body right now, even if its code is unchanged.
+     * Backs the editor's "Run" / "Save & Run" button: the store subscription only
+     * re-runs a script when its code or handlers actually change (so editing one
+     * script doesn't re-execute its untouched siblings), which means clicking
+     * "Run" twice — or running a script you didn't edit — would otherwise do
+     * nothing. wrapScript kills the script's previously registered anonymous
+     * handlers before re-registering, so repeated runs stay idempotent.
+     */
+    runScript(scriptId: string): void;
+    private runScriptLoad;
+    get currentVFS(): ProfileVFS | null;
+    /**
+     * Send a command from the command bar. Raises sysDataSendRequest, then either
+     * sends (and echoes locally) or aborts when a handler calls denyCurrentSend().
+     */
+    sendCommand(text: string): void;
+    /** Run input through aliases. Returns true if an alias matched (caller should not send). */
+    processInput(text: string): boolean;
+    /** Process a keyboard event. Returns true if a keybinding consumed it. */
+    processKey(event: KeyboardEvent): boolean;
+    raiseEvent(event: string, args?: unknown[]): void;
+    /** Raise sysExitEvent at most once, while the Lua runtime is still alive. */
+    private fireExit;
+    notifyMapOpen(): void;
+    /** Hand the API a getter for the current command-line text, used until the
+     *  first {@link setCmdLineValue} mirrors one. Pass null to clear. */
+    setCmdLineProvider(fn: (() => string) | null): void;
+    /** Mirror a command-bar edit so Lua's getCmdLine() reads it without waiting
+     *  for a re-render. Called by ProfileSession on every change. */
+    setCmdLineValue(text: string): void;
+    /** Hand the API a startLogging hook. Wired by ProfileSession, which owns
+     *  the actual SessionLogger lifecycle. */
+    setLoggingToggler(fn: ((enabled: boolean) => boolean) | null): void;
+    /** Mudlet's "Show errors in main console" — when on, script errors are also
+     *  echoed (in red) into the main output window, not just the Errors tab. */
+    setShowErrorsInMainWindow(enabled: boolean): void;
+    /** Mudlet `appendLog(text)` — forward to the active SessionLogger. */
+    setLogAppender(fn: ((text: string) => void) | null): void;
+    /** Mudlet `closeMudlet()` — close the active profile (disconnect + return
+     *  to the connection screen). */
+    setCloseProfileCallback(fn: (() => void) | null): void;
+    /**
+     * Mudlet `exportAreaImage(areaID, filePath[, zLevel])`. Renders the area to
+     * PNG bytes via the mounted map widget's renderer, then writes them to the
+     * profile VFS at `filePath` (relative paths resolve under the profile root,
+     * the same convention as `io.open`/`downloadFile`). Returns the absolute
+     * path written, or an error string (no VFS, mapper not open, or write
+     * failure). Mudlet requires the mapper open; mudix's renderer lives in the
+     * map widget, so the same precondition applies.
+     */
+    exportAreaImageToVfs(areaId: number, filePath: string, zLevel?: number): {
+        path: string;
+    } | {
+        error: string;
+    };
+    /**
+     * Mudlet `resetProfile()` — reload the entire profile as if just reopened:
+     * clear every UI surface, tear down and recreate the Lua runtime (fresh
+     * globals + event handlers), and re-run all scripts/aliases/triggers/timers/
+     * keys from the current profile state. The reinit is deferred to a fresh
+     * task: we are invoked from inside a Lua→JS call, and closing the lua_State
+     * mid-call would free the VM under the running call (WASM abort). This is
+     * exactly why Mudlet warns against calling it from a script-item — defer it
+     * (`tempTimer(0, resetProfile)` works) or run it from the command line. A
+     * concurrent reset is coalesced.
+     */
+    resetProfile(): void;
+    private performReset;
+    /**
+     * Resolves once the initial load pass has finished (scripts/aliases/timers/
+     * keys applied, sysLoadEvent fired, triggers compiled). The auto-connect
+     * path awaits this so the MUD socket isn't dialed until every handler and
+     * trigger is in place. Always resolves — never rejects — so a failed or
+     * torn-down load can't leave a profile waiting to connect forever.
+     */
+    whenScriptsLoaded(): Promise<void>;
+    /**
+     * Single entry point for dialing the MUD socket. Before the initial load
+     * finishes, the request is deferred (held in pendingConnectUrl) so the
+     * connection isn't made until every script handler and trigger is in place
+     * — this covers both the auto-connect on profile open and any script that
+     * calls connect()/connectToServer() from its body or a sysLoadEvent handler.
+     * Once loading is done, requests dial immediately (the normal reconnect
+     * path). The latest pending request wins, so exactly one socket opens.
+     */
+    /**
+     * Report a script-initiated call that teardown refused.
+     *
+     * Mudlet and mudix reach the same end state by opposite routes, and it is
+     * worth being precise about which:
+     *
+     *   Mudlet guards the ARRIVAL side. `TMainConsole::closeEvent` raises
+     *   sysExitEvent while `Host::mIsClosingDown` is still false, so a
+     *   handler's connectToServer/reconnect is accepted and may even open a
+     *   socket. `Host::closeChildren()` sets the flag afterwards, and every
+     *   inbound callback is gated on it — cTelnet::slot_socketConnected,
+     *   slot_socketDisconnected, slot_socketReadyToBeRead, postData,
+     *   postMessage all early-return. The connection is accepted, then
+     *   discarded.
+     *
+     *   mudix guards the INITIATION side, because its teardown is synchronous:
+     *   destroy() runs start to finish with no yield point, and MudSession
+     *   disposes the client immediately after, so a socket opened here would
+     *   be torn down microseconds later regardless. Refusing up front is the
+     *   same outcome without the pointless socket.
+     *
+     * The observable difference is only what the script is told, and there
+     * mudix is deliberately the more honest of the two: Mudlet returns success
+     * for a connection that will never deliver a byte. Hence this log line —
+     * the divergence is intentional, but it must not be silent.
+     *
+     * Routed to script.log rather than the output window: by this point the
+     * console may already be unmounting, and the log buffer lives on MudSession
+     * so the Errors tab can still show it.
+     */
+    private refuseDuringTeardown;
+    requestConnect(url: string): void;
+    /**
+     * Mark the initial load complete: unblock whenScriptsLoaded() and dial any
+     * connect request that arrived while loading. Idempotent. Called on every
+     * load outcome — success, load failure, and teardown — so a connect never
+     * waits forever.
+     */
+    private markScriptsLoaded;
+    destroy(): void;
+    private reportEntityError;
+    private wrapScript;
+    private executePermAlias;
+    private executePermTrigger;
+    private executePermKeybinding;
+    /**
+     * Run a button's command + code. The Lua `code` runs on every click.
+     * For two-state buttons, `nextState=true` (going DOWN) sends `commandDown`,
+     * otherwise (going UP, or single-state click) sends `command`.
+     */
+    executeButton(button: ButtonNode, nextState: boolean): void;
+    /**
+     * Run a flushLines batch end-to-end: triggers, rendering, then deferred-echo
+     * flush. Shared between the network-driven flushLines listener and the
+     * scripting `feedTriggers` API so both paths preserve identical semantics
+     * (line ordering, ANSI carry, trigger-echo placement).
+     */
+    /** Part of {@link EngineHost} — also reached directly from the flushLines
+     *  subscription, and by feedTriggers via the host so synthetic batches share
+     *  ordering semantics with network output. */
+    processFlushBatch(groups: {
+        text: string;
+        type: string;
+    }[]): void;
+    /**
+     * Attach clickable hyperlinks for the MXP `<SEND>`/`<A>` ranges the parser
+     * found. `setHyperlink` overlays each range while preserving the segments'
+     * existing colours/attributes (including the underline the parser applied as
+     * a link cue). Link behaviour — send a MUD command, open a URL in a new tab,
+     * or pop up a multi-command menu — is built by ScriptingAPI.
+     */
+    private wireMxpLinks;
+    /**
+     * Turn OSC 8 hyperlinks (recorded by the ANSI/MXP parser as a bare `url` on
+     * the segment) into clickable links. `createOsc8Hyperlink` maps the URI's
+     * scheme to the action — send a command, seed the command bar, or open a
+     * URL — and drops links whose scheme isn't allowed. Runs after
+     * `wireMxpLinks` so an MXP `<SEND>` overlaid on the same text wins.
+     */
+    private wireOsc8Links;
+    /**
+     * Run all triggers against `plain` (the original ANSI-stripped text).
+     * Trigger handlers that call selectString/fg/bg/deleteLine modify `buffer`
+     * in-place. The buffer is NOT rendered here — the caller renders it after
+     * this returns, so the final rendered line already has all colorization.
+     *
+     * echo/cecho output from trigger handlers is deferred (via ScriptingAPI)
+     * and flushed after all lines in the batch are rendered.
+     */
+    private processLineTriggers;
+    private emit;
+    private bridgeEvents;
+}