@mudlet/mudlet-web 0.3.1 → 0.4.0

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

@@ -1,11 +1,13 @@
 import type { MudSession } from '../mud/MudSession';
+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 { ButtonNode, ScriptNode } from '../storage/schema';
 import { type InstallOutcome } from './ScriptingAPI';
-import type { EngineHost } from './EngineHost';
+import { type EngineHost, type TempComplexTriggerSpec } from './EngineHost';
+import { ItemIdSequence } from '../mud/ItemIdSequence';
 import type { LuaGlobalEntry } from './IScriptingRuntime';
 import { ProfileVFS } from './vfs/ProfileVFS';
 import type { PackageManifest } from '../storage/schema';
@@ -74,13 +76,18 @@ export declare class ScriptingEngine implements EngineHost {
     /** 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 mspBaseUrl?;
     private gmcpMediaDefaultUrl;
     private exitFired;
     private readonly beforeUnload;
     private uuidToNumericId;
-    private nextNumericId;
+    /** 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;
+    /** 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;
     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
@@ -168,6 +175,19 @@ export declare class ScriptingEngine implements EngineHost {
     getModulePriority(moduleName: string): number;
     /** List installed module names. Order matches install order. */
     getModuleNames(): string[];
+    /**
+     * Write every module flagged to sync back out to its own file.
+     *
+     * Called by saveProfile, which is the only moment it happens — and the
+     * moment it has to: a module shared between profiles carries this one's
+     * edits to the others through its file, so a save that skipped this left
+     * them in our store alone, to be lost the next time another profile read
+     * the module back.
+     *
+     * Fire-and-forget per module, like syncModule itself: the write is async,
+     * and a save reports on what it started rather than waiting.
+     */
+    saveSyncedModules(): void;
     /** Snapshot of a module's manifest, or null if not installed / not a module. */
     getModuleInfo(moduleName: string): PackageManifest | null;
     /**
@@ -246,8 +266,31 @@ export declare class ScriptingEngine implements EngineHost {
     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. */
+    /**
+     * Mudlet `Host::send(cmd, wantPrint, dontExpandAliases = false)` — the one
+     * path every command the player types, and every item's built-in `command`
+     * field, travels down. Three stages, in this order:
+     *
+     *   1. echo the **whole, unsplit** text under the showSentText mode;
+     *   2. split it on the profile's command separator;
+     *   3. run each part through the aliases, and put on the wire whatever no
+     *      alias consumed.
+     *
+     * The order is the point. Echoing before the alias pass is why typing an
+     * alias shows the text you typed even though the alias swallows it — and
+     * why the alias's own command field, arriving back here in turn, is echoed
+     * again as a second line. Splitting after the echo is why `n;;s` echoes as
+     * one line but sends two commands.
+     *
+     * Lua `send()` skips only stage 3 ({@link ScriptingAPI.send}); Mudlet's
+     * `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;
     /** Mudlet `reconnect()` — redial the last URL, refused during teardown. */
     requestReconnect(): boolean;
@@ -255,7 +298,11 @@ export declare class ScriptingEngine implements EngineHost {
     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. */
+    /** 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
+     *  (installedAt, sourceFile, and latterly declaredInfo itself) alongside the
+     *  fields the module author actually wrote. */
     getModuleInfoRecord(name: string): Record<string, unknown> | null;
     /** Rewrite VFS-relative url(...) references to service-worker paths. */
     rewriteCss(css: string): string;
@@ -267,6 +314,8 @@ export declare class ScriptingEngine implements EngineHost {
      *  getMudletHomeDir()-prefixed paths work) and relative ones against the
      *  profile root. */
     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
@@ -284,7 +333,7 @@ export declare class ScriptingEngine implements EngineHost {
      * 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;
+    notifyPackageInstalled(packageName: string, fileName?: string): void;
     /**
      * Raise sysUninstall / sysUninstallPackage. Call this BEFORE removing the
      * package's items from the store so the package's own handlers (and the
@@ -342,6 +391,21 @@ export declare class ScriptingEngine implements EngineHost {
      * reloads. Returns null when the file can't be located or fetched.
      */
     private resolveMspMedia;
+    /**
+     * Last-resort media location when a server plays a file without ever
+     * announcing where it lives — neither an MSP `U=` nor a GMCP
+     * `Client.Media.Default { url }`. Mudlet guesses the MUD's own website:
+     * `https://www.<host>/media/` (TMedia::parseUrl). The host is the telnet
+     * host — for a `websocket`-mode profile, the endpoint's hostname — the same
+     * value getConnectionInfo() reports, standing in for Mudlet's `Host::mUrl`.
+     *
+     * The one deviation from Mudlet: it prepends `www.` unconditionally, which
+     * turns an already-qualified `www.example.com` into `www.www.example.com`.
+     * We skip the prefix when the host already carries it. Returns undefined
+     * when there's no host to guess from, so the caller reports "no base URL"
+     * rather than fetching a nonsense URL.
+     */
+    private defaultMediaLocation;
     /**
      * Resolve a media `file` (+ optional base `url` directory) to a VFS-relative
      * path under `media/` the SoundManager loader can read, downloading and
@@ -349,8 +413,9 @@ export declare class ScriptingEngine implements EngineHost {
      * 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.
+     * so a hostile server can't escape the cache root. With no base URL at all,
+     * {@link defaultMediaLocation} guesses one from the MUD's host. Returns null
+     * when the file can't be located or fetched.
      */
     private resolveMediaFile;
     /**
@@ -379,9 +444,15 @@ export declare class ScriptingEngine implements EngineHost {
      */
     uninstallPackageByName(packageName: string): boolean;
     /**
-     * Toggle a script's enabled flag by name (Mudlet enableScript/disableScript).
+     * Toggle scripts' enabled flag by name (Mudlet enableScript/disableScript).
      * The store subscription picks up the change synchronously and either loads
      * or unloads handlers in the runtime.
+     *
+     * Every script sharing the name flips, not just the first — same rule as
+     * {@link toggleTriggerByName}, and Other_spec pins it. Names are not unique
+     * in the tree, so stopping at the first match would leave duplicates in a
+     * state the caller never asked for and `isActive(name)` would disagree with
+     * `exists(name)`.
      */
     toggleScriptByName(name: string, enabled: boolean): boolean;
     /**
@@ -438,6 +509,19 @@ export declare class ScriptingEngine implements EngineHost {
      *  Those live in the Lua runtime, not the saved tree. */
     setTempItemEnabled(id: number, enabled: boolean): boolean;
     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
+     *  are IRE-style and never send mode switches, they just emit secure tags —
+     *  so without the secure-mode lock every `<SEND>`/`<A>`/definition tag would
+     *  be discarded as unsafe. The `promptForMXPProcessorOn` latch records that
+     *  this profile has been auto-enabled once, which is what lets a user turn
+     *  `specialForceMXPProcessorOn` back off without being overridden on the
+     *  next connect (the gate lives in MudClient → TelnetNegotiator).
+     *
+     *  A second detection while already forced on is a *re-initialisation* (a
+     *  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;
     existsByName(nameOrId: string | number, type: string): number;
     /**
      * Mudlet `isActive(nameOrId, type [, checkAncestors])`. Returns the count of
@@ -452,6 +536,7 @@ export declare class ScriptingEngine implements EngineHost {
      * findItems, isAncestorsActive). Type aliases mirror Mudlet: "key" and
      * "keybind" both target keybindings. Unknown types return an empty list.
      */
+    isKnownItemType(type: string): boolean;
     private nodeListForType;
     private nodeTypeLabel;
     /**
@@ -473,7 +558,7 @@ export declare class ScriptingEngine implements EngineHost {
      * 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[];
+    findItemsByName(name: string, type: string, exact: boolean, caseSensitive: boolean): number[] | null;
     /**
      * 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
@@ -533,6 +618,33 @@ export declare class ScriptingEngine implements EngineHost {
      */
     createPermPromptTrigger(name: string, parent: string, code: string): number;
     private createPermTrigger;
+    /**
+     * Mudlet `tempComplexRegexTrigger(...)`. A session-scoped trigger with
+     * everything a permanent one can have — an AND chain across lines, a filter
+     * that hands its captures to children, a fire length, a line delta, colour
+     * patterns — because that is what the call offers and none of it fits the
+     * flat temp-trigger primitive. So it makes a real node, marked temporary so
+     * it is not saved with the profile.
+     *
+     * Calling it again with a name that is already taken does not replace that
+     * trigger — it ADDS to it. Mudlet names the argument "trigger name create
+     * or add to": the new pattern is appended to the ones already there and the
+     * trigger is rebuilt around the longer list, which is how a multiline AND
+     * chain is assembled one condition per call.
+     */
+    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.
+     */
+    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;
     /**
      * Mudlet `permAlias(name, parent, regex, luaCode)`. Creates a saved alias
      * named `name` under the alias group `parent` (empty = root). The pattern
@@ -574,6 +686,16 @@ export declare class ScriptingEngine implements EngineHost {
     createTempButtonToolbar(name: string, orientation: number, location: number): number;
     /** Mudlet `setButtonState(name, state)`. Flips the buttonState on the named
      *  two-state button. */
+    /**
+     * 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';
+    /** 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;
     /** Mudlet `getButtonState(name)`. Reads the pressed state on a two-state
      *  button by name. Returns null when no such button (the Lua binding maps
@@ -582,10 +704,24 @@ export declare class ScriptingEngine implements EngineHost {
     /** 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 `showToolBar(name)` / `hideToolBar(name)`. Toggles the toolbar's
+     * own enabled flag — the ButtonsBar filters by isEffectivelyEnabled, 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)`).
+     *
+     * Three rules from `ActionUnit::setToolBarActive`, none of them obvious:
+     *
+     * - A toolbar that came in a package answers to its OWN name, and the
+     *   package's root node is left alone. Reaching a toolbar through its
+     *   package used to be the only way, which meant hiding one hid every bar
+     *   that package installed.
+     * - The package's name still works, and then it moves every toolbar in it.
+     * - A floating toolbar is refused, and says so: these functions dock and
+     *   undock, and a floating bar is not in the docking arrangement at all.
+     *   Reporting it as missing sent scripts looking for a name they had right.
+     */
+    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
@@ -595,14 +731,15 @@ export declare class ScriptingEngine implements EngineHost {
      */
     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).
+     * Mudlet `getScript(name [, pos]) → code, id`. Returns the source of the
+     * pos-th (1-indexed; default 1) script named `name` and that script's own
+     * numeric id. Null when nothing sits at that position — the Bridge.lua
+     * wrapper turns that into Mudlet's (-1, message).
      */
+    removeScriptById(id: number): boolean;
     getScriptByName(name: string, pos: number): {
         code: string;
-        count: number;
+        id: number;
     } | null;
     /**
      * Mudlet `killTimer/killAlias/killTrigger/killKey(name)` deletes every
@@ -638,12 +775,18 @@ export declare class ScriptingEngine implements EngineHost {
     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().
+     * Submit one line from the command bar — Mudlet's `TCommandLine` calling
+     * `Host::send` per newline-separated line. Echoes it, splits it on the
+     * command separator, runs the parts through the aliases, and sends what
+     * survives (raising sysDataSendRequest per part, so a handler calling
+     * denyCurrentSend() can still abort an individual command).
      */
     sendCommand(text: string): void;
     /** Run input through aliases. Returns true if an alias matched (caller should not send). */
     processInput(text: string): boolean;
+    /** Nesting depth of {@link processInput} — see the note there. */
+    private aliasDepth;
+    private processInputPass;
     /** Process a keyboard event. Returns true if a keybinding consumed it. */
     processKey(event: KeyboardEvent): boolean;
     raiseEvent(event: string, args?: unknown[]): void;
@@ -658,7 +801,9 @@ export declare class ScriptingEngine implements EngineHost {
     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;
+    setLoggingToggler(fn: ((enabled: boolean, format: LogFormat) => boolean) | null): 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
      *  echoed (in red) into the main output window, not just the Errors tab. */
     setShowErrorsInMainWindow(enabled: boolean): void;
@@ -774,7 +919,19 @@ export declare class ScriptingEngine implements EngineHost {
     processFlushBatch(groups: {
         text: string;
         type: string;
+        fromServer?: boolean;
     }[]): void;
+    /**
+     * Free everything killed while this batch was processed.
+     *
+     * Mudlet's alias/trigger/timer/key units each defer freeing a killed item to
+     * the end of the line that killed it, rather than dropping it at the kill.
+     * That is what makes a killed item still findable for the rest of the pass —
+     * `exists` finds it, `isActive` says 0, and a second kill can tell "already
+     * dead" (false) from "never existed" (also false, but for the other reason).
+     * Nothing can fire in the meantime: killing unsubscribes immediately.
+     */
+    private reapKilledTempItems;
     /**
      * Attach clickable hyperlinks for the MXP `<SEND>`/`<A>` ranges the parser
      * found. `setHyperlink` overlays each range while preserving the segments'

package/dist-lib/scripting/http/HttpService.d.ts

@@ -2,20 +2,70 @@ import type { ProfileVFS } from '../vfs/ProfileVFS';
 type EmitFn = (event: string, args: unknown[]) => void;
 type VFSGetter = () => ProfileVFS | null;
 type ProxyUrlGetter = () => string | undefined;
+/** Runs `fn` off the current call stack. See {@link HttpService.emitLater}. */
+type DeferFn = (fn: () => void) => void;
+/** Bytes behind a path in a read-only bundled namespace, or null. */
+type LocalReader = (path: string) => Uint8Array | null;
 export declare class HttpService {
     private readonly emit;
     private readonly vfsGetter;
     private readonly proxyUrlGetter;
+    private readonly defer;
+    /** Consulted before the profile VFS when serving a `file:` URL, so a
+     *  bundled path resolves the same way Lua's io.open resolves it. */
+    private readonly localReader;
     private readonly proxiedOrigins;
-    constructor(emit: EmitFn, vfsGetter: VFSGetter, proxyUrlGetter?: ProxyUrlGetter);
+    /**
+     * The response record Mudlet hands to every HTTP event as its last argument:
+     * `{ headers = {...}, cookies = {...} }`. Scripts read it to branch on what
+     * came back — a content type, a rate-limit header — and we were passing an
+     * empty string, so `response.headers` was an index into nothing.
+     *
+     * `cookies` is always empty, and has to be: a browser never exposes
+     * `Set-Cookie` to script, cross-origin or not. It is still present, because
+     * the shape is the contract — a script doing `response.cookies["session"]`
+     * should read nil, not fail on indexing a missing table.
+     */
+    private responseRecord;
+    constructor(emit: EmitFn, vfsGetter: VFSGetter, proxyUrlGetter?: ProxyUrlGetter, defer?: DeferFn, 
+    /** Consulted before the profile VFS when serving a `file:` URL, so a
+     *  bundled path resolves the same way Lua's io.open resolves it. */
+    localReader?: LocalReader);
     downloadFile(saveTo: string, url: string): void;
     getHTTP(url: string, headers?: Record<string, string>): void;
     postHTTP(data: string | null, url: string, headers?: Record<string, string>, file?: string): void;
     putHTTP(data: string | null, url: string, headers?: Record<string, string>, file?: string): void;
     deleteHTTP(url: string, headers?: Record<string, string>): void;
     customHTTP(method: string, data: string | null, url: string, headers?: Record<string, string>, file?: string): void;
+    /**
+     * Serve a `file:` URL out of the VFS, reporting through the same
+     * sysDownloadDone/sysDownloadError a network download would.
+     *
+     * The path is the URL's own, percent-decoded — `file:///lua/x` reads
+     * `/lua/x`, which may be the read-only bundled namespace as readily as the
+     * profile, exactly as Lua's io.open sees both.
+     */
+    private copyLocalFile;
     private runDownload;
     private readWithProgress;
+    /**
+     * Emit on a later turn of the event loop.
+     *
+     * Every other emit here fires from an async continuation, so it is already
+     * off the call that started the request. The synchronous failures are the
+     * exception — building an upload body, or refusing a url scheme outright —
+     * because they would otherwise emit, and therefore dispatch Lua event
+     * handlers, while still inside the `__postHTTP`/`__downloadFile` binding
+     * that Lua itself called. Re-entering the Lua state mid-call crashes
+     * wasmoon outright ("memory access out of bounds"), taking the whole
+     * runtime with it rather than failing one call.
+     *
+     * The caller supplies the deferral so it can pick a queue a script can
+     * actually observe: microtasks are fine in the app, but a synchronous Lua
+     * run (the busted harness) never yields to one, and the runtime hands us
+     * its timer queue instead.
+     */
+    private emitLater;
     private bodyForUpload;
     private runRequest;
     private fetchWithFallback;

package/dist-lib/scripting/lua/LuaRuntime.d.ts

@@ -7,8 +7,13 @@ export declare class LuaRuntime implements IScriptingRuntime {
     private readonly api;
     private vfs;
     private readonly proxyUrlGetter;
+    /** Script-created temp aliases/triggers by id. `dead` marks one killed but
+     *  not yet reaped: Mudlet frees a killed unit in the deferred cleanup it
+     *  runs at the end of a line, not at the kill, so until then it is still
+     *  findable while no longer firing — `exists` says 1, `isActive` says 0, and
+     *  a second kill finds a corpse and answers false. {@link reapKilledTempItems}
+     *  does the freeing. */
     private readonly tempIds;
-    private nextTempId;
     private readonly labelCbIds;
     private cmdLineActionCbId;
     private windowCmdLineActionCbIds;
@@ -17,8 +22,53 @@ export declare class LuaRuntime implements IScriptingRuntime {
     private currentCaptureSpans;
     private currentNamedSpans;
     private currentFullMatchSpan;
+    /**
+     * Move the capture positions recorded for the line being processed to
+     * follow `delta` characters inserted at column `at`.
+     *
+     * A trigger that calls `insertText` before its own match and then
+     * `selectCaptureGroup` would otherwise select the text that has slid into
+     * where the capture used to be. A capture that starts at or after the
+     * insert moves whole; one the insert lands inside grows by it.
+     */
+    shiftCaptureSpans(at: number, delta: number): void;
     private _denyCurrentSend;
+    /** The read-only `/lua/` namespace: bundled Mudlet Lua, and in busted builds
+     *  the spec corpus and its fixtures. Values are Latin-1 byte-strings. */
+    private builtinFiles;
+    /**
+     * Bytes behind a built-in `/lua/` path, or null when the path is not one.
+     *
+     * Lua's own `io.open` reaches these through the VFS shim, but a caller
+     * working in bytes does not: the package installer is handed a path and
+     * reads it through the *profile* VFS, which knows nothing about this
+     * namespace. That is why installing one of the corpus's fixture packages
+     * reported "file not found" for a file Lua could open perfectly well.
+     */
+    readBuiltinBytes(path: string): Uint8Array | null;
     private destroyed;
+    /**
+     * Set once the Lua WASM module has terminated for good — an Emscripten
+     * `ExitStatus` or `WebAssembly.RuntimeError` unwinding out of a call.
+     *
+     * Lua reaches `exit(EXIT_FAILURE)` in `luaD_throw` whenever an error is
+     * raised with no protected frame to catch it: a panic, or an allocation
+     * failure inside a JS-side API call (`lua_newthread`, `lua_pushstring`, …)
+     * that runs on the main state rather than inside a pcall. Emscripten then
+     * latches its own ABORT flag, so every later call into the module throws the
+     * same thing — one identical error per timer tick, forever, with nothing
+     * saying the engine is gone.
+     *
+     * Tracked apart from {@link destroyed} because teardown still has to run:
+     * the JS-side resources (global event channel, TTS, map dispatchers) outlive
+     * the WASM module and must still be released.
+     */
+    private fatal;
+    /** Notified once, when {@link fatal} latches. The engine uses it to stop the
+     *  timer pump — the only thing left that would keep calling in. */
+    onFatalError: (() => void) | null;
+    /** True once nothing can be executed any more, for either reason. */
+    private get inert();
     private readonly watchedPaths;
     private readonly rawFnPtrs;
     private http;
@@ -29,6 +79,34 @@ export declare class LuaRuntime implements IScriptingRuntime {
     private constructor();
     static create(api: ScriptingAPI, vfs?: ProfileVFS | null, proxyUrlGetter?: () => string | undefined): Promise<LuaRuntime>;
     private setup;
+    /**
+     * Make `tostring(someFunction)` safe — and Mudlet-shaped.
+     *
+     * wasmoon pushes every JS function as a C closure and gives it a metatable
+     * carrying `__tostring`/`__index` that dereference the JS value behind it.
+     * But Lua 5.1's `lua_setmetatable` on a non-table, non-userdata value sets
+     * the metatable for that *whole type* (`G(L)->mt[ttype(o)]`), so the last JS
+     * function bound here becomes the metatable of EVERY Lua function. Call
+     * `tostring` on an ordinary one and wasmoon looks up a JS ref that was never
+     * registered, gets `undefined`, and throws `Cannot read properties of
+     * undefined (reading 'toString')` — a JS TypeError, not a Lua error, so it
+     * unwinds straight through `pcall` and out of `doStringSync`, killing the
+     * whole lua_State. `tostring(print)`, `display{f = print}` and Mudlet's own
+     * `printTable` on a table holding a function all hit it.
+     *
+     * The fix replaces the global `tostring` rather than the metamethod: a JS
+     * function pushed later installs a *fresh* metatable and would silently
+     * revert a metamethod patch, whereas nothing rebinds this global. Clearing
+     * the shared metatable for the duration of the call takes Lua's own
+     * `function: 0x…` path — which is what Mudlet prints too, so this also drops
+     * wasmoon's habit of stringifying a bound global into its entire JS source.
+     * Lua 5.1's `print` reads the global at call time, so it follows along.
+     *
+     * Installed after every `global.set` above and before Bridge.lua, so no
+     * bundled or user chunk can capture the unsafe version as an upvalue.
+     */
+    private installSafeFunctionTostring;
+    private installMudletLuaOverrides;
     private installFastColorEcho;
     private setupAnsiColorTable;
     /**
@@ -37,8 +115,36 @@ export declare class LuaRuntime implements IScriptingRuntime {
      * don't live in the persisted store the way permanent items do.
      */
     tempItemExists(id: number, type: string): boolean;
+    /** A live temp item of `type` carrying this Mudlet-supplied name — how
+     *  exists()/killTrigger() reach a tempComplexRegexTrigger. */
+    tempItemIdByName(name: string, type: string): number | null;
+    /**
+     * killAlias/killTrigger with a numeric id, for a script-created item.
+     *
+     * The item is unsubscribed and its callback released straight away — it must
+     * not fire again, including later in the very line pass that killed it — but
+     * the entry stays in the map, marked dead, until {@link reapKilledTempItems}.
+     * That is Mudlet's deferred cleanup: until the line ends, the corpse is still
+     * findable, which is what lets a second kill report `false` rather than
+     * mistaking the id for one that never existed.
+     */
+    /** Resolve a killTrigger/killAlias argument to a live temp item's id: the
+     *  number itself, or the name a tempComplexRegexTrigger was given. */
+    tempItemId(idOrName: number | string, type: 'alias' | 'trigger'): number | null;
+    private killTempItem;
+    /**
+     * Free every temp alias/trigger killed since the last call, or only those of
+     * `type` when given.
+     *
+     * Mudlet cleans up per unit, at the end of whatever pass that unit runs:
+     * aliases when nested expandAlias processing unwinds, triggers when the line
+     * finishes. Passing the type keeps those independent, so an alias pass can't
+     * reap a trigger the current line is still walking past.
+     */
+    reapKilledTempItems(type?: 'alias' | 'trigger'): void;
     /** enableTrigger/disableTrigger/enableAlias/disableAlias with a numeric id.
-     *  False when no temp item of that id is live. */
+     *  False when no temp item of that id is live — a killed one is still
+     *  findable until the reap, but re-enabling it would resurrect it. */
     setTempItemEnabled(id: number, enabled: boolean): boolean;
     /** Whether a live temp item is enabled — backs isActive(id, type). */
     tempItemEnabled(id: number): boolean;
@@ -79,8 +185,30 @@ export declare class LuaRuntime implements IScriptingRuntime {
      *  unmatched optional group (`undefined`) is left unset → nil, as before. */
     private pushMatchesTable;
     private exec;
+    private static readonly LUA_GCCOUNT;
+    private static readonly MEMORY_WARN_MB;
+    private static readonly MEMORY_SAMPLE_EVERY;
+    private memoryWarnIndex;
+    private dispatchesSinceMemorySample;
+    /** Sample Lua's own memory every few thousand dispatches and warn once per
+     *  threshold crossed. Called from the two execution funnels; the counter
+     *  keeps the `lua_gc` call itself off the hot path. */
+    private checkMemoryPressure;
+    /**
+     * Latch a WASM-level termination — see {@link fatal}. Emscripten throws its
+     * `ExitStatus` from the `proc_exit` import (C `exit()`) and a
+     * `WebAssembly.RuntimeError` from `abort()`; either means the module is
+     * gone, not that this one script failed, so the per-entity error report is
+     * wrong and repeating it every tick is worse.
+     *
+     * Returns true when `e` was such a termination, so the caller drops its own
+     * reporting. The one user-facing line is printed here, on the first one.
+     */
+    private markFatal;
     private execInner;
+    private execOnThread;
     private runChunk;
+    private runChunkOnThread;
     private static readonly FILE_DIALOG_SENTINEL;
     /** Threads suspended in invokeFileDialog, tracked so destroy() forgets
      *  them (their registry refs die with the closed Lua state). */
@@ -112,6 +240,19 @@ export declare class LuaRuntime implements IScriptingRuntime {
      */
     startSpeedWalk(from: number, to: number): void;
     private execModule;
+    /**
+     * The native matcher behind `utf8.find`, and so behind `utf8.match`,
+     * `gmatch` and `gsub` — utf8.lua routes all four through one local, which
+     * calls this first and keeps its own matcher for whatever this declines.
+     * See utf8Patterns.ts for why (ASCII-only classes, ~35k VM instructions a
+     * find). Bound before the module loads, though the Lua side looks it up per
+     * call, so a runtime without it still works.
+     *
+     * The result crosses as a flat array — wasmoon hands JS arrays over
+     * 0-indexed — of `start, end, capture…`, or `false` for "no match" as
+     * distinct from nil's "not my pattern, use yours".
+     */
+    private installNativeUtf8Find;
     private dispatchingEvent;
     private readonly pendingEvents;
     emitEvent(event: string, args: unknown[]): void;
@@ -133,6 +274,14 @@ export declare class LuaRuntime implements IScriptingRuntime {
      * raises sysUnzipDone / sysUnzipError. Always fire-and-forget.
      */
     private runUnzipAsync;
+    /** Run `fn` off the current call stack, on the queue a blocked script still
+     *  pumps. See the note in HttpService.emitLater: a microtask would never be
+     *  reached by a script sitting in waitForEvent. */
+    private deferToTimerQueue;
+    /** The line the global `line` currently holds, so a caller can put it back
+     *  after a nested feedTriggers has processed a line of its own. */
+    getCurrentLine(): string;
+    private currentLineText;
     setCurrentLine(line: string, _isPrompt: boolean): void;
     setCommand(command: string): void;
     dispatchSendRequest(text: string): boolean;

package/dist-lib/scripting/lua/bindings/map.d.ts

@@ -1,14 +1,2 @@
 import type { BindingContext } from './context';
-/**
- * Mudlet's map API: the 2D view, room and area CRUD, exits, doors, custom
- * lines, labels, highlights, selection, per-room styling, user data, and the
- * mapInfo / context-menu extension points.
- *
- * This is by far the widest binding surface in the runtime — it mirrors
- * Mudlet's map Lua API essentially one-for-one — so it lives in its own
- * module. The heavy lifting is all in MapStore behind `api.map`; the code
- * here is argument coercion and Mudlet's return-shape conventions (notably
- * alse where Mudlet returns nil, which Bridge.lua unpacks into the
- * documented (nil, errMsg) multi-returns).
- */
 export declare function installMapBindings({ lua, api, vfs, channel, emitEvent, unregisterCb, pushJsValue, registerRawGlobal, evaluateMapInfo, evaluateExitWeightFilter, }: BindingContext): void;