@mudlet/mudlet-web 0.4.5 → 1.0.0

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

@@ -3,13 +3,14 @@ import type { LogFormat } from '../logging/SessionLogger';
 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 { KeyEngine, KeyNode } from '../mud/keybindings/KeyEngine';
 import type { ButtonNode, ScriptNode } from '../storage/schema';
 import { type InstallOutcome } from './ScriptingAPI';
 import { type EngineHost, type TempComplexTriggerSpec } from './EngineHost';
 import { ItemIdSequence } from '../mud/ItemIdSequence';
-import type { LuaGlobalEntry } from './IScriptingRuntime';
+import type { LuaGlobalEntry, VariableEdit } from './IScriptingRuntime';
 import { ProfileVFS } from './vfs/ProfileVFS';
+import type { MudletImportResult } from '../import/mudletXmlImport';
 import type { PackageManifest } from '../storage/schema';
 export declare class ScriptingEngine implements EngineHost {
     private readonly session;
@@ -23,11 +24,7 @@ export declare class ScriptingEngine implements EngineHost {
     private readonly api;
     private promptPending;
     private mudCarryState;
-    private gmcpNegotiated;
-    private msdpNegotiated;
-    private msspNegotiated;
-    private mnesNegotiated;
-    private mxpNegotiated;
+    private readonly enabledProtocols;
     /** 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
@@ -38,22 +35,25 @@ export declare class ScriptingEngine implements EngineHost {
      *  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;
+    /** cTelnet's `enableMXP`: the game switched MXP on (WILL, DO or a bare
+     *  subnegotiation) or it was auto-enabled, and has not turned it off. */
+    private telnetMxpEnabled;
+    /** cTelnet's `mMxpAutoEnabled`: MXP is on because the auto-detect turned it
+     *  on, so the game switching it on properly starts it afresh in open mode. */
+    private mxpAutoEnabled;
+    /** Mudlet's TMxpClient::mMxpEvents — element uses the parser has read but
+     *  not yet published, drained at the end of processFlushBatch. */
+    private readonly mxpEventQueue;
     /** 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. */
+     *  input / prompt / output after they're clicked) within 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. */
+     *  `<SUPPORTS>`/`<VERSION>` answers; `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;
@@ -67,6 +67,13 @@ export declare class ScriptingEngine implements EngineHost {
     private triggersReady;
     private triggersDirty;
     private prevScripts;
+    private profileScriptsCompiled;
+    private readonly scriptHandlerState;
+    private readonly failedScripts;
+    private readonly scriptLoadErrors;
+    private scriptCompileSeq;
+    private readonly scriptCompiledAt;
+    private compiledThisLoad;
     private resetting;
     private disposed;
     private moduleSyncTimers;
@@ -78,13 +85,25 @@ export declare class ScriptingEngine implements EngineHost {
     private mudletSaveName;
     private mspBaseUrl?;
     private gmcpMediaDefaultUrl;
+    private readonly gmcpMediaDownloads;
     private exitFired;
-    private readonly beforeUnload;
+    private readonly onPageHide;
+    private readonly onPageShow;
     private uuidToNumericId;
     /** The profile's single item-id sequence, shared with every engine and with
      *  the Lua runtime's temporary items — see {@link ItemIdSequence}. */
     readonly itemIds: ItemIdSequence;
-    private numericIdFor;
+    /**
+     * The number Lua sees for a store node, allocating one on first sight.
+     *
+     * Public because the editor's "Show Items' ID number" shows the same number:
+     * the whole point of that option is to read off the id you would then pass to
+     * `enableTrigger` or `killTimer`, so it has to be *this* id and not the store's
+     * UUID. Allocating on first sight matches Mudlet, whose own tooltip warns that
+     * an item's id "is constant during a session of the profile [but] may be
+     * different the next time the profile is loaded".
+     */
+    numericIdFor(uuid: string): number;
     /** Hand out the next item id. Backs the Lua runtime's temporary items, so a
      *  temp and a permanent item can never collide on one number. */
     allocateItemId(): number;
@@ -130,6 +149,36 @@ export declare class ScriptingEngine implements EngineHost {
      * `_G`. Called once before the initial script load so handlers see their
      * persisted state, and again after a profile reset (fresh global table).
      */
+    /**
+     * Put a package's own `<VariablePackage>` globals into `_G` and onto the
+     * profile's save-list.
+     *
+     * A package may carry nothing else — a module of variables, fonts, images or
+     * a map loads completely and leaves every one of the six item units empty —
+     * so skipping these made such a package indistinguishable from one whose
+     * contents never loaded at all. They are not items: nothing tags them and an
+     * uninstall does not take them away, which is Mudlet's behaviour too.
+     */
+    private restorePackageVariables;
+    /**
+     * Load an installed package's `<VariablePackage>` globals: into `_G`, and
+     * onto the save-list. For the installs that commit in one step — the
+     * Package Manager, the repository and Client.GUI — which desktop reads the
+     * same way as a script's installPackage. Call before the package's items go
+     * into the store, so its scripts see the values as they load.
+     */
+    loadPackageVariables(data: MudletImportResult): void;
+    /**
+     * Put an installed package's `<VariablePackage>` globals on the profile's
+     * save-list.
+     *
+     * Desktop's `XMLimport::readVariable` reads a package's variables exactly as
+     * it reads the profile's own, so each one lands on `VarUnit`'s saved list
+     * and it — and any later change to it — survives a restart. Called once the
+     * install commits, so a refused one adds nothing; the store change schedules
+     * the profile-data save that captures their values.
+     */
+    private savePackageVariables;
     private restoreSavedVariables;
     /**
      * Snapshot the save-listed globals out of `_G` into the store, just before a
@@ -142,24 +191,100 @@ export declare class ScriptingEngine implements EngineHost {
      * 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/
+     * Mudlet Web'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;
+    /**
+     * Write this client's server encoding, TLS and character name back to a
+     * linked Mudlet folder's own files for them (`encoding`, `ssl_tsl`,
+     * `login`), in desktop's format, so desktop connects the same way. Only a
+     * linked folder — a Mudlet Web profile that called saveProfile() has a
+     * current/ too, but no desktop reading these (#259) — and only files whose
+     * value changed (desktopProfileFileUpdates). Never the password.
+     */
+    private writeBackDesktopProfileFiles;
+    /**
+     * The profile as a Mudlet-format `<MudletPackage>` save: `baseXml` with its
+     * automation and variable packages replaced by the live store state, and its
+     * `<Host>` settings updated in place.
+     *
+     * Basing on an existing save is what keeps the ~130 `<Host>` fields Mudlet Web
+     * doesn't model — and any element it doesn't understand — from being dropped
+     * on the way out. With no save to base on, a profile imported from Mudlet
+     * falls back to the `<Host>` retained at import; one born in Mudlet Web gets the
+     * empty skeleton, so its `<Host>` carries only the settings Mudlet Web does model.
+     */
+    private buildProfileXml;
+    /**
+     * The `<Host>` a save starts from when there's no `current/*.xml` to base
+     * on: the one retained when this profile was imported from Mudlet, else the
+     * empty skeleton — either way stamped with the connection's current identity
+     * and package set, which desktop's `Host::saveProfile` always writes (the
+     * retained copy still names them as they were at import).
+     *
+     * Only reached when there's no `current/*.xml` to base on, so it never
+     * displaces a linked folder's own save. Undefined without a VFS; the bare
+     * retained file (or nothing) when the connection record is gone.
+     */
+    private hostBaseXml;
+    /**
+     * The XML half of Mudlet `saveProfile([location [, saveName]])`: write this
+     * profile out as a Mudlet-format save and answer with the full path written.
+     *
+     * Mirrors `Host::saveProfile`'s naming — an empty location means the
+     * profile's own `current/`, an empty name means a `YYYY-MM-DD#HH-mm-ss`
+     * stamp, and a name without one gains `.xml`. A default-located save also
+     * takes over as this session's write-back target, so the automatic flushes
+     * keep updating the newest file rather than leaving a stale older one as the
+     * save Mudlet would load.
+     */
+    saveProfileXml(location?: string, saveName?: string): {
+        ok: true;
+        path: string;
+    } | {
+        ok: false;
+        err: string;
+        path?: string;
+    };
     /** `_G` entries for the Variables view (user globals nested, built-ins
      *  flagged). Empty until the runtime is up. */
     listGlobals(): LuaGlobalEntry[];
+    /** Apply one Variables-view edit to `_G`. Returns null on success, or the
+     *  reason it was refused — including there being no runtime to edit. */
+    editVariable(request: VariableEdit): string | null;
     /**
      * 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;
+     * Mudlet `reloadModule(name)` — Host::reloadModule, for a script and for
+     * the editor's "Reload from file" alike. Answers like an install does:
+     * `{ ok: true, error }` with whatever in the module does not work, or
+     * `{ ok: false, error }` with why it was not reloaded.
+     *
+     * Two things are checked before anything else, so the module's items are
+     * untouched by either: that it is installed at all, and that the file it
+     * was installed from can still be read — the reload takes the module
+     * apart before reading that file back in, and a file that has gone would
+     * leave it listed with nothing in it. Only then is a reload asked for
+     * during a profile save put off until the save is over; the true answered
+     * now is all the caller hears, so how the reload went afterwards is said on
+     * the console.
+     */
+    reloadModuleFromFile(moduleName: string): InstallOutcome;
+    /** Whether the file a module was installed from is a file that reads —
+     *  QFileInfo's isFile() && isReadable() — in the profile or under the
+     *  read-only /lua/ namespace. */
+    private moduleFileReadable;
+    /** Reloads put off by a profile save, carried out once it is over. */
+    private readonly postponedReloads;
+    /** The end of a profile save: the reloads it held up are carried out now,
+     *  and only the console is left to tell how they went. */
+    private runPostponedReloads;
+    private reloadModuleNow;
     /** 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. */
@@ -173,7 +298,9 @@ export declare class ScriptingEngine implements EngineHost {
     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. */
+    /** List installed module names, in byte order by name — desktop keeps
+     *  them in a QMap keyed by name (Host::mInstalledModules), so that is the
+     *  order getModules() reports, not the order they were installed in. */
     getModuleNames(): string[];
     /**
      * Write every module flagged to sync back out to its own file.
@@ -207,12 +334,21 @@ export declare class ScriptingEngine implements EngineHost {
      *  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 `setPackageInfo(name, key, value)`. Records a custom info field,
+     *  answering why it would not, or null once it has
+     *  (TLuaInterpreter::setPackageInfo). */
+    setPackageInfo(name: string, key: string, value: string): string | null;
     /** Mudlet `setModuleInfo(name, key, value)`. Records a custom info field
-     *  surfaced by getModuleInfo. Always succeeds. */
-    setModuleInfo(name: string, key: string, value: string): boolean;
+     *  surfaced by getModuleInfo; see {@link setPackageInfo}. */
+    setModuleInfo(name: string, key: string, value: string): string | null;
+    /**
+     * Only for something installed — one being read in counts, so its own
+     * scripts can still describe it. Filed for any other name, the details were
+     * there for whatever was installed under it later. And `mpackage` is the
+     * name it is installed under, so only that same name is accepted for it: a
+     * package without a config.lua has no details to start from.
+     */
+    private setInfoField;
     /**
      * Mudlet `getModulePath(name) → path`. Absolute VFS path of an installed
      * module's XML. Modules referencing a file outside the managed package dir
@@ -224,11 +360,10 @@ export declare class ScriptingEngine implements EngineHost {
     /**
      * 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.
+     * the standard pkgDir. This method is reached only via the Lua
+     * `installModule()` binding, so on success it raises what desktop's
+     * ModuleFromScript install does: sysInstall and sysLuaInstallModule
+     * (name, fileName) — not sysInstallPackage or sysInstallModule.
      */
     installModuleFromPath(path: string): InstallOutcome;
     /**
@@ -250,17 +385,83 @@ export declare class ScriptingEngine implements EngineHost {
     flushPendingApplies(): void;
     private applyTimersFromStore;
     private applyKeybindingsFromStore;
+    /** What this engine last told the button bar cannot be active, so that
+     *  destroy() takes back only its own answer. */
+    private publishedInactiveButtons;
+    /**
+     * Tell the button bar which buttons, toolbars and menus will not compile.
+     * Desktop's TAction::compileScript leaves such a one with `mOK_code` false
+     * and Tree::activate refuses it, so the toolbar builders leave it off —
+     * a toolbar or menu with its buttons — while its switch stays as it was.
+     */
+    private applyButtonsFromStore;
+    /**
+     * Run every active push-down button once, in its saved state, as desktop
+     * does while a profile loads: TToolBar/TEasyButtonBar::addActionButtons
+     * and fillMenu execute each push-down button (menus' too) when
+     * `mIsProfileLoadingSequence` is set, with the console's mButtonState set
+     * from the saved state first. That is how a state-restoring button script
+     * re-applies itself on start (mudlet-web#356). Plain buttons do not run.
+     */
+    private runPushDownButtonsAtLoad;
     /**
      * 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
+     * Mudlet Web — the warning explains why they "do nothing". Page-level shortcuts
+     * Mudlet Web 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;
+    /**
+     * Mudlet-style module load priority: scripts owned by modules with a
+     * negative priority load before profile scripts; non-negative priorities
+     * load after. Within a priority bucket, original array order is preserved
+     * so existing trees stay deterministic. Profile-owned scripts (no
+     * packageName) are treated as priority 0. Equal priorities: the profile
+     * before its modules (its XML is read before any module installs), and
+     * modules by name among themselves.
+     */
+    private scriptLoadOrder;
+    /**
+     * ScriptUnit::compileAll at profile load. Desktop walks its live tree and
+     * asks each root whether it is active only when it reaches it, so a body
+     * that runs earlier can switch a later script on or off, replace its code
+     * or remove it, and the walk honours that. Here every step re-reads the
+     * store, and first takes in whatever the last body changed (handler
+     * activity, a body setScript replaced) — the store subscription is not
+     * attached yet on a first load, and the walk has to see the change before
+     * it moves on either way.
+     */
+    private compileProfileScripts;
+    /**
+     * Host::reportScriptsThatFailedToLoad: once the profile's scripts have run
+     * — at open, and again after a reset — one warning names every switched-on
+     * script whose body failed, in script-list order, so a broken script is
+     * not lost among the errors that scrolled past. Module scripts are left
+     * out, as on desktop: a module of positive priority runs its scripts only
+     * after this, so reporting the others would make the warning depend on a
+     * module's priority.
+     */
+    private reportScriptsThatFailedToLoad;
+    /** Whether the root `s` sits under is switched on — what compileAll asks
+     *  of each root before compiling its subtree. */
+    private scriptRootActive;
+    /**
+     * Event-handler lists (Host::mEventHandlerMap). Every script that lists
+     * events is registered, enabled or not — desktop registers them as the XML
+     * is read and asks isActive() && ancestorsActive() only when an event comes
+     * (TScript::callEventHandler). isActive() wants the body to have compiled
+     * too, so a script that failed, or sits under one that did, is registered
+     * inactive. Registration order is load order: the profile's own tree
+     * first, then modules by priority, which install after it
+     * (mudlet::slot_connectionDialogueFinished). Only what changed since the
+     * last sync is sent.
+     */
+    private syncScriptHandlersFrom;
+    private syncScriptHandlers;
     /** Map of module name → priority. Profile (no packageName) is implicitly 0. */
     private modulePriorityMap;
     private initRuntime;
@@ -286,9 +487,6 @@ export declare class ScriptingEngine implements EngineHost {
      * `expandAlias(text, echo)` is exactly this function.
      */
     hostSend(text: string, echo?: boolean): void;
-    /** Nesting depth of {@link hostSend} — see the runaway-alias note there. */
-    private sendDepth;
-    private static readonly MAX_SEND_DEPTH;
     /** Mudlet `expandAlias(text, echo)` — `Host::send` with both defaults, i.e.
      *  "run this as though I had typed it". */
     expandAlias(text: string, echo: boolean): void;
@@ -296,11 +494,34 @@ export declare class ScriptingEngine implements EngineHost {
     requestReconnect(): boolean;
     /** Raise sysDataSendRequest; true means a handler called denyCurrentSend(). */
     dispatchSendRequest(text: string): boolean;
+    /**
+     * The refusal for installing something under a name the *other* kind is
+     * already using, or null when the name is free of it.
+     *
+     * A package and a module may not share one name. Uninstall removes items by
+     * name alone, so a name held both ways loses both halves' items whichever
+     * half is removed — the user uninstalls a package and a module's triggers
+     * and scripts go with it, unwarned. Each half also displaced the other from
+     * its own listing, so nothing in the UI revealed the collision first
+     * (issue #104).
+     *
+     * Desktop refuses both directions with these two sentences
+     * (`Host::installPackage`, Host.cpp:2567 and :2584) and deliberately lets a
+     * profile that already holds the combination go on loading — only a *fresh*
+     * install is turned away, or a profile saved before the check existed would
+     * become unopenable. Here that exemption needs no flag: reopening a profile
+     * replays its modules through `reloadModuleFromVfs`, which never reaches
+     * this, so only the install entry points below can be refused.
+     *
+     * Asked after the name is settled, never before: `config.lua` can rename an
+     * archive to anything at all, so the file's own name answers nothing.
+     */
+    crossKindInstallRefusal(name: string, installing: 'package' | 'module'): string | null;
     /** Names of every package installed in this profile. */
     getPackageNames(): string[];
     /** What the module's config.lua declared, with Lua-set overrides applied.
      *  The same contract as getPackageInfo — see manifestInfoBase. This used to
-     *  hand back the whole manifest, so callers saw mudix's own bookkeeping
+     *  hand back the whole manifest, so callers saw Mudlet Web's own bookkeeping
      *  (installedAt, sourceFile, and latterly declaredInfo itself) alongside the
      *  fields the module author actually wrote. */
     getModuleInfoRecord(name: string): Record<string, unknown> | null;
@@ -316,30 +537,87 @@ export declare class ScriptingEngine implements EngineHost {
     readFileBytes(path: string): Uint8Array | null;
     writeFileBytes(path: string, bytes: Uint8Array): boolean;
     configDirectory(): string | 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;
+     * The VFS paths a media name may refer to, most likely first. An absolute
+     * path is taken as it stands (getMudletHomeDir().."/media/x.wav" is the
+     * common package idiom), falling back to reading it as profile-relative
+     * for the older "/media/x.wav" spelling. A relative name is looked up in
+     * the profile's media/ directory first, where Mudlet resolves it, then
+     * against the profile root ("media/x.wav" as packages have long written it).
+     */
+    private mediaPathCandidates;
+    /**
+     * The file a media name plays: the first of its {@link mediaPathCandidates}
+     * that exists, as a full VFS path. A `*` or `?` in the file name is a
+     * wildcard, as in Mudlet's TMedia, and plays one of the files it matches,
+     * picked at random. A URL is returned as it is; a name that matches no
+     * file is null, which the SoundManager refuses without listing it.
+     */
+    private resolveMediaPath;
+    /** Sound/video loader: absolute URLs hit the network; everything else is
+     *  read from the mounted profile VFS (see {@link mediaPathCandidates}). */
+    private loadMediaBytes;
+    private createRuntime;
     /**
      * 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, fileName?: string): void;
+    notifyPackageInstalled(packageName: string, fileName?: string, problems?: string | null): void;
+    /** The half of an install every kind shares: apply the new items, register
+     *  their fonts and raise the generic sysInstall. The caller raises the one
+     *  detailed event that fits how the install was asked for. */
+    private notifyInstalled;
+    /** Everything an install does once its items are in, short of saying so:
+     *  apply them and register the package's fonts. */
+    private finishInstall;
+    /** How many times each package or module has been removed — Host's
+     *  mRemovalsOf. A reload's own removal is not counted: it puts the same
+     *  module straight back. */
+    private readonly removalsOf;
+    private countRemoval;
+    /** A module whose XML broke before anything was read in has nothing
+     *  running, so it is not announced (Host's moduleLoadedNothing). */
+    private moduleLoadedNothing;
+    /**
+     * Raise an install's sysInstall and then its detailed event on the next
+     * pass of the event loop, as Host::installPackage does (a zero-timer), so
+     * everything the install set up - its variables above all - is in place
+     * before a handler runs. An install undone before then is not announced,
+     * nor is the detailed event raised once a sysInstall handler has taken it
+     * away again: its errors would be stale by then.
+     */
+    private announceInstallLater;
+    /** Re-register every installed package's fonts on profile open. See the
+     *  call site in `start()` and {@link registerPackageFonts}. */
+    private refreshInstalledPackageFonts;
+    /**
+     * Register the fonts one just-installed package ships — desktop's
+     * `Host::installPackageFonts` (Host.cpp:3513), called from `installPackage`
+     * at :2802. Without it a package's font unpacked correctly and was then
+     * never handed to the browser, so nothing in the profile could use it and
+     * nothing said why (issue #103).
+     *
+     * The faces are in `document.fonts` — so `getAvailableFonts()` lists them
+     * and `setFont` takes them — before this returns, which is before the
+     * caller raises sysInstall/sysInstallPackage: a package that sets its own
+     * font in its install handler finds it there, as on desktop (#438). Only
+     * the parse finishes later (`FontFace.load()` is async), and a font is not
+     * a reason to hold up an install that has otherwise succeeded — desktop's
+     * `loadFont` reports and carries on too.
+     *
+     * Failures reach the error log rather than the console, because a font that
+     * will not load is a defect in the package, which is exactly what the
+     * Errors tab is for.
+     */
+    private registerPackageFonts;
     /**
      * 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;
+    notifyPackageUninstalled(packageName: string, kind?: 'package' | 'module'): 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
@@ -407,9 +685,10 @@ export declare class ScriptingEngine implements EngineHost {
      */
     private defaultMediaLocation;
     /**
-     * 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
+     * Resolve a media `file` (+ optional base `url` directory) to its absolute
+     * VFS path under the profile's `media/` the SoundManager loader can read,
+     * downloading and caching it on a miss (raising sysDownloadDone /
+     * sysDownloadError for the download, as TMedia does). 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
@@ -419,13 +698,32 @@ export declare class ScriptingEngine implements EngineHost {
      */
     private resolveMediaFile;
     /**
-     * Handle a GMCP media message (`Client.Media.Play/Load/Stop/Default`).
+     * Handle a GMCP media message (`Client.Media.Play/Load/Stop/Pause/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.
+     * (a bare `Client.Media` is Default, as in TMedia::parseGMCP). Server-
+     * driven, so playback rides the `game` mute gate like MSP, and a Stop or
+     * Pause reaches only server media — never what a script started.
      */
     private handleClientMedia;
+    /** Mudlet's `cTelnet::postMessage`: a client notice on the main console,
+     *  written to the buffer as well as the renderer so getLines() and the
+     *  cursor APIs see the line the player reads (see ScriptingAPI.postInfo). */
+    private postMainMessage;
+    /**
+     * A `Client.GUI` offer, after its gmcp table update. Mudlet
+     * (cTelnet::setGMCPVariables) ignores the whole message when the profile
+     * refuses server packages; otherwise it acts on the install, and then — if
+     * the game declined the built-in starter UI with `{"baseui": false}` —
+     * raises sysServerGuiInstalled with no package named, the same event an
+     * installed interface raises. The install's synchronous part (its
+     * "Downloading" notice) runs first, as it does on desktop; the download
+     * itself settles later.
+     */
+    private handleClientGui;
+    /** Mudlet's `mAcceptServerGUI` — the profile's `allowMudPackageInstall`,
+     *  where undefined means allowed. */
+    private serverGuiAccepted;
     private handleClientGuiInstall;
     /** Guards against overlapping downloads — Mudlet TMap::mImportRunning. */
     private mapDownloadRunning;
@@ -437,6 +735,43 @@ export declare class ScriptingEngine implements EngineHost {
      * importer and everything else through the binary `.dat` reader.
      */
     downloadMap(remoteUrl?: string): Promise<boolean>;
+    /** The script whose body is running right now (Host's mRunningScript): its
+     *  chunk name and the package or module it came with ('' for the profile). */
+    private runningScript;
+    /**
+     * Which package or module owns the code a Lua frame is running, '' for the
+     * profile's own — desktop's packageOfFrame, which addCommand asks so that a
+     * package's commands go with it.
+     *
+     * The running script's own body is its package's. Otherwise the chunk is
+     * whoever's items run under that chunk name, or whose folder the file lies
+     * in; when several do — a package script and a profile script may share a
+     * name — the running script's package still owns it if a main chunk of
+     * the same source calls this frame directly (a local function its body
+     * called), and anything else is the profile's: code a package merely runs
+     * for someone else is theirs.
+     */
+    packageOfCaller(source: string, isMain: boolean, calledFromMain: boolean): string;
+    /**
+     * The chunks of a package's items as they are removed, with the package
+     * that owned them, until the next pass of the event loop. Desktop takes a
+     * removed item out of the tree at once but frees it only once the pass
+     * that is running it is over, so code of the item that is still running -
+     * a trigger that uninstalled its own package, then placed a command - is
+     * still its package's.
+     */
+    private readonly removedChunkOwners;
+    private rememberOwnersOfRemovedItems;
+    private ownersOfChunk;
+    /**
+     * Lua `uninstallPackage(name)`: why it would not, or null once it has
+     * (TLuaInterpreter::uninstallPackage). Whether the package is installed is
+     * asked first — retrying one that is not never works, so a running save is
+     * not the reason to give for it — and an installed one is refused only
+     * while a profile save is running. A save a handler starts once the
+     * uninstall is under way is no reason to abandon it.
+     */
+    uninstallPackageFromScript(packageName: string): string | null;
     /**
      * Uninstall a previously installed package by name. Raises sysUninstallPackage
      * before the store removal so the package's own handlers can still run.
@@ -476,6 +811,63 @@ export declare class ScriptingEngine implements EngineHost {
      * Same batching as toggleTriggerByName: one set() collapses N matches into
      * a single subscription tick (and a single TimerEngine.loadPerm rebuild).
      */
+    /** Whether a profile save still counts as running: a second save is
+     *  refused, and so is an uninstall, as Host::currentlySavingProfile()
+     *  makes them. */
+    private profileSaveInFlight;
+    /** Which save the scheduled end below belongs to, so the end of one that
+     *  was waited out cannot cut a later save short. */
+    private profileSaveGeneration;
+    /**
+     * Mark a profile save as running until the next pass of the event loop.
+     */
+    markProfileSaveInFlight(): void;
+    /**
+     * Host::waitForProfileSave for a script's install: desktop runs the event
+     * loop until the save's writes are done, delivering nothing but the save's
+     * own completions. Mudlet Web's save has already written everything by the
+     * time it counts as running (the VFS flush that follows only makes it
+     * durable, and later writes join it), so what is left to wait for is the
+     * window itself - ended here and now, so nothing else gets to run in the
+     * middle of the waiting script either.
+     */
+    private waitOutProfileSave;
+    private saveAfterPackageChangePending;
+    /**
+     * The profile save a package install or uninstall is followed by, put off
+     * to the next pass of the event loop (Host's mDeferredSaveTimer) so a batch
+     * of installs is not queued behind one save each — and again until no save
+     * or install is running, as one started under an install would hold its
+     * scripts up. Asked for twice, it saves once.
+     *
+     * Nothing is waiting on an answer, so a save that cannot be written is said
+     * on the console (Host::saveProfileReportingFailure); one turned away
+     * because another is running names no file and is let be.
+     */
+    private saveAfterPackageChange;
+    /** Runs a package's config.lua the way Mudlet does — in an environment with
+     *  nothing in it — so a manifest that would raise is read as raising here
+     *  too. Bound rather than a method reference so the installer can hold it. */
+    private get readPackageConfig();
+    /**
+     * A crash part-way through an install leaves the folder it was unpacking
+     * into, a "mudlet-installing-" one marked ".mudlet-unpacking"; the next
+     * install of an archive clears it away (Host::installPackage). One
+     * holding files an install had moved out of the way (".mudlet-replaced")
+     * is all that is left of them, so it is kept and its place said instead.
+     * A package or module that is itself called that is left alone.
+     */
+    private clearAwayCrashedUnpacking;
+    /** Said when a package's XML would not read, once per file that broke,
+     *  with the reader's reason — Host::installPackage's "Failed to load
+     *  package/module" warning. Only modules were ever asked whether their
+     *  contents loaded, so a package installed to silence. */
+    private announceUnreadableContents;
+    /** What a lost manifest costs, said once, where the player will see it: the
+     *  package installed under the archive's own name and filed no details, so a
+     *  name-based uninstall, a repository update and anything depending on it
+     *  all stop matching with nothing to go on. */
+    private announceLostManifest;
     toggleTimerByName(name: string, enabled: boolean): boolean;
     /**
      * Toggle aliases' enabled flag by name (Mudlet enableAlias/disableAlias).
@@ -501,13 +893,12 @@ export declare class ScriptingEngine implements EngineHost {
     /** 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;
+    savedKeyNode(idOrName: number | string): KeyNode | null;
+    /** Host::setForceMXPProcessorOn and the slot its signal drives: forcing on a
+     *  processor that is off turns it on locked to secure mode (IRE-style games
+     *  use secure tags without sending mode switches), while one the game
+     *  already had on keeps its mode. Turning it off leaves the modes alone and
+     *  stops the processor unless the game has MXP on. */
     setForceMxpProcessorOn(on: boolean): void;
     /** Mudlet `cTelnet::autoEnableMXPProcessor`. Runs when MXP started from an
      *  in-band `ESC[<n>z` rather than a telnet option-91 handshake: such servers
@@ -522,6 +913,24 @@ export declare class ScriptingEngine implements EngineHost {
      *  server re-announcing MXP after e.g. `config mxp on`): re-apply the lock,
      *  but stay silent — Mudlet returns before its postMessage there. */
     private autoEnableMxpProcessor;
+    /**
+     * The temporary half of a kind's one tree, as the lookups below read it, or
+     * null for a kind whose temporaries are not yet held this way.
+     *
+     * Desktop keeps temporary and permanent items of a kind in one tree and
+     * one name table, so exists/isActive/findItems/ancestors see both; here
+     * the permanent half is the store and the temporary half is the engine.
+     */
+    private tempTree;
+    /**
+     * The temporary item a store node hangs off, when that item is killed or
+     * already freed — desktop's `*Unit::pendingDeletion`, which walks the item
+     * and every ancestor, so a killed parent takes its whole subtree out of
+     * exists/isActive/findItems until the cleanup frees it for good.
+     */
+    private isPendingDeletion;
+    /** `list` without the nodes {@link isPendingDeletion} rules out. */
+    private liveNodes;
     existsByName(nameOrId: string | number, type: string): number;
     /**
      * Mudlet `isActive(nameOrId, type [, checkAncestors])`. Returns the count of
@@ -538,6 +947,25 @@ export declare class ScriptingEngine implements EngineHost {
      */
     isKnownItemType(type: string): boolean;
     private nodeListForType;
+    /**
+     * Give every item saved with this profile its number, at load, before a
+     * script can run and claim one.
+     *
+     * {@link numericIdFor} allocates on first sight, which is enough for the Lua
+     * API on its own — but "first sight" then depends on what a script happened
+     * to touch, and (since the editor's "Show Items' ID number" reads the same
+     * ids) on whether the editor had been opened. Desktop has no such ambiguity:
+     * `TTrigger`, `TAlias` and the rest take their id as they are constructed
+     * from the profile XML, so the profile's own items always hold the first
+     * numbers and a temporary one created later carries on from there. Doing the
+     * same here costs one pass over the tree and makes the ids people read off
+     * the editor the ones they would have got anyway.
+     *
+     * Same order as the store, which is the order the profile was written in.
+     * Groups are numbered too: desktop gives a group an id like any other item,
+     * and `ancestors()` already reports them by number.
+     */
+    private assignSavedItemIds;
     private nodeTypeLabel;
     /**
      * Mudlet `ancestors(id, type)`. Walks from the item's immediate parent up to
@@ -570,18 +998,18 @@ export declare class ScriptingEngine implements EngineHost {
      * 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.
+     * their counts come from those engines: `temp` is the temp count and is
+     * folded into `total`/`active`, matching Mudlet's report. Desktop's
+     * assembleReport walks the live root lists unfiltered, so a killed item —
+     * and whatever hangs under it — still counts until the cleanup frees it.
+     * Scripts have no temp form.
      */
     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.
+     * with that name exists. The body runs once, before this returns.
      */
     createPermScript(name: string, parent: string, code: string): number;
     /**
@@ -618,6 +1046,15 @@ export declare class ScriptingEngine implements EngineHost {
      */
     createPermPromptTrigger(name: string, parent: string, code: string): number;
     private createPermTrigger;
+    /**
+     * The parent a `perm*(name, parent, …)` call names: the NEWEST item of the
+     * kind carrying that name, temporary or permanent — desktop's findTrigger /
+     * findFirstAlias / findFirstTimer / findFirstKey look both up in the one
+     * name table, newest first, with no folder and no pending-deletion check.
+     * A temporary parent is answered as its temp parent ref (see
+     * TEMP_PARENT_PREFIX in schema.ts); null when nothing carries the name.
+     */
+    private resolvePermParent;
     /**
      * Mudlet `tempComplexRegexTrigger(...)`. A session-scoped trigger with
      * everything a permanent one can have — an AND chain across lines, a filter
@@ -634,17 +1071,30 @@ export declare class ScriptingEngine implements EngineHost {
      */
     createTempComplexTrigger(spec: TempComplexTriggerSpec): number;
     /**
-     * Remove a temporary trigger by the numeric id `tempComplexRegexTrigger`
-     * handed the script. False when that id names no temporary trigger — a
-     * permanent one is refused, as Mudlet's killTrigger refuses it.
+     * Remove a temporary trigger node — an isTempTrigger="yes" item a package
+     * XML brought in — by its numeric id. False when that id names no such
+     * node — a permanent one is refused, as Mudlet's killTrigger refuses it.
      */
     removeTemporaryTriggerById(id: number): boolean;
     /** Remove a trigger and everything under it. A child outlives its parent
      *  nowhere in the tree, and a permanent trigger parented to a temporary one
      *  goes with it — which is the only way it could have been reached. */
     private removeTriggerSubtree;
-    /** The root ancestor of a trigger node — what a lineage is recorded against. */
-    private rootTriggerOf;
+    /**
+     * Remove from the store the permanent items whose temporary parent has been
+     * freed. Desktop deletes an item's children with it (~TTrigger →
+     * deleteChildren), temporary or not, so the cleanup that frees a killed
+     * temporary item frees the permanent subtree a script hung under it.
+     * The engines report which parents went (takeOrphanedParents); until this
+     * runs nothing reaches those nodes, and the lookups count them as gone.
+     */
+    private removeOrphanedTempChildren;
+    /** Remove every permanent item hanging off a temporary one, of every kind. */
+    private dropTempParentedNodes;
+    /** Remove every store node of `type` hanging (at any depth) off one of the
+     *  temp parent refs in `refs`, or off any temp parent at all when `refs`
+     *  is null. */
+    private removeSubtreesUnder;
     /**
      * Mudlet `permAlias(name, parent, regex, luaCode)`. Creates a saved alias
      * named `name` under the alias group `parent` (empty = root). The pattern
@@ -655,7 +1105,7 @@ export declare class ScriptingEngine implements EngineHost {
     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
+     * repeating 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.
      */
@@ -670,43 +1120,71 @@ export declare class ScriptingEngine implements EngineHost {
      */
     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
+     * Mudlet `tempButton(toolbar, name, orientation)`. Appends a transient
+     * button under an existing toolbar group, with no command and no script:
+     * TLuaInterpreter::tempButton gives it an empty one, and its third
+     * argument is the orientation. Returns the new id, or a refusal code:
+     * -1 when nothing has the toolbar's name, -2 when what has it is a plain
+     * button (desktop's findAction(toolbar) takes the first action of that
+     * name and refuses one that is not a folder, as a button under a button
+     * never reaches a toolbar), -3 when a button or toolbar already has the
+     * name — desktop refuses a duplicate rather than adding a second button,
+     * so a script that makes its buttons on every load does not pile them up
+     * (mudlet-web#238). The Lua wrapper turns each into nil and desktop's
+     * message. `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;
+    createTempButton(toolbar: string, name: 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.
+     * Returns -1 when a toolbar or button of that name already exists —
+     * desktop's findAction(name) is not limited to toolbars.
      */
     createTempButtonToolbar(name: string, orientation: number, location: number): number;
     /** Mudlet `setButtonState(name, state)`. Flips the buttonState on the named
      *  two-state button. */
+    /**
+     * The button the button-state functions mean: a name finds the first
+     * button (not toolbar) called that, a number is an item ID — the one
+     * findItems() handed out, which Mudlet's getAction(id) resolves whatever
+     * the item is, so a toolbar found by ID is simply not a push-down button.
+     */
+    private findButton;
     /**
      * What `name` refers to, so the Lua side can say which of Mudlet's several
      * refusals applies: no such button, or a button that has no state to set
      * because it is not a two-state one.
      */
-    buttonKindByName(name: string): 'missing' | 'plain' | 'pushdown';
+    buttonKindByName(name: string | number): 'missing' | 'plain' | 'pushdown';
     /** True when the state actually changed. Mudlet answers false for a button
      *  that was already in the state asked for — "nothing to do" rather than
      *  "could not do it", which is why the caller can tell them apart only by
      *  having checked the name first. */
-    setButtonStateByName(name: string, state: boolean): boolean;
+    setButtonStateByName(name: string | number, 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. */
+     *  that to nil — Mudlet returns false/error). A button whose code will not
+     *  compile still answers its state: TLuaInterpreter::getButtonState reads
+     *  mButtonState without asking whether the button is active. */
+    getButtonStateByName(name: string | number): boolean | null;
+    /** Mudlet `setButtonStyleSheet(name, css)`. Stores raw CSS on every
+     *  button, toolbar and menu with that name — desktop's
+     *  `getActionUnit()->findItems(name)` styles each match, and a toolbar's
+     *  sheet restyles the whole bar (mudlet-web#356). ButtonsBar applies it. */
     setButtonStyleSheetByName(name: string, css: string): boolean;
+    /**
+     * Apply a change to the button bars and lay it out before the script goes
+     * on. A bar along the top or bottom takes its room from the main console,
+     * which getMainWindowSize() and sysWindowResizeEvent report at once on
+     * desktop — and a script holds the event loop a deferred render waits for.
+     */
+    private layOutButtonBarsNow;
     /**
      * Mudlet `showToolBar(name)` / `hideToolBar(name)`. Toggles the toolbar's
-     * own enabled flag — the ButtonsBar filters by isEffectivelyEnabled, so that
+     * own enabled flag — the ButtonsBar shows only buttons whose toolbar is on, so that
      * is the show/hide hook. Returns null on success, or the reason it moved
      * nothing (which the Bridge shapes into Mudlet's `(nil, errMsg)`).
      *
@@ -724,9 +1202,8 @@ export declare class ScriptingEngine implements EngineHost {
     toggleToolBarByName(name: string, show: boolean): string | null;
     /**
      * 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
+     * `pos`-th script (1-indexed; default 1) named `name` and runs the new
+     * body once, before this returns. Returns the script's id, -1 if no such
      * script exists.
      */
     setScriptByName(name: string, code: string, pos: number): number;
@@ -765,14 +1242,42 @@ export declare class ScriptingEngine implements EngineHost {
     /**
      * 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
+     * re-runs a script when its code actually changes (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.
+     * nothing. Event-handler registrations live apart from the body (see
+     * applyScriptsFromStore), so repeated runs stay idempotent.
      */
     runScript(scriptId: string): void;
     private runScriptLoad;
+    /**
+     * Bring the runtime up to date with the scripts in the store right now,
+     * and make sure the script `id` has been compiled since `before` (a
+     * {@link scriptCompileSeq} read ahead of the store write): a body runs as
+     * its code is set, whether or not the code changed (TScript::setScript).
+     * The store subscription will usually have run it already. Returns why
+     * that compile failed, or null when it ran. Backs permScript, setScript
+     * and appendScript, which run the body exactly once — through here — and
+     * report its error themselves.
+     */
+    private compileScriptNow;
+    /**
+     * Take in a script-tree change a Lua call just made, now rather than when
+     * the store subscription next runs: it is not attached while a first
+     * profile load compiles the scripts, and a script that a body switches off
+     * then must stop receiving events at once, as one it replaces must not be
+     * compiled again by the walk. A no-op once the subscription has seen it,
+     * and before the profile's scripts were first loaded, which takes in
+     * everything anyway.
+     */
+    private takeInScriptChanges;
+    /** What a script's last compile raised, for permScript/setScript's own
+     *  error: the message, or for an error object that is not one, its type
+     *  (TLuaInterpreter treats a number as a message, as lua_isstring does). */
+    private describeScriptLoadError;
+    /** Why the script with this numeric id failed the last time its body ran,
+     *  or null if it ran cleanly. */
+    scriptLoadErrorById(id: number): string | null;
     get currentVFS(): ProfileVFS | null;
     /**
      * Submit one line from the command bar — Mudlet's `TCommandLine` calling
@@ -786,10 +1291,17 @@ export declare class ScriptingEngine implements EngineHost {
     processInput(text: string): boolean;
     /** Nesting depth of {@link processInput} — see the note there. */
     private aliasDepth;
+    /** Set when a chain hits {@link MAX_ALIAS_DEPTH}, until it unwinds to the outermost pass. */
+    private aliasRunawayStopped;
+    /** AliasUnit::scmMaxProcessingDepth. */
+    private static readonly MAX_ALIAS_DEPTH;
     private processInputPass;
     /** Process a keyboard event. Returns true if a keybinding consumed it. */
     processKey(event: KeyboardEvent): boolean;
     raiseEvent(event: string, args?: unknown[]): void;
+    /** Part of {@link EngineHost}: closeMudlet raises the exit event before it
+     *  disconnects. */
+    raiseExitEvent(): void;
     /** Raise sysExitEvent at most once, while the Lua runtime is still alive. */
     private fireExit;
     notifyMapOpen(): void;
@@ -799,9 +1311,31 @@ export declare class ScriptingEngine implements EngineHost {
     /** 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;
+    /** What getCmdLine() answers with — the mirror, which is current the moment
+     *  a script writes it, unlike the React state behind it. */
+    getCmdLineValue(): string;
+    /** The game took hidden input (ECHO): what the command bar holds is put
+     *  aside as the command line, and the bar becomes the hidden-input box
+     *  (see ScriptingAPI.beginHiddenInput). */
+    beginHiddenInput(command: string): void;
+    /** The prompt for hidden input ended. */
+    endHiddenInput(): void;
+    /** The commands packages placed with addCommand, for the bar that draws
+     *  them. Narrower than handing out the whole API: the toolbar needs to read
+     *  the list, hear when it changes, and report a click. */
+    get addonCommands(): import("../ui/commands/addonCommands").AddonCommandRegistry;
+    addonCommandClicked(id: number): void;
+    /** See ScriptingAPI.interceptMapperButton — the map button, menu entry and
+     *  shortcut ask this before toggling the map. */
+    interceptMapperButton(): boolean;
+    mapperButtonMode(): 'default' | 'scripted' | 'disabled';
+    onMapperButtonModeChange(fn: () => void): () => void;
     /** Hand the API a startLogging hook. Wired by ProfileSession, which owns
      *  the actual SessionLogger lifecycle. */
     setLoggingToggler(fn: ((enabled: boolean, format: LogFormat) => boolean) | null): void;
+    /** Mudlet `startLogging(state)` from outside a script — the autolog resume
+     *  on profile load (Host::startSavedLogging). */
+    startLogging(enabled: boolean): void;
     /** Where the live logger is writing, so startLogging can report the file. */
     setLoggingPathProvider(fn: (() => string | null) | null): void;
     /** Mudlet's "Show errors in main console" — when on, script errors are also
@@ -818,14 +1352,20 @@ export declare class ScriptingEngine implements EngineHost {
      * 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
+     * failure). Mudlet requires the mapper open; Mudlet Web's renderer lives in the
      * map widget, so the same precondition applies.
      */
-    exportAreaImageToVfs(areaId: number, filePath: string, zLevel?: number): {
+    exportAreaImageToVfs(areaId: number, filePath: string, zLevel?: number | true): {
         path: string;
     } | {
         error: string;
+        target?: boolean;
     };
+    /** exportAreaImage(areaID, filePath, true) — T2DMap::exportAreaToImage's
+     *  every-z-level branch: one image per level of the area, each named
+     *  `<base>_level_<z>.<suffix>` beside `filePath` (QFileInfo's
+     *  completeBaseName and suffix, `png` when there is none). */
+    private exportEveryAreaLevelToVfs;
     /**
      * Mudlet `resetProfile()` — reload the entire profile as if just reopened:
      * clear every UI surface, tear down and recreate the Lua runtime (fresh
@@ -836,8 +1376,12 @@ export declare class ScriptingEngine implements EngineHost {
      * 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.
+     *
+     * Answers what Host::resetProfile_phase1 does: true once the reset is
+     * armed, false for one already in progress (which it folds into) or one
+     * refused because the profile is closing.
      */
-    resetProfile(): void;
+    resetProfile(): boolean;
     private performReset;
     /**
      * Resolves once the initial load pass has finished (scripts/aliases/timers/
@@ -859,7 +1403,7 @@ export declare class ScriptingEngine implements EngineHost {
     /**
      * Report a script-initiated call that teardown refused.
      *
-     * Mudlet and mudix reach the same end state by opposite routes, and it is
+     * Mudlet and Mudlet Web reach the same end state by opposite routes, and it is
      * worth being precise about which:
      *
      *   Mudlet guards the ARRIVAL side. `TMainConsole::closeEvent` raises
@@ -871,14 +1415,14 @@ export declare class ScriptingEngine implements EngineHost {
      *   postMessage all early-return. The connection is accepted, then
      *   discarded.
      *
-     *   mudix guards the INITIATION side, because its teardown is synchronous:
+     *   Mudlet Web 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
+     * Mudlet Web 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.
      *
@@ -896,15 +1440,111 @@ export declare class ScriptingEngine implements EngineHost {
      */
     private markScriptsLoaded;
     destroy(): void;
+    /** Packages and modules whose items are being read in right now — their
+     *  scripts are running as part of the install. */
+    private readonly installing;
+    /**
+     * Modules whose XML stopped part-way through (#8696). The items read in
+     * before the break are in the profile and running, but they are only part
+     * of the module, so writing them back out over its file — which is what a
+     * sync does — would destroy the rest. Kept until a read gets all the way
+     * through.
+     */
+    private readonly unloadedModules;
+    private noteModuleLoaded;
+    /** Removals asked of a package or module by its own install-time scripts,
+     *  waiting for that install to finish. */
+    private readonly heldRemovals;
+    /**
+     * A package's scripts run while its install is still reading it in, and a
+     * one-shot installer package asks for its own removal from one of them.
+     * Carried out there and then, that took the items out from under the
+     * install (Mudlet #10867 — a crash there, a half-installed package here),
+     * so a removal of the package being installed is held over and carried
+     * out once the install is done: the install is announced, and then the
+     * removal. Removing any OTHER package still happens at once. Answers
+     * whether it was held; asking twice holds it once.
+     */
+    private holdRemovalIfInstalling;
+    /** Carry out the held removals once nothing they name is installing, on the
+     *  next pass of the event loop — after the install that held them has
+     *  answered and raised its events. On the timer engine, as the postponed
+     *  installs are, so a spec's pumpEvents() reaches it. */
+    private carryOutHeldRemovals;
+    /**
+     * Each item's last compile check, per kind: what it was run on (chunk name
+     * and code) and the error, or null. Kept so an item is compiled again only
+     * when its code or name changes, not on every reload of its unit.
+     */
+    private readonly compileChecks;
+    /** Compile errors already put in the error log, by kind, chunk and code —
+     *  not by id, so a module re-read under new ids does not report again. */
+    private readonly reportedCompileErrors;
+    /**
+     * The error compiling a piece of an item's code gives (see itemSyntaxError),
+     * or null when it compiles — or when there is no runtime to ask yet, which
+     * lets the item be. A new error is handed to `report`, once.
+     */
+    private compileError;
+    /**
+     * Whether an item's code will not compile — Mudlet's `mOK_code = false`,
+     * or for a trigger's Lua-function pattern `mOK_init = false`. Either way
+     * `Tree::canBeActivated` refuses it: the item never matches or fires, its
+     * command is not sent, and `isActive` reports it off, whatever its switch
+     * says. Fixing the code brings it back as its switch has it.
+     *
+     * The error goes in the error log once: desktop shows it on the item in
+     * the editor, where it is found when the item "does nothing".
+     */
+    private cannotCompile;
+    /** The ids of `items` whose code will not compile (see cannotCompile), for
+     *  their engine to leave inactive. Checks for items no longer in the list
+     *  are forgotten. */
+    private uncompilableIds;
+    /**
+     * Whether a permanent item of `kind` cannot be active because something in
+     * it failed to compile: its code, or (triggers and aliases) a pattern.
+     */
+    private itemCannotBeActive;
+    /** Scripts and triggers of the package being installed that do not work,
+     *  gathered while it installs; null when no install is under way. */
+    private installProblems;
+    /**
+     * Commit a package's (or module's) items with `commit` and answer what in
+     * them does not work, as Host::installPackage does: every script whose body
+     * stopped with an error as it ran, in the order the package lists them,
+     * then every trigger whose body will not even compile — a trigger's body
+     * does not run until its pattern matches, so compiling it is the only way
+     * to find out now. Plain text, joined with "; ", or null when all is well.
+     *
+     * The console is left alone: a script asked for this install and has the
+     * answer to report however it likes, and a module sync would otherwise
+     * repeat it on every save for as long as the module stays broken.
+     */
+    private collectInstallProblems;
+    /**
+     * Why a trigger's patterns do not all compile, in the plain text
+     * XMLimport hands back for TTrigger::setRegexCodeList's error: one
+     * sentence per pattern that failed, numbered by its place in the list, or
+     * null when they all compile (a trigger with no patterns is kept for its
+     * script and is not broken).
+     */
+    private triggerPatternErrors;
     private reportEntityError;
-    private wrapScript;
     private executePermAlias;
     private executePermTrigger;
+    /** Paint a trigger's built-in highlight over what one match captured, on
+     *  the line being processed. Shared by the single-line fire and by each
+     *  condition of a multiline trigger as it matches. */
+    private paintHighlight;
     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`.
+     * otherwise (going UP) sends `command`. A single-state button sends
+     * `command` — its desktop commandButtonDown, which the importer moves
+     * there. A plain button imported before that still carries the desktop
+     * down command in `commandDown`, and that is the one desktop sends.
      */
     executeButton(button: ButtonNode, nextState: boolean): void;
     /**
@@ -921,6 +1561,13 @@ export declare class ScriptingEngine implements EngineHost {
         type: string;
         fromServer?: boolean;
     }[]): void;
+    /**
+     * Lead the first server group with whatever an unterminated feedTriggers
+     * left held. Mudlet feeds both into the one TBuffer, whose mMudLine the
+     * fed text is still sitting in, so the server's next line completes it
+     * rather than arriving above it.
+     */
+    private withHeldFeedText;
     /**
      * Free everything killed while this batch was processed.
      *
@@ -958,6 +1605,9 @@ export declare class ScriptingEngine implements EngineHost {
      * and flushed after all lines in the batch are rendered.
      */
     private processLineTriggers;
+    /** How many {@link processLineTriggers} passes are running, one inside the
+     *  other when a trigger calls feedTriggers. */
+    private lineTriggerDepth;
     private emit;
     private bridgeEvents;
 }